🔌 Klipper MCP Server

Servidor Model Context Protocol de nivel industrial para el ecosistema Klipper / Moonraker.

klipper-mcp-server expone, mediante una API uniforme (tools, resources y prompts), las capacidades necesarias para que clientes LLM (Claude, GPT, Cursor, VS Code) operen sobre el stack Klipper + Moonraker con garantías industriales de resiliencia, observabilidad, seguridad y rendimiento extremo.

📑 Tabla de contenidos

1. Estado del proyecto

2. Descripción y propósito

3. Casos de uso

4. Optimizaciones de rendimiento

5. Requisitos técnicos

6. Instalación y puesta en marcha

7. Configuración

8. Manual de uso

9. Benchmarks y perfilado

10. Contribuir

11. Créditos y financiación

12. Contacto

13. Licencia

Related MCP server: Klipper MCP Server

📌 Estado del proyecto

Importante: el repositorio contiene actualmente la especificación técnica v0.1 (docs/mcp-klipper.md) como fuente única de verdad. Dicha especificación incluye la implementación de referencia del núcleo y los contratos de tools, resources, prompts, agentes y skills. El código ejecutable se genera a partir de ella.

Las optimizaciones de rendimiento descritas en la sección 4 están especificadas y diseñadas; sus objetivos son metas de ingeniería verificables mediante el arnés de benchmark incluido en el plan de medida. Los valores de línea base deben capturarse en CI antes de certificar la mejora (ver Benchmarks).

🎯 Descripción y propósito

El problema

El desarrollo de extensiones para Klipper y plugins para Moonraker presenta tres barreras recurrentes:

1. Reglas de oro no verificables automáticamente: muchas contribuciones fallan en revisión por usar time.sleep(), variables globales o I/O síncrono en callbacks del reactor.

2. Errores silenciosos de configuración: SAVE_CONFIG solo escribe en printer.cfg; los parámetros auto-calibrados en includes provocan fallos de arranque difíciles de diagnosticar.

3. Ausencia de tooling LLM-aware: los asistentes genéricos no disponen de contexto estructural del ecosistema Klipper/Moonraker.

La solución

Un servidor MCP que actúa como capa de abstracción tipada entre el cliente LLM y:

• La API REST/JSON-RPC de Moonraker.

• El sistema de archivos de configuración Klipper.

• El log de eventos de Klipper (klippy.log).

• Validadores AST y plantillas canónicas de código conforme.

Objetivos principales

• Contratos verificables: cada tool valida su entrada contra schema y devuelve resultados deterministas.

• Resiliencia activa: circuit breaker por fábrica, cache con purga periódica y detector de anomalías EWMA con histéresis.

• Seguridad por defecto: comandos G-code peligrosos requieren confirm=True; las API keys nunca se registran en logs.

• Rendimiento extremo: cache multinivel, coalescencia de peticiones y economía de tokens (ver sección 4).

• Asincronía estricta: el event loop nunca se bloquea.

Capacidades entregadas (v0.1)

🧩 Casos de uso

1. Validación offline de configuración: comprobar printer.cfg y todo su sistema de [include] antes de reiniciar la impresora, detectando parámetros auto-calibrados mal ubicados.

2. Desarrollo de extras y componentes: generar plantillas canónicas y validar con el linter AST que se respetan las reglas del reactor.

3. Diagnóstico asistido: analizar klippy.log y telemetría con prompts especializados y detección de anomalías.

4. Operación controlada: ejecutar G-code con salvaguardas para comandos peligrosos (movimientos, calibración, cambios de estado).

5. Telemetría y SLO: exponer latencias, hit-rate de cache y estado del circuit breaker para integrarlos en observabilidad.

⚡ Optimizaciones de rendimiento

Las siguientes técnicas están especificadas en docs/mcp-klipper.md (§6.2 y §6.6) y son las que habilitan los objetivos medibles del proyecto.

Objetivos declarados (metas, no resultados medidos)

La metodología completa de perfilado y medición está en §6.6.6 de la especificación y en Benchmarks y perfilado.

🛠 Requisitos técnicos

Herramientas de desarrollo:

Sistemas operativos soportados: Debian 12, Ubuntu 22/24 y Raspberry Pi OS.

🚀 Instalación y puesta en marcha

1. Clonar el repositorio

git clone https://github.com/<org>/klipper-mcp-server.git
cd klipper-mcp-server

2. Crear el entorno e instalar dependencias

Se recomienda uv por velocidad y reproducibilidad:

