内容
上下文信号 MCP
[](https://www.npmjs.com/package/context-signals-mcp)
[](https://www.npmjs.com/package/context-signals-mcp)
[](./LICENSE)
> **编码代理的仓库导航压缩层。**
与 Claude Desktop、OpenCode、Cursor/Roo 风格的 MCP 客户端以及任何兼容 MCP 的编码代理一起工作。
上下文信号结构大于代理的即时工作内存时最为有价值。它帮助代理更快地找到正确的代码，并减少不相关的代码阅读。源代码仍然是事实的依据。
代理可以询问： “上传端点在哪里？”
> “哪个函数处理？”
> “此服务中存在哪些路由？”
> “提供者调度在哪里发生？”
并首先获得精确的结构信号。
---
## 问题：导航浪费
编码代理在知道在哪里工作时擅长编辑代码。但发现成本高昂：
1. 语义匹配范围广或部分匹配
2. 打开多个完整文件（每个查询 5-15K 个标记）
3. 将整个文件内容发送到 LLM 进行结构发现
4. 在下一个会话中重复相同的导航，零重用
---
## 方法：结构化信号
一次提取紧凑的代码结构信号，本地存储，并通过 MCP 暴露。代理在读取源文件之前通过元数据导航。
> **之前：** 个文件，40k，8 个搜索循环
> **之后：** 4 个文件，12k 个标记，3 个搜索循环测试显示，在 LiteLLM 上，与 grep 基线相比，上下文减少了 73%。
---
## 快速开始
```bash
npm install -g context-signals-mcp
```
或使用 npx：
```bash
npx context-signals-mcp
```
---
## 提取内容
上下文信号 MCP 构建一个本地信号存储，包含：
- **函数** — 声明头函数、异步、生成器
- **类**具有方法和构造函数信息
- **API 路 — Express、Fastify、Next.js（方法 + 路径 + 处理程序 **React 组件** — 函数-arrow 组件
- **导入/导出** — ESCommonJS、Python/默认
- **接口和类型** — TypeScript 类型别名和接口
- **调用边** — 函数到函数的调用关系（关键区分器）
### 调用边启用多跳导航
大多数代码搜索工具返回扁平的关键字匹配。上下文信号还捕获**谁调用谁**：
```
config.getProvider() → modelRouter() → _provider() → call_openai()
```
这意味着代理库中跟踪请求路径，而无需 grep。搜索“提供”会返回入口点；图边揭示下一个跳转。
信号是一张地图，而不是领土。
源代码仍然是事实的依据。
---
## 真实的导航同一个问题，同一个代码库，两种方法：
> **M 中提供者发生？**
MCP
```
grep "dispatch" → 47 matches, 12 files
open litellm.py (12,340 chars) → finds completion grep "dispatch_to_provider" → provider_dispatcher.py
open provider_dispatcher.py (8,200 chars) → finds dispatch_to_provider
grep "call_openai" → providers/openai.py
open providers/openai.py (6,500 chars) → finds call_openai
```
**5 步，27K 字符读取，2 个 grep 循环**
### 使用上下文信号
```
signals_search "provider dispatch"
→ 返回：
[
{
"kind": "function",
"name": "dispatch_to_provider",
"file": "litellm/provider_dispatcher.py",
"line": 182,
"call_edges": ["call_openai"]
},
{
"kind": "function",
"name": "completion",
"file": "litellm.py "line": 50,
"call_edges": ["dispatch_to_provider"]
},
{
"kind": "function",
"name":_openai",
"file": "providers/openai "line": 120
}
]
→ 信号负载：420 字符
→ 跟随：dispatch_to_provider →
→ 读取ai.py（第 135 行，1,字符）
```
**3 步，2.2K 字符读取，0 grep 循环**
结构化映射（函数、调用边、行号）消除了搜索-读取-重复的循环。信号在扫描时预先提取；代理直接导航。
适用于所有导航查询：函数、类、导入、组件。
---
## 基准测试结果
针对 LiteLLM（统一 LLM API，200+ 文件，Python + TypeScript）进行测试。正在添加更多仓库 - 请参见路线图。
| 项目 | 文件 | 代码大小 | 上下文减少 |
| ------- | --------- | ----------------- |
| LiteLLM | 200--400 | 350K 字符 | 73% |
### 关键指标（v0.7 确定性基线）
| 导航指标 | 结果 | 备注 |
| ----------------- | ------ | ----- |
| 上下 | 73% | 与 LiteLLM 上的 grep 基线相比 |
| 找到事实真相 | 94% 使用上下文信号 | 与 88% grep-only 基线（+6%）相比 |
| 避免打开文件 | 27% 减少 |-only 探索相比 |
| 消除搜索循环 | 2 → 0 | grep 调用替换为 1 个信号搜索 |
| 平衡点 | ~5--15 查询 | 索引成本在 ~10 查询后收回 |
| 检索指标 | 结果 | 备注 |
| ---------------- | ------ | ----- |
| 前 3 名命中率 | 83% | 正确的前 3 名结果 |
| 前 5 名命中率 | 88% | 正确的前 5 名结果 |
| 精确度 | 78% | 相关结果/返回总结果 |
| 召回率 | 85 找到的相关结果/相关结果总数 |
### 基础设施
| 功能 | 状态 |
| ------- | ------ |
| 自动索引 | 是 - 启动时索引 |
| 增量重新索引 | 是 - 仅更改的文件 |
| 存储 | SQLite + JSON（本地） |
| 嵌入式重新排序器 | 可选，默认关闭 |
> **基准测试范围说明 这些结果来自单个项目（LiteLLM）。在单个仓库上的基准测试可能感觉很窄 - 指标可能无法推广到所有代码库。我们正在积极添加更多仓库（Cal.com、LangChain、Supabase、Next.js - 请参见路线图）。结果应被视为方法的证据，而不是通用性能保证。
这些结果主要和发现适用于完整的实现推理。
---
## 最适用的场景信号 MCP 在以下情况下非常有用：
- 项目有 50+ 个文件 代理重复询问“在哪里…”，“查找…”，“显示路由…”
- 代码库是 JavaScript 或 TypeScript
- 代理需要在编辑前定位文件/函数/路由
- 工作流程是长期的，而不是一次性的
---
## 不适用的场景
在以下情况下，这种方法可能没有用：
- 非常
- 一次性问题
- 仅冷启动使用
- 需要读取完整源代码的深度实现推理
- 不支持的结构提取有限的语言
---
## OpenCode 设置
在您的 MCP 配置中添加：
```json
{
"mcp": {
"context-signals": {
"type": "stdio",
"command": "npx",
"args":-signals-mcp"],
"env": {
"WORKTREE": "${PWD }
}
}
}
```
---
## Claude Desktop 设置
添加到：
`~/Library/Application Support/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"context-signals": {
"command": "npx",
"args": ["context-mcp"]
}
}
}
```
---
## 推荐的代理工作流程
1. 启动 MCP 服务器
2. 让它自动索引项目
3. 使用 `signals_search` 询问导航/发现问题
4. 使用返回的文件路径和行号
5. 仅在需要实现详细信息时读取源代码
6. 更改的文件会自动重新索引
---
## 冷启动与热缓存
| 模式 | 发生情况 | 结果 |
| ----------- | ----------------------------- | --------------------------- |
| 冷启动 | 初始索引 | 首次查询可能不会受益 |
| 热缓存 | 信号已索引 | 上下文节省最高 |
| 增量 | 仅重新索引更改的文件 | 更快的更新 |
---
## 语言支持
| 语言 | 状态 | 备注 |
| ---------- | ---------------- | ------------------------- |
| JavaScript | 生产就绪 | AST 提取 |
| TypeScript | 生产就绪 | AST 提取 |
| Python | | 计划原生 Python AST |
| Go | 计划中 | 未来支持 |
| Rust | 计划中 | 未来支持 |
| Java | 计划中 | 未来支持 |
---
## 为什么不使用 RAG？
RAG 对于语义相似性很有用。
上下文信号 MCP 不同。
RAG 询问：
> “哪些代码块与此查询在语义上相似？”
上下文信号询问：
> “哪些结构入口点与此路由、函数、类、组件、导入或文件
它们可以一起工作。
首先使用上下文信号进行导航。
在后面使用 RAG 或源代码读取进行更深入。
---
## - 不会将代码发送到外部服务器
- 信号存储在本地
- 用户控制生成的信号文件
- 设计用于本地编码代理工作流
---
## 当前范围
该项目是一个**仓库导航**编码代理。
它专注于一个狭窄的问题：
**在代码库发现过程中减少不必要的源文件读取。**
它不试图成为：
- 一个完整的语义代码搜索引擎
- LSP品
- 源代码读取的替代品
- 比嵌入式或 RAG 更好
- 一个完整的编码代理内存系统
正确定位：上下文信号是一个定位器和紧凑的内存层。它帮助代理更快地找到正确的代码，并减少不相关的代码读取。
---
## 路线图
### 已完成
- [x] TypeScript/JavaScript AST 提取
- [x] Express、Fastify、Next.js 路由提取器
- [x] React 组件提取
- [x] Python 提取（基于正则表达式 [x] BM25 + 混合搜索与字段提升
- [x] 查询意图检测 + 术语- [x] 基于图的评分（调用边）
- [x] SQLite信号存储
x] 带有文件哈希的增量扫描
- [x] v0.5 确定性基线（冻结）
- [x] v0.7 导航基准测试（94% 找到事实真相）
- [x嵌入式重新排序器（可选，默认关闭）
### 进行中
- [ ] 原生 Python AST（替换正则表达式）
- 框架特定 Djangoask 提取器
- [ ] 可选 LSP 丰富
- [ ] 目标文件/范围读取 MCP 工具
- [ ] 更多仓库的基准测试：Cal.com、LangChain、Supabase、Next.js
- [ ] 与 grep、ripgrep、CodeGraph、RAG 比较
- [ ] v0.8 代理基准测试完成（WSL）
---
## 许可证
MIT
