事件知識圖譜 MCP Server（Incident Knowledge Graph）

以 MCP（stdio） 對外提供的、以事件（incident）為中心的知識圖譜,可供任何相容 MCP 的 client 使用(本專案以 Codex CLI 與 OpenCode 為目標)。它是整個 SRE × MCP 架構中「可寫入、可完整測試」的核心:負責保存那些 beever-atlas MCP 介面 本身無法保存的觀測訊號與 Atlas 永久座標,讓上層 agent 在查詢時能把事件與對話 內容關聯起來。

設計原則:不把 Atlas 內容複製進來。 我們只存指標(pointer) (channel_id + 永久 message_id + url),避免產生重複的真實來源。

本 repo 只實作 KG server(見 spec 第 0 節)。真實的 Atlas / Prometheus / DB2 client、signature 的內容(門檻)、JSON 以外的儲存後端、MCP gateway 等,皆為整合 擴充點(spec 第 10 節),不在此實作。

文件導覽

文件	內容
SPEC_knowledge_graph_mcp.md	需求規格:資料模型、工具規格、驗證規則、驗收標準
NEXT_STEPS.md	安裝說明、後續待確認事項、注意事項
skills/mmdb-troubleshooting/SKILL.md	MMDB activelog / busy-ratio 排障手冊(規則)
本檔 README	安裝、設定、工具清單、專案結構

環境需求

• Python 3.11+

安裝

# 於專案根目錄
python -m venv .venv
# Windows PowerShell:  .venv\Scripts\Activate.ps1
# macOS/Linux:         source .venv/bin/activate
pip install -e ".[dev]"

設定

所有設定皆由環境變數驅動(見 .env.example),程式碼與 repo 內不寫死任何真實環境資訊。

變數	預設值	意義
KG_DATA_PATH	./data/graph.json	JSON 圖譜的持久化路徑

資料檔於首次寫入時建立,採用原子寫入(temp 檔 + rename),寫入中途崩潰也不會毀損 既有資料。

執行

kg-mcp-server          # console 進入點(以 stdio 提供服務)
# 或
python -m kg_server.server

此 server 走 stdio,設計上由 MCP host 啟動,而非互動式使用。

註冊到 MCP client

本 server 走標準 MCP stdio 協定,任何相容 client 都能啟動它。建議直接指定 venv 的 Python(當 kg-mcp-server 不在 PATH 時最穩)。

Codex CLI

加入 ~/.codex/config.toml:

[mcp_servers.incident-knowledge-graph]
command = "C:\\path\\to\\tsmc\\.venv\\Scripts\\python.exe"
args = ["-m", "kg_server.server"]
env = { KG_DATA_PATH = "C:\\path\\to\\tsmc\\data\\graph.json" }

(若 kg-mcp-server 已在 PATH,也可用 command = "kg-mcp-server"、args = []。)

OpenCode

加入 OpenCode 設定檔(專案根目錄的 opencode.json,或全域的 ~/.config/opencode/opencode.json):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "incident-knowledge-graph": {
      "type": "local",
      "command": [
        "C:\\path\\to\\tsmc\\.venv\\Scripts\\python.exe",
        "-m",
        "kg_server.server"
      ],
      "environment": { "KG_DATA_PATH": "C:\\path\\to\\tsmc\\data\\graph.json" },
      "enabled": true
    }
  }
}

重啟 client 後,KG 工具就會出現在其 MCP 工具清單中。

多 MCP server 協作（方案 A）

本 server 是 MCP server,不會主動去呼叫別的 server。要整合 Grafana / MariaDB 等資料源,標準做法是在 client 層並列掛載多個 server,由 agent 自己編排跨源查詢:

Codex CLI / OpenCode（agent = MCP client）
   ├── incident-knowledge-graph（本專案）  寫入事件、查因果鏈、存 Teams 座標
   ├── grafana（官方 mcp-grafana）         跑 PromQL、查 Loki logs、dashboard
   └── mariadb（官方 MariaDB/mcp）         唯讀 SQL、查 schema

分工原則:讀在別人,寫在我們。 Grafana / MariaDB 負責讀取現場資料;本 server 負責 把「判讀後的結論」沉澱成可累積、可回溯的知識圖譜。

可直接套用的設定範例:

• Codex CLI → examples/codex-config.toml
• OpenCode → examples/opencode.json

外部 server 安裝方式:

Server	安裝	需要的認證
mcp-grafana	go install github.com/grafana/mcp-grafana/cmd/mcp-grafana@latest 或 docker pull grafana/mcp-grafana	GRAFANA_URL + service account token
MariaDB/mcp	見其 README	連線資訊(請用唯讀帳號)

典型的跨 server 排障流程

agent 在一次對話中會這樣串接(括號內是它呼叫的 server):

1. 「正式機昨天下午怪怪的」→ resolve_alias("正式機") (KG) → 得知 canonical 是 MMDB、Prometheus instance 是 mmdb-prod-01:9104
2. query_prometheus("mmdb_busy_ratio{...}") (Grafana) → 撈出指標曲線
3. 判讀出異常區段 → create_incident(system="MMDB", slug_hint="busy_ratio", ...) (KG) → 自動建立 AFFECTS 關係
4. record_signature_match(...) (KG) → 掛上 mmdb.busy_ratio.sustained
5. incident_time_window(...) (KG) → 取得時間窗
6. 用該時間窗查 Teams/Atlas → attach_atlas_reference(...) (KG) 存永久座標
7. 需要細看資料庫狀態時 → 唯讀 SQL (MariaDB) → 結論寫回 add_observation(...) (KG)

