上下文+

面向大规模工程的语义智能。

Context+ 是一款 MCP 服务器，专为追求 99% 准确率的开发者设计。通过结合 RAG、Tree-sitter AST、谱聚类以及 Obsidian 风格的链接功能，Context+ 可以将庞大的代码库转化为可搜索的分层特性图。

既然你在这里，不妨看看我的另一个项目 Airena。组建一支 AI 代理团队，与其他编排者展开对决。排行榜第一名将获得 1600 美元的奖金！

https://github.com/user-attachments/assets/a97a451f-c9b4-468d-b036-15b65fc13e79

工具

发现

工具	描述
get_context_tree	项目的结构化 AST 树，包含文件头和符号范围（函数/类/方法的行号）。动态剪枝会自动缩减输出内容。
get_file_skeleton	函数签名、类方法和类型定义，附带行号范围，无需读取完整函数体。展示 API 表面。
semantic_code_search	按语义而非精确文本进行搜索。基于文件头/符号的嵌入向量进行检索，并返回匹配的符号定义行。
semantic_identifier_search	针对函数/类/变量的标识符级语义检索，按调用站点和行号排序。
semantic_navigate	使用谱聚类按语义浏览代码库。将语义相关的文件分组到带有标签的簇中。

分析

工具	描述
get_blast_radius	追踪符号被导入或使用的每一个文件和行。防止出现孤立引用。
run_static_analysis	运行原生 linter 和编译器，查找未使用的变量、死代码和类型错误。支持 TypeScript、Python、Rust 和 Go。

代码运维

工具	描述
propose_commit	编写代码的唯一方式。在保存前会根据严格规则进行验证。写入前会创建一个影子恢复点。
get_feature_hub	Obsidian 风格的特性枢纽导航器。枢纽是带有 [[wikilinks]] 的 .md 文件，用于将特性映射到代码文件。

版本控制

工具	描述
list_restore_points	列出由 propose_commit 创建的所有影子恢复点。每个恢复点都记录了 AI 修改之前的文件状态。
undo_change	将文件恢复到特定 AI 修改之前的状态。使用影子恢复点。不会影响 Git。

内存与 RAG

工具	描述
upsert_memory_node	创建或更新内存节点（概念、文件、符号、笔记），并自动生成嵌入向量。
create_relation	在节点之间创建有类型的边（relates_to、depends_on、implements、references、similar_to、contains）。
search_memory_graph	基于图遍历的语义搜索——先找到直接匹配项，再遍历一阶和二阶邻居。
prune_stale_links	移除衰减的边（e^(-λt) 低于阈值）以及访问次数过低的孤立节点。
add_interlinked_context	批量添加节点，并自动建立相似度链接（余弦相似度 ≥ 0.72 时会自动创建边）。
retrieve_with_traversal	从某个节点出发向外遍历——返回所有可达邻居，并按衰减程度和深度评分。

互补服务器： pmll-memory-mcp (npx pmll-memory-mcp) 是 @drQedwards 开发的独立 MCP 服务器，它基于 Context+ 的长期记忆图，增加了短期 KV 上下文记忆、Q-promise 去重功能以及解决方案引擎。详情请参阅 drQedwards/PPM。

设置

快速入门（npx / bunx）

无需安装。将 Context+ 添加到你的 IDE MCP 配置中。

对于 Claude Code、Cursor 和 Windsurf，使用 mcpServers：

{
  "mcpServers": {
    "contextplus": {
      "command": "bunx",
      "args": ["contextplus"],
      "env": {
        "OLLAMA_EMBED_MODEL": "nomic-embed-text",
        "OLLAMA_CHAT_MODEL": "gemma2:27b",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY"
      }
    }
  }
}

对于 VS Code（.vscode/mcp.json），使用 servers 和 inputs：

{
  "servers": {
    "contextplus": {
      "type": "stdio",
      "command": "bunx",
      "args": ["contextplus"],
      "env": {
        "OLLAMA_EMBED_MODEL": "nomic-embed-text",
        "OLLAMA_CHAT_MODEL": "gemma2:27b",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY"
      }
    }
  },
  "inputs": []
}

如果你更喜欢使用 npx，可以这样设置：

• "command": "npx"
• "args": ["-y", "contextplus"]

或者直接在当前目录生成 MCP 配置文件：

