tilt-mcp

Tilt MCP es un servidor del Protocolo de Contexto de Modelo que se integra con Tilt para proporcionar acceso programático a los recursos, registros y operaciones de gestión de Tilt para entornos de desarrollo en Kubernetes.

GitHub
6
Prueba este MCPPatrocinado

Documentación

Servidor Tilt MCP

Un servidor de Model Context Protocol (MCP) que se integra con Tilt para proporcionar acceso programático a los recursos y registros de Tilt a través de aplicaciones LLM.

¿Por qué usar un servidor Tilt MCP?

Imagina una solicitud como esta:

Por favor, trabaja en {alguna solicitud LLM} y luego revisa tilt MCP para los registros del recurso "backend-api" para el estado de compilación. Asegúrate de que el recurso "backend-tests" sea exitoso con tus cambios.

La idea clave es que ya no necesitas decirle a tu LLM cómo construir y desplegar tu código. En su lugar, puedes simplemente pedirle qué construir y desplegar.

Tilt es una herramienta poderosa para trabajar con cargas de trabajo de Docker/Kubernetes. Con el servidor Tilt MCP, puedes integrar las funciones de Tilt directamente en tu flujo de trabajo usando Modelos de Lenguaje Grande (LLMs) como Claude Code / Codex / Gemini / VS Code Copilot / etc.

Esto ahorra tokens LLM significativos (y por lo tanto ⏱️+💰), tanto al evitar dar contexto adicional a tu LLM sobre cómo construir/desplegar, como al evitar que los LLM realmente hagan la construcción/despliegue. Todo lo que el LLM necesita saber es hacer cambios de código y luego llamar al servidor tilt MCP para obtener retroalimentación en tiempo real.

Resumen

El servidor Tilt MCP permite que los Modelos de Lenguaje Grande (LLMs) y asistentes de IA interactúen con tu entorno de desarrollo Tilt. Proporciona herramientas para:

  • Listar todos los recursos Tilt habilitados
  • Obtener registros de recursos específicos
  • Monitorear el estado y la salud de los recursos
  • Habilitar y deshabilitar recursos dinámicamente
  • Obtener información detallada sobre los recursos
  • Activar reconstrucciones de recursos
  • Esperar a que los recursos alcancen condiciones específicas

Esto permite flujos de trabajo de desarrollo impulsados por IA, asistencia de depuración, monitoreo automatizado y gestión inteligente de recursos de tus servicios gestionados por Tilt.

Capacidades MCP Disponibles

El servidor Tilt MCP sigue la especificación del Model Context Protocol y expone tres tipos de capacidades:

🔍 Recursos (Datos de Solo Lectura)

Los recursos proporcionan acceso de solo lectura a los datos de Tilt. Son descubiertos automáticamente por los clientes MCP y se pueden acceder a través de su URI.

URI del RecursoDescripción
tilt://resources/all{?tilt_port}Lista de todos los recursos Tilt habilitados con su estado actual
tilt://resources/{resource_name}/logs{?tail,filter,tilt_port}Registros de un recurso específico con filtrado regex opcional (insensible a mayúsculas por defecto)
tilt://resources/{resource_name}/describe{?tilt_port}Información detallada sobre un recurso específico

Todos los recursos admiten un parámetro opcional tilt_port (por defecto: 10350) para consultar diferentes instancias de Tilt.

Ejemplos de URIs:

  • tilt://resources/all - Obtener todos los recursos del puerto predeterminado (10350)
  • tilt://resources/all?tilt_port=10351 - Obtener todos los recursos del puerto 10351
  • tilt://resources/frontend/logs - Obtener las últimas 1000 líneas de frontend (por defecto)
  • tilt://resources/frontend/logs?tail=100&tilt_port=10351 - Obtener las últimas 100 líneas de frontend en el puerto 10351
  • tilt://resources/backend/logs?filter=error - Filtrar registros por errores (insensible a mayúsculas)
  • tilt://resources/backend/logs?filter=X-Request-Id:%20abc123 - Filtrar por ID de solicitud
  • tilt://resources/backend/describe - Obtener información detallada sobre backend

