tilt-mcp

O Tilt MCP é um servidor do Model Context Protocol que se integra ao Tilt para fornecer acesso programático aos recursos, logs e operações de gerenciamento do Tilt para ambientes de desenvolvimento Kubernetes.

GitHub
6
Experimente este MCPPatrocinado

Documentação

Servidor Tilt MCP

Um servidor Model Context Protocol (MCP) que se integra ao Tilt para fornecer acesso programático aos recursos e logs do Tilt por meio de aplicações LLM.

Por que usar um servidor Tilt MCP?

Imagine um prompt como este:

Por favor, trabalhe em {alguma solicitação LLM} e depois verifique o tilt MCP para os logs do recurso "backend-api" para status de compilação. Certifique-se de que o recurso "backend-tests" seja bem-sucedido com suas alterações.

A principal percepção é que você não precisa mais dizer ao seu LLM como construir e implantar seu código. Em vez disso, você pode simplesmente pedir a ele o que construir e implantar.

Tilt é uma ferramenta poderosa para trabalhar com cargas de trabalho Docker/Kubernetes. Com o servidor Tilt MCP, você pode integrar os recursos do Tilt diretamente ao seu fluxo de trabalho usando Modelos de Linguagem de Grande Porte (LLMs) como Claude Code / Codex / Gemini / VS Code Copilot / etc.

Isso economiza tokens significativos de LLM (e, portanto, ⏱️+💰), tanto por evitar dar contexto extra ao seu LLM sobre como construir/implantar, quanto por evitar que os LLMs realmente façam a construção/implantação. Tudo o que o LLM precisa saber é fazer alterações no código e depois chamar o servidor tilt MCP para obter feedback em tempo real.

Visão Geral

O servidor Tilt MCP permite que Modelos de Linguagem de Grande Porte (LLMs) e assistentes de IA interajam com seu ambiente de desenvolvimento Tilt. Ele fornece ferramentas para:

  • Listar todos os recursos Tilt habilitados
  • Buscar logs de recursos específicos
  • Monitorar o status e a saúde dos recursos
  • Habilitar e desabilitar recursos dinamicamente
  • Obter informações detalhadas sobre recursos
  • Acionar reconstruções de recursos
  • Aguardar que os recursos atinjam condições específicas

Isso possibilita fluxos de trabalho de desenvolvimento com IA, assistência de depuração, monitoramento automatizado e gerenciamento inteligente de recursos dos seus serviços gerenciados pelo Tilt.

Capacidades MCP Disponíveis

O servidor Tilt MCP segue a especificação do Model Context Protocol e expõe três tipos de capacidades:

🔍 Recursos (Dados Somente Leitura)

Os recursos fornecem acesso somente leitura aos dados do Tilt. Eles são descobertos automaticamente pelos clientes MCP e podem ser acessados por meio de seu URI.

URI do RecursoDescrição
tilt://resources/all{?tilt_port}Lista de todos os recursos Tilt habilitados com seu status atual
tilt://resources/{resource_name}/logs{?tail,filter,tilt_port}Logs de um recurso específico com filtragem opcional por regex (sem diferenciar maiúsculas/minúsculas por padrão)
tilt://resources/{resource_name}/describe{?tilt_port}Informações detalhadas sobre um recurso específico

Todos os recursos suportam um parâmetro opcional tilt_port (padrão: 10350) para consultar diferentes instâncias do Tilt.

Exemplos de URIs:

  • tilt://resources/all - Obter todos os recursos da porta padrão (10350)
  • tilt://resources/all?tilt_port=10351 - Obter todos os recursos da porta 10351
  • tilt://resources/frontend/logs - Obter as últimas 1000 linhas do frontend (padrão)
  • tilt://resources/frontend/logs?tail=100&tilt_port=10351 - Obter as últimas 100 linhas do frontend na porta 10351
  • tilt://resources/backend/logs?filter=error - Filtrar logs por erros (sem diferenciar maiúsculas/minúsculas)
  • tilt://resources/backend/logs?filter=X-Request-Id:%20abc123 - Filtrar por ID de solicitação
  • tilt://resources/backend/describe - Obter informações detalhadas sobre o backend

🛠️ Ferramentas (Ações com Efeitos Colaterais)

