openapi: 3.1.0
info:
title: On-Call Runbook MCP Server API (Planned)
version: 0.1.0
description: >
Draft contract derived from functional requirements FR-001..FR-020.
MCP 工具會包裝這些邏輯；此為內部抽象接口（非公開 HTTP）雛形，方便後續若需外部化。
servers: []
paths:
/search:
get:
summary: Runbook 檢索 (FR-001)
parameters:
- name: q
in: query
required: true
schema:
type: string
- name: topK
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 20
default: 5
responses:
'200':
description: 搜尋結果
content:
application/json:
schema:
type: object
properties:
query: { type: string }
topK: { type: integer }
results:
type: array
items:
type: object
properties:
path: { type: string }
score: { type: number }
headingPath: { type: string }
snippet: { type: string }
stale: { type: boolean }
warnings:
type: array
items: { type: string }
/answer:
post:
summary: 問答整合 (FR-008, FR-007, FR-015, FR-018)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
question: { type: string }
topK:
type: integer
minimum: 1
maximum: 20
default: 5
useLLM:
type: boolean
default: false
responses:
'200':
description: 回答結果
content:
application/json:
schema:
type: object
properties:
question: { type: string }
summary: { type: [ 'string', 'null' ] }
citations:
type: array
items:
type: object
properties:
path: { type: string }
chunkIndex: { type: integer }
chunks:
type: array
items:
type: object
properties:
path: { type: string }
chunkIndex: { type: integer }
text: { type: string }
score: { type: number }
safe_ops:
type: array
items: { type: string }
risk_ops:
type: array
items:
type: object
properties:
command: { type: string }
rollbackHint: { type: string }
warnings:
type: array
items: { type: string }
staleFlag: { type: boolean }
secondarySources:
type: array
items: { type: string }
result_class:
type: string
enum: [ ANSWERED, ESCALATE, STALE, ERROR ]
/checklist:
get:
summary: 擷取初步診斷與緩解步驟 (FR-004)
parameters:
- name: path
in: query
required: true
schema: { type: string }
responses:
'200':
description: Checklist 結果
content:
application/json:
schema:
type: object
properties:
path: { type: string }
diagnosis: { type: array, items: { type: string } }
mitigation: { type: array, items: { type: string } }
warnings: { type: array, items: { type: string } }
/commands:
get:
summary: 指令分類 (FR-005, FR-015, FR-019)
parameters:
- name: path
in: query
required: true
schema: { type: string }
responses:
'200':
description: 指令分類結果
content:
application/json:
schema:
type: object
properties:
path: { type: string }
safe_ops: { type: array, items: { type: string } }
risk_ops:
type: array
items:
type: object
properties:
command: { type: string }
rollbackHint: { type: string }
warnings: { type: array, items: { type: string } }
/severity:
post:
summary: 嚴重度建議 (FR-006)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
symptom: { type: string }
responses:
'200':
description: 建議 SEV
content:
application/json:
schema:
type: object
properties:
suggested_sev: { type: string }
matched_keywords: { type: array, items: { type: string } }
escalation_contacts: { type: array, items: { type: string } }
/handoff:
post:
summary: 交接模板 (FR-013)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
incident_summary: { type: string }
executed_steps: { type: array, items: { type: string } }
responses:
'200':
description: 交接模板
content:
application/json:
schema:
type: object
properties:
statusSummary: { type: string }
executedSteps: { type: array, items: { type: string } }
residualRisks: { type: array, items: { type: string } }
nextActions: { type: array, items: { type: string } }
/postmortem:
post:
summary: 事後檢討模板 (FR-014)
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
incident: { type: string }
impact: { type: string }
responses:
'200':
description: PM 模板
content:
application/json:
schema:
type: object
properties:
overview: { type: string }
impact: { type: string }
timeline: { type: array, items: { type: object, properties: { ts: { type: string }, note: { type: string } } } }
actionItems: { type: array, items: { type: string } }
rootCause: { type: [ 'string', 'null' ] }
components: {}
