# Modal MCP Server

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

## Arquitetura

O projeto usa o [SDK oficial do MCP](https://github.com/modelcontextprotocol/typescript-sdk) 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

```bash
npm install
npm run build
```

## Uso

### Iniciar o servidor

```bash
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:

```json
{
  "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 |