openapi: 3.0.3
info:
title: OnCall Runbook MCP Server - Answer Tool Only
version: 2.0.0
description: |
簡化版OnCall Runbook MCP服務器API，僅保留answer工具功能。
提供智能問答服務，支援LLM整合和優雅降級。
paths:
/tools/list:
post:
summary: 列出可用工具
description: 返回MCP服務器中可用的工具清單，簡化版僅包含rb.answer工具
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/MCPRequest'
example:
jsonrpc: "2.0"
id: "1"
method: "tools/list"
responses:
'200':
description: 成功返回工具清單
content:
application/json:
schema:
$ref: '#/components/schemas/ToolsListResponse'
example:
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"]
/tools/call:
post:
summary: 調用工具
description: 調用rb.answer工具進行問答
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ToolCallRequest'
examples:
basic_question:
summary: 基本問題
value:
jsonrpc: "2.0"
id: "2"
method: "tools/call"
params:
name: "rb.answer"
arguments:
question: "How do I restart the payment service?"
advanced_question:
summary: 進階查詢
value:
jsonrpc: "2.0"
id: "3"
method: "tools/call"
params:
name: "rb.answer"
arguments:
question: "Database connection timeout troubleshooting"
topK: 10
useLLM: true
responses:
'200':
description: 成功返回問答結果
content:
application/json:
schema:
$ref: '#/components/schemas/AnswerResponse'
examples:
online_mode:
summary: 線上模式回應
value:
jsonrpc: "2.0"
id: "2"
result:
content:
- type: "text"
text: |
{
"question": "How do I restart the payment service?",
"mode": "online",
"summary": "To restart the payment service, first check current status, then use systemctl restart payment-service, and verify the restart was successful.",
"citations": [
{
"doc_id": "payment-service-runbook.md",
"title": "Payment Service Operations",
"score": 0.95,
"snippet": "## Service Restart Procedure\n\n1. Check current status: `systemctl status payment-service`\n2. Stop service: `systemctl stop payment-service`",
"heading": "Service Restart Procedure",
"stale": false,
"risk_level": "MEDIUM"
}
],
"risks": {
"operations": ["systemctl restart payment-service"],
"warning": "CAUTION: Risk operations identified. Verify rollback procedures before execution."
},
"safe_operations": ["systemctl status payment-service"],
"metadata": {
"sources_found": 3,
"sources_used": 1,
"conflicts_resolved": 0,
"llm_available": true
}
}
offline_mode:
summary: 離線模式回應
value:
jsonrpc: "2.0"
id: "3"
result:
content:
- type: "text"
text: |
{
"question": "How do I restart the payment service?",
"mode": "offline",
"summary": "",
"citations": [
{
"doc_id": "payment-service-runbook.md",
"title": "Payment Service Operations",
"score": 0.95,
"snippet": "## Service Restart Procedure\n\n1. Check current status...",
"heading": "Service Restart Procedure",
"stale": false,
"risk_level": "MEDIUM"
}
],
"risks": {
"operations": ["systemctl restart payment-service"],
"warning": "CAUTION: Risk operations identified. Verify rollback procedures before execution."
},
"safe_operations": ["systemctl status payment-service"],
"metadata": {
"sources_found": 3,
"sources_used": 1,
"conflicts_resolved": 0,
"llm_available": false
},
"message": "Operating in offline mode. Citations reference the most relevant runbook sections for your question."
}
no_results:
summary: 無結果回應
value:
jsonrpc: "2.0"
id: "4"
result:
content:
- type: "text"
text: |
{
"question": "How to configure quantum computing?",
"mode": "no_results",
"summary": "",
"citations": [],
"risks": {
"operations": [],
"warning": null
},
"safe_operations": [],
"metadata": {
"sources_found": 0,
"sources_used": 0,
"conflicts_resolved": 0,
"llm_available": true
},
"message": "No relevant runbook content found. Consider rephrasing your question or checking related topics: [service management, troubleshooting, configuration]"
}
'400':
description: 請求錯誤
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
description: 服務器內部錯誤
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/initialize:
post:
summary: 初始化MCP連線
description: MCP協定初始化端點
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InitializeRequest'
responses:
'200':
description: 初始化成功
content:
application/json:
schema:
$ref: '#/components/schemas/InitializeResponse'
components:
schemas:
MCPRequest:
type: object
required: [jsonrpc, id, method]
properties:
jsonrpc:
type: string
enum: ["2.0"]
id:
oneOf:
- type: string
- type: number
method:
type: string
ToolsListResponse:
type: object
required: [jsonrpc, id, result]
properties:
jsonrpc:
type: string
enum: ["2.0"]
id:
oneOf:
- type: string
- type: number
result:
type: object
required: [tools]
properties:
tools:
type: array
items:
$ref: '#/components/schemas/ToolDefinition'
ToolDefinition:
type: object
required: [name, description, inputSchema]
properties:
name:
type: string
description:
type: string
inputSchema:
type: object
ToolCallRequest:
type: object
required: [jsonrpc, id, method, params]
properties:
jsonrpc:
type: string
enum: ["2.0"]
id:
oneOf:
- type: string
- type: number
method:
type: string
enum: ["tools/call"]
params:
type: object
required: [name, arguments]
properties:
name:
type: string
enum: ["rb.answer"]
arguments:
$ref: '#/components/schemas/AnswerArguments'
AnswerArguments:
type: object
required: [question]
properties:
question:
type: string
minLength: 1
maxLength: 1000
description: "Question about procedures, troubleshooting, or system behavior"
topK:
type: integer
minimum: 1
maximum: 20
default: 5
description: "Number of relevant sources to consider"
useLLM:
type: boolean
default: true
description: "Whether to use LLM for summary generation"
AnswerResponse:
type: object
required: [jsonrpc, id, result]
properties:
jsonrpc:
type: string
enum: ["2.0"]
id:
oneOf:
- type: string
- type: number
result:
type: object
required: [content]
properties:
content:
type: array
items:
type: object
required: [type, text]
properties:
type:
type: string
enum: ["text"]
text:
type: string
description: "JSON formatted answer response"
Citation:
type: object
required: [doc_id, title, score, snippet, stale, risk_level]
properties:
doc_id:
type: string
description: "Document unique identifier"
title:
type: string
description: "Document title"
score:
type: number
minimum: 0
maximum: 1
description: "Relevance score"
snippet:
type: string
maxLength: 200
description: "Text excerpt"
heading:
type: string
description: "Section heading"
stale:
type: boolean
description: "Whether content is stale"
risk_level:
type: string
enum: ["LOW", "MEDIUM", "HIGH", "UNKNOWN"]
description: "Risk level assessment"
RiskAssessment:
type: object
required: [operations]
properties:
operations:
type: array
items:
type: string
description: "List of risky operations"
warning:
type: string
nullable: true
description: "Warning message for risky operations"
ResponseMetadata:
type: object
required: [sources_found, sources_used, conflicts_resolved, llm_available]
properties:
sources_found:
type: integer
minimum: 0
description: "Number of sources found"
sources_used:
type: integer
minimum: 0
description: "Number of sources actually used"
conflicts_resolved:
type: integer
minimum: 0
description: "Number of conflicts resolved"
llm_available:
type: boolean
description: "Whether LLM service is available"
InitializeRequest:
type: object
required: [jsonrpc, id, method, params]
properties:
jsonrpc:
type: string
enum: ["2.0"]
id:
oneOf:
- type: string
- type: number
method:
type: string
enum: ["initialize"]
params:
type: object
properties:
protocolVersion:
type: string
capabilities:
type: object
InitializeResponse:
type: object
required: [jsonrpc, id, result]
properties:
jsonrpc:
type: string
enum: ["2.0"]
id:
oneOf:
- type: string
- type: number
result:
type: object
required: [protocolVersion, capabilities, serverInfo]
properties:
protocolVersion:
type: string
example: "2024-11-05"
capabilities:
type: object
properties:
tools:
type: object
serverInfo:
type: object
required: [name, version]
properties:
name:
type: string
example: "oncall-runbook-server"
version:
type: string
example: "2.0.0"
ErrorResponse:
type: object
required: [jsonrpc, id, error]
properties:
jsonrpc:
type: string
enum: ["2.0"]
id:
oneOf:
- type: string
- type: number
- type: "null"
error:
type: object
required: [code, message]
properties:
code:
type: integer
message:
type: string
data:
type: object
