使用说明

mcp rca

根本原因分析MCP服务器，帮助SRE团队在与LLM协作的同时构建观察结果、假设和测试计划。

亮点

基于提示的指导：MCP提示引导LLM完成每个RCA阶段
- rca_start_investigation -从结构化的初始步骤开始调查
- rca_next_step -根据案例状态获取上下文感知建议
- rca_hypothesis_propose -生成可测试的根本原因假设
- rca_verification_planning -制定有效的测试计划
- rca_conclusion_guide -记录结论，包括根本原因和后续行动
面向LLM的工具：指导工具提供最佳实践和特定阶段的检查表
- guidance_best_practices -RCA原则和反模式
- guidance_phase -阶段性步骤和危险信号
- guidance_prompt_scaffold -任务的结构化输出格式
- guidance_followups -结论后的后续行动
- guidance_prompts_catalog -使用默认模板发现可用提示
- guidance_tools_catalog -具有工作流程指导的全面工具目录
假设生成 返回具有ID的持久化对象
- hypothesis_propose 持久化生成的假设，并返回每个项目 id, caseId, createdAt，以及 updatedAt.
- 当生成器在其输出中提供验证计划时 test_plan_create 自动调用，并将最小信息附加到假设（方法/预期/度量？）。
Git/deploy元数据 案例/观察/测试计划
- 可选字段： gitBranch, gitCommit, deployEnv.
- 开始创建和更新工具；经过 null 更新时清除该字段。

安装

npm install mcp-rca

要直接将服务器作为CLI启动，请执行以下操作：

npx mcp-rca

服务器通过stdio通信，可以连接到任何兼容MCP的客户端。CLI标志包括 --help (-h)使用和 --version (-v)打印当前版本。

入门（开发）

克隆存储库并安装依赖项：

git clone https://github.com/mako10k/mcp-rca.git
cd mcp-rca
npm install

使用热重新加载启动开发人员服务器：
```
npm run dev
```
生产捆绑包（发射 dist/ 并复制提示资产）：
```
npm run build
```

项目布局

src/
  framework/         # Local stub for MCP server lifecycle
  server.ts          # MCP server entrypoint
  schema/            # TypeScript data models
  tools/             # Tool handlers surfaced to MCP clients
  llm/               # Prompt assets and LLM utilities
data/
  .gitkeep           # Runtime storage directory (cases.json generated at runtime)
scripts/
  copy-assets.mjs    # Copies static prompt assets into dist/ post-build

参见 AGENT.md 了解完整的规范、路线图和设计指南。

快速入门：使用提示

MCP提示指导您完成每个阶段的调查：

1.开始调查

Use prompt: rca_start_investigation
→ Creates a structured plan for case creation and initial observations

2.跟踪进度

Use prompt: rca_next_step with caseId
→ Analyzes current state and suggests next actions

3.生成假设

Use prompt: rca_hypothesis_propose with caseId
→ Guides hypothesis generation with best practices
→ Then call tool: hypothesis_propose to create and persist hypotheses

4.计划验证

Use prompt: rca_verification_planning with caseId, hypothesisId, hypothesisText
→ Provides test plan templates and prioritization guidance
→ Then call tool: test_plan_create to create verification plans

5.文件结论

Use prompt: rca_conclusion_guide with caseId
→ Guides documentation of root causes, fixes, and follow-ups
→ Then call tool: conclusion_finalize to close the case

LLM指导工具

随时致电指导工具以获得额外支持：

guidance_best_practices -核心RCA原则
guidance_phase -阶段特定检查表（观察/假设/测试/结论）
guidance_prompt_scaffold -特定任务的输出格式模板
guidance_followups -预防和后续建议

MCP工具亮点

假设

输入（摘要）：

{
  "caseId": "case_...",
  "text": "Short incident summary",
  "rationale": "Optional background",
  "context": { "service": "api", "region": "us-east-1" },
  "logs": "... optional log snippets ..."
}

