om-metrics MCP Server

<div align="center">

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

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

</div>

---

目录

👤 我是用户

• 项目简介
• 核心功能
• 快速开始
• 使用方式

🛠️ 我是开发者

• 开发指南
• 故障排查
• 文档索引
• 后端 API 说明
• 贡献

---

🦎 项目简介

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

然后运行：

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 工具，无需手动编写工具函数。

工作原理

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

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

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

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

3. 特殊处理

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

添加新 API 工具

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

手动添加工具

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

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

示例：

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 服务器无法启动

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

查询返回错误

1. 确认网络连接正常，可访问远程 API：curl https://datastat.osinfra.cn/server/
2. 检查社区名称是否正确（使用 list_communities 工具查看支持的社区）
3. 运行测试脚本验证：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！

贡献前请：

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

---

<div align="center">

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

Made with ❤️ for Open Source Communities

</div>