上下文服务器

Name: 上下文服务器
Author: ReyNeill

作者：ReyNeill10 星标更新：2025-08-30

安装使用来源：spider==github.com

项目介绍

【技术文档摘要】：

Marketplace 徽章

Kontxt MCP 服务器

这是一个模型上下文协议（MCP）服务器，旨在解决代码库索引问题（直到代理可以处理）。

特性

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

配置

克隆/下载：获取服务器代码。

创建环境：

python -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

安装依赖项：
```
pip install -r requirements.txt
```
安装 tree：确保系统中有tree命令可用。
- macOS: brew install tree
- Debian/Ubuntu: sudo apt update && sudo apt install tree
- Windows: 需要安装一个端口或使用WSL。
配置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

提示：你可以使用 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"
    }
  }
}

提示：记得始终刷新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

# 或通过环境变量
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，否则禁用。

分词器（Gemma）访问与自动恢复

此服务器使用google/gemma-7b分词器来估计令牌。该模型由Google在Hugging Face上进行了限制。

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

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

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

访问 https://huggingface.co/google/gemma-7b 并登录（如有需要，创建一个帐户）。
在模型页面接受Google的条款。
如果在无头/CI或容器中运行，认证环境：huggingface-cli login（或设置HF_TOKEN）。

配置：

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

基本用法

示例查询：

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

提示：你可以进一步指定代理使用MCP工具，如果它没有使用："auth文件第三代码块的最后一句话是什么？使用可用的MCP工具。"

上下文附加

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

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

服务器会向Gemini提及这些文件，但不会自动读取或包含它们的内容。相反，Gemini将基于查询上下文决定读取哪些文件。

这种方法允许Gemini只读取实际需要的文件，防止上下文因无关文件内容而膨胀。

令牌使用跟踪

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

仓库结构列表
文件读取
grep搜索
用户查询中附加的文件
生成的响应

这些信息在操作过程中被记录下来，帮助你监控API使用情况并优化查询。

PD：想要改进工具吗？欢迎PR。