npx -y contextplus init claude
bunx contextplus init cursor
npx -y contextplus init opencode

支持的编码助手名称：claude、cursor、vscode、windsurf、opencode。

配置文件位置：

IDE	配置文件
Claude Code	.mcp.json
Cursor	.cursor/mcp.json
VS Code	.vscode/mcp.json
Windsurf	.windsurf/mcp.json
OpenCode	opencode.json

CLI 子命令

• init [target] - 生成 MCP 配置（目标：claude、cursor、vscode、windsurf、opencode）。
• skeleton [path] 或 tree [path] - （新增） 直接在终端中查看项目的结构树，包含文件头和符号定义。
• [path] - 为指定路径启动 MCP 服务器（标准输入输出），默认为当前目录。

从源码安装

npm install
npm run build

嵌入提供者

Context+ 支持两种由 CONTEXTPLUS_EMBED_PROVIDER 控制的嵌入后端：

提供者	值	需要	适用场景
Ollama（默认）	ollama	本地 Ollama 服务器	免费、离线、私密
OpenAI 兼容	openai	API 密钥	Gemini（免费层）、OpenAI、Groq、vLLM

Ollama（默认）

无需额外配置。只需运行带有嵌入模型的 Ollama 即可：

ollama pull nomic-embed-text
ollama serve

Google Gemini（免费层）

完整的 Claude Code .mcp.json 示例：

{
  "mcpServers": {
    "contextplus": {
      "command": "npx",
      "args": ["-y", "contextplus"],
      "env": {
        "CONTEXTPLUS_EMBED_PROVIDER": "openai",
        "CONTEXTPLUS_OPENAI_API_KEY": "YOUR_GEMINI_API_KEY",
        "CONTEXTPLUS_OPENAI_BASE_URL": "https://generativelanguage.googleapis.com/v1beta/openai",
        "CONTEXTPLUS_OPENAI_EMBED_MODEL": "text-embedding-004"
      }
    }
  }
}

可在 Google AI Studio 获取免费 API 密钥。

OpenAI

{
  "mcpServers": {
    "contextplus": {
      "command": "npx",
      "args": ["-y", "contextplus"],
      "env": {
        "CONTEXTPLUS_EMBED_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_EMBED_MODEL": "text-embedding-3-small"
      }
    }
  }
}

其他 OpenAI 兼容 API（Groq、vLLM、LiteLLM）

任何实现 OpenAI Embeddings API 的端点均可使用：

{
  "mcpServers": {
    "contextplus": {
      "command": "npx",
      "args": ["-y", "contextplus"],
      "env": {
        "CONTEXTPLUS_EMBED_PROVIDER": "openai",
        "CONTEXTPLUS_OPENAI_API_KEY": "YOUR_KEY",
        "CONTEXTPLUS_OPENAI_BASE_URL": "https://your-proxy.example.com/v1",
        "CONTEXTPLUS_OPENAI_EMBED_MODEL": "your-model-name"
      }
    }
  }
}

注意： semantic_navigate 工具也会使用聊天模型进行聚类标注。当使用 openai 提供者时，请设置 CONTEXTPLUS_OPENAI_CHAT_MODEL（默认值为 gpt-4o-mini）。

对于 VS Code、Cursor 或 OpenCode，可在 IDE 的 MCP 配置格式中使用相同的 env 块（参见上文的【配置文件位置】表格）。

架构

基于 Model Context Protocol SDK，使用 TypeScript 和标准输入输出构建的三层架构：

核心层（src/core/）- 多语言 AST 解析（tree-sitter，43 个扩展）、支持 .gitignore 的遍历、带磁盘缓存的 Ollama 向量嵌入、维基链接枢纽图、带有衰减评分的内存属性图。

工具层（src/tools/）- 17 个 MCP 工具，提供结构化、语义化、操作性和内存图功能。

Git 层（src/git/）- 影子还原点系统，用于撤销操作而不会影响 Git 历史记录。

运行时缓存（.mcp_data/）- 在服务器启动时创建；存储可重用的文件、标识符和调用站点嵌入，以避免重复的 GPU/CPU 嵌入计算。实时跟踪器会增量刷新已更改的文件/函数。

配置

