Diagnosis Service

独立故障诊断 MCP 服务，作为可被任意业务服务接入的异常诊断中心：

• 业务服务通过 HTTP 推送异常日志。
• 诊断服务使用独立 MySQL 库 diagnosis_db 保存日志、服务注册、静态代码索引、历史工单和诊断报告。
• Codex、Claude Desktop 或其他 MCP 客户端可通过 /mcp 查询日志并生成诊断报告。
• demo-service/ 是随项目携带的外接测试服务，会随机制造 timeout 和空指针异常，用于验证接入链路。

Project Map

• app/: 诊断服务 FastAPI 应用。
  • main.py: HTTP API 和 MCP JSON-RPC 入口。
  • log_store.py: 日志写入、查询、统计和报告生成。
  • mcp_tools.py: MCP 工具定义和工具调用分发。
  • db.py: MySQL 访问层。
  • schemas.py: API DTO。
• demo-service/: 外部服务接入测试用例。
• infra/mysql/diagnosis_init.sql: 独立诊断库初始化脚本。
• scripts/: 本地链路冒烟测试和诊断静态数据导入脚本。
• docker-compose.yml: diagnosis-service、demo-service 一键运行，MySQL 连接外部 infra-stack。

APIs

Endpoint	Description
POST /api/logs	业务服务推送异常日志
GET /api/logs?service=&level=&trace_id=	查询异常日志
GET /api/logs/stats?hours=24	查询日志聚合统计
GET /api/services	查询已接入服务
POST /api/reports	生成诊断报告
GET /api/reports/{report_id}	查询诊断报告
POST /mcp	MCP JSON-RPC 工具入口
GET /.well-known/oauth-protected-resource/mcp	MCP OAuth protected resource metadata
GET /.well-known/oauth-authorization-server/mcp	MCP OAuth authorization server metadata
POST /mcp/oauth/token	可选 client_credentials token 端点
GET /health	健康检查

MCP Tools

• search_logs: 按服务、级别、traceId 和时间窗口查日志。
• search_code: 查询静态导入的代码符号。
• search_tickets: 查询相似历史故障工单。
• generate_report: 聚合日志、代码和工单证据生成诊断报告。
• get_report: 按报告 ID 查询报告。

Quick Start

cp .env.example .env
# 先启动外部 ai-agent-infra-stack，再启动诊断服务
docker compose up -d diagnosis-service demo-service
curl http://localhost:8200/health

推送一条异常：

curl -X POST http://localhost:8200/api/logs \
  -H 'Content-Type: application/json' \
  -d '{"service":"demo-service","level":"ERROR","trace_id":"tr_001","endpoint":"/api/order/1","exception_type":"TimeoutError","message":"order query timeout"}'

生成诊断报告：

curl -X POST http://localhost:8200/mcp \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"generate_report","arguments":{"service":"demo-service","trace_id":"tr_001"}}}'

运行 demo-service 外部接入验证：

for i in 1 2 3 4 5; do curl -s http://localhost:8300/api/order/$i || true; done
curl 'http://localhost:8200/api/logs?service=demo-service&page_size=10'

Local Development

python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
DIAGNOSIS_MYSQL_DSN=mysql://agent:agent123@localhost:3306/diagnosis_db \
  uvicorn app.main:app --host 127.0.0.1 --port 8200 --reload

demo-service 本地启动：

cd demo-service
pip install -r requirements.txt
DIAGNOSIS_URL=http://localhost:8200 uvicorn app.main:app --host 127.0.0.1 --port 8300 --reload

Codex MCP Usage

把 MCP HTTP 入口配置到本地 Codex/其他 MCP 客户端时，服务地址使用：

http://localhost:8200/mcp

默认本地开发不启用 MCP 鉴权。部署到外部网络时建议配置 MCP 专用 Bearer token：

export MCP_AUTH_TOKEN='replace-with-a-long-random-token'
uvicorn app.main:app --host 127.0.0.1 --port 8200 --reload

客户端连接 /mcp 时带上：

Authorization: Bearer replace-with-a-long-random-token

启用 token 后，未带或带错 token 的 /mcp、/api/tools 和 /api/tools/{tool_name} 会返回 401，并通过 WWW-Authenticate 指向 MCP/OAuth protected resource metadata。Codex、Claude Code 等客户端探测这些地址时不会再遇到 well-known 404：

/.well-known/oauth-protected-resource/mcp
/.well-known/oauth-authorization-server/mcp
/mcp/.well-known/oauth-authorization-server
/.well-known/oauth-authorization-server
/.well-known/openid-configuration/mcp
/mcp/.well-known/openid-configuration
/.well-known/openid-configuration

如果客户端支持 MCP OAuth Client Credentials 扩展，也可以额外配置：

export MCP_AUTH_TOKEN='replace-with-a-long-random-token'
export MCP_OAUTH_CLIENT_ID='diagnosis-client'
export MCP_OAUTH_CLIENT_SECRET='replace-with-a-long-random-secret'

然后用 client_credentials 从 /mcp/oauth/token 换取 Bearer token。这个端点同时支持 client_secret_basic 和 client_secret_post。

工具发现请求：

curl -X POST http://localhost:8200/mcp \
  -H 'Authorization: Bearer replace-with-a-long-random-token' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

Environment

• DIAGNOSIS_MYSQL_DSN: 诊断库连接串，默认 mysql://agent:agent123@localhost:3306/diagnosis_db。
• MCP_AUTH_TOKEN: MCP 专用 Bearer token；为空时 /mcp 保持免鉴权，便于本地开发。
• MCP_AUTH_SCOPE: MCP OAuth scope，默认 diagnosis:mcp。
• MCP_AUTH_ISSUER: OAuth issuer；默认按请求 host 自动生成。
• MCP_OAUTH_CLIENT_ID: 可选 OAuth client credentials 客户端 ID。
• MCP_OAUTH_CLIENT_SECRET: 可选 OAuth client credentials 客户端密钥。
• DIAGNOSIS_URL: demo-service 推送诊断服务地址，默认 http://localhost:8200。
• SERVICE_NAME: demo-service 上报服务名，默认 demo-service。

Verification

python3 -m compileall app demo-service/app
bash scripts/smoke_test.sh

导入诊断静态数据：

python3 scripts/ingest_code.py --repo-dir demo-service --service demo-service
python3 scripts/ingest_tickets.py --ticket-dir datasets/tickets --service demo-service
python3 scripts/ingest_logs.py --log-dir datasets/logs --service demo-service