om-metrics MCP Server

开源社区数据查询 MCP 服务器

为 Claude Desktop 提供开源社区数据查询能力的 Model Context Protocol 服务器

![License: MIT](https://opensource.org/licenses/MIT) ![Python](https://www.python.org/)

</div>

---

🦎 项目简介

om-metrics MCP Server 是一款面向开源社区运营团队和数据分析人员的 MCP 工具，通过 Claude Desktop 提供自然语言查询开源社区数据的能力。

适用人群

| 角色 | 使用场景 | |------|---------| | 社区运营 | 查询社区健康度、PR/Issue 统计、贡献者排行 | | 数据分析师 | 获取社区趋势数据、生成运营报告、制作 PPT | | 开发者 | 查询 CI/CD 指标、仓库活跃度、技术栈分布 | | 管理者 | 跨社区对比分析、企业贡献统计、CLA 签署情况 |

支持的社区

支持 23 个开源社区，包括：

华为开源社区：openEuler、openGauss、openUBMC、CANN
AI 框架：MindSpore、MindIE、MindStudio、MindSpeed、MindSeriesSDK、MindCluster
推理加速：vllm、sgl、VeRL、pytorch、triton
其他项目：openFuyao、PTA、UnifiedBus、CannOpen、TileLang、ascendnpuir、boostkit、opensource

---

✨ 核心功能

📊 社区健康度分析

综合评分：查询社区健康度综合评分（1-5 分）
子指标分析：社区影响力、下载量、Issue 关闭率、PR 合并率等
趋势追踪：按月/周/天统计社区活跃度变化

🔍 PR/Issue 统计

聚合统计：总数、开启数、关闭数、合并数、响应时长、关闭率
按 SIG 分组：各兴趣组的 PR/Issue 分布和处理效率
时间维度：支持按天/周/月查询趋势数据

👥 贡献者分析

企业排行：Top N 企业贡献数量和占比
个人排行：Top N 个人开发者贡献统计
活跃用户：仓库活跃用户列表（PR/Issue/评论数）
组织统计：参与社区的企业/组织数量

📝 CLA 签署查询

签署统计：总签署数、企业签署数、个人签署数
签署趋势：按月/周/天统计签署增长趋势
用户列表：分页查询签署用户详情（支持按类型、姓名、时间筛选和排序）

🚀 CI/CD 指标

运行统计：总运行次数、成功/失败/待处理数、成功率
性能分析：平均运行时长、趋势变化

📦 项目仓库

仓库列表：最近更新的 50 个仓库
热点仓库：最近更新的前 10 个热点仓库
活跃统计：总仓库数、活跃数、非活跃数

---

🚀 快速开始

适合新用户快速安装和配置。开发者详细指南见开发指南。

前置要求

Python 3.8+
Claude Desktop 或 Claude Code CLI
网络连接（需访问 https://datastat.osinfra.cn/server/）

安装步骤

1. 克隆项目

git clone https://github.com/zhongjun2/om-mcp.git
cd om-mcp

2. 安装依赖

pip install -e .

3. 验证安装

python3 -c "from server import mcp; print('安装成功')"

4. 配置 Claude Desktop

在 Claude Desktop 中，项目根目录已包含 .mcp.json 配置文件，会自动识别。

或手动配置全局 MCP 服务器（编辑 ~/.config/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "om-metrics": {
      "command": "python3",
      "args": ["-m", "om-mcp"],
      "cwd": "/完整路径/om-mcp"
    }
  }
}

5. 验证连接

在 Claude Desktop 中运行：

/mcp

应该看到： `` ❯ om-metrics · ✔ connected ``

---

💡 使用方式

在 Claude Desktop 或 Claude Code 中直接用自然语言提问，MCP 工具会自动调用。

基础查询示例

查询 openEuler 社区的健康度评分
openEuler 社区 2025 年的 PR 总数
CANN 社区有多少个参与的企业？
查询 MindSpore 社区最近的热点仓库

趋势分析示例

openEuler 2025 年每月的 PR 合并趋势
MindSpore 社区 2025 年 1-3 月的 Issue 关闭率
openUBMC 社区 2025 年的 CLA 签署趋势

贡献者分析示例

哪些企业对 openEuler 贡献最多？
openEuler 的 Top 10 个人贡献者
CANN 社区最活跃的开发者名单

跨社区对比示例

openEuler 和 CANN 社区的 PR 合并率对比
MindSpore 和 openGauss 的 Issue 关闭率对比
各社区的企业参与数量对比

更多使用示例请参考 FEATURES.md。

---

🛠️ 开发指南

详细的开发者安装指南请参考 INSTALL.md。

环境变量配置

项目需要设置 MAGIC_API_TOKEN 环境变量才能正常工作。

设置方式（推荐）

方式 1：临时设置（当前会话有效）

export MAGIC_API_TOKEN=your_token_here

方式 2：永久设置（写入 Shell 配置）

在 ~/.bashrc 或 ~/.zshrc 中添加：

export MAGIC_API_TOKEN=your_token_here

然后运行： ``bash source ~/.bashrc # 或 source ~/.zshrc ``

验证配置

echo $MAGIC_API_TOKEN  # 应显示你的 token 值

安全提示：

⚠️ 切勿将 .env 或 .envrc 文件提交到 Git 仓库
⚠️ 切勿在代码中硬编码 token
✅ 使用环境变量或安全的密钥管理工具
✅ 项目已将 .env 添加到 .gitignore