As ferramentas permitem que LLMs executem ações que modificam o estado do seu ambiente Tilt.

FerramentaDescriçãoParâmetros
trigger_resourceAciona um recurso Tilt para reconstruir/atualizarresource_name (obrigatório), tilt_port (opcional, padrão: '10350')
enable_resourceHabilita um ou mais recursos Tiltresource_names (obrigatório, lista), enable_only (opcional, padrão: false), tilt_port (opcional, padrão: '10350')
disable_resourceDesabilita um ou mais recursos Tiltresource_names (obrigatório, lista), tilt_port (opcional, padrão: '10350')
wait_for_resourceAguardar um recurso atingir uma condição específicaresource_name (obrigatório), condition (opcional, padrão: 'Ready', valores válidos: 'Ready' ou 'UpToDate'), timeout_seconds (opcional, padrão: 30), tilt_port (opcional, padrão: '10350')

Ferramentas Somente Leitura (para clientes que não suportam Recursos MCP):

FerramentaDescriçãoParâmetros
list_resourcesListar todos os recursos Tilt habilitados com seu statustilt_port (opcional, padrão: '10350')
get_resource_logsObter logs de um recurso específico com filtragem opcional por regexresource_name (obrigatório), tail (opcional, padrão: 1000), filter (opcional, padrão regex), tilt_port (opcional, padrão: '10350')
describe_resourceObter informações detalhadas sobre um recurso específicoresource_name (obrigatório), tilt_port (opcional, padrão: '10350')

Nota: As ferramentas somente leitura (list_resources, get_resource_logs, describe_resource) fornecem a mesma funcionalidade que os Recursos MCP acima, mas são expostas como ferramentas para melhor compatibilidade com clientes LLM (como Claude Code) que podem não suportar totalmente a descoberta de recursos MCP.

Todas as ferramentas suportam um parâmetro opcional tilt_port para direcionar diferentes instâncias do Tilt executando em portas diferentes.

💡 Prompts (Fluxos de Trabalho Guiados)

Os prompts são modelos reutilizáveis que guiam o LLM por fluxos de trabalho comuns de depuração e solução de problemas.

PromptDescriçãoParâmetros
debug_failing_resourceGuia de depuração passo a passo para um recurso com falharesource_name (obrigatório)
analyze_resource_logsAnalisar logs de um recurso para identificar errosresource_name (obrigatório), lines (opcional, padrão: 100)
troubleshoot_startup_failureInvestigar por que um recurso não inicia ou continua travandoresource_name (obrigatório)
health_check_all_resourcesVerificação de saúde abrangente em todos os recursosNenhum
optimize_resource_usageOtimizar o uso de recursos habilitando/desabilitando serviços seletivamentefocus_resources (obrigatório, lista)

Tratamento de Erros

Todas as capacidades incluem tratamento abrangente de erros:

  • Recurso Não Encontrado: Levanta ValueError com mensagem útil
  • Problemas de Conexão com o Tilt: Levanta RuntimeError com detalhes do erro do Tilt
  • Erros de Análise JSON: Fornece informações detalhadas sobre erros de análise

Todas as operações são registradas em ~/.tilt-mcp/tilt_mcp.log para depuração.

Recursos