🛠️ Herramientas (Acciones con Efectos Secundarios)

Las herramientas permiten a los LLMs realizar acciones que modifican el estado de tu entorno Tilt.

HerramientaDescripciónParámetros
trigger_resourceActiva un recurso Tilt para reconstruir/actualizarresource_name (obligatorio), tilt_port (opcional, por defecto: '10350')
enable_resourceHabilita uno o más recursos Tiltresource_names (obligatorio, lista), enable_only (opcional, por defecto: false), tilt_port (opcional, por defecto: '10350')
disable_resourceDeshabilita uno o más recursos Tiltresource_names (obligatorio, lista), tilt_port (opcional, por defecto: '10350')
wait_for_resourceEspera a que un recurso alcance una condición específicaresource_name (obligatorio), condition (opcional, por defecto: 'Ready', valores válidos: 'Ready' o 'UpToDate'), timeout_seconds (opcional, por defecto: 30), tilt_port (opcional, por defecto: '10350')

Herramientas de Solo Lectura (para clientes que no admiten Recursos MCP):

HerramientaDescripciónParámetros
list_resourcesListar todos los recursos Tilt habilitados con su estadotilt_port (opcional, por defecto: '10350')
get_resource_logsObtener registros de un recurso específico con filtrado regex opcionalresource_name (obligatorio), tail (opcional, por defecto: 1000), filter (opcional, patrón regex), tilt_port (opcional, por defecto: '10350')
describe_resourceObtener información detallada sobre un recurso específicoresource_name (obligatorio), tilt_port (opcional, por defecto: '10350')

Nota: Las herramientas de solo lectura (list_resources, get_resource_logs, describe_resource) proporcionan la misma funcionalidad que los Recursos MCP anteriores, pero se exponen como herramientas para una mejor compatibilidad con clientes LLM (como Claude Code) que pueden no admitir completamente el descubrimiento de recursos MCP.

Todas las herramientas admiten un parámetro opcional tilt_port para apuntar a diferentes instancias de Tilt que se ejecutan en diferentes puertos.

💡 Prompts (Flujos de Trabajo Guiados)

Los prompts son plantillas reutilizables que guían al LLM a través de flujos de trabajo comunes de depuración y resolución de problemas.

PromptDescripciónParámetros
debug_failing_resourceGuía de depuración paso a paso para un recurso con fallosresource_name (obligatorio)
analyze_resource_logsAnalizar registros de un recurso para identificar erroresresource_name (obligatorio), lines (opcional, por defecto: 100)
troubleshoot_startup_failureInvestigar por qué un recurso no se inicia o sigue fallandoresource_name (obligatorio)
health_check_all_resourcesVerificación de salud integral en todos los recursosNinguno
optimize_resource_usageOptimizar el uso de recursos habilitando/deshabilitando servicios selectivamentefocus_resources (obligatorio, lista)

Manejo de Errores

Todas las capacidades incluyen un manejo de errores integral:

  • Recurso No Encontrado: Lanza ValueError con un mensaje útil
  • Problemas de Conexión con Tilt: Lanza RuntimeError con detalles del error de Tilt
  • Errores de Análisis JSON: Proporciona información detallada del error de análisis

Todas las operaciones se registran en ~/.tilt-mcp/tilt_mcp.log para depuración.

Características

