# Quick Start Guide: 簡化版OnCall Runbook MCP伺服器
**版本**: 2.0.0
**功能**: 僅保留Answer工具的簡化版
**更新日期**: 2025-10-13
## 概述
簡化版OnCall Runbook MCP伺服器專注於提供核心的問答功能，移除了其他輔助工具以減少系統複雜性並提升效能。
## 主要變更
### ✅ 保留功能
- **rb.answer**: 核心問答工具，支援LLM整合和降級機制
- 完整的搜尋和索引功能
- 風險分類和安全操作識別
- 離線模式支援
- Runbook新鮮度檢查
### ❌ 移除功能
- `rb.search` - 搜尋工具（功能整合到answer中）
- `rb.read` - 讀取工具
- `rb.checklist` - 檢查清單工具
- `rb.commands` - 命令提取工具
- `rb.handoff` - 交接模板工具
- `rb.postmortem` - 事後檢討工具
## 快速安裝
### 前置需求
- Node.js 18+
- 現有的runbook目錄結構
- （可選）LLM API金鑰用於智能摘要
### 安裝步驟
1. **克隆並安裝**:
```bash
git clone <repository-url>
cd OnCallRunbookMCPServer
git checkout 002-tools-answer
npm install
```
2. **設定環境變數**:
```bash
# 必需：Runbook目錄
export RUNBOOK_ROOT="/path/to/your/runbooks"
# 可選：LLM API設定（支援優雅降級）
export LLM_API_KEY="your-api-key"
# 或使用 OPENAI_API_KEY, ANTHROPIC_API_KEY
export LLM_ENDPOINT="custom-endpoint" # 可選
```
3. **驗證安裝**:
```bash
npm test
node server.mjs
```
## 基本使用
### 啟動伺服器
```bash
node server.mjs
```
伺服器將在stdio模式下運行，適合MCP客戶端連接。
### 查詢可用工具
```json
{
"jsonrpc": "2.0",
"id": "1",
"method": "tools/list"
}
```
**回應**:
```json
{
"jsonrpc": "2.0",
"id": "1",
"result": {
"tools": [
{
"name": "rb.answer",
"description": "Answer questions about on-call procedures using runbook knowledge base with optional LLM summarization",
"inputSchema": {
"type": "object",
"properties": {
"question": {
"type": "string",
"description": "Question about procedures, troubleshooting, or system behavior"
},
"topK": {
"type": "number",
"description": "Number of relevant sources to consider (default: 5, max: 20)",
"minimum": 1,
"maximum": 20
},
"useLLM": {
"type": "boolean",
"description": "Whether to use LLM for summary generation (default: true)"
}
},
"required": ["question"]
}
}
]
}
}
```
### 問答查詢
#### 基本問題
```json
{
"jsonrpc": "2.0",
"id": "2",
"method": "tools/call",
"params": {
"name": "rb.answer",
"arguments": {
"question": "How do I restart the payment service?"
}
}
}
```
#### 進階查詢
```json
{
"jsonrpc": "2.0",
"id": "3",
"method": "tools/call",
"params": {
"name": "rb.answer",
"arguments": {
"question": "Database connection timeout troubleshooting",
"topK": 10,
"useLLM": true
}
}
}
```
### 回應格式
伺服器回應包含完整的問答信息：
```json
{
"jsonrpc": "2.0",
"id": "2",
"result": {
"content": [{
"type": "text",
"text": "{\n \"question\": \"How do I restart the payment service?\",\n \"mode\": \"online\",\n \"summary\": \"智能摘要內容...\",\n \"citations\": [...],\n \"risks\": {...},\n \"safe_operations\": [...],\n \"metadata\": {...}\n}"
}]
}
}
```
## 使用模式
### 線上模式 (Online)
- LLM服務可用
- 提供智能問題摘要
- 完整的上下文理解
### 離線模式 (Offline/Degraded)
- LLM服務不可用或設定為關閉
- 提供結構化的runbook引用
- 保持完整的安全分析和風險標示
### 無結果模式 (No Results)
- 找不到相關runbook內容
- 提供搜尋建議和相關主題
## 效能最佳化
### 記憶體使用
- 簡化架構減少約30%記憶體使用
- 工具載入時間減少約50%
### 回應時間目標
- **標準查詢**: <3秒（優先保證）
- **複雜查詢**: <5秒
- **P95目標**: 95%查詢在目標時間內完成
### 快取機制
- 自動tokenization快取
- 相同查詢快速回應
## 疑難排解
### 常見問題
**Q: 為什麼沒有其他工具了？**
A: 為了簡化系統並提升效能，移除了非核心工具。rb.answer工具整合了主要功能。
**Q: LLM不可用時還能使用嗎？**
A: 是的，系統支援優雅降級，會提供結構化的runbook引用和安全分析。
**Q: 如何恢復舊版本的所有工具？**
A: 切換到主分支：`git checkout main`
**Q: 效能是否真的有改善？**
A: 是的，測試顯示載入時間減少50%，記憶體使用減少30%。
### 除錯模式
```bash
# 啟用詳細日誌
DEBUG=1 node server.mjs
# 測試離線模式
NO_LLM=1 node server.mjs
# 檢查索引狀態
node -e "
const { SimpleMCPServer } = await import('./server.mjs');
const server = new SimpleMCPServer();
await server.initialize();
"
```
### 日誌監控
系統會記錄關鍵指標：
- 查詢處理時間
- LLM可用性狀態
- 引用來源數量
- 錯誤和警告
## 遷移指南
### 從完整版遷移
1. 確保備份現有設定
2. 切換到`002-tools-answer`分支
3. 測試核心問答功能
4. 更新客戶端代碼移除對舊工具的調用
### API相容性
- `rb.answer`工具API完全相容
- 回應格式無變更
- 所有參數和選項保持不變
## 支援與回饋
### 效能監控
系統會自動追蹤：
- 查詢匹配率
- 回應時間分布
- 記憶體和CPU使用
- 錯誤率
### 回報問題
提供以下資訊以便除錯：
- 查詢內容（去除敏感資訊）
- 回應時間
- 錯誤訊息
- 環境設定
### 功能建議
雖然專注於簡化，我們仍歡迎：
- 答案品質改善建議
- 效能優化想法
- 用戶體驗改進