Conformidade com o Protocolo MCP:

  • 🔍 Recursos: Acesso somente leitura aos dados do Tilt por meio de modelos de URI (por exemplo, tilt://resources/all)
  • 🛠️ Ferramentas: Ações com efeitos colaterais para gerenciamento e controle de recursos
  • 💡 Prompts: Fluxos de trabalho guiados para depuração e solução de problemas

Capacidades:

  • 📊 Descoberta de Recursos: Listar todos os recursos Tilt ativos com seu status atual
  • 📜 Recuperação de Logs: Buscar logs recentes de qualquer recurso Tilt com cauda configurável
  • 🔄 Acionamento de Recursos: Acionar manualmente recursos Tilt para reconstruir/atualizar
  • ✅ Controle de Recursos: Habilitar ou desabilitar recursos dinamicamente
  • 📋 Informações Detalhadas: Obter detalhes abrangentes sobre qualquer recurso
  • ⏳ Condições de Espera: Aguardar que os recursos atinjam estados específicos
  • 🤖 Fluxos de Trabalho Guiados: Prompts pré-construídos para cenários comuns de depuração

Recursos Técnicos:

  • 🛡️ Segurança de Tipos: Construído com dicas de tipo Python para melhor suporte a IDE
  • 🚀 Suporte Assíncrono: Implementação totalmente assíncrona usando FastMCP
  • 📈 Melhores Práticas MCP: Separação adequada de recursos, ferramentas e prompts
  • 🔧 Registro Abrangente: Todas as operações registradas em ~/.tilt-mcp/tilt_mcp.log

Pré-requisitos

  • Python 3.10 ou superior (exigido pelo FastMCP 2.0)
  • Tilt instalado e configurado
  • Um cliente compatível com MCP (por exemplo, Claude Desktop, mcp-cli)

Instalação

Você pode instalar o Tilt MCP de três maneiras:

Opção 1: Usando Docker (Recomendado para macOS/Windows)

A instalação baseada em Docker não requer configuração de Python e é mantida automaticamente atualizada com builds mensais. A imagem é otimizada para tamanho usando Alpine Linux (~320MB vs 545MB+ para imagens baseadas em Debian - redução de 41%).

Como funciona:

  • Descobre automaticamente a porta da API do Tilt a partir de ~/.tilt-dev/config com base no parâmetro tilt_port
  • Usa socat para criar dinamicamente um túnel TCP de dentro do contêiner para o servidor Tilt do host
  • O diretório ~/.tilt-dev do seu host é montado com acesso de escrita (o CLI do Tilt precisa de arquivos de bloqueio)
  • Um único servidor MCP pode consultar várias instâncias do Tilt especificando diferentes valores de tilt_port (10350, 10351, etc.)
  • O código Python lida com a descoberta de porta e o gerenciamento do socat automaticamente

Nota: O tamanho da imagem é principalmente impulsionado pelas dependências do FastMCP 2.0 (cryptography, pydantic, etc.). Para referência:

  • Base Alpine + Python: ~50MB
  • Tilt binary: ~20MB
  • FastMCP 2.0 + dependências: ~250MB

Consulte a seção Configuração MCP abaixo para instruções de configuração.

Opção 2: Do PyPI

pip install tilt-mcp

Melhor para: Usuários Linux ou quando você prefere instalação local

Opção 3: Do Código Fonte

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

Melhor para: Desenvolvimento ou teste de alterações locais

Configuração

Configuração Docker (Recomendado para macOS/Windows)

Adicione o seguinte ao seu arquivo de configuração do 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 (instância única do Tilt na porta padrão 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últiplas instâncias do Tilt:

Um único servidor MCP pode consultar várias instâncias do Tilt. Basta especificar o parâmetro tilt_port ao chamar ferramentas ou 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

Nenhuma configuração adicional é necessária - use a mesma configuração Docker de instância única acima.

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): Use %USERPROFILE% em vez de ${env:USERPROFILE} nos caminhos de montagem de volume.

Notas Chave de Configuração:

  • O parâmetro tilt_port representa a porta da interface web (10350, 10351, etc.) - NÃO a porta da API
  • O código Python descobre automaticamente a porta real da API a partir de ~/.tilt-dev/config
  • Nomenclatura de contexto: porta 10350 → "tilt-default", porta 10351 → "tilt-10351", etc.
  • O diretório ~/.tilt-dev deve ser montado com acesso de escrita (o CLI do Tilt precisa de arquivos de bloqueio)
  • socat encaminha dinamicamente a porta da API descoberta para host.docker.internal
  • --network=host é necessário para que host.docker.internal funcione no macOS/Windows

Variáveis de Ambiente:

VariávelPadrãoDescrição
IS_DOCKER_MCP_SERVERfalseDefinido como true quando executado em Docker (definido automaticamente na imagem Docker)
TILT_MCP_USE_SOCATautoControla o comportamento de encaminhamento TCP do socat (veja abaixo)
TILT_HOSThost.docker.internalHost para encaminhar ao usar socat
TILT_MCP_LOG_FILE(nenhum)Substitui o caminho do arquivo de log (padrão: ~/.tilt-mcp/tilt_mcp.log)

Modos TILT_MCP_USE_SOCAT:

  • auto (padrão): Detecção automática com base na acessibilidade da porta. Ignora o socat se o Tilt já estiver acessível em localhost (por exemplo, Docker no Linux com --network=host).
  • true ou 1: Sempre usar encaminhamento socat, mesmo que a porta já esteja acessível.
  • false ou 0: Nunca usar socat, mesmo em ambientes Docker.

Configuração de Instalação Local

Se você instalou via PyPI ou a partir do código fonte, use esta configuração mais simples:

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

Certifique-se de que tilt-mcp esteja no seu PATH.

Para Desenvolvimento/Teste

Você pode executar o servidor diretamente:

python -m tilt_mcp.server

Ou use-o com o CLI MCP:

mcp run python -m tilt_mcp.server

Verificando a Versão

Para verificar a versão instalada do tilt-mcp:

tilt-mcp --version

Construindo a Imagem Docker Localmente

Construa a imagem otimizada baseada em Alpine:

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

Ou construa com uma versão específica do Tilt:

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

Para usar Debian em vez de Alpine (imagem maior, mas melhor compatibilidade):

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

Uso

Uma vez configurado, o servidor Tilt MCP fornece Recursos, Ferramentas e Prompts por meio do Model Context Protocol.

Usando Recursos

Os recursos são somente leitura e fornecem acesso direto aos dados do Tilt. Os clientes MCP podem acessá-los por meio de seu URI:

Obter todos os recursos:

tilt://resources/all

Retorna:

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

Obter logs de um recurso:

tilt://resources/frontend/logs

Retorna as últimas 1000 linhas de logs como texto simples (padrão).

Obter número personalizado de linhas de log:

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

Retorna as últimas 50 linhas de logs como texto simples.

Obter informações detalhadas do recurso:

tilt://resources/backend/describe

Retorna saída detalhada em YAML/texto com configuração, status e histórico de build.

Usando Ferramentas

As ferramentas executam ações que modificam o estado do seu ambiente Tilt.

Acionar um rebuild:

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

Habilitar recursos específicos:

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

Desabilitar recursos:

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

Aguardar um recurso ficar pronto:

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

Usando Prompts

Os prompts fornecem fluxos de trabalho guiados para tarefas comuns. Eles geram mensagens contextuais que orientam o LLM durante depuração e solução de problemas.

Depurar um recurso com falha:

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

Isso gera um fluxo de trabalho abrangente de depuração que orienta o LLM a verificar logs, status e sugerir correções.

Realizar uma verificação de saúde:

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

Isso cria um fluxo de trabalho sistemático de verificação de saúde em todos os recursos.

Otimizar o uso de recursos:

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

Isso orienta o LLM a habilitar apenas os recursos especificados e desabilitar outros para conservar recursos do sistema.

Exemplos de Prompts

Aqui estão alguns exemplos de prompts que você pode usar com um assistente de IA que tenha acesso a este servidor MCP:

Usando Modelos de Prompt Integrados:

  • "Use o prompt debug_failing_resource para o serviço backend"
  • "Execute uma verificação de saúde em todos os meus recursos"
  • "Use o prompt troubleshoot_startup_failure para investigar por que o frontend não inicia"
  • "Analise os logs do serviço backend usando o prompt analyze_resource_logs"
  • "Ajude-me a otimizar meus recursos para focar apenas no backend e no banco de dados"

Descoberta e Status de Recursos:

  • "Mostre-me todos os recursos Tilt que estão em execução atualmente"
  • "Quais serviços estão falhando ou apresentam erros?"
  • "Compare o status dos serviços frontend e backend"
  • "Acesse o recurso tilt://resources/all para ver todos os serviços"

Análise de Logs:

  • "Obtenha as últimas 100 linhas de logs do serviço backend-api"
  • "Leia os logs de tilt://resources/frontend/logs?tail=50"
  • "Mostre-me as últimas 200 linhas de logs de quaisquer serviços com falha"
  • "Ajude-me a depurar por que o serviço frontend está travando analisando os logs recentes"

Controle de Recursos:

  • "Desabilite os serviços frontend e backend"
  • "Habilite apenas o serviço de banco de dados e desabilite todo o resto"
  • "Habilite o serviço frontend"
  • "Desabilite todos os serviços não essenciais para economizar recursos"

Build e Implantação:

  • "Acione um rebuild do serviço backend"
  • "Reconstrua o frontend e mostre-me os logs"
  • "Acione todos os serviços que apresentam erros"
  • "Aguarde o backend ficar pronto antes de verificar seus logs"

Fluxos de Trabalho Avançados de Automação:

  • "Habilite o backend, aguarde ele ficar pronto e depois verifique seus logs"
  • "Desabilite todos os serviços, depois habilite apenas o frontend e aguarde ele iniciar"
  • "Obtenha informações detalhadas sobre o banco de dados e mostre-me seus logs recentes"
  • "Acione um rebuild do serviço de API e aguarde até que ele esteja pronto"
  • "Execute uma verificação de saúde completa e corrija quaisquer problemas que encontrar"

Usando Recursos Diretamente:

  • "Leia tilt://resources/backend/describe para entender a configuração"
  • "Compare logs de tilt://resources/frontend/logs?tail=500 e tilt://resources/backend/logs?tail=500"
  • "Verifique tilt://resources/all para ver quais serviços precisam de atenção"
  • "Obtenha as últimas 50 linhas do frontend: tilt://resources/frontend/logs?tail=50"

Desenvolvimento

Configurando o ambiente de desenvolvimento

# 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]"

Executando testes

pytest

Formatação de código e linting

# Format code
black src tests

# Run linter
ruff check src tests

# Type checking
mypy src

Solução de Problemas

Problemas Comuns

  1. Erro "Tilt não encontrado"

    • Certifique-se de que o Tilt está instalado e disponível no seu PATH
    • Tente executar tilt version para verificar a instalação

  2. "Nenhum recurso encontrado" quando o Tilt está em execução

    • Certifique-se de que seu Tiltfile está carregado e os recursos foram iniciados
    • Verifique se você está executando o servidor MCP no diretório correto

  3. Erros de conexão

    • Verifique se a configuração do cliente MCP está correta
    • Verifique os logs em ~/.tilt-mcp/tilt_mcp.log

  4. tilt-mcp baseado em Docker não consegue conectar

    • Certifique-se de que seu diretório ~/.tilt-dev existe e está sendo criado pela sua instância Tilt
    • O diretório deve ser montado com acesso de escrita: ~/.tilt-dev:/home/mcp-user/.tilt-dev (o Tilt CLI precisa de arquivos de bloqueio)
    • O parâmetro tilt_port deve ser a porta da sua interface web (10350, 10351, etc.), não a porta aleatória da API
    • Verifique os logs em ~/.tilt-mcp/tilt_mcp.log para ver a porta da API descoberta
    • O código Python descobre automaticamente a porta da API a partir da configuração e inicia socat automaticamente
    • Certifique-se de que --network=host está incluído nos argumentos do docker (necessário para host.docker.internal)
    • Se o socat estiver causando problemas, você pode controlá-lo através da variável de ambiente TILT_MCP_USE_SOCAT:
      • auto (padrão): Detecta automaticamente se o socat é necessário verificando a acessibilidade da porta
      • true: Força o socat ativado
      • false: Força o socat desativado

  5. Compatibilidade com Alpine Linux

    • A imagem Docker usa Alpine Linux para otimização de tamanho
    • A maioria dos pacotes Python funciona bem, mas se você encontrar problemas com dependências binárias, pode compilar usando a base Debian alterando o argumento de build BASE_IMAGE para python:3.11-slim-bookworm

Log de Depuração

O servidor MCP registra todas as operações em ~/.tilt-mcp/tilt_mcp.log. O log inclui:

  • Eventos de inicialização/desligamento do servidor
  • Operações de busca de recursos
  • Operações de recuperação de logs
  • Mensagens de erro com detalhes completos

Para habilitar o log de depuração, defina a variável de ambiente:

export LOG_LEVEL=DEBUG

Formato do Log: timestamp - logger_name - level - message

Visualizando Logs:

# 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

Contribuindo

Aceitamos contribuições! Consulte nosso Guia de Contribuição para detalhes sobre:

  • Configuração do seu ambiente de desenvolvimento
  • Execução de testes
  • Envio de pull requests
  • Diretrizes de estilo de código

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos

  • Construído com FastMCP para a implementação do servidor MCP
  • Integra-se com Tilt para desenvolvimento Kubernetes

Suporte