项目结构

om-mcp/
├── server.py              # MCP 服务器入口
├── lib/
│   ├── http.py           # HTTP 请求封装
│   ├── apidocs_loader.py # API 文档加载器（从 .ms 文件解析）
│   ├── template_loader.py # 工具模板加载器（YAML 配置）
│   ├── tool_generator.py  # 动态工具生成器
│   └── response_formatter.py # 响应格式化
├── tools/
│   ├── health.py         # 社区健康度查询
│   ├── common.py         # 通用工具（社区列表）
│   ├── server_apis.py    # 服务端 API（社区列表、指标字典、热点仓库等）
│   ├── query_apis.py     # 查询 API（PR/Issue 聚合、按 SIG 统计等）
│   ├── cla_apis.py       # CLA 相关 API
│   ├── project_apis.py   # 项目 CI 指标
│   └── general_apis.py   # 通用查询 API
├── api-docs/              # API 文档目录（自动生成工具）
│   ├── datastat/          # datastat 模块 API
│   └── 社区运营质量/       # 社区运营质量模块 API
└── test/                  # 测试目录
    ├── test_mcp.py        # 测试脚本
    └── README.md          # 测试说明

自动工具注册机制

项目支持从 API 文档自动生成 MCP 工具，无需手动编写工具函数。

工作原理

API 文档加载 (lib/apidocs_loader.py)

从 api-docs/ 目录加载 .ms 格式的 API 文档
解析文档中的 HTTP 路径、方法、参数定义
生成 ToolTemplate 数据结构

工具函数生成 (lib/tool_generator.py)

根据 ToolTemplate 动态生成异步工具函数
自动处理参数类型转换、社区名称归一化、路径参数替换
注册到 FastMCP 实例

特殊处理

路径参数：如 /{contributeType}/detail 中的 contributeType 会被识别为路径参数
工具命名：路径参数占位符 {xxx} 会被替换为 xxx，避免生成多个工具
社区归一化：自动将社区名称映射为标准格式

添加新 API 工具

只需在 api-docs/ 目录下添加 .ms 文档文件，重启服务即可自动注册。

手动添加工具

对于复杂的业务逻辑，仍可手动编写工具函数：

在 tools/ 目录下创建新的 Python 文件
定义 register(mcp: FastMCP) 函数
使用 @mcp.tool() 装饰器注册工具
在 server.py 中导入并注册

示例： ```python from mcp.server.fastmcp import FastMCP from lib.http import get, post, extract_data

def register(mcp: FastMCP): @mcp.tool() async def my_new_tool(param: str) -> str: """工具描述""" result = await get("/api/endpoint") return f"结果: {result}" ```

测试

运行测试脚本验证所有功能：

cd test
python3 test_mcp.py

测试脚本会模拟真实使用场景，调用所有 MCP 工具并验证返回结果。详见 test/README.md。

---

🔧 故障排查

MCP 服务器无法启动

检查 Python 版本：python3 --version（需要 3.8+）
检查依赖安装：pip list | grep mcp
查看 Claude Desktop 日志

查询返回错误

确认网络连接正常，可访问远程 API：curl https://datastat.osinfra.cn/server/
检查社区名称是否正确（使用 list_communities 工具查看支持的社区）
运行测试脚本验证：cd test && python3 test_mcp.py

常见错误

| 错误信息 | 原因 | 解决方案 | |---------|------|---------| | ModuleNotFoundError: No module named 'mcp' | MCP SDK 未安装 | 运行 pip install "mcp[cli]" | | Connection refused | 无法访问远程 API | 检查网络连接和防火墙设置 | | Community not found | 社区名称错误 | 使用 list_communities 查看支持的社区 |

---

📚 文档索引

| 文档 | 说明 | |------|------| | FEATURES.md | 完整功能列表和使用示例 | | INSTALL.md | 详细安装指南（含虚拟环境配置） | | test/README.md | 测试说明和故障排查 |

---

🔗 后端 API 说明

本 MCP 服务器调用远程 API 服务：

API 地址：https://datastat.osinfra.cn/server/
修改方式：编辑 lib/http.py 中的 API_BASE_URL 变量

---

📄 许可证

MIT License

---

🤝 贡献

欢迎提交 Issue 和 Pull Request！

贡献前请：

Fork 本项目
创建特性分支：git checkout -b feature/your-feature
提交更改：git commit -m 'Add some feature'
推送到分支：git push origin feature/your-feature
提交 Pull Request

---

om-metrics MCP Server — 让开源社区数据查询更简单 📊

Made with ❤️ for Open Source Communities

</div>

om-metrics MCP Server

om-metrics MCP Server

目录

🦎 项目简介

适用人群

支持的社区

✨ 核心功能

📊 社区健康度分析

🔍 PR/Issue 统计

👥 贡献者分析

📝 CLA 签署查询

🚀 CI/CD 指标

📦 项目仓库

🚀 快速开始

前置要求

安装步骤

💡 使用方式

基础查询示例

趋势分析示例

贡献者分析示例

跨社区对比示例

🛠️ 开发指南

环境变量配置

项目结构

自动工具注册机制

工作原理

添加新 API 工具

手动添加工具

测试

🔧 故障排查

MCP 服务器无法启动

查询返回错误

常见错误

📚 文档索引

🔗 后端 API 说明

📄 许可证

🤝 贡献

Related MCP servers

MCP servers by category