ZT Playground - MCP Server

Servidor MCP (Model Context Protocol) para gerenciamento de projetos, issues, bugs, analytics e monitoramento do ZT Playground.

Ferramentas disponíveis

• Projetos - listar projetos, plataformas, saúde do projeto
• Issues - criar, buscar, atualizar issues (tasks, bugs, stories)
• Epics - criar épicos com sub-tasks automáticas
• Bugs - reportar bugs com contexto enriquecido (steps to reproduce, expected/actual behavior)
• Comentários - adicionar comentários em issues
• Anexos - anexar arquivos/imagens em issues
• Labels - gerenciar labels em issues
• Analytics - relatórios por repositório e análise por área
• Monitor - overview de erros, listagem, detalhes, eventos, performance

Setup para usar com Claude Code

Pre-requisitos

• Node.js v18+
• Acesso ao banco de dados PostgreSQL do ZT Playground
• Uma API Key válida do ZT Playground

Passo 1 - Clonar o repositório

git clone [email protected]:v0up3r/zt-mcp-server.git
cd zt-mcp-server

Passo 2 - Instalar dependências

npm install

Passo 3 - Gerar o Prisma Client

npx prisma generate

Passo 4 - Build do projeto

npm run build

Passo 5 - Configurar o MCP no Claude Code

Abra o arquivo de configuração do Claude Code. Existem duas opções:

Opção A - Configuração global (funciona em qualquer projeto):

# Abre o arquivo de configuração global
nano ~/.claude/settings.json

Opção B - Configuração por projeto (apenas no projeto específico):

# Na raiz do seu projeto, crie/edite o arquivo
nano .mcp.json

Passo 6 - Adicionar a configuração do MCP

Cole a seguinte configuração (ajuste os caminhos e variáveis):

Para ~/.claude/settings.json (configuração global):

{
  "mcpServers": {
    "zt-playground": {
      "command": "node",
      "args": ["/CAMINHO/COMPLETO/PARA/zt-mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://USUARIO:SENHA@HOST:PORTA/BANCO",
        "ZT_API_KEY": "SUA_API_KEY_AQUI"
      }
    }
  }
}

Para .mcp.json (configuração por projeto):

{
  "mcpServers": {
    "zt-playground": {
      "command": "node",
      "args": ["/CAMINHO/COMPLETO/PARA/zt-mcp-server/dist/index.js"],
      "env": {
        "DATABASE_URL": "postgresql://USUARIO:SENHA@HOST:PORTA/BANCO",
        "ZT_API_KEY": "SUA_API_KEY_AQUI"
      }
    }
  }
}

Importante: Substitua:

• /CAMINHO/COMPLETO/PARA/zt-mcp-server/ pelo caminho real onde você clonou o repositório
• DATABASE_URL pela connection string do banco PostgreSQL
• ZT_API_KEY pela sua API key pessoal

Passo 7 - Reiniciar o Claude Code

Feche e abra o Claude Code novamente (ou use /mcp para verificar o status do servidor).

Passo 8 - Verificar se está funcionando

No Claude Code, digite:

/mcp

Você deve ver o servidor zt-playground listado e ativo. Agora pode usar comandos como:

• "Liste os projetos do ZT Playground"
• "Crie uma task no projeto X"
• "Mostre os bugs abertos"
• "Qual a saúde do projeto X?"
• "Mostre os erros do monitor"

Setup para usar com OpenAI Codex

Passos 1 a 4

Mesmos passos do Claude Code (clonar, instalar, gerar prisma, build).

Passo 5 - Configurar o MCP no Codex

Opção A - Via CLI:

codex mcp add zt-playground \
  --env DATABASE_URL=postgresql://USUARIO:SENHA@HOST:PORTA/BANCO \
  --env ZT_API_KEY=SUA_API_KEY_AQUI \
  -- node /CAMINHO/COMPLETO/PARA/zt-mcp-server/dist/index.js

Opção B - Editando o arquivo de configuração:

Edite ~/.codex/config.toml (global) ou .codex/config.toml (por projeto):

[mcp_servers.zt-playground]
command = "node"
args = ["/CAMINHO/COMPLETO/PARA/zt-mcp-server/dist/index.js"]

[mcp_servers.zt-playground.env]
DATABASE_URL = "postgresql://USUARIO:SENHA@HOST:PORTA/BANCO"
ZT_API_KEY = "SUA_API_KEY_AQUI"

Passo 6 - Verificar

Reinicie o Codex e as ferramentas do ZT Playground estarão disponíveis.

Variáveis de ambiente

| Variável | Descrição | Obrigatório | | -------------- | ------------------------------------------ | ----------- | | DATABASE_URL | Connection string do PostgreSQL | Sim | | ZT_API_KEY | API Key para autenticação no ZT Playground | Sim |

Desenvolvimento

# Rodar em modo desenvolvimento
npm run dev

# Build
npm run build

# Gerar Prisma Client
npm run prisma:generate