AI导哈

代码库上下文服务器

Kontxt MCP Server 是一个模型上下文协议服务器，用于连接本地代码库并为AI客户端提供代码库上下文分析功能，适用于代码理解和开发辅助场景。

  • by ReyNeill
  • Python
  • 本地部署
  • 10 星标
  • 更新于
在 GitHub 查看 reyneill/kontxt

使用说明

市场徽章

Kontxt MCP服务器

一个模型上下文协议（MCP）服务器，试图解决condebase索引问题（直到代理可以）。

特性

  • 连接到用户指定的本地代码存储库。
  • 提供(get_codebase_context)AI客户端的工具（如Cursor、Claude Desktop）。
  • 在内部使用Gemini 2.0 Flash的1M输入窗口来分析代码库，并根据用户的客户端查询生成上下文。
  • Flash本身可以使用内部工具(list_repository_structure, read_files, grep_codebase)理解代码。
  • 支持SSE（推荐）和stdio传输协议。
  • 支持客户查询中的用户附加文件/docs/context，以进行更有针对性的分析。
  • 跟踪代币使用情况，并提供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/mcp.json 文件：

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

PS：记住始终在光标设置或其他客户端上刷新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：拥抱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客户端，请传递显式的origins或使用env var：

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用于估计令牌。该模型由谷歌在Hugging Face上进行门控。

如果您还没有访问权限，会发生什么：

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

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

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

配置：

  • --tokenizer-model 或 KONTXT_TOKENIZER_MODEL：如果需要，请使用不同的HF标记器id。
  • KONTXT_TOKENIZER_RELOAD_INTERVAL （秒，默认值60）：服务器重新尝试加载标记器的频率。

基本用法

示例查询：

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

PS：如果代理不使用MCP工具，您可以进一步指定代理使用它：“身份验证文件第三个代码块的最后一个单词是什么？使用可用的MCP工具。”

上下文附件

查询中引用的文件/上下文将作为分析上下文包含在内：

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

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

这种方法允许Gemini只读取实际需要的文件，并防止上下文中充斥着无关的文件内容。

令牌使用跟踪

服务器跟踪不同操作中的令牌使用情况：

  • 存储库结构列表
  • 文件读取
  • Grep搜索
  • 用户查询的附件
  • 生成的响应

此信息将在操作过程中记录，帮助您监控API的使用情况并优化查询。

PD：想要改进工具吗？PR是开放的。

相关 MCP