uv venv
# Linux / macOS
source .venv/bin/activate
# Windows (PowerShell)
.\.venv\Scripts\Activate.ps1

# Instalación editable con dependencias de desarrollo y rendimiento
uv pip install -e ".[dev,perf]"

Alternativa con pip estándar:

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,perf]"

3. Configurar las impresoras

Cada impresora se declara con dos variables de entorno: la URL de Moonraker y, opcionalmente, su API key.

# Linux / macOS
export PRINTER_DEFAULT="http://localhost:7125"
export PRINTER_VORON="http://192.168.1.100:7125"
export PRINTER_VORON_API_KEY="tu-api-key"

# Windows (PowerShell)
$env:PRINTER_DEFAULT = "http://localhost:7125"
$env:PRINTER_VORON   = "http://192.168.1.100:7125"
$env:PRINTER_VORON_API_KEY = "tu-api-key"

4. Arrancar el servidor

python -m klipper_mcp.server

El servidor se comunica por stdio con el cliente MCP. Si no se declara ninguna impresora, se usa http://localhost:7125 por defecto.

5. Verificar la instalación

pytest tests/ -q

⚙️ Configuración

Todas las variables se leen del entorno y se validan de forma tipada en src/klipper_mcp/config.py.

Impresoras

<NAME> se normaliza a minúsculas. Si solo hay una impresora, no es necesario indicar su nombre en las llamadas.

Núcleo runtime

Ejemplo completo

export PRINTER_DEFAULT="http://localhost:7125"
export MCP_CACHE_DISK="/var/cache/klipper-mcp"
export MCP_CACHE_TTL="30"
export MCP_CACHE_L2_TTL="300"
export MCP_MAX_CONCURRENCY="32"
export MCP_TOKEN_BUDGET="4000"
export MCP_LOG_LEVEL="INFO"

📖 Manual de uso

Integración con Claude Desktop

Edita claude_desktop_config.json:

{
  "mcpServers": {
    "klipper": {
      "command": "python",
      "args": ["-m", "klipper_mcp.server"],
      "env": {
        "PRINTER_DEFAULT": "http://192.168.1.100:7125",
        "PRINTER_DEFAULT_API_KEY": "tu-api-key",
        "MCP_CACHE_SIZE": "512",
        "MCP_CACHE_TTL": "30"
      }
    }
  }
}

Instalación en TRAE IDE (install link)

TRAE permite instalar un servidor MCP desde un enlace con esquema propio (documentación oficial). El proyecto incluye un generador reproducible en install_link.py.

Formato del enlace:

trae://trae.ai-ide/mcp-import?type=<TYPE>&name=<NAME>&config=<B64_URLENCODED>

Generar el enlace:

# Con el script de consola instalado (pip install -e .)
klipper-mcp-install-link --name klipper \
  --printer-url http://192.168.1.100:7125

# Equivalente sin instalar el entry point
python -m klipper_mcp.install_link --name klipper \
  --printer-url http://192.168.1.100:7125

# Con API key y variables extras (repetible)
klipper-mcp-install-link --name voron \
  --printer-url http://192.168.1.100:7125 \
  --env PRINTER_VORON_API_KEY=TU_API_KEY \
  --env MCP_CACHE_DISK=/var/cache/klipper-mcp

# Emitir un badge Markdown para el README
klipper-mcp-install-link --markdown

Ejemplo de enlace generado:

trae://trae.ai-ide/mcp-import?type=stdio&name=klipper&config=eyJjb21tYW5kIjoicHl0aG9uIiwiYXJncyI6WyItbSIsImtsaXBwZXJfbWNwLnNlcnZlciJdLCJlbnYiOnsiUFJJTlRFUl9ERUZBVUxUIjoiaHR0cDovLzE5Mi4xNjguMS4xMDA6NzEyNSJ9fQ%3D%3D

Importar en TRAE:

1. Pega el enlace en la barra de direcciones del navegador y pulsa Enter.

2. Confirma en el diálogo del navegador que quieres abrir TRAE.

3. En la ventana Configure Manually de TRAE, revisa la configuración y pulsa Confirm.

Seguridad: config va codificado en Base64, no cifrado. No compartas enlaces que incluyan API keys; genera el enlace en local y pasa los secretos vía --env solo cuando lo vayas a usar.

Tools

Consulta la especificación (§7) para el contrato completo de las 17 tools, sus parámetros y sus valores de retorno.

Resources

Los recursos se direccionan por URI, por ejemplo:

klipper://config/printer.cfg
klipper://logs/klippy.log
klipper://docs/index

Prompts

