Skip to main content
Glama
Token-Optimized MCP Server

Token-Optimized MCP Server

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


Related MCP server: readdown-mcp

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.

Note: The metrics database initializes automatically as an in-memory instance on server startup. No external setup, schema migration, or configuration is required.


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

License

ISC

Available Tools

2 tools
extract_web_contentA

Fetches raw HTML and converts it into structurally sound, token-efficient Markdown. Preserves semantic tags for AI readability.

Inputs: url (required).

query_metrics_databaseC

Queries internal metrics. Outputs strictly in YAML format for maximum token efficiency.

Inputs: query (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have entirely distinct domains: one handles web content extraction, the other queries a metrics database. There is no overlap or ambiguity.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern using snake_case, making them predictable and disambiguated.

    Tool Count3/5

    With only 2 tools, the server feels thin for its name 'Token-Optimized MCP Server' which implies a broader scope. The count is borderline acceptable.

    Completeness2/5

    The server name suggests a focus on token optimization, but the tools only cover web extraction and database queries. Key operations like text optimization or token analysis are missing.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Fetches web pages and converts them to clean, readable markdown format by extracting main content while removing navigation, ads, and other non-essential elements to minimize token usage.
      4
      -
    • A
      license
      A
      quality
      D
      maintenance
      Converts web pages and HTML strings into clean, LLM-optimized Markdown with metadata extraction and token estimation. It uses a lightweight, browserless approach to provide token-efficient output for more effective LLM processing.
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables token-efficient web page fetching by converting HTML to Markdown with tiered access (outline, section, search) to minimize LLM context usage.
      Apache 2.0
    • F
      license
      A
      quality
      D
      maintenance
      Reduces token consumption by 73-87% by cleaning web and API data before it reaches the LLM context window. Supports fetching URLs, searching the web, optimizing JSON, and more.
      6
      1
      -