Semantic Context Mcp

中文

🚀 概览

Semantic Context MCP Server 是一个模型上下文协议（MCP）服务，利用向量数据库高效地为代码库建立索引并执行语义搜索。

它会智能地将代码解析为结构化代码块（如函数和类），将其转换为向量嵌入，并存储在本地向量数据库中。这样，你就可以通过自然语言查询找到语义相关的代码片段，而不仅仅依靠关键词匹配。

该服务在后台运行，自动跟踪文件变更并增量更新索引，确保代码上下文始终保持最新。

✨ 功能特性

• 增量索引：使用 Merkle 树检测文件变更，确保仅重新索引已修改的文件，从而提高效率。
• 多语言支持：采用 AST（抽象语法树）解析，支持多种语言，包括 Python、Java、C++、JavaScript、TypeScript 和 Go。
• 语义代码搜索：根据含义和上下文查找代码，而不仅仅依靠关键词。
• 后台自动化：自动执行首次完整索引，之后每 5 分钟定期执行增量更新。
• 简单的 MCP 接口：提供易于使用的工具（full_index、status、query），以便与其他系统集成。
• 本地优先：所有数据（向量数据库、索引元数据）都存储在用户主目录（~/.chromadb）中。

🛠️ 工作原理

1. 检测变更：根据文件内容哈希构建 Merkle 树，以便快速识别新增、修改或删除的文件。
2. 解析代码：使用 AST 解析器解析变更文件，提取有意义的代码块（函数、类等）。
3. 生成嵌入：使用嵌入模型（例如 Jina、OpenAI）将提取的代码块转换为数值表示（向量嵌入）。
4. 存储到向量数据库：将这些嵌入及相关元数据存储在本地 ChromaDB 实例中。
5. 查询：收到查询后，将其转换为嵌入，并在向量数据库中查找最相似的代码块。

📂 项目结构

.
├── vector_search/
│   ├── ast_parser.py          # Smart AST parser for multiple languages
│   ├── code_change_tracker.py # Detects file changes using a Merkle Tree
│   ├── code_indexer.py        # Main logic for incremental and full indexing
│   ├── fast_mcp_server.py     # The MCP server exposing the tools
│   └── vector_db.py           # Vector database manager (ChromaDB wrapper)
├── LICENSE
├── README_zh.md
└── README.md

⚙️ 前置条件

• Python 3.8+
• 用于生成嵌入的 OpenAI 兼容 API。你需要设置以下环境变量：

  export OPENAI_API_KEY="your_api_key"
  export OPENAI_BASE_URL="your_api_base_url"
  export OPENAI_MODEL_NAME="your_embedding_model_name"
  

📦 安装

1. 克隆仓库：

   git clone https://github.com/zishengwu/semantic-context-mcp
   cd semantic-context-mcp
   

🚀 使用方法

1. 在 IDE 中配置 MCP JSON file：

    {
  "mcpServers": {
    "Semantic Context MCP Server": {
      "command": "fastmcp",
      "args": [
        "run",
        "your_code_base/semantic-context-mcp/vector_search/fast_mcp_server.py:mcp"
      ],
      "env": {
        "OPENAI_API_KEY": "your_api_key",
        "OPENAI_BASE_URL": "your_api_base_url",
        "OPENAI_MODEL_NAME": "your_embedding_model_name"
      }
    }
  }
}

尽情使用！👏