Cumplimiento del Protocolo MCP:

  • 🔍 Recursos: Acceso de solo lectura a los datos de Tilt mediante plantillas URI (por ejemplo, tilt://resources/all)
  • 🛠️ Herramientas: Acciones con efectos secundarios para la gestión y control de recursos
  • 💡 Prompts: Flujos de trabajo guiados para depuración y resolución de problemas

Capacidades:

  • 📊 Descubrimiento de Recursos: Listar todos los recursos Tilt activos con su estado actual
  • 📜 Recuperación de Registros: Obtener registros recientes de cualquier recurso Tilt con cola configurable
  • 🔄 Activación de Recursos: Activar manualmente recursos Tilt para reconstruir/actualizar
  • ✅ Control de Recursos: Habilitar o deshabilitar recursos dinámicamente
  • 📋 Información Detallada: Obtener detalles completos sobre cualquier recurso
  • ⏳ Condiciones de Espera: Esperar a que los recursos alcancen estados específicos
  • 🤖 Flujos de Trabajo Guiados: Prompts preconstruidos para escenarios comunes de depuración

Características Técnicas:

  • 🛡️ Seguridad de Tipos: Construido con sugerencias de tipo de Python para un mejor soporte de IDE
  • 🚀 Soporte Asíncrono: Implementación totalmente asíncrona usando FastMCP
  • 📈 Mejores Prácticas MCP: Separación adecuada de recursos, herramientas y prompts
  • 🔧 Registro Integral: Todas las operaciones registradas en ~/.tilt-mcp/tilt_mcp.log

Requisitos Previos

  • Python 3.10 o superior (requerido por FastMCP 2.0)
  • Tilt instalado y configurado
  • Un cliente compatible con MCP (por ejemplo, Claude Desktop, mcp-cli)

Instalación

Puedes instalar Tilt MCP de tres maneras:

Opción 1: Usando Docker (Recomendado para macOS/Windows)

La instalación basada en Docker no requiere configuración de Python y se mantiene automáticamente actualizada con compilaciones mensuales. La imagen está optimizada en tamaño usando Alpine Linux (~320MB vs 545MB+ para imágenes basadas en Debian - reducción del 41%).

Cómo funciona:

  • Descubre automáticamente el puerto de la API de Tilt desde ~/.tilt-dev/config basado en el parámetro tilt_port
  • Usa socat para crear dinámicamente un túnel TCP desde dentro del contenedor al servidor Tilt del host
  • El directorio ~/.tilt-dev de tu host se monta con acceso de escritura (la CLI de Tilt necesita archivos de bloqueo)
  • Un solo servidor MCP puede consultar múltiples instancias de Tilt especificando diferentes valores de tilt_port (10350, 10351, etc.)
  • El código Python maneja el descubrimiento de puertos y la gestión de socat automáticamente

Nota: El tamaño de la imagen está impulsado principalmente por las dependencias de FastMCP 2.0 (cryptography, pydantic, etc.). Para referencia:

  • Base Alpine + Python: ~50MB
  • Binario de Tilt: ~20MB
  • FastMCP 2.0 + dependencias: ~250MB

Consulta la sección Configuración MCP a continuación para instrucciones de configuración.

Opción 2: Desde PyPI

pip install tilt-mcp

Mejor para: Usuarios de Linux o cuando prefieras instalación local

Opción 3: Desde el Código Fuente

git clone https://github.com/rrmistry/tilt-mcp.git
cd tilt-mcp
pip install -e .

Mejor para: Desarrollo o prueba de cambios locales

Configuración

Configuración Docker (Recomendado para macOS/Windows)

Agrega lo siguiente a tu archivo de configuración de Claude Desktop:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

Para macOS/Linux (instancia única de Tilt en el puerto predeterminado 10350):

{
  "mcpServers": {
    "tilt": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${HOME}/.tilt-dev:/home/mcp-user/.tilt-dev",
        "-v",
        "${HOME}/.tilt-mcp:/home/mcp-user/.tilt-mcp",
        "--network=host",
        "ghcr.io/rrmistry/tilt-mcp:latest"
      ],
      "env": {}
    }
  }
}

Para múltiples instancias de Tilt:

Un solo servidor MCP puede consultar múltiples instancias de Tilt. Simplemente especifica el parámetro tilt_port al llamar a herramientas o recursos:

# Query resources from different Tilt instances
trigger_resource(resource_name="backend", tilt_port="10350")  # First instance
trigger_resource(resource_name="backend", tilt_port="10351")  # Second instance

# Get logs from specific instance
# URI: tilt://resources/backend/logs?tilt_port=10351

No se necesita configuración adicional: usa la misma configuración Docker de instancia única anterior.

Para Windows (PowerShell):

{
  "mcpServers": {
    "tilt": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "${env:USERPROFILE}\\.tilt-dev:/home/mcp-user/.tilt-dev",
        "-v",
        "${env:USERPROFILE}\\.tilt-mcp:/home/mcp-user/.tilt-mcp",
        "--network=host",
        "ghcr.io/rrmistry/tilt-mcp:latest"
      ],
      "env": {}
    }
  }
}

