OnCall Runbook MCP Server

# OnCall Runbook MCP Server 使用指南 ## 🚀 快速開始 ### 1. 系統要求 - Node.js 14+ (已測試 v14.21.3) - PowerShell 或 Bash - Claude Desktop ### 2. 安裝與設置 #### 步驟 1: 準備 Runbook 目錄 ```bash # 將您的 runbook 文件放在專用目錄中 mkdir runbooks ``` #### 步驟 2: Runbook 格式 每個 runbook 文件必須包含 frontmatter： ```markdown --- title: Database Connection Timeout Troubleshooting category: database severity: P2 keywords: database, connection, timeout, postgresql last_updated: 2025-10-13 version: "1.0" --- # Database Connection Timeout ## Symptoms - Application throws connection timeout errors - Database pool exhausted warnings ## Initial Diagnosis 1. Check connection pool utilization 2. Review active connections 3. Analyze slow query logs ## Safe Operations - `SHOW PROCESSLIST` - Check running queries - Monitor connection metrics - Review application logs ## Risk Operations - Restart database service ⚠️ - Kill long-running queries ⚠️ - Failover to replica ⚠️ ``` #### 步驟 3: 配置 Claude Desktop 編輯 Claude Desktop 配置檔案，加入以下設定： **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` **Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json` ```json { "mcpServers": { "oncall-runbook": { "command": "node", "args": ["F:\\mcpTest\\OnCallRunbookMCPServer\\server-simple.mjs"], "env": { "RUNBOOK_ROOT": "F:\\mcpTest\\OnCallRunbookMCPServer\\runbooks", "LLM_API_KEY": "your-api-key-here" } } } } ``` #### 步驟 4: 重啟 Claude Desktop 關閉並重新啟動 Claude Desktop 以載入 MCP 伺服器。 ## 🛠️ 可用工具 ### 🔍 rb.search - 搜尋 Runbook ``` 搜尋資料庫連線問題的相關文件 ``` ### 📖 rb.read - 閱讀文件 ``` 讀取 database-connection-timeout.md 的完整內容 ``` ### ✅ rb.checklist - 診斷清單 ``` 給我網路延遲問題的診斷步驟清單 ``` ### ⚡ rb.commands - 指令分類 ``` 提取重啟資料庫服務的相關指令並分類風險等級 ``` ### 🤖 rb.answer - 智能問答 ``` 如何處理 HTTP 5xx 錯誤率突增？請提供詳細的解決方案 ``` ### 🤝 rb.handoff - 事件交接 ``` 為資料庫效能問題生成交接文件 ``` ### 📋 rb.postmortem - 事後檢討 ``` 為昨天的服務中斷事件生成事後檢討模板 ``` ## 🎯 使用範例 ### 範例 1: 故障排除工作流程 ``` 使用者: "我的網站回應很慢，幫我診斷可能的原因" Claude 會： 1. 使用 rb.search 搜尋相關 runbook 2. 使用 rb.checklist 生成診斷步驟 3. 使用 rb.commands 提取安全的檢查指令 4. 提供結構化的故障排除指南 ``` ### 範例 2: 事件處理 ``` 使用者: "幫我處理資料庫連線超時問題並生成交接文件" Claude 會： 1. 搜尋相關程序 2. 提供診斷步驟 3. 分類安全和風險操作 4. 生成結構化的交接文件 ``` ## 🔧 測試驗證 ### 手動測試 ```bash # 設定環境變數 $env:RUNBOOK_ROOT = "F:\mcpTest\OnCallRunbookMCPServer\runbooks" # 測試伺服器啟動 node server-simple.mjs # 應該看到： # {"event":"server.init","status":"starting"} # {"event":"server.index","documents":3,"chunks":10} # {"event":"server.tool.registered","name":"rb.search"} # ... 其他工具註冊訊息 ``` ### 自動測試 ```bash node test-mcp-simple.mjs ``` ## 📊 效能指標 基準測試結果 (300 文檔規模)： - **P95 延遲**: 13ms - **平均回應**: 10ms - **索引建構**: 290ms - **快取效能提升**: 50%+ ## 🚨 故障排除 ### 常見問題 **問題**: "Cannot find module" 錯誤 ```bash # 解決方案：安裝依賴 npm install ``` **問題**: "RUNBOOK_ROOT required" 錯誤 ```bash # 解決方案：設定環境變數 $env:RUNBOOK_ROOT = "path/to/your/runbooks" ``` **問題**: Claude Desktop 無法連線 1. 檢查 claude_desktop_config.json 路徑是否正確 2. 確認檔案路徑使用正斜線或雙反斜線 3. 重啟 Claude Desktop **問題**: 找不到 runbook 1. 檢查 runbook 檔案是否包含正確的 frontmatter 2. 確認檔案為 .md 格式 3. 檢查 RUNBOOK_ROOT 路徑 ## 🏆 生產部署 ### 建議配置 - 使用專用 runbooks 目錄 - 定期更新 runbook 內容 - 監控伺服器性能日誌 - 設定適當的 LLM API 限制 ### 擴展功能 - 新增更多 runbook 類別 - 整合監控系統 - 自動化工作流程 - 團隊協作功能 ## 📈 架構特色 - **離線優先**: 無需外部 API 即可運行 - **優雅降級**: LLM 不可用時自動降級 - **高效能**: P95 < 20ms，支援大規模 runbook 庫 - **模組化**: 清潔分層架構，易於擴展 - **生產就緒**: 完整錯誤處理和日誌記錄 現在您就可以開始使用 OnCall Runbook MCP Server 了！🎉