输出（每个假设都是持久的，包括标识符；如果生成器提供了初始测试计划，则可能存在）：

{
  "hypotheses": [
    {
      "id": "hyp_...",
      "caseId": "case_...",
      "text": "Cache node eviction storm caused by oversized payloads",
      "rationale": "Spike correlates with payload growth and cache TTL",
      "createdAt": "2025-10-21T00:00:00.000Z",
      "updatedAt": "2025-10-21T00:00:00.000Z",
      "testPlan": {
        "id": "tp_...",          
        "hypothesisId": "hyp_...",
        "method": "Reproduce with oversized payloads and inspect eviction rate",
        "expected": "Evictions rise sharply with payload size > X",
        "metric": "cache.evictions"
      }
    }
  ]
}

元数据参数（git/deploy）

以下工具接受可选的元数据字段；在更新时， null 清除现场。

案例
- case_create: gitBranch, gitCommit, deployEnv
- case_update: gitBranch?, gitCommit?, deployEnv? （可空清除）
观察
- observation_add: gitBranch?, gitCommit?, deployEnv?
- observation_update: gitBranch?, gitCommit?, deployEnv? （可空清除）
测试计划
- test_plan_create: gitBranch?, gitCommit?, deployEnv?
- test_plan_update: gitBranch?, gitCommit?, deployEnv? （可空清除）

清除的更新有效负载示例 gitCommit 根据观察：

{
  "caseId": "case_...",
  "observationId": "obs_...",
  "gitCommit": null
}

响应包括设置时的持久元数据；未设置时省略字段。

观察结果搜索和分页

使用 observations_list 在不提取完整案例有效载荷的情况下查询观察结果：

{
  "caseId": "case_...",
  "query": "DriveNotFoundException",
  "fields": ["what", "context"],
  "pageSize": 10,
  "gitBranch": "release",
  "order": "desc"
}

响应返回 observations, nextCursor, total, pageSize，以及 hasMore.通行证 cursor 下一次呼叫呼叫翻页。结合 case_get 摘要模式(include: [])以最小化令牌使用。看 docs/CASE_GET_PAGINATION.md 查看光标详细信息。

API响应结构

所有突变工具都遵循一致的响应结构，以实现可预测性和易用性：

标准突变反应

{
  caseId: string;           // Always at top level
  [resourceName]: Resource; // The created/updated/removed resource
  case: Case;               // Full case object after the mutation
}

优点：

✅ 一致的：所有突变工具的模式相同
✅ 上下文访问: caseId 始终处于最高水平
✅ 立即状态：已满 case 对象可用，无需额外查询
✅ 令牌优化：结合 case_gets include 高效工作流程的参数

示例：

observation_add → { caseId, observation, case }
hypothesis_propose → { caseId, hypotheses, case }
test_plan_create → { caseId, testPlan, case }
conclusion_finalize → { caseId, conclusion, case }

看 docs/RESPONSE_STRUCTURE_STANDARDIZATION.md 了解完整细节。

性能和最佳实践

令牌优化

许多突变工具（例如。， observation_add, hypothesis_update)返回完整 case 响应中的对象，每次操作可能会消耗数千个令牌。

推荐模式：

// Perform mutations without relying on the case field
await observation_add({ caseId, what: "..." });
await observation_add({ caseId, what: "..." });

// Fetch case data selectively when needed
const caseData = await case_get({
  caseId,
  include: ['observations'],  // Only fetch what you need
});

看 docs/API_RESPONSE_OPTIMIZATION.md文件了解详细的优化策略和令牌节省示例。

有关分页详细信息（限制、光标和 include 语义）参见 docs/CASE_GET_PAGINATION.md.

许可证

该项目在MIT许可证下发布。请参阅 LICENSE 文件以获取详细信息。

出版

该包已配置为公共npm注册表。升级版本后，运行：

npm publish --access public

prepublishOnly 在生成tarball之前，重建TypeScript源代码并复制所需的资产。