Kontxt MCP Server

Marketplace 徽章

Kontxt MCP 服务

一个试图解决代码库索引问题（直到 Agent 能够解决）的 Model Context Protocol (MCP) 服务。

功能

• 连接到用户指定的本地代码仓库。
• 为 AI 客户端（如 Cursor、Claude Desktop）提供 get_codebase_context 工具。
• 内部使用 Gemini 2.0 Flash 的 1M 输入窗口分析代码库，并根据用户客户端的查询生成上下文。
• Flash 本身可以使用内部工具（list_repository_structure、read_files、grep_codebase）来理解代码。
• 支持 SSE（推荐）和 stdio 传输协议。
• 支持使用用户查询中附带的文件/文档/上下文进行更有针对性的分析。
• 跟踪令牌用量，并详细展示 API 消耗情况。
• 用户可配置上下文生成的令牌上限（选项：500k、800k 或 1M 个令牌；默认值：800k）。

设置

1. 克隆/下载： 获取服务端代码。
2. 创建环境：

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. 安装依赖项：

   pip install -r requirements.txt
   

4. 安装 tree： 确保系统中可以使用 tree 命令。
   • macOS：brew install tree
   • Debian/Ubuntu：sudo apt update && sudo apt install tree
   • Windows：需要安装移植版本或使用 WSL。
5. 配置 API 密钥：
   • 将 .env.example 复制为 .env。
   • 编辑 .env 并添加 Google Gemini API 密钥：

     GEMINI_API_KEY="YOUR_ACTUAL_API_KEY"
     

   • 或者，也可以通过 --gemini-api-key 命令行参数提供密钥。

作为独立服务运行（推荐）

默认情况下，服务以 SSE 模式运行，您可以：

• 独立启动服务
• 从多个客户端连接
• 重启客户端时保持服务运行

运行服务：

python kontxt_server.py --repo-path /path/to/your/codebase

PS：您可以使用 pwd 列出项目路径

服务默认会在 http://127.0.0.1:8080/sse 启动。

如需其他选项：

python kontxt_server.py --repo-path /path/to/your/codebase --host 0.0.0.0 --port 6900

关闭服务

在运行服务的终端中按 Ctrl+C 即可停止服务。服务将尝试在 3 秒超时内正常关闭。

从客户端连接到服务（Cursor 示例）

服务运行后，您可以通过编辑 ~/.cursor/mcp.json 文件将 Cursor 连接到服务：

{
  "mcpServers": {
    "kontxt-server": {
      "serverType": "sse",
      "url": "http://localhost:8080/sse"
    }
  }
}

PS：请记得始终在 Cursor 设置或其他客户端中刷新 MCP 服务，以通过 SSE 连接到 MCP

替代方案：使用 stdio 传输运行

如果您希望由客户端启动并管理服务进程：

python kontxt_server.py --repo-path /path/to/your/codebase --transport stdio

对于此模式，请按如下方式配置 ~/.cursor/mcp.json 文件：

{
  "mcpServers": {
    "kontxt-server": {
      "serverType": "stdio",
      "command": "python",
      "args": ["/absolute/path/to/kontxt_server.py", "--repo-path", "/absolute/path/to/your/codebase", "--transport", "stdio"],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

命令行参数

• --repo-path PATH：必需。要分析的本地代码仓库绝对路径。
• --gemini-api-key KEY：Google Gemini API 密钥（若提供，则覆盖 .env 中的设置）。
• --token-threshold NUM：上下文的目标最大令牌数。允许的值为：
  • 500000
  • 800000（默认值）
  • 1000000
• --gemini-model NAME：要使用的特定 Gemini 模型（默认值：models/gemini-2.5-flash-preview-04-17）。
• --tokenizer-model NAME：用于估算令牌数的 Hugging Face 分词器 ID（默认值：google/gemma-7b；可通过 KONTXT_TOKENIZER_MODEL 覆盖）。
• --transport {stdio,sse}：要使用的传输协议（默认值：sse）。
• --host HOST：SSE 服务的主机地址（默认值：127.0.0.1）。
• --port PORT：SSE 服务的端口（默认值：8080）。
• --cors-origins ORIGINS：允许的 CORS 来源列表，以逗号分隔。若省略，则默认仅允许环回地址。
• --cors-credentials：允许 CORS 凭据（默认禁用）。

CORS 配置

出于安全考虑，不使用通配符 CORS。默认情况下，仅允许环回来源：

• http://127.0.0.1、http://localhost 和绑定的 host:port。

若要在开发期间允许特定 Web 客户端，请传入明确的来源或使用环境变量：

python kontxt_server.py \
  --repo-path /path/to/your/codebase \
  --cors-origins http://localhost:3000,http://127.0.0.1:5173

# or via environment variable
KONTXT_CORS_ORIGINS="http://localhost:3000,http://127.0.0.1:5173" \
python kontxt_server.py --repo-path /path/to/your/codebase

注意：

• 允许的方法：GET、OPTIONS。请求头：全部。凭据：默认关闭，除非设置了 --cors-credentials。

Tokenizer（Gemma）访问权限与自动恢复

此服务使用 google/gemma-7b tokenizer 来估算 token 数量。该模型由 Google 在 Hugging Face 上设为受限访问。

如果你尚未获得访问权限，会发生以下情况：

• 启动时，如果无法下载 tokenizer，服务会记录一条明确的消息，并自动打开：https://huggingface.co/google/gemma-7b
• 服务会继续运行，并使用启发式 token 估算器（不会崩溃）。
• 服务会定期重试加载 tokenizer；获得访问权限后，会自动切换（无需重启）。

如何获得访问权限（免费，约需 2 分钟）：

1. 访问 https://huggingface.co/google/gemma-7b 并登录（如有需要，请创建账户）。
2. 在模型页面接受 Google 的条款。
3. 如果在无头环境、CI 或容器中运行，请对环境进行身份验证：huggingface-cli login（或设置 HF_TOKEN）。

配置：

• --tokenizer-model 或 KONTXT_TOKENIZER_MODEL：如有需要，使用其他 HF tokenizer ID。
• KONTXT_TOKENIZER_RELOAD_INTERVAL（秒，默认值为 60）：服务重试加载 tokenizer 的间隔。

基本用法

查询示例：

• “这个代码库是做什么的？”
• “身份验证系统是如何工作的？”
• “解释一下应用程序中的数据流”

附言：如果 Agent 没有使用 MCP 工具，你可以进一步指定要使用该工具：“auth 文件中第三个代码块的最后一个单词是什么？请使用可用的 MCP 工具。”

上下文附加

查询中引用的文件／上下文会作为分析上下文提供：

• “解释此文件的工作原理：@kontxt_server.py”
• “找出所有与 @user_model.py 交互的文件”
• “比较 @file1.js 和 @file2.js 的实现”

服务会将这些文件告知 Gemini，但不会自动读取或包含其内容。相反，Gemini 会根据查询上下文，使用其工具决定要读取哪些文件。

这种方式使 Gemini 只读取实际需要的文件，并避免上下文被无关的文件内容填满。

Token 用量跟踪

服务会跟踪不同操作的 token 用量：

• 仓库结构列表
• 文件读取
• Grep 搜索
• 用户查询中附加的文件
• 生成的回复

这些信息会在运行期间记录，帮助你监控 API 用量并优化查询。

附言：想让这个工具变得更好？欢迎提交 PR。