Referencia de herramientas MCP

Las 46 herramientas Model Context Protocol que Korva expone a asistentes de IA por stdio JSON-RPC. Particionadas en tres perfiles de permiso — agent (41), readonly (17), admin (46) — seleccionados vía KORVA_MCP_PROFILE.

Actualizado: 2026-04-30

Korva implementa el Model Context Protocol versión 2024-11-05 sobre stdio JSON-RPC 2.0. Cada IDE soportado habla con el Vault usando este protocolo. El mismo servidor Vault habla con humanos por HTTP en :7437 y con agentes de IA por MCP en stdin/stdout simultáneamente.

Perfiles de permisos

El conjunto de herramientas expuestas depende de KORVA_MCP_PROFILE:

Perfil	Tools	Caso de uso
`agent`	19	Asistente de IA en desarrollo activo. Default.
`readonly`	8	Clientes no confiables — búsqueda y contexto solo lectura
`admin`	22	Tooling administrativo. Añade `vault_delete`, `vault_bulk_save`.

Herramientas de búsqueda y contexto (agent + readonly)

Tool	Descripción	Inputs clave
vault_search	Búsqueda full-text FTS5 con modos compact / why	`query`, `project`, `team`, `country`, `type`, `limit`, `compact`, `why`
vault_context	Restaura observaciones recientes de un proyecto al inicio de sesión	`project`, `limit`, `budget_tokens`, `delta`, `prompt`, `file_paths`, `skill_limit`
vault_timeline	Consulta por rango de fechas	`project`, `from` (RFC3339), `to`
vault_get	Obtiene una observación por ULID	`id`
vault_hint	Búsqueda ultraligera — solo id+type+title, ~10× menos tokens	`query`, `project`, `type`, `limit`
vault_summary	Resumen de alto nivel del proyecto	`project`
vault_stats	Estadísticas globales del Vault	ninguno
vault_query	Consulta estructurada (sin FTS) por type/date/project	`project`, `team`, `type`, `since`, `until`, `limit`
vault_skill_match	Smart Skill Auto-Loader (Teams+)	`prompt`, `project`, `file_paths`, `limit`
vault_compress	Compresión caveman de output extenso	`text`, `mode` (off/lite/full/ultra)
vault_pattern_mine	Detecta patrones emergentes (Teams+)	`project`, `max`, `min_count`
vault_code_health	Calificación A–F de salud del código (Teams+)	ninguno
vault_team_context	Skills + scrolls privados del equipo (Teams+)	usa session token
vault_export_lore	Exporta los scrolls privados del equipo (Teams+)	`since` (RFC3339)

Herramientas de escritura (solo agent)

Tool	Descripción	Inputs clave
vault_save	Guarda una observación, con filtro de privacidad + dedup	`title`, `content`, `type`, `tags`, `project`, `team`, `country`, `author`, `session_id`, `dry_run`, `force`
vault_save_prompt	Guarda una plantilla de prompt reutilizable	`name`, `content`, `tags`
vault_session_start	Inicia una sesión de trabajo trackeada	`project`, `team`, `country`, `agent`, `goal`
vault_session_end	Cierra una sesión con un resumen	`session_id`, `summary`
vault_sdd_phase	Lee o avanza la fase SDD	`project`, `phase` (opcional)
vault_qa_checklist	Criterios de calidad para una fase + lenguaje	`phase`, `language` (go/typescript/react)
vault_qa_checkpoint	Registra un resultado de QA con lógica de gate	`project`, `phase`, `language`, `status`, `score`, `findings`, `notes`, `gate_passed`, `session_id`

Herramientas admin (solo admin)

Tool	Descripción	Inputs clave
vault_delete	Elimina una observación por ULID	`id`
vault_bulk_save	Guarda hasta 50 observaciones en una sola llamada	`observations[]`

Tipos de observación

Cada save declara un type. Son filtrables en la búsqueda y actúan como pista para el modelo:

decision, pattern, bugfix, learning, context, antipattern, task, feature, refactor, discovery.

Fases SDD (persistidas en `sdd_state`)

explore → propose → spec → design → tasks → apply → verify → archive → onboard.

Esquema de input de `vault_save`

{
  "title":      "string (máx. 100 caracteres)",
  "content":    "string",
  "type":       "decision|pattern|bugfix|learning|context|antipattern|task|feature|refactor|discovery",
  "tags":       ["string"],
  "project":    "string",
  "team":       "string",
  "country":    "string",
  "author":     "string",
  "session_id": "ULID (opcional)",
  "dry_run":    false,
  "force":      false
}

Devuelve { "id": "ULID" } o { "deduplicated": true, "existing_id": "ULID" } si el mismo content_hash ya existe en esta sesión.

Cuándo llamar a cada tool

Inicio de sesión → vault_context con project, prompt, file_paths. Trae auto_skills + observaciones recientes.
Discovery económico → vault_hint (10× más barato en tokens que vault_search).
Discovery completo → vault_search con modo why opcional para razonamiento de hint.
Decisión que vale la pena guardar → vault_save con type=decision o type=pattern.
Output extenso al vault → vault_compress primero, luego vault_save.
Cierre de sesión → vault_session_end con un resumen de un párrafo.

Búsqueda híbrida en cloud

vault_search?cloud=1 mezcla resultados locales con el cerebro comunitario opcional de Hive (timeout duro de 3 segundos). Los IDs locales siempre tienen prioridad. Ver Hive.