变量	类型	默认值	描述
CONTEXTPLUS_EMBED_PROVIDER	字符串	ollama	嵌入模型后端：ollama 或 openai
OLLAMA_EMBED_MODEL	字符串	nomic-embed-text	Ollama 嵌入模型
OLLAMA_API_KEY	字符串	-	Ollama Cloud API 密钥
OLLAMA_CHAT_MODEL	字符串	llama3.2	用于聚类标注的 Ollama 对话模型
CONTEXTPLUS_OPENAI_API_KEY	字符串	-	兼容 OpenAI 的提供商 API 密钥（别名：OPENAI_API_KEY）
CONTEXTPLUS_OPENAI_BASE_URL	字符串	https://api.openai.com/v1	兼容 OpenAI 的 API 端点 URL（别名：OPENAI_BASE_URL）
CONTEXTPLUS_OPENAI_EMBED_MODEL	字符串	text-embedding-3-small	兼容 OpenAI 的嵌入模型（别名：OPENAI_EMBED_MODEL）
CONTEXTPLUS_OPENAI_CHAT_MODEL	字符串	gpt-4o-mini	用于标注的兼容 OpenAI 的对话模型（别名：OPENAI_CHAT_MODEL）
CONTEXTPLUS_EMBED_BATCH_SIZE	字符串（解析为数字）	8	每次 GPU 调用的嵌入批次大小，限制在 5–10 之间
CONTEXTPLUS_EMBED_CHUNK_CHARS	字符串（解析为数字）	2000	合并前每个分块的字符数，限制在 256–8000 之间
CONTEXTPLUS_MAX_EMBED_FILE_SIZE	字符串（解析为数字）	51200	跳过大于此字节数的非代码文本文件
CONTEXTPLUS_EMBED_NUM_GPU	字符串（解析为数字）	-	可选的 Ollama 嵌入运行时 num_gpu 替代值
CONTEXTPLUS_EMBED_MAIN_GPU	字符串（解析为数字）	-	可选的 Ollama 嵌入运行时 main_gpu 替代值
CONTEXTPLUS_EMBED_NUM_THREAD	字符串（解析为数字）	-	可选的 Ollama 嵌入运行时 num_thread 替代值
CONTEXTPLUS_EMBED_NUM_BATCH	字符串（解析为数字）	-	可选的 Ollama 嵌入运行时 num_batch 替代值
CONTEXTPLUS_EMBED_NUM_CTX	字符串（解析为数字）	-	可选的 Ollama 嵌入运行时 num_ctx 替代值
CONTEXTPLUS_EMBED_LOW_VRAM	字符串（解析为布尔值）	-	可选的 Ollama 嵌入运行时 low_vram 替代值
CONTEXTPLUS_EMBED_TRACKER	字符串（解析为布尔值）	true	在文件变更时启用实时嵌入刷新
CONTEXTPLUS_EMBED_TRACKER_MAX_FILES	字符串（解析为数字）	8	每次跟踪器刷新处理的最大变更文件数，限制在 5–10 之间
CONTEXTPLUS_EMBED_TRACKER_DEBOUNCE_MS	字符串（解析为数字）	700	跟踪器刷新前的去抖动时间窗口

测试

npm test
npm run test:demo
npm run test:all

Context+ 快速上手指南

Context+ 是一个专为大规模工程设计的 MCP（Model Context Protocol）服务器。它结合 RAG、Tree-sitter AST 分析、谱聚类和 Obsidian 风格的链接技术，将庞大的代码库转化为可搜索、分层级的特征图谱，旨在为开发者提供 99% 准确率的语义智能支持。

环境准备

在开始之前，请确保满足以下系统要求和前置依赖：

• 运行时环境：
  • 推荐安装 Bun (性能更优) 或 Node.js (v18+)。
  • 若使用 npx，需确保 npm 已安装。
• 嵌入模型后端 (二选一)：
  • 方案 A (推荐/免费/离线)：安装并运行 Ollama。
    • 需拉取嵌入模型：ollama pull nomic-embed-text
    • 需拉取聊天模型（用于聚类标签）：ollama pull gemma2:27b (或 llama3.2)
  • 方案 B (API/云端)：拥有 OpenAI 兼容的 API Key (如 OpenAI, Google Gemini, Groq 等)。
    • 国内用户推荐使用 Google Gemini (免费层可用) 或国内加速的 OpenAI 兼容接口。
