MCP Context Graph

MCP上下文图

一个独立的、内存中的AI代理图形数据库。通过模型上下文协议（MCP）提供语义代码理解。

为什么是这个工具？

人工智能编码助手经常在处理大型代码库时遇到困难。他们要么：

• 读取整个文件（代价高昂，达到上下文限制）
• 搜索文本（缺少语义关系）
• 无法追踪函数的调用来源

MCP上下文图通过构建代码库的语义图来解决这个问题 AI能够高效地进行查询。

关键差异化因素

运作原理

Your Codebase                    MCP Context Graph                AI Agent
     |                                  |                              |
     |  ──── tree-sitter parse ────>    |                              |
     |                                  |                              |
     |   [caller1, caller2] ───> |
     |                                  |                              |
     |                                  |   exact original code ─>  |

AI无需加载整个文件即可快速进行语义查询。当它需要完整的源代码时，它可以使用源映射扩展特定的符号。

特性

• Polyglot支持：使用树形图解析Python、TypeScript和JavaScript
• 源地图：用于精确上下文提取的令牌级来源
• 懒惰摄入：文件按需索引并自动刷新
• 零配置：通过以下方式立即工作 uvx 存在合理的违约

安装

主要方法（推荐）

无需安装。直接与 uvx:

uvx mcp-context-graph /path/to/your/project

替代方案：通过pip/uv安装

# Using uv
uv pip install mcp-context-graph

# Using pip
pip install mcp-context-graph

如何使用

MCP上下文图作为人工智能助手可以连接的MCP服务器运行。在MCP客户端中配置它：

A.临床（VS代码）

添加到您的Cline MCP设置(cline_mcp_settings.json):

{
  "mcpServers": {
    "context-graph": {
      "command": "uvx",
      "args": ["mcp-context-graph", "."],
      "autoApprove": []
    }
  }
}

这 . 参数使用当前工作区目录作为项目根目录。

B.克劳德桌面

添加到您的Claude Desktop配置(claude_desktop_config.json):

{
  "mcpServers": {
    "context-graph": {
      "command": "uvx",
      "args": ["mcp-context-graph", "/absolute/path/to/your/project"]
    }
  }
}

备注：Claude Desktop需要绝对路径。相对路径，如 . 将无法正常工作。

可用工具

连接后，AI代理可以使用以下工具：

工作流示例

1. AI对项目进行索引：

   index_project()

1. AI找到一个函数定义：

   find_symbol(name="calculate_tax", include_calls=true)

1. AI探索了什么叫这个函数：

   find_callers(name="calculate_tax")

1. AI获得了更广泛的背景（2个层次的连接）：

   get_context(name="calculate_tax", depth=2, format="markdown")

1. AI展开特定符号以查看完整源代码：

   expand_source(symbol_id="abc123")

来源地图：秘密酱汁

大多数代码索引器存储以下内容之一：

• 完整源代码（昂贵）
• 仅符号名称（失去上下文）

MCP上下文图存储 缩小签名 和 字符精确源映射:

# Original (45 bytes)
def calculate_tax(amount: float, rate: float) -> float:
    """Calculate tax for the given amount."""
    return amount * rate

# Stored signature (minified)
def calculate_tax(amount: float, rate: float) -> float: ...

# Source map
Segment(minified: 0-52, original: 0-52)  # signature preserved exactly

当AI需要完全实现时， expand_source 将缩小的偏移量映射回原始文件，并返回精确的源代码。

基准测试

基准结果

成本效益（每1000次通话美元）

*通过OpenRouter API的代币计数（精确）*

关键要点：

• AI可以与 小14倍 代码库的表示
• 查询已完成 微秒，而不是秒
• 节省91-93%的成本 所有主要LLM提供商的上下文令牌使用情况
• 完整源代码始终可通过源代码映射按需提供

在您自己的项目上运行基准测试：

OPENROUTER_API_KEY=your-key uv run python benchmarks/run_benchmarks.py /path/to/project

CLI使用情况

# Index current directory
uvx mcp-context-graph .

# Index a specific project
uvx mcp-context-graph /path/to/project

# Show version
uvx mcp-context-graph --version

发展

先决条件

• Python 3.12+
• 紫外线 包管理器

设置

# Clone the repository
git clone https://github.com/padobrik/mcp-context-graph.git
cd mcp-context-graph

# Install dependencies
uv sync

# Run tests
uv run pytest tests/

# Run linting
uv run ruff check .

# Run type checking
uv run mypy src/

项目结构

src/mcp_context_graph/
  core/           # Graph data structures (Node, Edge, Graph)
  ingest/         # File parsing and graph construction
  languages/      # Language-specific configurations (Python, TypeScript)
  mcp/            # MCP server and tool handlers
  provenance/     # Source map implementation

许可证

MIT许可证。看 许可证 了解详情。