felixkwasisarpong/incident-triage-mcp

# Incident Triage MCP       Incident Triage MCP 是一个用于事件分诊的 Model Context Protocol (MCP) 服务器。它提供安全、可审计的工具，用于证据检索、确定性摘要、工单工作流和通知。 ## 本项目是什么 - 事件分诊工具的 MCP 控制平面。 - 兼容本地 (`stdio`) 和网络 (`streamable-http`) MCP 客户端。 - 支持独立模式、Docker Compose 和 Kubernetes。 ## 本项目不是什么 - 不是独立的 LLM agent 平台。 - 不是提供商凭证保管库。 - 不是你证据流水线的替代品；它消费的是标准化证据包。 ## 架构概览 - MCP 服务器保持轻量且专注于策略。 - 证据收集在 Airflow（可选）中运行，并写入 EvidenceBundle artifacts。 - Agents 仅调用 MCP 工具。 - 契约稳定性在 `spec/` 下定义。 欲知详情，请参阅 [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)。 ## 核心工具 | Tool | Purpose | Mutating | |---|---|---| | `evidence_get_bundle` | 获取某个事件的标准化 EvidenceBundle | No | | `evidence_wait_for_bundle` | 轮询直到 bundle 可用 | No | | `incident_triage_summary` | 从 bundle 构建确定性的分诊摘要 | No | | `jira_draft_ticket` | 构建非变更性工单草稿 | No | | `jira_create_ticket` | 带安全门控创建工单 | Yes | 变更性操作受 RBAC、`dry_run`、`confirm_token`、审计日志和幂等性的保护。 ## 提供商矩阵 | Area | Supported providers | |---|---| | Alerts | `mock`, `datadog`, `cloudwatch`, `prometheus`, `pagerduty`, `opsgenie` | | Metrics | `mock`, `datadog`, `cloudwatch`, `prometheus` | | Logs | `mock`, `datadog`, `cloudwatch`, `elk`, `none` | | Traces | `mock`, `datadog`, `cloudwatch`, `xray`, `otel`, `none` | | Ticketing (`JIRA_PROVIDER`) | `mock`, `cloud`, `servicenow` | | Notify (`NOTIFY_PROVIDER`) | `slack`, `teams` | ## 快速开始 ### 本地 ``` python -m venv .venv source .venv/bin/activate pip install -e . MCP_TRANSPORT=stdio \ WORKFLOW_BACKEND=none \ EVIDENCE_BACKEND=fs \ EVIDENCE_DIR=./evidence \ incident-triage-mcp ``` ### 本地 agent 运行 (单个事件) ``` incident-triage-agent \ --incident-id INC-123 \ --service payments-api \ --artifact-store fs \ --artifact-dir ./evidence \ --compact ``` ### Docker (streamable-http) ``` docker run --rm -p 3333:3333 \ -e MCP_TRANSPORT=streamable-http \ -e WORKFLOW_BACKEND=none \ -e EVIDENCE_BACKEND=fs \ ghcr.io/felixkwasisarpong/incident-triage-mcp:latest ``` 可选的本地技术栈 (Airflow + Postgres + MinIO + MCP): ``` docker compose up --build ``` ## Kubernetes: 每次触发一个 Agent Job 这是推荐的运行时模式： 1. 入站触发器 (webhook/手动) 到达。 2. 调度器 (或 operator) 为每个事件创建一个 Kubernetes `Job`。 3. Job 运行 `incident-triage-agent` 一次后退出。 4. Agent 通过 HTTP 调用 MCP 工具。 5. MCP 可选地触发 Airflow DAG (`incident_evidence_v1`) 并从 `fs`/`s3` 消费 bundle。 ### 部署 MCP 服务器 ``` helm upgrade --install incident-triage-mcp ./charts/incident-triage-mcp \ --namespace incident-triage --create-namespace \ --set image.repository=ghcr.io/felixkwasisarpong/incident-triage-mcp \ --set image.tag=0.2.8 \ --set env.MCP_TRANSPORT=streamable-http \ --set env.MCP_HTTP_AUTH_MODE=api_key \ --set secretEnv.MCP_HTTP_API_KEY=change-me ``` ### 使用单次运行 agent Job 触发一个事件 ``` kubectl -n incident-triage create job triage-inc-123 \ --image=ghcr.io/felixkwasisarpong/incident-triage-mcp:0.2.8 \ -- incident-triage-agent \ --incident-id INC-123 \ --service payments-api \ --mcp-url http://incident-triage-mcp/mcp \ --mcp-api-key change-me \ --compact ``` ### 确保单次运行行为 - 为每个事件使用确定性的作业名称 (`triage-inc-`)。 - 如果作业已存在，在调度器层面拒绝重复。 - 使用 `idempotency_key` 保持工单创建的幂等性。 - 配置 Job 生命周期控制 (`backoffLimit`, `activeDeadlineSeconds`, `ttlSecondsAfterFinished`)。 ## 配置要点 | Variable | Meaning | |---|---| | `MCP_TRANSPORT` | `stdio` 或 `streamable-http` | | `WORKFLOW_BACKEND` | `none` 或 `airflow` | | `EVIDENCE_BACKEND` | `none`, `fs`, `s3`, `airflow` | | `EVIDENCE_DIR` | 使用 `fs` 时的本地 bundle 目录 | | `AIRFLOW_BASE_URL` | Airflow trigger/read 工具所需 | | `MCP_HTTP_AUTH_MODE` | `none`, `api_key`, `jwt_hs256` | | `AUDIT_MODE` | `stdout` (推荐在 k8s 中) 或 `file` | | `DEPLOYMENT_PROFILE` | `local`, `staging`, `prod` | 配置模板位于 `deploy/profiles/`： - `local.env.example` - `staging.env.example` - `prod.env.example` ## 测试 运行完整测试： ``` pytest -q ``` 仅运行契约检查： ``` pytest -q tests/test_contract_evidence_bundle.py tests/test_contract_mcp_tools.py python scripts/validate_contrib.py ``` ## 发布 ### 从 PyPI 安装 ``` pip install incident-triage-mcp==X.Y.Z ``` ### 拉取容器镜像 ``` docker pull ghcr.io/felixkwasisarpong/incident-triage-mcp:X.Y.Z ``` 支持的镜像标签： - `X.Y.Z` (精确版本) - `X.Y` (次版本流) - `latest` 有关发布工作流的详细信息，请参阅 [docs/RELEASING.md](docs/RELEASING.md)。 ## 项目布局 ``` incident-triage-mcp/ src/incident_triage_mcp/ # MCP server + tools + adapters spec/ # versioned contracts airflow/dags/ # evidence pipeline charts/incident-triage-mcp/ # Helm chart k8s/ # Kubernetes manifests contrib/ # polyglot contribution area docs/ # architecture, release, governance docs ``` ## 支持与分诊 - 讨论区: https://github.com/felixkwasisarpong/incident-triage-mcp/discussions - 问题反馈: https://github.com/felixkwasisarpong/incident-triage-mcp/issues - 安全报告: [SECURITY.md](SECURITY.md) ## 文档索引 - [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) - [docs/CONTRIBUTION_GUIDE.md](docs/CONTRIBUTION_GUIDE.md) - [docs/REPO_LAYOUT.md](docs/REPO_LAYOUT.md) - [docs/VERSIONING.md](docs/VERSIONING.md) - [docs/RELEASING.md](docs/RELEASING.md) - [docs/MAINTAINERS_RUNBOOK.md](docs/MAINTAINERS_RUNBOOK.md) ## 贡献 在提交 PR 之前，请阅读 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 MIT

标签：Airflow, AI智能体, Docker, ESC漏洞, Jira集成, LLM工具, MCP服务器, Python, RBAC, Site Reliability Engineering, SOAR, 事件分类, 云端原生, 子域名突变, 安全防御评估, 审计日志, 工单系统, 故障诊断, 无后门, 服务健康, 模型上下文协议, 确定性摘要, 网络研究, 证据收集, 请求拦截, 运维工具, 运维自动化, 逆向工具