内容
# Ceph 分析器 MCP 服务器
用于分析 Ceph 分布式存储系统代码库的综合模型上下文协议（MCP）服务器。该服务器提供双模式访问：本地仓库分析用于快速、详细的代码探索，GitHub API 集成用于访问全局 `ceph/ceph` 仓库。
## 功能
### 双模式操作
**本地仓库分析**（快速，离线）
- 支持正则表达式的深度代码搜索
- 符号定义和引用跟踪
- 代码流跟踪
- Git 历史分析
- 文件系统探索
**GitHub API 集成**（始终保持最新）
- 在全局 ceph/ceph 仓库中搜索代码
- 直接从 GitHub 读取文件
- 访问最新的提交历史
- 搜索和分析拉取请求
### 可用工具
#### 本地仓库工具
1. **搜索 Ceph 代码** - 在本地仓库中搜索代码模式
- 支持纯文本和正则表达式模式
- 返回文件路径、行号和上下文
- 可配置的文件模式过滤（例如 `*.py`、`*.cc`）
2. **读取 Ceph 文件** - 读取文件内容并显示行号
- 可选指定大文件的行范围
- 强制执行合理的文件大小限制（最大 1MB）
3. **查找符号定义** - 查找符号的定义位置
- 搜索函数、类和结构体
- 返回文件路径、行号和上下文
- 支持 Python、C 和 C++ 代码
4. **查找符号引用** - 查找符号的所有引用
- 定位函数、类或变量的所有用法
- 返回文件路径、行号和上下文
5. **跟踪代码流** - 跟踪代码的执行流
- 分析从入口点开始的函数调用
- 返回具有可配置深度的调用树（最大 5 级）
- 帮助理解代码库中功能的流程
6. **列出 Ceph 文件** - 列出目录中的文件
- 探索代码库结构
- 可选模式过滤
- 返回文件/目录信息
7. **获取 Git 日志** - 从本地仓库获取 Git 提交历史
- 查看文件或目录的提交历史
- 返回提交哈希、作者、日期和消息
- 可配置结果数量（最大 100）
#### GitHub API 工具
8. **搜索 GitHub 代码** - 在全局 ceph/ceph 仓库中搜索代码
- 返回文件路径、URL 和相关性得分
- 支持文件扩展名过滤
9. **获取 GitHub 文件** - 从 GitHub 读取文件
- 访问 ceph/ceph 仓库中的任何文件
- 指定分支或提交引用
- 返回内容和行号
10. **获取 GitHub 提交记录** - 从 GitHub 获取提交历史
- 访问全局仓库的最新提交
- 按文件或目录路径过滤
- 返回提交详细信息和 URL
11. **搜索 GitHub 拉取请求** - 搜索拉取请求
- 通过标题或描述查找拉取请求
- 返回拉取请求详细信息、状态和 URL
- 按最近更新排序
## 安装
### 先决条件
- Node.js 16 或更高版本
- TypeScript 5 或更高版本
- Git 已安装并可在 PATH 中使用
- （可选）用于本地分析功能的本地 Ceph 仓库克隆
- （可选）用于更高 API 请求限制的 GitHub 个人访问令牌
### 平台兼容性
**✅ 完全支持（Windows、macOS、Linux）：**
- 所有 GitHub API 工具（search_github_code、get_github_file、get_github_commits、search_github_prs）
- 文件读取（read_ceph_file）
- 目录列表（list_ceph_files）
- Git 历史记录（get_git_log）
**⚠️ 仅限 Unix/Linux/macOS：**
- 本地代码搜索（search_ceph_code）- 需要 `grep`
- 符号查找（find_symbol_definition、find_symbol_references）- 需要 `grep`
- 代码流跟踪（trace_code_flow）- 依赖于符号查找
**Windows 用户：**
- 所有 GitHub API 功能在 Windows 上完美运行
- 对于本地仓库工具，请安装 [Git for Windows](https://git-scm.com/download/win)（包含 Git Bash 和 `grep`）或 [WSL](https://docs.microsoft.com/en-us/windows/wsl/install)
- 或者，仅使用 GitHub API 工具，它们提供对全局 ceph/ceph 仓库的完全访问
### 设置
1. **克隆或导航到 MCP 服务器目录：**
```bash
cd /path/to/your/mcp/servers/ceph-analyzer
```
2. **安装依赖项：**
```bash
npm install
```
3. **构建服务器：**
```bash
npm run build
```
4. **在 MCP 设置文件中配置 MCP 服务器：**
**macOS/Linux：** `~/.bob/settings/mcp_settings.json`
**Windows：** `%USERPROFILE%\.bob\settings\mcp_settings.json`
**macOS/Linux 配置：**
```json
{
"mcpServers": {
"ceph-analyzer": {
"command": "node",
"args": ["/absolute/path/to/ceph-analyzer/build/index.js"],
"env": {
"CEPH_REPO_PATH": "/path/to/your/ceph/repository",
"GITHUB_TOKEN": "your-github-token-here"
},
"disabled": false,
"alwaysAllow": [],
"disabledTools": []
}
}
}
```
**Windows 配置：**
```json
{
"mcpServers": {
"ceph-analyzer": {
"command": "node",
"args": ["C:\\Users\\YourUsername\\path\\to\\ceph-analyzer\\build\\index.js"],
"env": {
"CEPH_REPO_PATH": "C:\\Users\\YourUsername\\path\\to\\ceph",
"GITHUB_TOKEN": "your-github-token-here"
},
"disabled": false,
"alwaysAllow": [],
"disabledTools": []
}
}
}
```
**重要：**
- 用实际路径替换路径
- **Windows：** 在路径中使用双反斜杠 (`\\`) 或正斜杠 (`/`)
- **macOS/Linux：** 在路径中使用正斜杠 (`/`)
- `GITHUB_TOKEN` 是可选的，但建议使用它以获得更高的 API 请求限制
- Node.js 必须安装并在系统 PATH 中可用
5. **重启 Bob** 以加载 MCP 服务器
### 环境变量
- `CEPH_REPO_PATH` - 本地 Ceph 仓库的路径（本地工具需要）
- 示例：`/home/user/projects/ceph` 或 `~/dev/ceph`
- `GITHUB_TOKEN` - （可选）用于更高 API 请求限制的 GitHub 个人访问令牌
- 没有令牌：60 请求/小时
- 有令牌：5000 请求/小时
### 获取 GitHub 令牌（可选）
对于更高的 API 请求限制，请创建一个 GitHub 个人访问令牌：
1. 访问 https://github.com/settings/tokens
2. 点击“生成新令牌” → “生成新令牌（经典）”
3. 为其命名（例如，“Ceph 分析器 MCP”）
4. 选择作用域：`public_repo`（用于公共仓库访问）
5. 点击“生成令牌”
6. 复制令牌并将其添加到您的 MCP 设置中
**注意：** 服务器在没有令牌的情况下工作，但请求限制较低（60 请求/小时 vs 5000 请求/小时且有身份验证）。
## 用法
### 与 Bob 一起使用
配置完成后，您可以使用自然语言命令：
- “Ceph 仓库的最新提交是什么？”
- “在代码库中搜索 OSDMap”
- “查找实现审计数据库的拉取请求”
- “显示 handle_command 的定义”
- “跟踪 handle_osd_map 的代码流”
### 直接工具用法示例
#### 搜索代码模式
```typescript
use_mcp_tool("ceph-analyzer", "search_ceph_code", {
"pattern": "OSDMap",
"file_pattern": "*.cc"
})
```
#### 从 GitHub 获取最新提交记录
```typescript
use_mcp_tool("ceph-analyzer", "get_github_commits", {
"max_count": 20
})
```
#### 搜索拉取请求
```typescript
use_mcp_tool("ceph-analyzer", "search_github_prs", {
"query": "audit database"
})
```
#### 从 GitHub 读取文件
```typescript
use_mcp_tool("ceph-analyzer", "get_github_file", {
"file_path": "README.md",
"ref": "main"
})
```
#### 查找符号定义
```typescript
use_mcp_tool("ceph-analyzer", "find_symbol_definition", {
"symbol": "handle_osd_map"
})
```
#### 跟踪代码流
```typescript
use_mcp_tool("ceph-analyzer", "trace_code_flow", {
"entry_point": "handle_command",
"max_depth": 3
})
```
## 测试
运行测试套件以验证所有工具是否正确工作：
```bash
node test-server.js
```
测试套件验证：
- 本地仓库工具（文件列表、代码搜索、git 日志）
- GitHub API 工具（代码搜索、提交记录、拉取请求、文件读取）
- 响应格式和数据验证
## 限制和安全性
服务器强制执行合理的限制以确保性能和安全性：
- **最大搜索结果**：每个查询 50 个
- **最大文件大小**：1MB
- **每文件最大行数**：10,000
- **最大跟踪深度**：5 级
- **最大 git 日志条目**：100
- **GitHub API 请求限制**：60/小时（未经身份验证）或 5000/小时（已身份验证）
## 开发
### 项目结构
```
ceph-analyzer/
├── src/
│ └── index.ts # 主要服务器实现
├── build/ # 编译的 JavaScript 输出
├── package.json # 项目依赖项和脚本
├── tsconfig.json # TypeScript 配置
├── test-server.js # 测试套件
└── README.md # 此文件
```
### 构建
```bash
npm run build
```
### 开发过程中监视更改
```bash
npm run watch
```
### 添加新工具
1. 将工具定义添加到 `tools` 数组
2. 在 `CallToolRequestSchema` 处理程序中实现工具处理程序
3. 添加验证逻辑
4. 使用用法示例更新此 README
5. 将测试添加到 `test-server.js`
## 故障排除
### “Ceph 仓库未找到”错误
- 验证 `CEPH_REPO_PATH` 指向有效的 git 仓库
- 确保路径存在并包含 `.git` 目录
### GitHub API 请求限制错误
- 添加 `GITHUB_TOKEN` 到您的 MCP 设置
- 等待请求限制重置（错误消息中显示）
### “命令失败”错误
- 确保 git 已安装并可在 PATH 中使用
- 检查您的系统上是否可用 `grep`
- 验证 Ceph 仓库的文件权限
### 服务器未在 Bob 中显示
- 检查服务器是否正确配置在 `~/.bob/settings/mcp_settings.json`
- 验证构建输出是否存在于指定路径
- 在配置更改后重启 Bob
- 检查 Bob 的日志中是否有错误消息
## 贡献
为此 MCP 服务器贡献时：
1. 遵循现有的代码风格
2. 为新功能添加测试
3. 更新文档
4. 确保在提交前所有测试都通过
## 许可证
ISC
## 鸣谢
为分析 Ceph 分布式存储系统代码库而创建。集成了本地仓库和 GitHub API 以实现全面的代码分析功能。