Para Windows (CMD): Usa %USERPROFILE% en lugar de ${env:USERPROFILE} en las rutas de montaje de volúmenes.

Notas Clave de Configuración:

  • El parámetro tilt_port representa el puerto de la interfaz web (10350, 10351, etc.) - NO el puerto de la API
  • El código Python descubre automáticamente el puerto real de la API desde ~/.tilt-dev/config
  • Nombres de contexto: puerto 10350 → "tilt-default", puerto 10351 → "tilt-10351", etc.
  • El directorio ~/.tilt-dev debe montarse con acceso de escritura (la CLI de Tilt necesita archivos de bloqueo)
  • socat reenvía dinámicamente el puerto de API descubierto a host.docker.internal
  • --network=host es necesario para que host.docker.internal funcione en macOS/Windows

Variables de Entorno:

VariablePredeterminadoDescripción
IS_DOCKER_MCP_SERVERfalseEstablecer a true cuando se ejecuta en Docker (se establece automáticamente en la imagen Docker)
TILT_MCP_USE_SOCATautoControlar el comportamiento de reenvío TCP de socat (ver más abajo)
TILT_HOSThost.docker.internalHost al que reenviar cuando se usa socat
TILT_MCP_LOG_FILE(ninguno)Sobrescribir la ruta del archivo de registro (por defecto: ~/.tilt-mcp/tilt_mcp.log)

Modos de TILT_MCP_USE_SOCAT:

  • auto (por defecto): Auto-detección basada en la accesibilidad del puerto. Omite socat si Tilt ya es accesible en localhost (por ejemplo, Docker en Linux con --network=host).
  • true o 1: Usar siempre el reenvío de socat, incluso si el puerto ya es accesible.
  • false o 0: Nunca usar socat, incluso en entornos Docker.

Configuración de Instalación Local

Si instalaste vía PyPI o desde el código fuente, usa esta configuración más simple:

{
  "mcpServers": {
    "tilt": {
      "command": "tilt-mcp"
    }
  }
}

Asegurándote de que tilt-mcp esté en tu PATH.

Para Desarrollo/Pruebas

Puedes ejecutar el servidor directamente:

python -m tilt_mcp.server

O úsalo con la CLI de MCP:

mcp run python -m tilt_mcp.server

Verificando la Versión

Para verificar la versión instalada de tilt-mcp:

tilt-mcp --version

Construyendo la Imagen Docker Localmente

Construye la imagen optimizada basada en Alpine:

docker build -t ghcr.io/rrmistry/tilt-mcp:latest .

O construye con una versión específica de Tilt:

docker build --build-arg TILT_VERSION=0.35.2 -t ghcr.io/rrmistry/tilt-mcp:latest .

Para usar Debian en lugar de Alpine (imagen más grande pero mejor compatibilidad):

docker build --build-arg BASE_IMAGE=python:3.11-slim-bookworm -t ghcr.io/rrmistry/tilt-mcp:latest .

Uso

Una vez configurado, el servidor Tilt MCP proporciona Recursos, Herramientas y Prompts a través del Model Context Protocol.

Usando Recursos

Los recursos son de solo lectura y proporcionan acceso directo a los datos de Tilt. Los clientes MCP pueden acceder a ellos a través de su URI:

Obtener todos los recursos:

tilt://resources/all

Devuelve:

{
  "resources": [
    {
      "name": "frontend",
      "type": "k8s",
      "status": "ok",
      "updateStatus": "ok"
    },
    {
      "name": "backend-api",
      "type": "k8s",
      "status": "pending",
      "updateStatus": "pending"
    }
  ],
  "count": 2
}

Obtener logs de un recurso:

tilt://resources/frontend/logs

Devuelve las últimas 1000 líneas de logs como texto plano (predeterminado).

Obtener un número personalizado de líneas de log:

tilt://resources/frontend/logs?tail=50

Devuelve las últimas 50 líneas de logs como texto plano.

Obtener información detallada del recurso:

tilt://resources/backend/describe

Devuelve una salida detallada en YAML/texto con configuración, estado e historial de compilación.

Uso de Herramientas

Las herramientas realizan acciones que modifican el estado de tu entorno Tilt.

Activar una reconstrucción:

{
  "name": "trigger_resource",
  "arguments": {
    "resource_name": "backend"
  }
}

Habilitar recursos específicos:

{
  "name": "enable_resource",
  "arguments": {
    "resource_names": ["frontend", "backend"],
    "enable_only": false
  }
}

Deshabilitar recursos:

{
  "name": "disable_resource",
  "arguments": {
    "resource_names": ["frontend", "backend"]
  }
}

Esperar a que un recurso esté listo:

{
  "name": "wait_for_resource",
  "arguments": {
    "resource_name": "backend",
    "condition": "Ready",
    "timeout_seconds": 60
  }
}

Uso de Prompts

Los prompts proporcionan flujos de trabajo guiados para tareas comunes. Generan mensajes contextuales que guían al LLM a través de la depuración y resolución de problemas.

Depurar un recurso con fallos:

{
  "name": "debug_failing_resource",
  "arguments": {
    "resource_name": "backend"
  }
}

Esto genera un flujo de trabajo de depuración integral que guía al LLM para revisar logs, estado y sugerir correcciones.

Realizar una verificación de salud:

{
  "name": "health_check_all_resources",
  "arguments": {}
}

Esto crea un flujo de trabajo sistemático de verificación de salud en todos los recursos.

Optimizar el uso de recursos:

{
  "name": "optimize_resource_usage",
  "arguments": {
    "focus_resources": ["backend", "database"]
  }
}

Esto guía al LLM para habilitar solo los recursos especificados y deshabilitar otros para conservar recursos del sistema.

Ejemplos de Prompts

Aquí hay algunos ejemplos de prompts que puedes usar con un asistente de IA que tenga acceso a este servidor MCP:

Uso de Plantillas de Prompt Integradas:

  • "Usa el prompt debug_failing_resource para el servicio backend"
  • "Ejecuta una verificación de salud en todos mis recursos"
  • "Usa el prompt troubleshoot_startup_failure para investigar por qué el frontend no arranca"
  • "Analiza los logs del servicio backend usando el prompt analyze_resource_logs"
  • "Ayúdame a optimizar mis recursos para enfocarme solo en el backend y la base de datos"

Descubrimiento y Estado de Recursos:

  • "Muéstrame todos los recursos de Tilt que se están ejecutando actualmente"
  • "¿Qué servicios están fallando o tienen errores?"
  • "Compara el estado de los servicios frontend y backend"
  • "Accede al recurso tilt://resources/all para ver todos los servicios"

Análisis de Logs:

  • "Obtén las últimas 100 líneas de logs del servicio backend-api"
  • "Lee los logs de tilt://resources/frontend/logs?tail=50"
  • "Muéstrame las últimas 200 líneas de logs de cualquier servicio con fallos"
  • "Ayúdame a depurar por qué el servicio frontend está fallando revisando los logs recientes"

Control de Recursos:

  • "Deshabilita los servicios frontend y backend"
  • "Habilita solo el servicio de base de datos y deshabilita todo lo demás"
  • "Habilita el servicio frontend"
  • "Deshabilita todos los servicios no esenciales para ahorrar recursos"

Compilación y Despliegue:

  • "Activa una reconstrucción del servicio backend"
  • "Reconstruye el frontend y muéstrame los logs"
  • "Activa todos los servicios que tengan errores"
  • "Espera a que el backend esté listo antes de revisar sus logs"

Flujos de Trabajo Avanzados de Automatización:

  • "Habilita el backend, espera a que esté listo y luego revisa sus logs"
  • "Deshabilita todos los servicios, luego habilita solo el frontend y espera a que arranque"
  • "Obtén información detallada sobre la base de datos y muéstrame sus logs recientes"
  • "Activa una reconstrucción del servicio API y espera hasta que esté listo"
  • "Ejecuta una verificación de salud completa y corrige cualquier problema que encuentres"