下次再遇到類似狀況,find_incidents / trace_incident_chain 就能直接調出歷史情境, 不必再人工翻聊天紀錄。

工具（Tools）

寫入類:

• upsert_system(name, aliases=[], labels={}) — 建立/合併 System(合併、去重)。
• create_incident(system, occurred_at, ...) — 建立事件,自動建立 AFFECTS 關係。
• add_observation(entity_name, observation) — 對實體追加自由備註。
• link(from_entity, to_entity, relation_type) — 建立關係,強制型別紀律。
• record_signature_match(incident_id, signature_name) — 建立/連結 Signature(MATCHES)。
• attach_atlas_reference(incident_id, channel_id, message_id, url, fact_id=None) — 附上 Atlas 永久座標。

查詢類:

• get_incident(incident_id) — 事件完整視圖 + 關係。
• find_incidents(system=, signature=, severity=, since=, until=) — 條件篩選摘要。
• resolve_alias(term) — canonical / alias / label → System。
• incident_time_window(incident_id, pad_minutes=15) — {start_utc, end_utc}。
• trace_incident_chain(incident_id, direction="downstream") — 沿 CAUSED 追鏈。

重要慣例

• 時間戳一律為 ISO-8601 UTC(例:2026-06-12T03:14:00Z)。無時區或非 UTC 的值會被拒絕——請先轉成 UTC 再送。這是對齊 Prometheus(UTC)與 Teams(本地時間) 的前提。
• incident_id 格式為 INC-YYYY-MM-DD-<slug>;未指定時由 server 依 system slug 自動產生。
• System 的 canonical 名稱採用團隊口語慣用的短名(以便與 Atlas 實體對齊);精確的 ops 標籤(如 prometheus_instance)放進 labels。
• Atlas 永久鍵是 message_id;fact_id 僅為快取(Atlas 重新同步後可能改變)。

關係契約（強制）

RelationType	from	to
AFFECTS	Incident	System
MATCHES	Incident	Signature
BASED_ON	Signature	Metric
HANDLED_BY	Incident	Person
RESOLVED_BY	Incident	Remediation
CAUSED	Incident	Incident

連結端點型別錯誤時,會回傳明確錯誤。

測試

pytest

測試全程離線(mock Atlas client + 暫存檔儲存),不依賴任何外部服務或網路。

專案結構

src/kg_server/
  models.py       # pydantic 模型 + enums + 關係契約
  storage.py      # Storage protocol + JsonStorage(原子寫入) + MemoryStorage
  validation.py   # server 端驗證規則 + 型別化錯誤
  graph.py        # entity/relation CRUD、查詢、alias、追鏈、Atlas 配對
  atlas.py        # AtlasClient protocol + MockAtlasClient
  tools.py        # MCP 工具定義(薄封裝、結構化錯誤)
  server.py       # FastMCP 組裝 + stdio 進入點
  sources/        # 監控 / 資料庫來源整合(擴充點)
    prometheus.py # 功能完整:偵測門檻突破 -> 自動 create_incident
    db2.py        # 骨架 + mock:DB2 insight 報告增補
    mariadb.py    # 骨架 + mock:MariaDB(MMDB)狀態增補
skills/
  mmdb-troubleshooting/SKILL.md   # MMDB activelog / busy-ratio 排障手冊(規則)
tests/            # pytest 測試 + 合成 fixtures

來源整合（sources/）

每個來源都比照 AtlasClient 的樣式——一個 Protocol 介面加上離線的 Mock*—— 讓偵測/增補流程無需真實基礎設施即可完整測試。換成真實 client 時,圖譜與工具邏輯 完全不需更動。

• prometheus.py(功能完整): record_threshold_anomalies(graph, prom, system, rule, start, end) 會查詢序列、偵測「持續超過門檻」的突破(ThresholdRule), 並自動建立事件 + signature 連結。具冪等性(同一 system+start 不會重複建立)。這就是 目標 (1)+(2) 的示範:一個指標來源自動餵入圖譜。
• db2.py / mariadb.py(骨架): enrich_incident_with_* 把報告 / 狀態快照 併入既有事件(合併 metrics、findings 轉為 observation)。報告格式為待與團隊確認的 起始形狀。

上述流程引用的 MMDB signatures(如 mmdb.busy_ratio.sustained)記錄於 skills/mmdb-troubleshooting/SKILL.md ——規則歸 Skill,事件實例歸圖譜。

擴充點（仍待處理）

• 真實 AtlasClient,由 Atlas MCP 支撐(接回 Teams 對話)。
• 真實 PrometheusClient / Db2InsightClient / MariaDbClient(替換 mock)。
• 截圖辨識(vision/OCR)——屬於上層另一層處理。
• Signature 門檻——與 ops 確認 SKILL.md 中的 placeholder 數值。
• TKMSAPI 研究(spec 凍結,待其文件釋出)。
• 額外 Storage 後端(SqliteStorage、Neo4jStorage)——protocol 已抽象化,工具 邏輯不變。