Token Context MCP (v0.3.5)

🌐 English: README.md | 🇻🇳 Tiếng Việt: README.vi.md | 🇨🇳 简体中文: README.cn.md | 📝 Prompt Protocol: sample_prompt.md | 📋 Changelog: CHANGELOG.md

token-context-mcp is an on-demand, budget-governed Model Context Protocol (MCP) server for autonomous AI coding agents (Claude Code, Cursor, Codex, Google Antigravity). Instead of blindly dumping an entire repository or compressing it into a static snapshot that strips function bodies down to signatures, it provides an interactive AST-level pull pipeline that delivers exact code symbols and downstream impact graphs with verified file:line + SHA-256 evidence.

🖼️ Architecture & Benchmark Infographics (2x Retina Dark Green)

⚡ Core Architectural Pillars

1. 3-Layer Governance Microkernel (kernel/):
   • Every request is governed by a lightweight execution pipeline:
     • Layer 1 — Clean AST-Boundary Cap: Enforces max_response_tokens at syntactic boundaries without cutting functions in half.
     • Layer 2 — Per-Tool Async Timeout Gate: Prevents runaway hangs on large monorepos (10s for get_repo_map, 5s for search_source).
     • Layer 3 — 150K Session Budget Circuit Breaker: Emits a telemetry warning at 80% usage and halts runaway loops at 150,000 cumulative tokens to prevent bill shocks.
2. Zero Schema Bloat:
   • The default tools/list payload exposes only 10 core read-only retrieval tools (keeping 10 extension tools and 2 admin tools off the wire until requested). Server-side JSON schemas are slimmed to reduce initial prompt tax.
3. Incremental Tree-sitter AST & Persistent SQLite Graph (index/):
   • Fast mtime_ns + SHA-256 change detection across Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, and C# with symlink-escape and path traversal guards.

📊 Empirical Benchmarks (tiktoken o200k_base Audited)

All numbers are measured using OpenAI's o200k_base tokenizer across two real-world open-source repositories: rich (Python, 213 files, 507k tokens) and fastify (JS/TS, 291 files, 538k tokens):

🚀 Quick Start

Option 1: Run instantly with uvx (Recommended)

# Register, index, and print agent config for the current directory
uvx token-context-mcp quickstart .

Option 2: Install via pip

pip install token-context-mcp

# Register a codebase and launch server
token-context register --repo-id my-project --root /path/to/project
token-context index --repo-id my-project
token-context serve

Desktop GUI Controller (PySide6)

Includes hardware telemetry, CPU/RAM monitoring, and repository status overview:

uvx --from "token-context-mcp[gui]" token-context-gui

🤖 Coding Agent Setup

token-context-mcp communicates over local stdio. Add the configuration below to your agent:

1. Claude Code

claude mcp add --transport stdio --scope user token-context -- uvx token-context-mcp serve

2. Cursor

In Cursor Settings > Features > MCP Servers:

• Name: token-context
• Type: command
• Command: uvx token-context-mcp serve

3. Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/.config/Claude/claude_desktop_config.json (macOS/Linux):

{
  "mcpServers": {
    "token-context": {
      "command": "uvx",
      "args": ["token-context-mcp", "serve"]
    }
  }
}

4. Google Antigravity IDE / Gemini CLI

Add to mcp_config.json:

{
  "mcpServers": {
    "token-context": {
      "command": "uvx",
      "args": [
        "token-context-mcp",
        "serve",
        "--output-mode", "text",
        "--schema-profile", "gemini_safe"
      ]
    }
  }
}

🛠 Tool Reference Catalog (10 Default Core Tools)

By default, the server exposes 10 read-only retrieval tools to preserve agent context:

(10 extension tools including SQLite multi-agent memory memory_*, lazy tool discovery *_tools, hardware-adaptive compressor sample_summarize, and 2 admin tools agent_control, audit_logs can be enabled via configuration).

🔒 Security Guarantees & Privacy

• No Remote Code Execution (RCE): No tool can execute shell commands, eval code, or modify repository source files.
• 100% Local & Private: All SQLite WAL indexes remain on your machine; zero cloud telemetry or external API calls.
• Automatic Secret Redaction: Regex-based redaction of API keys, tokens, and private keys ([REDACTED: potential secret]) plus hard denial of sensitive files (.env*, .ssh, *.pem, id_rsa).

📚 Technical Documentation

• sample_prompt.md: Standard two-phase prompt templates (EN / VI / CN).
• CHANGELOG.md: Release history and upgrade notes.
• launch/00_fact_sheet.md: Verified empirical benchmarks and measurement methodologies.
• docs/CLIENT_MATRIX.md: Step-by-step MCP client verification matrix.

Maintained by the Token Context MCP community. Licensed under MIT.