• IDE 支持：
  • 支持配置 MCP 的编辑器，如 Cursor, VS Code, Windsurf, Claude Code 等。

安装步骤

Context+ 无需全局安装，可直接通过 npx 或 bunx 在 IDE 配置中调用，也可生成配置文件。

方式一：自动生成配置文件 (推荐)

在项目根目录或全局配置目录下，运行以下命令自动生成对应 IDE 的 MCP 配置文件：

# 根据你使用的 IDE 选择对应的命令
npx -y contextplus init claude    # 生成 .mcp.json
npx -y contextplus init cursor    # 生成 .cursor/mcp.json
npx -y contextplus init vscode    # 生成 .vscode/mcp.json
npx -y contextplus init windsurf  # 生成 .windsurf/mcp.json
npx -y contextplus init opencode  # 生成 opencode.json

方式二：手动配置

如果自动命令未生效，可手动编辑 IDE 的 MCP 配置文件。

1. 使用 Ollama (本地离线模式)

编辑配置文件 (例如 .cursor/mcp.json 或 .vscode/mcp.json)：

{
  "mcpServers": {
    "contextplus": {
      "command": "bunx",
      "args": ["contextplus"],
      "env": {
        "OLLAMA_EMBED_MODEL": "nomic-embed-text",
        "OLLAMA_CHAT_MODEL": "gemma2:27b",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY" 
      }
    }
  }
}

注：若使用 npx，请将 command 改为 "npx"，args 改为 ["-y", "contextplus"]。本地 Ollama 通常不需要 API Key，除非连接 Ollama Cloud。

2. 使用 Google Gemini (免费 API 模式)

适合没有本地 GPU 资源的开发者。需在 Google AI Studio 获取 Key。

{
  "mcpServers": {
    "contextplus": {
      "command": "npx",
      "args": ["-y", "contextplus"],
      "env": {
        "CONTEXTPLUS_EMBED_PROVIDER": "openai",
        "CONTEXTPLUS_OPENAI_API_KEY": "YOUR_GEMINI_API_KEY",
        "CONTEXTPLUS_OPENAI_BASE_URL": "https://generativelanguage.googleapis.com/v1beta/openai",
        "CONTEXTPLUS_OPENAI_EMBED_MODEL": "text-embedding-004",
        "CONTEXTPLUS_OPENAI_CHAT_MODEL": "gpt-4o-mini"
      }
    }
  }
}

基本使用

配置完成后，重启你的 IDE 或重新加载窗口以激活 MCP 服务器。你可以在 AI 助手对话框中直接使用以下自然语言指令调用工具功能：

1. 探索代码结构

询问代码库的整体架构或特定文件的功能表面：

"展示当前项目的结构树，包含文件和符号范围。" (触发工具：get_context_tree)

"生成 src/utils 目录下所有文件的骨架，只显示函数签名和类型定义。" (触发工具：get_file_skeleton)

2. 语义搜索与导航

不再依赖精确文本匹配，而是通过含义查找代码：

"查找处理用户登录验证逻辑的所有函数。" (触发工具：semantic_code_search)

"浏览代码库，将语义相关的文件分组并展示集群标签。" (触发工具：semantic_navigate)

3. 影响分析与静态检查

在修改代码前评估风险：

"如果我修改了 UserService 类，会影响哪些文件和行？" (触发工具：get_blast_radius)

"运行静态分析，找出项目中未使用的变量和死代码。" (触发工具：run_static_analysis)

4. 安全写入与回滚

Context+ 提供了独特的“影子恢复点”机制，确保 AI 写代码的安全：

"重构 auth.ts 文件以优化性能。" (触发工具：propose_commit - 写入前会创建恢复点)

"撤销上一次 AI 对 auth.ts 的更改。" (触发工具：undo_change - 不影响 Git 历史，仅恢复文件状态)

5. 终端直接查看 (CLI)

你也可以直接在终端查看项目结构，无需启动 IDE：

# 查看项目结构树
bunx contextplus tree ./src

# 查看特定文件的骨架
bunx contextplus skeleton ./src/main.ts

---

提示：首次运行时，Context+ 会在 .mcp_data/ 目录构建嵌入缓存，这可能需要几分钟时间，取决于项目大小。后续操作将显著加速。