# Token-Optimized MCP Server

A high-performance [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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](#overview)
- [Available Tools](#available-tools)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Building](#building)
- [Configuration](#configuration)
  - [Claude Desktop](#claude-desktop)
  - [VS Code / Antigravity IDE](#vs-code--antigravity-ide)
- [Usage](#usage)
  - [Development Mode](#development-mode)
  - [Production Mode](#production-mode)
  - [MCP Inspector](#mcp-inspector)
- [Project Structure](#project-structure)
- [Security](#security)
- [License](#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:**
```json
{
  "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:**
```json
{
  "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:

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

---

## Installation

```bash
# 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:

```bash
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`

```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):

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

> **Windows example:**
> ```json
> "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):

```bash
npm run dev
```

### Production Mode

Build first, then start the compiled server:

```bash
npm run build
npm start
```

### MCP Inspector

The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) provides a browser-based UI for testing tools, simulating LLM requests, and inspecting JSON-RPC messages — no API keys required.

```bash
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