内容
# C++ MCP 服务器
用于分析 C++ 代码库的 MCP（模型上下文协议）服务器，使用 libclang。
## 关于此分支
该项目是 [kandrwmrtn/cplusplus_mcp](https://github.com/kandrwmrtn/cplusplus_mcp) 的一个分支。主要目标是添加对 `compile_commands.json` 描述的项目的支持。
**⚠️ 开发状态**：该 MCP 服务器目前正在积极开发中，**不适合生产使用**。请自行承担风险。
**平台支持**：该服务器主要在 **Linux 和 macOS** 上开发和测试。虽然 Windows 支持可能有效，但它不是开发的主要关注点。
## 为什么使用它？
与其让 AI 代理在 C++ 代码库中进行 grep 搜索以了解结构，不如使用该服务器提供代码的语义理解。代理可以立即找到类、函数及其关系，而无需在数千个文件中迷失。它了解 C++ 语法、继承层次和调用图，使 AI 代理能够像 IDE 一样导航代码库。
**注意**：这些工具主要用于与较弱的 LLM 模型一起使用，这些模型在本地运行（例如，通过 LM Studio 或 Ollama），以帮助它们理解复杂的代码库，但它们与 Claude 3.5 Sonnet 或 GPT-4o 等前沿模型同样有效。
## 功能
整合的 C++ 代码分析工具（从多个独立工具统一）：
- **设置项目** - 必需的第一步：设置项目目录或配置文件，并等待索引完成。
- **同步项目** - 检查系统状态或触发增量/完整项目刷新。
- **按模式查找符号** - 通过名称模式发现类和函数，并带有命名空间和文件过滤器。
- **在文件中查找** - 列出在特定文件中定义的所有符号。
- **获取类信息** - 获取详细的类信息（方法、成员、继承）。
- **获取类层次结构** - 获取类的完整继承层次结构（祖先、后代或两者）。
- **获取类型别名信息** - 解析类型别名（`using`、`typedef`）和模板别名。
- **查找输出调用** - 查找特定函数调用的函数（被调用者）。
- **查找输入调用** - 查找调用特定函数的函数（调用者）。
- **跟踪执行路径** - 查找两个函数之间的执行路径（调用链）。
**限定名称支持**：
- **命名空间感知搜索**：按限定模式搜索，如 `"ui::View"`、`"app::Database::save"`。
- **模板特化检测**：区分 `template<> void foo<int>()` 和通用 `template<typename T> void foo(T)`。
- **消歧义**：所有结果都包含 `qualified_name` 和 `namespace` 字段。
**附加功能**：
- **自动头文件分析**：项目头文件在被源文件包含时自动分析。
- **智能重复数据删除**：头文件仅处理一次以优化性能。
- **增量分析**：检测更改并仅重新分析受影响的文件（速度快 30-300 倍）。
- **错误恢复**：即使在文件出现非致命解析错误时，也能提取符号。
## 传输协议
服务器支持多种传输协议：
### 标准输入/输出（默认）
用于 MCP 客户端集成的标准输入/输出传输（Claude Desktop 等）：
```bash
python -m mcp_server
```
### HTTP（可流式 HTTP）
用于 API 访问的 RESTful HTTP 传输：
```bash
python -m mcp_server --transport http --host 127.0.0.1 --port 8000
```
### SSE（服务器发送事件）
用于事件驱动应用程序的实时流式传输：
```bash
python -m mcp_server --transport sse --host 127.0.0.1 --port 8000
```
有关 HTTP/SSE 使用的详细信息，请参见 **[HTTP_USAGE.md](docs/HTTP_USAGE.md)**
## 先决条件
- Python 3.10 或更高版本
- pip（Python 包管理器）
- Git（用于克隆存储库）
- LLVM 的 libclang（设置脚本将尝试下载便携式构建）
## 设置
1. 克隆存储库：
```bash
git clone https://github.com/andreymedv/clang_index_mcp.git
cd clang_index_mcp
```
2. 运行设置脚本：
- **Linux/macOS**：
```bash
./server_setup.sh
```
- **Windows**：
```bash
server_setup.bat
```
3. 测试安装：
```bash
source mcp_env/bin/activate # Linux/macOS
python scripts/test_installation.py
```
## 性能优化
分析器针对多核系统的性能进行了优化。
### 可选依赖项
对于大型项目，安装 `orjson` 以实现 3-5 倍更快的 JSON 解析：
```bash
pip install .[performance]
```
### 自动优化
1. **GIL 绕过**：使用 `ProcessPoolExecutor` 实现真正的并行解析。
2. **二进制缓存**：解析的 `compile_commands.json` 和符号被缓存，以便快速后续启动。
3. **智能增量分析**：检测更改时仅重新分析受影响的文件。
## 客户端配置
此 MCP 服务器可与各种 AI 编码助手和 IDE 一起使用。有关详细说明，请参见 **[CLIENT_SETUP.md](CLIENT_SETUP.md)**：
- Claude Desktop / Claude Code
- Cursor / Windsurf
- Cline / Continue
### 通用 CLI 代理配置
要将其与 MCP 兼容的 CLI 代理一起使用，请将服务器添加到您的配置中：
```json
{
"mcpServers": {
"cpp-analyzer": {
"command": "python",
"args": ["-m", "mcp_server"],
"cwd": "/absolute/path/to/clang_index_mcp",
"env": {
"PYTHONPATH": "/absolute/path/to/clang_index_mcp"
}
}
}
}
```
## 与 AI 代理一起使用
配置完成后，您可以在对话中使用 C++ 分析器：
1. 首先，设置您的项目目录：
```
"将项目目录设置为 /path/to/your/cpp/project"
```
2. 然后，您可以提问：
- "查找所有包含 'Actor' 的类"
- "显示我 Component 类的详细信息"
- "查找所有调用 Update() 的函数"
- "Render() 调用哪些函数？"
- "显示 GameObject 的继承层次"
## 配置选项
服务器行为通过 `.json` 配置文件进行配置。您必须在初始化项目时提供此文件的路径。
服务器从以下位置加载配置：
1. 传递给 `set_project` 工具的路径（推荐）。
2. 由 `CPP_ANALYZER_CONFIG` 环境变量指定的路径。
### 示例配置
```json
{
"project_root": "/path/to/source",
"exclude_directories": [".git", "build", "node_modules"],
"include_dependencies": true,
"max_workers": null,
"query_behavior": "allow_partial",
"compile_commands": {
"enabled": true,
"path": "compile_commands.json"
}
}
```
### 关键选项
- **project_root**：（可选）指定相对于配置文件源根目录。这允许将配置文件放在源树之外。
- **exclude_directories**：在项目扫描期间跳过的文件夹。
- **include_dependencies**：是否分析依赖目录中的文件（例如 `third_party`）。
- **max_workers**：工作进程数（默认值：`null` = 使用所有 CPU 核心）。
- **query_behavior**：`allow_partial`（在索引期间返回结果）、`block`（等待索引）或 `reject`。
- **compile_commands**：配置 `compile_commands.json` 集成的路径和行为。
**有关 `compile_commands.json` 集成的详细信息，请参见 [COMPILE_COMMANDS_INTEGRATION.md](docs/COMPILE_COMMANDS_INTEGRATION.md)**
## 故障排除
### 常见问题
1. **"libclang not found" 错误**
- 运行设置脚本以自动下载 libclang，或将 `LIBCLANG_PATH` 环境变量设置为您的 `libclang.so`/`.dylib`/`.dll` 的路径。
2. **服务器无法启动**
- 确保已安装 Python 3.10+，并且 `requirements.txt` 中的所有依赖项都可用。
3. **解析警告与致命错误**
- 分析器会从具有语法错误的 文件中提取尽可能多的信息。如果文件致命失败，请检查其在 `compile_commands.json` 中的条目或运行 `python scripts/diagnose_parse_errors.py`。
