SECCIÓN 12

MCP Server

El MCP (Model Context Protocol) expone las capacidades de ixtli como herramientas nativas que Claude Code u otro cliente MCP puede invocar directamente.

Nota: Para la mayoría de los casos de uso, los hooks y slash commands son más eficientes que el servidor MCP, ya que no requieren cargar los schemas de herramientas en el contexto del modelo. Usa el MCP cuando necesites acceder a recursos estructurados (grafo PIL, historial de reviews) o cuando trabajes con un cliente que lo requiera explícitamente.

Iniciar el servidor

ixtli mcp serve

Inicia el servidor MCP en modo stdio. Normalmente no lo corres manualmente — el cliente MCP lo lanza como proceso hijo automáticamente.

Configurar en Claude Code

Por proyecto (.mcp.json en la raíz del repo):

{
  "mcpServers": {
    "ixtli": {
      "command": "ixtli",
      "args": ["mcp", "serve"]
    }
  }
}

Global (~/.claude/claude_desktop_config.json):

{
  "mcpServers": {
    "ixtli": {
      "command": "ixtli",
      "args": ["mcp", "serve"]
    }
  }
}

ixtli setup escribe el .mcp.json automáticamente.

Herramientas disponibles (15)

Grupo review:

Herramienta	Descripción
`review_staged_files`	Analiza los archivos staged. Acepta `agent_context` con task, confidence, iterations y tool_outputs para contexto del agente.
`review_files`	Analiza archivos específicos (rutas relativas). Acepta `agent_context`.
`review_diff`	Analiza un diff en formato unified diff
`review_commit`	Analiza commits y genera mensaje Conventional Commits
`poll_review`	Consulta el estado de un review en progreso dado un `review_session_id`
`re_review`	Verifica que los fixes aplicados a un archivo resolvieron los issues de un review anterior

Parámetros de re_review:

Parámetro	Tipo	Descripción
`file`	string	Ruta del archivo (relativa al root)
`resolved_issues`	array	Issues que el agente dice haber resuelto. Cada item: `{issue_id, issue, code_evidence, fix_applied}`
`session_id`	string (opcional)	ID de la sesión original para correlación
`intent`	string (opcional)	Descripción de los fixes en lenguaje natural

Parámetros de agent_context (en review_staged_files y review_files):

Campo	Tipo	Descripción
`task`	string	Instrucción exacta que recibió el agente
`confidence`	number	Confianza del agente en su solución (0.0–1.0)
`iterations`	integer	Número de intentos para llegar a la solución
`tool_outputs`	array de strings	Output de herramientas ejecutadas (pytest, ruff, tsc, etc.)

Grupo issues:

Herramienta	Parámetros	Descripción
`list_issues`	`review_session_id`, `severities[]`, `status`, `filename`	Lista issues con filtros opcionales
`resolve_issue`	`review_session_id`, `issue_id`	Marca un issue como resuelto
`ignore_issue`	`review_session_id`, `issue_id`, `reason`	Marca un issue como ignorado (falso positivo)

Grupo PIL — 100% local, sin red, sin API key (equivalentes a ixtli index ...):

Herramienta	Parámetros	Descripción
`get_project_context`	—	Framework, ORM, lenguaje principal, estado del índice
`get_symbol_info`	`symbol`	Callers, endpoints afectados, línea de definición
`get_impacted_files`	`file`, `symbol`, `depth`	Radio de impacto de modificar un archivo/símbolo
`get_endpoints`	`method`, `path_contains`	Lista de endpoints HTTP detectados, con filtros
`get_models`	`name_contains`	Lista de modelos ORM detectados, con filtro
`search_symbols`	`query`, `kind`, `file`	Busca símbolos por nombre o tipo (incluye `model`)

Grupo historial:

Herramienta	Parámetros	Descripción
`list_reviews`	`type`	Historial de reviews anteriores con filtro por tipo

Recursos disponibles

URI	Contenido
`ixtli://project/metadata`	Framework, ORM, estado del PIL
`ixtli://project/index/symbols`	Primeros 500 símbolos del índice
`ixtli://project/index/graph`	Grafo completo de dependencias
`ixtli://project/endpoints`	Todos los endpoints detectados
`ixtli://reviews/recent`	Últimos 5 reviews
`ixtli://review/{id}/issues`	Issues de un review específico

Prompts disponibles

Prompt	Descripción
`review_and_fix`	Review staged + ofrece aplicar fixes críticos/altos
`pre_commit_review`	Review rápido min_severity=high antes de commit
`understand_codebase`	Resumen del proyecto: framework, endpoints, calidad
`impact_analysis`	Análisis de impacto antes de modificar un archivo/símbolo

Ejemplo de flujo encadenado (MCP)

1. review_staged_files(include_fix=true, agent_context={task: "Fix auth bug"})
   → encuentra SQL injection en auth.py:42

2. get_symbol_info("UserService.create_user")
   → callers: [AuthController.login], endpoints: [POST /auth/login]

3. [Claude explica el issue con contexto completo]

4. [Claude edita auth.py aplicando fixed_code]

5. re_review(file="src/api/auth.py", resolved_issues=[{issue_id: "abc", fix_applied: "Parameterized queries"}])
   → {"resolved": ["SQL injection"], "still_present": [], "new_issues": []}

6. resolve_issue(review_session_id="...", issue_id="abc")

Integración con herramientas AI LSP — Language Server Protocol