Uso Directo de Recursos:

  • "Lee tilt://resources/backend/describe para entender la configuración"
  • "Compara logs de tilt://resources/frontend/logs?tail=500 y tilt://resources/backend/logs?tail=500"
  • "Revisa tilt://resources/all para ver qué servicios necesitan atención"
  • "Obtén las últimas 50 líneas del frontend: tilt://resources/frontend/logs?tail=50"

Desarrollo

Configuración del entorno de desarrollo

# Clone the repository
git clone https://github.com/yourusername/tilt-mcp.git
cd tilt-mcp

# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Ejecución de pruebas

pytest

Formato de código y linting

# Format code
black src tests

# Run linter
ruff check src tests

# Type checking
mypy src

Solución de Problemas

Problemas Comunes

  1. Error "Tilt no encontrado"

    • Asegúrate de que Tilt esté instalado y disponible en tu PATH
    • Intenta ejecutar tilt version para verificar la instalación

  2. "No se encontraron recursos" cuando Tilt está en ejecución

    • Asegúrate de que tu Tiltfile esté cargado y los recursos estén iniciados
    • Verifica que estés ejecutando el servidor MCP en el directorio correcto

  3. Errores de conexión

    • Verifica que la configuración del cliente MCP sea correcta
    • Revisa los logs en ~/.tilt-mcp/tilt_mcp.log

  4. tilt-mcp basado en Docker no puede conectarse

    • Asegúrate de que tu directorio ~/.tilt-dev exista y esté siendo creado por tu instancia de Tilt
    • El directorio debe estar montado con acceso de escritura: ~/.tilt-dev:/home/mcp-user/.tilt-dev (la CLI de Tilt necesita archivos de bloqueo)
    • El parámetro tilt_port debe ser tu puerto de interfaz web (10350, 10351, etc.), no el puerto API aleatorio
    • Revisa los logs en ~/.tilt-mcp/tilt_mcp.log para ver el puerto API descubierto
    • El código Python descubre automáticamente el puerto API desde la configuración y lanza socat automáticamente
    • Asegúrate de que --network=host esté incluido en los argumentos de docker (requerido para host.docker.internal)
    • Si socat está causando problemas, puedes controlarlo mediante la variable de entorno TILT_MCP_USE_SOCAT:
      • auto (predeterminado): Detecta automáticamente si socat es necesario verificando la accesibilidad del puerto
      • true: Forzar socat activado
      • false: Forzar socat desactivado

  5. Compatibilidad con Alpine Linux

    • La imagen de Docker usa Alpine Linux para optimizar el tamaño
    • La mayoría de los paquetes de Python funcionan bien, pero si encuentras problemas con dependencias binarias, puedes compilar usando la base Debian cambiando el argumento de compilación BASE_IMAGE a python:3.11-slim-bookworm

Registro de Depuración

El servidor MCP registra todas las operaciones en ~/.tilt-mcp/tilt_mcp.log. El registro incluye:

  • Eventos de inicio/apagado del servidor
  • Operaciones de obtención de recursos
  • Operaciones de recuperación de logs
  • Mensajes de error con detalles completos

Para habilitar el registro de depuración, establece la variable de entorno:

export LOG_LEVEL=DEBUG

Formato de Registro: timestamp - logger_name - level - message

Visualización de Registros:

# View recent logs
tail -f ~/.tilt-mcp/tilt_mcp.log

# Search for errors
grep ERROR ~/.tilt-mcp/tilt_mcp.log

# View logs from a specific resource fetch
grep "get_all_resources" ~/.tilt-mcp/tilt_mcp.log

Contribuciones

¡Agradecemos las contribuciones! Consulta nuestra Guía de Contribuciones para obtener detalles sobre:

  • Configuración de tu entorno de desarrollo
  • Ejecución de pruebas
  • Envío de solicitudes de extracción
  • Pautas de estilo de código

Licencia

Este proyecto está licenciado bajo la Licencia MIT: consulta el archivo LICENCIA para más detalles.

Agradecimientos

  • Construido con FastMCP para la implementación del servidor MCP
  • Se integra con Tilt para el desarrollo de Kubernetes

Soporte