MCP Metrics

GitHub工程生产力仪表板

PRD/TechnicalStack文件中所述系统的基础脚手架。包括FastAPI编排器、Next.js前端、Postgres和通过Docker Compose的GitHub MCP服务器。

堆栈

• FastAPI（Python 3.12）用于编排、MCP工具调用、DORA+洞察端点
• Next.js（App Router）用于仪表板、聊天、每日简报
• PostgreSQL用于度量+洞察存储
• GitHub MCP服务器（Docker）作为检索层
• 用于AI聊天+洞察生成的可选OpenAI（或兼容API）模型

运行全栈（Docker+MCP）

先决条件：Docker和Compose，GitHub PAT repo:read，如果你想要LLM聊天/摘要，可以选择OpenAI/Anthropic键。

1. 配置环境

cp infra/env/.env.example .env
# Required
GITHUB_PAT=ghp_your_pat_here   # needs repo:read for target repos
# Optional (enables LLM-backed chat/insight rewriting)
OPENAI_API_KEY=...
ANTHROPIC_API_KEY=...
# Ingestion defaults
INGEST_REPOSITORIES=owner/repo   # comma-separated
INGEST_LOOKBACK_DAYS=7

1. 开始一切

cd infra
docker compose --env-file ../.env up --build
# add -d to run detached

1. 事情的发展方向

• 前端：http://localhost:3000
• APIhttp://localhost:8000（docs at/docs，health at/health）
• MCP服务器：http://localhost:3001
• Postgres:本地主机：5432（db mcp_metrics，用户 mcp，通过 mcp_password)

1. 使用应用程序

• 在UI中，将存储库设置为 owner/repo （必填）并单击 运行摄入.
• 使用 刷新指标 / 刷新见解 根据需要。
• 深入挖掘和聊天依赖于MCP；确保PAT有效，MCP容器健康。

故障排除

• UI中的“获取失败”：确认API已启动(http://localhost:8000/health)而且 NEXT_PUBLIC_API_BASE_URL 前端内部是 http://localhost:8000 （compose中的默认设置）。API CORS允许 http://localhost:3000.
• MCP错误：验证 GITHUB_PAT 在 .env 以及MCP的健康状况(http://localhost:3001/health)返回ok。
• 如果使用npm dev而不是Docker，导出 NEXT_PUBLIC_API_BASE_URL=http://localhost:8000 之前 npm run dev.

日常自动化（摄取+洞察）

• 集 INGEST_REPOSITORIES env（逗号分隔的所有者/仓库）和可选 INGEST_LOOKBACK_DAYS.
• 运行作业一次： cd api && INGEST_REPOSITORIES=owner/repo uvicorn app.main:app --reload API，或 python -m app.jobs 对于批处理作业。
• 要通过cron安排每日日程： 0 2 * * * cd /path/to/api && INGEST_REPOSITORIES=owner/repo python -m app.jobs >> /tmp/mcp_cron.log 2>&1

最近添加

• 仪表板可配置GitHub PAT：直接在UI中输入PAT以分析任何存储库，而无需重新启动服务。
• 增强型AI聊天：询问有关DORA指标、MCP概念或存储库性能的问题。使用或不使用OpenAI API密钥：

- 使用OpenAI：全对话式AI，结合您的指标和GitHub数据 - 没有OpenAI：常见DORA/MCP问题的智能回退响应

• MCP健康检查浮出水面 /health.
• DORA CFR/MTTR启发式方法和贡献者风险终点。
• 前端图表、深入分析、组织视图切换、贡献者风险卡。
• 用于后端/前端和计划摄取工作流模板的CI(.github/workflows).

聊天功能

聊天可以回答以下问题：

• DORA指标：“DORA指标是什么？”，“解释交付周期”，“什么是好的部署频率？”
• MCP概念：“什么是MCP？”，“模型上下文协议是如何工作的？”
• 您的存储库：“上周发货了什么？”，“谁是最大的贡献者？”，，“我的回购怎么样？”
• 风险分析：“风险标志是什么？”，“是否存在公共汽车因素风险？”

为了获得最佳体验，请配置 OPENAI_API_KEY 在你的 .env 文件。即使没有它，系统也会提供有用的回退响应。

没有Docker的开发

• API cd api && uvicorn app.main:app --reload
• 前端： cd frontend && npm install && npm run dev

前端开发提示

• 你只需要 npm install 当 package.json /锁文件更改或新克隆。否则，请直接前往 npm run dev.
• 保持节点版本一致（例如，通过 nvm use)以避免重复安装。
• 如果你在Docker中开发，缓存或烘焙 node_modules 以防止它在每个容器启动时被擦拭。

测试

• 后端： cd api && pip install .[dev] && pytest
• 前端： cd frontend && npm run lint && npm run build

备注

• Compose希望Docker提供MCP服务器镜像 ghcr.io/modelcontextprotocol/github-mcp-server:latest。确保你的PAT有目标的repo:read范围。