代码上下文 MCP 服务器

这是一个基于模型上下文协议（MCP）的服务器，用于从本地 Git 仓库中提取代码上下文。该服务器提供以下功能：

在本地克隆 Git 仓库
处理分支和文件
为代码块生成嵌入向量
执行代码的语义搜索

功能特点

使用本地 Git 仓库而非 GitHub API
数据存储在 SQLite 数据库中
将代码分割为语义相关的代码块
使用 Ollama 为代码块生成嵌入向量
提供代码的语义搜索功能

前提条件

Node.js（v16 或更高版本）
Git
安装了嵌入模型的 Ollama

安装步骤

# 克隆代码仓库
git clone <仓库地址>
cd code-context-mcp

# 安装依赖项
npm install

# 构建项目
npm run build

配置说明

设置以下环境变量：

DATA_DIR：SQLite 数据库目录（默认：'~/.codeContextMcp/data'）
REPO_CACHE_DIR：克隆仓库的存储目录（默认：'~/.codeContextMcp/repos'）

使用 Ollama

为了获得更快、更强大的嵌入向量，可以使用 Ollama：

# 从 https://ollama.ai/ 安装 Ollama

# 拉取一个嵌入模型（推荐使用 unclemusclez/jina-embeddings-v2-base-code）
ollama pull unclemusclez/jina-embeddings-v2-base-code

使用方法

与 Claude Desktop 配合使用

在你的 Claude Desktop 配置文件（claude_desktop_config.json）中添加以下配置：

{
  "mcpServers": {
    "code-context-mcp": {
      "command": "/path/to/your/node",
      "args": ["/path/to/code-context-mcp/dist/index.js"]
    }
  }
}

提供的工具

该服务器提供以下工具：

queryRepo

克隆仓库、处理代码并执行语义搜索：

{
  "repoUrl": "https://github.com/username/repo.git",
  "branch": "main", // 可选 - 默认使用仓库的默认分支
  "query": "你的搜索查询",
  "keywords": ["关键词1", "关键词2"], // 可选 - 按关键词过滤结果
  "filePatterns": ["**/*.ts", "src/*.js"], // 可选 - 按通配符模式过滤文件
  "excludePatterns": ["**/node_modules/**"], // 可选 - 按通配符模式排除文件
  "limit": 10 // 可选 - 返回的结果数量，默认为 10
}

branch 参数是可选的。如果不提供，工具将自动使用仓库的默认分支。

keywords 参数是可选的。如果提供，结果将被过滤，只包含包含至少一个指定关键词的代码块（不区分大小写匹配）。

filePatterns 和 excludePatterns 参数是可选的。它们允许你使用通配符模式（例如 **/*.ts 表示所有 TypeScript 文件）来过滤要处理和搜索的文件。

数据库结构

服务器使用 SQLite 数据库，其结构如下：

repository：存储仓库信息
branch：存储分支信息
file：存储文件信息
branch_file_association：关联文件与分支
file_chunk：存储代码块及其嵌入向量

调试

Mac M 系列 - ARM 架构问题

在 Mac M 系列芯片（ARM 架构）上安装 better-sqlite3 时，如果遇到类似 "mach-o file, but is an incompatible architecture (have 'x86_64', need 'arm64e' 或 'arm64')" 的错误，你需要确保二进制文件与你的架构匹配。以下是解决方法：

# 检查你的 Node.js 架构
node -p "process.arch"

# 如果显示 'arm64'，但仍有问题，尝试：
npm rebuild better-sqlite3 --build-from-source

# 或者进行干净安装：
npm uninstall better-sqlite3
export npm_config_arch=arm64
export npm_config_target_arch=arm64
npm install better-sqlite3 --build-from-source

如果你使用 Rosetta，确保你的整个环境是一致的。你的错误表明构建了 x86_64 二进制文件，但你的系统需要 arm64。要持久化配置，请添加到你的 .zshrc 或 .bashrc：

export npm_config_arch=arm64
export npm_config_target_arch=arm64

测试 Ollama 嵌入向量

curl http://localhost:11434/api/embed -d '{"model":"unclemusclez/jina-embeddings-v2-base-code","input":"Llamas are members of the camelid family"}' curl http://127.0.01:11434/api/embed -d '{"model":"unclemusclez/jina-embeddings-v2-base-code","input":"Llamas are members of the camelid family"}' curl http://[::1]:11434/api/embed -d '{"model":"unclemusclez/jina-embeddings-v2-base-code","input":"Llamas are members of the camelid family"}'

许可证

MIT