Plantillas predefinidas para diagnóstico, optimización y generación:

• Troubleshooting: análisis guiado de klippy.log.

• Optimización: tuning de pressure_advance, input_shaper, etc.

• Generación: scaffolding de extras y componentes conforme a las reglas de Klipper/Moonraker.

Docker Compose

# Definir la API key en el entorno del host
export VORON_API_KEY="tu-api-key"
docker compose up --build

📊 Benchmarks y perfilado

El proyecto incluye un arnés offline (benchmarks/profile_harness.py) que ejecuta las operaciones contra un Moonraker simulado (tests/harness/sim_moonraker.py) para eliminar ruido de red.

# CPU: flamegraph sin instrumentar el proceso
py-spy record -o profile.svg -- python -m klipper_mcp.server

# Línea base de CPU
python -m cProfile -o baseline.prof -m klipper_mcp.server

# Memoria (detección de fugas en ejecución prolongada)
memray run -o mem.bin benchmarks/profile_harness.py
memray flamegraph mem.bin

# Benchmarks reproducibles y comparables en CI
pytest benchmarks/ --benchmark-only --benchmark-json=out.json

Protocolo de medición

1. Congelar la línea base en la revisión v0.1 y versionar benchmarks/baseline.json.

2. Medir la candidata en el mismo hardware, con el mismo corpus e idénticas iteraciones.

3. Comparar p50/p95/p99, throughput y RSS. Se acepta la candidata solo si cumple los objetivos y no introduce regresiones > 10 %.

4. Verificar estabilidad: soak de 24 h sin crecimiento de RSS (pendiente ≤ 0.1 %/h) con hit-rate estable.

🤝 Contribuir

Estándares de código

• Estilo: ruff (lint + format) sin errores y mypy sin errores.

• Longitud de línea: ≤ 80 caracteres.

• Cabeceras: todo archivo .py incluye cabecera GPLv3.

• Asincronía: prohibido time.sleep() en código del reactor; usar mecanismos del reactor o asyncio. Sin variables globales mutables.

• I/O: nunca bloqueante dentro del event loop.

• Tipado: anotaciones en todas las funciones públicas.

Flujo de trabajo con Git

1. Crea una rama descriptiva desde main: git checkout -b feat/single-flight-cache.

2. Realiza commits atómicos siguiendo Conventional Commits: feat:, fix:, perf:, docs:, refactor:, test:.

3. Asegura que los tests y linters pasan antes de subir la rama.

4. Abre un Pull Request hacia main.

Proceso de revisión de Pull Requests

• Al menos una aprobación de un maintainer.

• La CI debe estar en verde (lint, mypy, tests y benchmarks).

• Todo cambio de rendimiento debe incluir evidencia de medición (JSON de benchmark) y no introducir regresiones > 10 %.

• Los PR deben ser pequeños y con un único propósito.

Requisitos de pruebas

• Cobertura mínima: 80 %.

• Tests nuevos obligatorios para toda funcionalidad: casos válidos, inválidos y de borde.

• Tests de integración con el Moonraker simulado para todo acceso de red.

• Los tests de rendimiento usan pytest-benchmark y no dependen de red real.

ruff check src/ tests/
mypy --ignore-missing-imports src/
pytest tests/ -v --cov=src/klipper_mcp --cov-fail-under=80

🙌 Créditos y financiación

Autores

• Equipo Klipper MCP Server — diseño de arquitectura, núcleo runtime y especificación técnica.

Agradecimientos

• A los proyectos Klipper y Moonraker por su documentación abierta y su ecosistema.

• A la comunidad de Model Context Protocol por el estándar y los SDKs de referencia.

• A los mantenedores de aiohttp, orjson y zstandard.

Fuentes de financiación

Este proyecto es de desarrollo independiente y no cuenta actualmente con financiación institucional. Si deseas apoyar su mantenimiento, contacta con el equipo (ver Contacto).

📬 Contacto

• Issues y bugs: GitHub Issues

• Solicitudes de funcionalidad: usa la plantilla de feature request en el mismo repositorio.

• Consultas generales y seguridad: escribe a maintainers@klipper-mcp.dev.

Por favor, reporta vulnerabilidades de forma privada y no abras un issue público hasta que se haya evaluado el impacto.

📄 Licencia

Este proyecto se distribuye bajo la GNU General Public License v3.0. Consulta el archivo LICENSE para el texto completo.

La elección de GPLv3 garantiza que las mejoras derivadas —incluidas las optimizaciones de rendimiento— permanezcan disponibles para la comunidad del ecosistema Klipper/Moonraker.