📝 docs: comprehensive MCP usage guide (fb-31)
신규 docs/mcp-usage.md (~280 line) — agent integration 의 종합 가이드: - Quick start + `--config` thread 예시 - Host config 예시 (Claude Code / Cursor / OpenAI Agents / Copilot CLI) - 6 tool catalog (search / ask / schema / doctor / ingest_file / ingest_stdin) 각 tool 의 input shape, defaults, output 예시, "언제 사용", mutation 주의사항. - Troubleshooting — error.v1 의 7 code 별 조치 표 + grounded:false + doctor !ok + empty search + tool-not-found 시나리오. - Multi-turn ask + session 관리 — session_id 명명, 새 session 시작 시점, lifetime, single-shot vs session 비교. - Performance / Security 절. README.md 의 기존 MCP 절은 quick start 만 유지하고 docs/mcp-usage.md 링크. integrations/claude-code/kebab/SKILL.md 도 동일 cross-link. agent 사용자 도그푸딩 후속 의견 — host-agnostic 가이드 + 명시적 troubleshooting 표 + multi-turn session 명명 컨벤션 부재 해소. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
th-kim0823
486
docs/mcp-usage.md
Normal file
486
docs/mcp-usage.md
Normal file
@@ -0,0 +1,486 @@
|
||||
# MCP usage — agent integration guide
|
||||
|
||||
`kebab mcp` runs an MCP (Model Context Protocol) stdio JSON-RPC server. agent host (Claude Code / Cursor / OpenAI Agents / Copilot CLI 등) 가 본 binary 를 spawn 하여 KB 검색 / 답변 / ingest 를 호출.
|
||||
|
||||
shipped since **v0.3.1** (fb-30). 6 tool 으로 확장 (v0.3.2, fb-31).
|
||||
|
||||
---
|
||||
|
||||
## Quick start
|
||||
|
||||
binary 를 PATH 에 두고 (`cargo install --path crates/kebab-cli` 또는 release tarball), agent host 의 mcp config 에 등록:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"kebab": {
|
||||
"command": "kebab",
|
||||
"args": ["mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
session 시작 시 host 가 `kebab mcp` 를 spawn — process 가 session 동안 살아 있어 SQLite / Lance / fastembed 가 hot. 첫 tool call 만 cold-start 비용, 이후 sub-100ms.
|
||||
|
||||
`--config` 옵션 thread:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"kebab": {
|
||||
"command": "kebab",
|
||||
"args": ["--config", "/Users/me/.config/kebab/agent.toml", "mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Host config 예시
|
||||
|
||||
### Claude Code
|
||||
|
||||
`~/.claude/mcp.json` (또는 OS 별 동등 위치):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"kebab": {
|
||||
"command": "kebab",
|
||||
"args": ["mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
session 재시작 후 `kebab` server 가 tool list 에 등장. agent 가 `mcp__kebab__search` / `mcp__kebab__ask` 등 호출 가능.
|
||||
|
||||
### Cursor
|
||||
|
||||
`~/.cursor/mcp.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"kebab": {
|
||||
"command": "kebab",
|
||||
"args": ["mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Cursor 의 Composer / Agent 모드에서 활성화.
|
||||
|
||||
### OpenAI Agents (`agents-sdk`)
|
||||
|
||||
Python:
|
||||
|
||||
```python
|
||||
from openai_agents import Agent, MCPServerStdio
|
||||
|
||||
kebab = MCPServerStdio(
|
||||
name="kebab",
|
||||
params={"command": "kebab", "args": ["mcp"]},
|
||||
)
|
||||
|
||||
agent = Agent(
|
||||
name="researcher",
|
||||
mcp_servers=[kebab],
|
||||
)
|
||||
```
|
||||
|
||||
Node:
|
||||
|
||||
```ts
|
||||
import { Agent, MCPServerStdio } from "openai-agents";
|
||||
|
||||
const kebab = new MCPServerStdio({
|
||||
name: "kebab",
|
||||
params: { command: "kebab", args: ["mcp"] },
|
||||
});
|
||||
|
||||
const agent = new Agent({ name: "researcher", mcpServers: [kebab] });
|
||||
```
|
||||
|
||||
### Copilot CLI
|
||||
|
||||
`~/.config/copilot-cli/mcp.json` (or wherever the CLI looks):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"kebab": {
|
||||
"command": "kebab",
|
||||
"args": ["mcp"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 기타 host
|
||||
|
||||
stdio JSON-RPC MCP 표준을 따르는 모든 host 가 지원. 위 형식 (`command` + `args`) 만 맞추면 동작.
|
||||
|
||||
---
|
||||
|
||||
## Tool catalog (6 tools)
|
||||
|
||||
모든 tool 의 출력은 wire schema v1 JSON 을 MCP `text` content block 으로 직렬화. CLI `--json` 모드와 byte-동일 (single source of truth).
|
||||
|
||||
### `search` — corpus 검색
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Input | `{ "query": string, "mode"?: "lexical"\|"vector"\|"hybrid", "k"?: 1-100 }` |
|
||||
| Defaults | `mode = "hybrid"`, `k = 10` |
|
||||
| Output | `search_hit.v1` array, ranked |
|
||||
|
||||
예시:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "search",
|
||||
"arguments": {
|
||||
"query": "Kubernetes ingress controller setup",
|
||||
"mode": "hybrid",
|
||||
"k": 5
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
응답 (한 hit 발췌):
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"schema_version": "search_hit.v1",
|
||||
"rank": 1,
|
||||
"score": 0.847,
|
||||
"doc_id": "...",
|
||||
"chunk_id": "...",
|
||||
"doc_path": "k8s/ingress.md",
|
||||
"heading_path": ["Setup", "Ingress controller"],
|
||||
"snippet": "...",
|
||||
"citation": { ... }
|
||||
},
|
||||
...
|
||||
]
|
||||
```
|
||||
|
||||
**언제 사용**: 사용자가 \"문서 어디 있는지\" 묻거나, agent 가 답변 전 raw chunk 가 필요할 때.
|
||||
|
||||
### `ask` — RAG 답변
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Input | `{ "query": string, "session_id"?: string, "mode"?: "lexical"\|"vector"\|"hybrid" }` |
|
||||
| Defaults | `mode = "hybrid"` |
|
||||
| Output | `answer.v1` (single object) |
|
||||
|
||||
예시:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "ask",
|
||||
"arguments": {
|
||||
"query": "What's our internal Kubernetes ingress setup?",
|
||||
"session_id": "ops-onboarding-2026-05"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
응답:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "answer.v1",
|
||||
"answer": "...",
|
||||
"citations": [ ... ],
|
||||
"grounded": true,
|
||||
"refusal_reason": null,
|
||||
"model": { ... },
|
||||
"conversation_id": "...",
|
||||
"turn_index": 0
|
||||
}
|
||||
```
|
||||
|
||||
**`grounded: false` 처리**: KB 에 충분한 context 없음. `refusal_reason` 확인 후 사용자에게 \"KB 에 정보 없음\" 으로 안내, 본인 지식 fallback 또는 source 요청. **paraphrase 하면 안 됨** (hallucination 위험).
|
||||
|
||||
multi-turn 은 [Session 관리](#session-관리-multi-turn-ask) 참조.
|
||||
|
||||
### `schema` — capability discovery
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Input | `{}` (no args) |
|
||||
| Output | `schema.v1` |
|
||||
|
||||
예시:
|
||||
|
||||
```json
|
||||
{ "name": "schema", "arguments": {} }
|
||||
```
|
||||
|
||||
응답:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "schema.v1",
|
||||
"kebab_version": "0.3.2",
|
||||
"wire": { "schemas": ["answer.v1", "search_hit.v1", ...] },
|
||||
"capabilities": {
|
||||
"json_mode": true,
|
||||
"rag_multi_turn": true,
|
||||
"mcp_server": true,
|
||||
"streaming_ask": false,
|
||||
...
|
||||
},
|
||||
"models": { "parser_version": "...", "embedding_version": "...", ... },
|
||||
"stats": { "doc_count": 128, "chunk_count": 2147, "asset_count": 130, ... }
|
||||
}
|
||||
```
|
||||
|
||||
**언제 사용**: session 시작 시 한 번 — feature gate 결정 (`capabilities.streaming_ask` true 면 streaming 사용 등). cheap call (no LLM, no embedder), session 동안 1 회 충분.
|
||||
|
||||
### `doctor` — health check
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Input | `{}` (no args) |
|
||||
| Output | `doctor.v1` |
|
||||
|
||||
예시:
|
||||
|
||||
```json
|
||||
{ "name": "doctor", "arguments": {} }
|
||||
```
|
||||
|
||||
응답:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "doctor.v1",
|
||||
"ok": true,
|
||||
"checks": [
|
||||
{ "name": "config_loaded", "ok": true, "detail": "..." },
|
||||
{ "name": "ollama_reachable", "ok": true, "detail": "..." },
|
||||
...
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**언제 사용**: 다른 tool 이 실패하거나 비정상 응답 줄 때 first triage. `ok: false` 면 `checks[]` 의 failed entry 가 원인 — 사용자에게 보고 후 stop (자동 retry 금지).
|
||||
|
||||
### `ingest_file` — 단일 파일 저장 (mutation)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Input | `{ "path": string }` |
|
||||
| Supported ext | `.md` / `.pdf` / `.png` / `.jpg` / `.jpeg` (`unsupported extension` error 그 외) |
|
||||
| Output | `ingest_report.v1` (single asset) |
|
||||
|
||||
예시:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "ingest_file",
|
||||
"arguments": { "path": "/Users/me/Downloads/article.md" }
|
||||
}
|
||||
```
|
||||
|
||||
응답:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "ingest_report.v1",
|
||||
"scanned": 1,
|
||||
"new": 1,
|
||||
"updated": 0,
|
||||
"unchanged": 0,
|
||||
"skipped": 0,
|
||||
"errors": 0,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**언제 사용**: 사용자가 disk 의 file 을 KB 에 저장 의향 명시 시. workspace 외부 path OK — 파일은 `<workspace.root>/_external/<hash12>.<ext>` 으로 copy. 동일 content 재 ingest 면 idempotent (`unchanged: 1`).
|
||||
|
||||
**주의**: mutation tool — 사용자 명시 의도 없을 때 자동 호출 금지.
|
||||
|
||||
### `ingest_stdin` — stdin markdown 저장 (mutation)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Input | `{ "content": string, "title": string, "source_uri"?: string }` |
|
||||
| v1 scope | markdown only |
|
||||
| Output | `ingest_report.v1` (single asset) |
|
||||
|
||||
예시:
|
||||
|
||||
```json
|
||||
{
|
||||
"name": "ingest_stdin",
|
||||
"arguments": {
|
||||
"content": "## Article body\n\nMain text here.",
|
||||
"title": "Article X",
|
||||
"source_uri": "https://example.com/x"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
응답:
|
||||
|
||||
```json
|
||||
{
|
||||
"schema_version": "ingest_report.v1",
|
||||
"scanned": 1,
|
||||
"new": 1,
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
**언제 사용**: agent 가 web fetch 한 markdown article 을 KB 에 저장. 사용자가 \"이거 나중에 또 보고 싶어\" 명시 시 또는 multi-turn 대화에서 자료 누적. content 가 이미 frontmatter (`---` 시작) 이면 error — `ingest_file` 사용.
|
||||
|
||||
`title` + `source_uri` 가 frontmatter 로 자동 prepend → `Document.metadata` 에 저장 → 후속 `search` 결과의 `doc_meta` 에 포함. agent 가 source URL 추적 가능.
|
||||
|
||||
**주의**: mutation tool. 같은 content 무한 ingest 안 함 (idempotent 보장이지만 embedding cost 낭비).
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### `isError: true` + `error.v1` content
|
||||
|
||||
tool dispatch 가 `Err` 반환 시. content 의 `error.v1` JSON 의 `code` 로 분기:
|
||||
|
||||
| code | 의미 | 조치 |
|
||||
|------|------|------|
|
||||
| `config_invalid` | `--config` path missing / TOML parse 실패 | path 확인 + `kebab schema` 로 검증. `details.path` + `details.cause` 확인. |
|
||||
| `not_indexed` | `kebab.sqlite` 미존재 / migration 미실행 | 사용자에게 `kebab init` + `kebab ingest` 실행 안내. retry 자동 금지. |
|
||||
| `model_unreachable` | Ollama endpoint 연결 실패 | Ollama 실행 확인 (`ollama serve`). `details.endpoint` 의 host 가 reachable 한지. retry 1-2 회 후 사용자 보고. |
|
||||
| `model_not_pulled` | Ollama model not found | 사용자에게 `ollama pull <model>` 안내 — `details.model` 표시. |
|
||||
| `timeout` | LLM stream / embed deadline 초과 | 일시적이면 retry 1 회. 재발 시 사용자 보고 (model 응답 느림 / Ollama load). |
|
||||
| `io_error` | filesystem / 권한 / disk full | `details.kind` 보고 사용자에게 disk space / permission 확인 안내. |
|
||||
| `generic` | catch-all | `details.chain` (verbose 시) 보고 사용자에게 그대로 전달. retry 금지. |
|
||||
|
||||
`hint` field 가 있으면 사용자에게 그대로 보여주기 (각 code 의 가장 빠른 조치).
|
||||
|
||||
### `grounded: false` (ask refusal)
|
||||
|
||||
`isError: false` (정상 응답). KB 에 충분한 context 없음. `refusal_reason` 확인 후:
|
||||
|
||||
- `NoChunks` — 검색 자체가 0 hit. 다른 표현 / 더 일반적인 query 시도.
|
||||
- `LowScores` — hit 있지만 score gate 미달. `kebab search` (별도) 로 raw hit 확인.
|
||||
- 그 외 — refusal 메시지 그대로 사용자에게 보고.
|
||||
|
||||
자동 paraphrase 금지. 사용자에게 \"KB 에 정보 없음\" 명시 후 본인 지식 또는 source 요청.
|
||||
|
||||
### `doctor` `ok: false`
|
||||
|
||||
다른 tool 호출 전 `doctor` 부터. `checks[]` 의 failed entry 원인 명시 — 사용자에게 보고 후 stop.
|
||||
|
||||
### empty `search` result
|
||||
|
||||
`isError: false`, content = `[]` (빈 array). KB 에 매칭 없음. `mode` 변경 (lexical → vector or vice versa) 또는 query 표현 다양화. 그래도 빈 결과면 KB coverage 부족 — 사용자에게 보고.
|
||||
|
||||
### tool not found
|
||||
|
||||
`tools/list` 에서 본 binary 의 6 tool 확인. 0.3.1 (fb-30) 은 4 tool, 0.3.2 (fb-31) 부터 6. binary version 확인:
|
||||
|
||||
```json
|
||||
{ "name": "schema", "arguments": {} }
|
||||
```
|
||||
|
||||
응답의 `kebab_version` 이 0.3.2+ 인지 확인.
|
||||
|
||||
---
|
||||
|
||||
## Session 관리 (multi-turn ask)
|
||||
|
||||
`ask` tool 의 `session_id` 가 multi-turn RAG context 활성화. 같은 `session_id` 로 연속 호출 시 이전 Q/A history 가 새 query 의 retrieval expansion + prompt context 에 포함.
|
||||
|
||||
### session_id 명명
|
||||
|
||||
`<topic>-<date>` 형식 권장 — 사용자 친화 + uniqueness:
|
||||
|
||||
- `ops-onboarding-2026-05`
|
||||
- `kubernetes-ingress-debug-2026-05-07`
|
||||
- `agent-research-session-1` (auto-numbered)
|
||||
|
||||
session_id 는 임의 string — kebab 이 처음 보는 id 면 새 session 생성, 기존 id 면 history append.
|
||||
|
||||
### 언제 새 session 시작?
|
||||
|
||||
- 주제 완전 전환 (KB 의 다른 도메인) — 이전 history 가 noise.
|
||||
- 사용자 명시 reset 요청.
|
||||
- Long session (50+ turn) 의 context bloat — 새 session 으로 fresh start.
|
||||
|
||||
### Session lifetime
|
||||
|
||||
session 데이터는 SQLite `chat_sessions` + `chat_turns` 에 영속. `kebab reset --data-only` 가 모두 wipe. session 별 삭제 명령은 없음 (P+).
|
||||
|
||||
### 예시 multi-turn flow
|
||||
|
||||
```json
|
||||
// turn 1
|
||||
{ "name": "ask", "arguments": {
|
||||
"query": "What's our internal Kubernetes ingress setup?",
|
||||
"session_id": "ops-2026-05"
|
||||
}}
|
||||
// → answer.v1 with conversation_id, turn_index: 0
|
||||
|
||||
// turn 2 — 이전 답변을 context 로 retrieval expansion
|
||||
{ "name": "ask", "arguments": {
|
||||
"query": "What about TLS?",
|
||||
"session_id": "ops-2026-05"
|
||||
}}
|
||||
// → kebab 가 "TLS" 만으로 retrieval 안 함, 이전 \"Kubernetes ingress\" history 포함 query 로 검색
|
||||
|
||||
// turn 3 — 명시적 reference
|
||||
{ "name": "ask", "arguments": {
|
||||
"query": "How does that compare to AWS ALB?",
|
||||
"session_id": "ops-2026-05"
|
||||
}}
|
||||
```
|
||||
|
||||
### Session vs single-shot
|
||||
|
||||
`session_id` 없이 `ask` 호출 = single-shot. agent host 자체가 conversation 추적하면 single-shot + agent-side context 도 OK. session 이 필요한 경우:
|
||||
|
||||
- KB 가 \"이전 질문\" 을 retrieval expansion 에 사용해야 정확 (e.g. follow-up 의 대명사).
|
||||
- 한 session 안에서 같은 chunk 반복 fetch 회피 (kebab 가 turn 간 chunk overlap 인지).
|
||||
|
||||
agent host 가 conversation 추적 + 충분한 context 보유면 session 불필요.
|
||||
|
||||
---
|
||||
|
||||
## Performance
|
||||
|
||||
- **첫 tool call**: cold start ~1-2s (SQLite open + Lance dataset open + fastembed model load).
|
||||
- **이후 tool call (same session)**: hot — search ~50-200ms, ask ~수 초 (Ollama LLM dominant).
|
||||
- **session 종료** (host 가 process kill): 모든 cache lost. 다음 session 첫 call 다시 cold.
|
||||
- **`schema` / `doctor`**: cheap (no LLM / no embedder), 매 call ~ms.
|
||||
- **`ingest_file` / `ingest_stdin`**: 첫 call 시 fastembed cold start. 이후 file 당 ~수 백 ms (parse + chunk + embed).
|
||||
|
||||
cold-start 회피하려면 host 가 long-running session 유지 (Claude Code default).
|
||||
|
||||
---
|
||||
|
||||
## Security
|
||||
|
||||
- stdio MCP — 외부 네트워크 노출 없음. agent host 만 access.
|
||||
- `kebab mcp` 가 호출하는 facade 는 `--config` 의 권한으로 동작. config 내 secret (Ollama API key 등) 은 process 환경에 한정.
|
||||
- mutation tool (`ingest_file` / `ingest_stdin`) 는 사용자 명시 의도 없이 자동 호출 금지 — agent 측 가드.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- CLI usage: `kebab --help` + [README.md](../README.md)
|
||||
- Wire schemas: `docs/wire-schema/v1/*.schema.json`
|
||||
- design contract: `docs/superpowers/specs/2026-04-27-kebab-final-form-design.md` §10.2
|
||||
- Claude Code 전용 skill: `integrations/claude-code/kebab/SKILL.md`
|
||||
- HOTFIXES (post-merge deviations): `tasks/HOTFIXES.md`
|
||||
Reference in New Issue
Block a user