AI导哈

语义代码索引服务器

基于Python的高端MCP服务器，提供本地语义记忆和代码索引功能，帮助AI助手突破上下文窗口限制。

  • by maschmann
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 maschmann/mcp-context-memory

使用说明

语义项目大脑MCP服务器

一个基于Python的高端MCP（模型上下文协议）服务器，提供本地语义内存和代码索引器。使用 tree-sitter 用于基于AST的源代码解析，以理解类定义、方法签名和结构，而不是简单的文本分块。它还充当“长期记忆”，通过在会话中持久化架构决策，帮助AI助手绕过上下文窗口限制。

服务器使用 ChromaDB 用于快速、本地嵌入存储，并将其数据存储在 .context_db 当前项目目录中的文件夹。

先决条件

你需要 紫外线 安装后，无需手动管理虚拟环境即可运行服务器。

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

可用工具

服务器提供三个MCP工具：

  1. index_project(path: str = ".")：扫描目录，使用AST（Python、Java、PHP、TS、JS、HTML）从语义上解析代码，并对其进行索引。默认为当前目录。
  2. search_context(query: str)：对AST节点和过去的项目决策进行统一搜索。
  3. remember_decision(topic: str, context: str)：保存手动架构注释或推理（例如，“我们为什么选择框架X”）。

使用AI助手

您可以使用 uvx （部分 uv)直接从PyPI运行此服务器。这是使用语义项目大脑的推荐方式，因为它会自动处理所有依赖关系。

Claude桌面集成

要在Claude Desktop中安装和使用此MCP服务器，请将以下内容添加到您的 claude_desktop_config.json:

{
  "mcpServers": {
    "semantic-brain": {
      "command": "uvx",
      "args": ["mcp-context-memory"],
      "alwaysAllow": [
        "index_project",
        "search_context",
        "remember_decision"
      ]
    }
  }
}

光标集成

在光标中，转到 设置>功能>MCP 并添加新的MCP服务器：

  • 姓名： 语义大脑
  • 类型： command
  • 命令： uvx mcp-context-memory

启动现有项目

为了在现有代码库中充分利用语义项目大脑，请按照以下步骤为其添加相关上下文：

  1. 初始语义索引: 运行索引工具来构建代码的初始AST映射： index_project(path=".") 这使大脑能够立即理解你的类、方法和结构化HTML。

  2. 捕获核心架构: 使用 remember_decision 记录项目的基本“为什么”。初次参赛的优秀候选人包括：

    • 技术栈选择: remember_decision(topic="Tech Stack", context="We use Symfony 7 with PHP 8.3 because...")
    • 数据库模式: remember_decision(topic="Data Model", context="The 'Orders' table is partitioned by year to handle high volume...")
    • 身份验证流程: remember_decision(topic="Auth", context="JWT tokens are handled via LexikJWTAuthenticationBundle with a 1-hour TTL...")

  3. 索引文档: 如果你有现有 DOCS.md 或 ARCHITECTURE.md 文件，您可以将其关键见解复制粘贴到 remember_decision 使它们与代码一起在语义上可搜索。

  4. 验证: 通过问一个问题来测试大脑的“记忆” search_context(query="How is authentication handled?")。如果它返回您存储的决策，它已准备好提供帮助。

人工智能代理说明（Agents.md）

复制以下块并将其粘贴到项目的 .cursorrules, AGENTS.md，或 GEMINI.md 指示LLM如何使用此服务器：

# Semantic Project Brain Usage Guidelines

You have access to the `semantic-brain` MCP server. Follow these rules rigorously:

1. **Re-indexing:** 
   - If you make significant structural changes (e.g., creating a new module, renaming classes, or refactoring), you MUST trigger `index_project(path=".")` when you finish to keep the AST index up to date.
   - If you cannot find expected code in `search_context`, trigger an index update first.

2. **Understanding the Codebase:**
   - Use `search_context(query="ClassName")` to understand class hierarchies, locate method definitions, and retrieve precise semantic chunks of code instead of grepping the entire workspace.

3. **Remembering Decisions:**
   - Before completing a task that involved a notable architectural decision, tradeoff, or complex logic, you are OBLIGATED to call `remember_decision(topic="...", context="...")`.
   - Store "Why" something was built a certain way, so you and other agents can retrieve it in future sessions using `search_context`.

相关 MCP