📝 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
@@ -166,9 +166,11 @@ config 예시는 [docs/SMOKE.md](docs/SMOKE.md) 의 `/tmp/kebab-smoke/config.tom
|
|||||||
- **MCP server** — stdio JSON-RPC 로 `kebab-app` facade 1:1 노출. `kebab mcp` 참조.
|
- **MCP server** — stdio JSON-RPC 로 `kebab-app` facade 1:1 노출. `kebab mcp` 참조.
|
||||||
- **HTTP wrapper** — `kebab serve --bind 127.0.0.1:7711` (P+, local-only 가치 신중).
|
- **HTTP wrapper** — `kebab serve --bind 127.0.0.1:7711` (P+, local-only 가치 신중).
|
||||||
|
|
||||||
## MCP 사용 (Claude Code 예시)
|
## MCP 사용
|
||||||
|
|
||||||
`~/.claude/mcp.json` (또는 host 의 동등 위치):
|
`kebab mcp` 가 stdio MCP server. 6 tool: `search` / `ask` / `schema` / `doctor` / `ingest_file` / `ingest_stdin`.
|
||||||
|
|
||||||
|
Claude Code 빠른 등록 (`~/.claude/mcp.json` 또는 host 동등 위치):
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
@@ -181,7 +183,7 @@ config 예시는 [docs/SMOKE.md](docs/SMOKE.md) 의 `/tmp/kebab-smoke/config.tom
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
Claude Code 가 session 시작 시 `kebab mcp` 를 spawn — process 가 session 동안 살아 있어 SQLite / Lance / fastembed 가 hot. 6 tool: `search` (lexical/vector/hybrid 검색), `ask` (RAG 답변, optional `session_id` for multi-turn + optional `mode` override), `schema` (capability 조회), `doctor` (health check), `ingest_file` (단일 파일 KB 저장), `ingest_stdin` (markdown 본문 + title/source_uri 로 KB 저장). 모든 tool 의 결과는 wire schema v1 JSON 으로 text content 안에 직렬화 — agent 가 parse 후 사용. tool dispatch 실패 (잘못된 config / 미초기화 KB 등) 는 `isError: true` + error.v1 content; refusal / no-hit / unhealthy 는 정상 응답 (semantic flag 으로 분기).
|
자세한 사용법 (Cursor / OpenAI Agents / Copilot CLI config, per-tool 입출력 예시, troubleshooting, multi-turn ask + session 관리, performance / security) — **[docs/mcp-usage.md](docs/mcp-usage.md)** 참조.
|
||||||
|
|
||||||
## 비-목표
|
## 비-목표
|
||||||
|
|
||||||
|
|||||||
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`
|
||||||
@@ -90,6 +90,8 @@ Claude Code spawns `kebab mcp` at session start; the process stays alive across
|
|||||||
|
|
||||||
If your host doesn't support MCP, the CLI subprocess pattern (`kebab search --json` / `kebab ask --json`) above continues to work.
|
If your host doesn't support MCP, the CLI subprocess pattern (`kebab search --json` / `kebab ask --json`) above continues to work.
|
||||||
|
|
||||||
|
For per-tool input/output examples, error code reference, multi-turn ask + session management, and host config beyond Claude Code (Cursor / OpenAI Agents / Copilot CLI), see [docs/mcp-usage.md](../../../docs/mcp-usage.md) in the kebab repo.
|
||||||
|
|
||||||
## Recipe D — agent fetched a web doc, save to KB
|
## Recipe D — agent fetched a web doc, save to KB
|
||||||
|
|
||||||
When you've fetched a markdown article (e.g. via WebFetch) that the user might query later:
|
When you've fetched a markdown article (e.g. via WebFetch) that the user might query later:
|
||||||
|
|||||||
Reference in New Issue
Block a user