Token-Optimized MCP Server

A high-performance Model Context Protocol (MCP) server built with Node.js and TypeScript. This server is purpose-built to minimize LLM token consumption through YAML serialization, structural HTML-to-Markdown distillation, and pre-flight token counting via the BPE tokenizer.

---

Table of Contents

• Overview
• Available Tools
• Prerequisites
• Installation
• Building
• Configuration
  • Claude Desktop
  • VS Code / Antigravity IDE
• Usage
  • Development Mode
  • Production Mode
  • MCP Inspector
• Project Structure
• Security
• License

---

Overview

Modern AI agents connected via MCP suffer from context window exhaustion when tool responses contain verbose JSON payloads or raw HTML. This server addresses the problem at the architecture layer:

Optimization Strategy	Token Reduction
YAML serialization over JSON	~40–48%
HTML → structured Markdown	~60–80%
Pre-flight token gating	Prevents overflow

All diagnostic logging is routed to stderr to preserve the JSON-RPC protocol integrity on stdout.

---

Available Tools

extract_web_content

Fetches a web page, strips HTML noise, and returns clean, semantically structured Markdown optimized for LLM consumption.

Parameter	Type	Required	Description
url	string	Yes	A valid URL to fetch and convert.

Example input:

{
  "url": "https://example.com"
}

Returns: Token-efficient Markdown with preserved heading hierarchy, links, and tables. Token count is logged to stderr.

---

query_metrics_database

Queries an internal metrics database and returns the results serialized in YAML format to reduce token overhead by approximately 45% compared to equivalent JSON.

Parameter	Type	Required	Description
query	string	Yes	A natural-language or structured query string.

Example input:

{
  "query": "Show CPU and memory usage for the last hour"
}

Returns: YAML-formatted metrics payload. If the response exceeds 8,000 tokens, a warning is emitted to stderr recommending semantic chunking.

---

Prerequisites

• Node.js v18.0.0 or higher
• npm v9+ (bundled with Node.js 18+)

Verify your installation:

node --version   # Must be >= 18.0.0
npm --version

---

Installation

# Clone or navigate to the project directory
cd optimized-mcp-server

# Install all dependencies
npm install

Dependencies at a Glance

Package	Purpose
@modelcontextprotocol/sdk	Official MCP server SDK
zod	Runtime input schema validation
js-tiktoken	BPE token counting (OpenAI compatible)
node-html-markdown	High-fidelity HTML → Markdown conversion
@kreuzberg/html-to-markdown	Native Rust-binding Markdown converter
yaml	JSON → YAML serialization

---

Building

Compile the TypeScript source to JavaScript:

npm run build

The compiled output is written to the build/ directory.

---

Configuration

To connect this server to an MCP-compatible AI host, register it in the host's configuration file. Below are copy-pasteable templates for common hosts.

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "token-optimized-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/optimized-mcp-server/build/index.js"
      ]
    }
  }
}

Important: Replace /absolute/path/to/ with the actual absolute path on your system. On Windows, use double backslashes (\\) or forward slashes (/) in JSON strings.

After saving, fully quit and restart Claude Desktop to re-initialize the JSON-RPC handshake.

---

VS Code / Antigravity IDE

Add the following to your MCP configuration file (typically mcp_config.json in your editor's settings directory):

{
  "mcpServers": {
    "token-optimized-server": {
      "command": "node",
      "args": [
        "/absolute/path/to/optimized-mcp-server/build/index.js"
      ]
    }
  }
}

Windows example:

"args": [
    "C:\\Users\\YourName\\projects\\optimized-mcp-server\\build\\index.js"
]

---

Usage

Development Mode

Run the server directly from TypeScript source using tsx (no build step required):

npm run dev

Production Mode

Build first, then start the compiled server:

npm run build
npm start

MCP Inspector

The MCP Inspector provides a browser-based UI for testing tools, simulating LLM requests, and inspecting JSON-RPC messages — no API keys required.

npx @modelcontextprotocol/inspector node build/index.js

This launches a local proxy and opens the Inspector UI in your default browser. Use it to:

1. Verify the protocol handshake completes successfully.
2. Execute extract_web_content with a test URL.
3. Execute query_metrics_database and confirm YAML output.
4. Monitor stderr logs for token counts and threshold warnings.

---

Project Structure

optimized-mcp-server/
├── src/
│   └── index.ts          # Core server implementation
├── build/                # Compiled JavaScript output (generated)
├── node_modules/         # Dependencies (generated)
├── package.json          # Project metadata and scripts
├── tsconfig.json         # TypeScript compiler configuration
├── .gitignore            # Git exclusion rules
├── README.md             # This file
└── SECURITY.md           # Security guidelines and best practices

---

License

ISC