Modal MCP Server

Servidor MCP (Model Context Protocol) que conecta agentes de IA (como o Google Antigravity) à infraestrutura da Modal.com, permitindo gerenciar deployments, apps, containers, volumes, secrets e ambientes via ferramentas MCP.

Arquitetura

O projeto usa o SDK oficial do MCP para expor comandos da CLI modal como ferramentas MCP. A comunicação é feita via stdio (StdioServerTransport), ideal para integração com agentes que suportam subprocessos MCP.

Agente de IA (ex: Antigravity)
        |
    [MCP - stdio]
        |
Modal MCP Server (Node.js)
        |
    [CLI: modal]
        |
    Modal.com API

Estrutura do Projeto

modal-mcp/
├── build/                      # Código compilado (TypeScript → JavaScript)
│   ├── index.js
│   ├── tools/
│   │   ├── deploy.js
│   │   ├── container.js
│   │   ├── volume.js
│   │   ├── secret.js
│   │   ├── app.js
│   │   └── environment.js
│   └── utils/
│       └── exec.js
├── src/                        # Código-fonte TypeScript
│   ├── index.ts                # Entry point do servidor MCP
│   ├── tools/                  # Módulos de ferramentas MCP
│   │   ├── deploy.ts           # Deploy e execução de apps
│   │   ├── container.ts        # Gerenciamento de containers
│   │   ├── volume.ts           # Gerenciamento de volumes persistentes
│   │   ├── secret.ts           # Gerenciamento de secrets
│   │   ├── app.ts              # Gerenciamento de apps
│   │   └── environment.ts      # Gerenciamento de ambientes
│   └── utils/
│       └── exec.ts             # Utilitário de execução da CLI modal
├── package.json
├── tsconfig.json
└── README.md

Pré-requisitos

• Node.js 18+
• Conta no Modal.com e token de autenticação configurado (modal token set)
• CLI do Modal instalada (pip install modal ou modal disponível no PATH)

Instalação

npm install
npm run build

Uso

Iniciar o servidor

npm start
# ou diretamente:
node build/index.js

O servidor escuta comandos MCP via stdin/stdout e se comunica com seu agente de IA.

Integração com Antigravity (opencode.json)

Exemplo de configuração no seu opencode.json para conectar o agente do Google Antigravity ao Modal MCP Server:

{
  "antigravityAgents": {
    "meu-agente": {
      "mcpServers": {
        "modal": {
          "command": "node",
          "args": ["caminho/para/modal-mcp/build/index.js"]
        }
      }
    }
  }
}

Ferramentas MCP Disponíveis

Deploy & Run

Ferramenta	Descrição
modal_deploy	Deploy de uma aplicação Modal a partir de um script Python
modal_run	Execução de função ou entrypoint local no Modal

App Management

Ferramenta	Descrição
modal_app_list	Lista apps em execução, deployed ou parados
modal_app_history	Histórico de deploys de um app
modal_app_logs	Logs de um app
modal_app_stop	Para permanentemente um app
modal_app_rollback	Redeploy de versão anterior
modal_app_rollover	Redeploy sem mudanças de código (novos containers)

Container Management

Ferramenta	Descrição
modal_container_list	Lista containers em execução
modal_container_exec	Executa comando dentro de um container
modal_container_logs	Logs de um container específico
modal_container_stop	Termina um container

Volume Management

Ferramenta	Descrição
modal_volume_list	Lista volumes
modal_volume_create	Cria um volume persistente
modal_volume_delete	Deleta um volume
modal_volume_ls	Lista arquivos/diretórios dentro de um volume
modal_volume_put	Upload de arquivo/diretório para um volume
modal_volume_get	Download de arquivos de um volume
modal_volume_rm	Remove arquivo/diretório de um volume
modal_volume_rename	Renomeia um volume

Secret Management

Ferramenta	Descrição
modal_secret_list	Lista secrets publicados
modal_secret_create	Cria um novo secret
modal_secret_delete	Deleta um secret

Environment Management

Ferramenta	Descrição
modal_env_list	Lista ambientes do workspace
modal_env_create	Cria um novo ambiente
modal_env_delete	Deleta um ambiente
modal_env_update	Atualiza configurações de ambiente
modal_env_members_list	Lista membros de ambiente restrito
modal_env_members_update	Adiciona/atualiza papel de membro
modal_env_members_remove	Remove membro de ambiente restrito

Fluxo de Funcionamento

1. O agente de IA (ex: Google Antigravity) envia requisições MCP via stdio
2. O servidor MCP recebe a requisição e identifica qual ferramenta foi chamada
3. A ferramenta monta o comando modal <subcomando> apropriado
4. O comando é executado via child_process.exec
5. O stdout do comando é retornado como resposta MCP

Scripts

Comando	Descrição
npm run build	Compila TypeScript para JavaScript (tsc)
npm run dev	Compila em modo watch (tsc -w)
npm start	Inicia o servidor MCP