SupaMCP Server

Um servidor MCP configurável em tempo de execução que transforma um projeto Supabase em uma interface de ferramenta compatível com IA.

GitHub
11
Experimente este MCPPatrocinado

Documentação

SupaMCPBuilder

Um servidor MCP (Model Context Protocol) configurável em tempo de execução para bancos de dados Supabase, com suporte a configuração JSON inline. Crie ferramentas dinâmicas para seu banco de dados Supabase sem escrever código!

Recursos

  • 🚀 Zero Configuração: Funciona imediatamente com qualquer projeto Supabase
  • 🔧 Configurável em Tempo de Execução: Defina ferramentas usando configuração JSON
  • 🔐 Autenticação Integrada: Atualização automática de token JWT e gerenciamento de sessão
  • 📊 Geração Dinâmica de Ferramentas: Crie operações de banco de dados personalizadas via JSON
  • 🎯 Suporte a Templates: Use templates estilo Jinja2 em suas configurações
  • 🔄 Suporte a Base64: Lide com configurações JSON complexas com segurança

Início Rápido

Usando com npx (Recomendado)

npx supamcpbuilder --url YOUR_SUPABASE_URL --anon-key YOUR_ANON_KEY --email YOUR_EMAIL --password YOUR_PASSWORD --tools-json-base64 BASE64_ENCODED_TOOLS

Instalação

npm install -g supamcpbuilder

Opções de Configuração

Uso Básico

supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "your-email@example.com" \
  --password "your-password"

Com Arquivo de Configuração JSON

supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "your-email@example.com" \
  --password "your-password" \
  --config-path "./tools-config.json"

Com Ferramentas Codificadas em Base64

supamcpbuilder \
  --url "https://your-project.supabase.co" \
  --anon-key "your-anon-key" \
  --email "your-email@example.com" \
  --password "your-password" \
  --tools-json-base64 "W3sibmFtZSI6Imxpc3QtdXNlcnMiLCJkZXNjcmlwdGlvbiI6Ikxpc3QgYWxsIHVzZXJzIn1d"

Formato de Configuração de Ferramentas

Estrutura Básica de Ferramenta

[
  {
    "name": "list-users",
    "description": "List all users from the users table",
    "parameters": {
      "type": "object",
      "properties": {
        "limit": {
          "type": "number",
          "description": "Number of users to return",
          "default": 10
        }
      }
    },
    "action": {
      "type": "select",
      "table": "users",
      "columns": ["id", "name", "email"],
      "limit": "{{limit}}"
    }
  }
]

Tipos de Ação Suportados

  • select: Consultar dados de tabelas
  • insert: Criar novos registros
  • update: Modificar registros existentes
  • delete: Remover registros

Variáveis de Template

Use templates estilo Jinja2 em suas configurações:

{
  "action": {
    "type": "select",
    "table": "{{table_name}}",
    "filters": {
      "id": "{{user_id}}"
    }
  }
}

Configuração do Cliente MCP

Configuração do Cursor IDE

Adicione ao seu ~/.cursor/mcp.json:

{
  "mcpServers": {
    "supamcpbuilder": {
      "command": "npx",
      "args": [
        "-y",
        "supamcpbuilder",
        "--url", "https://your-project.supabase.co",
        "--anon-key", "your-anon-key",
        "--email", "your-email@example.com",
        "--password", "your-password",
        "--tools-json-base64", "YOUR_BASE64_ENCODED_TOOLS"
      ]
    }
  }
}

Configuração do Claude Desktop

Adicione à configuração do seu Claude Desktop:

{
  "mcpServers": {
    "supamcpbuilder": {
      "command": "npx",
      "args": [
        "-y",
        "supamcpbuilder",
        "--url", "https://your-project.supabase.co",
        "--anon-key", "your-anon-key",
        "--email", "your-email@example.com",
        "--password", "your-password",
        "--config-path", "/path/to/your/tools-config.json"
      ]
    }
  }
}

Variáveis de Ambiente

Você também pode usar variáveis de ambiente:

export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_ANON_KEY="your-anon-key"
export SUPABASE_EMAIL="your-email@example.com"
export SUPABASE_PASSWORD="your-password"

supamcpbuilder --config-path "./tools-config.json"

Configuração Avançada

Exemplo de Ferramenta Complexa

[
  {
    "name": "create-user-with-profile",
    "description": "Create a new user with profile information",
    "parameters": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "description": "User's full name"
        },
        "email": {
          "type": "string",
          "description": "User's email address"
        },
        "bio": {
          "type": "string",
          "description": "User's biography"
        }
      },
      "required": ["name", "email"]
    },
    "action": {
      "type": "insert",
      "table": "users",
      "values": {
        "name": "{{name}}",
        "email": "{{email}}",
        "bio": "{{bio}}",
        "created_at": "now()"
      },
      "returning": ["id", "name", "email"]
    }
  }
]

Autenticação e Segurança

  • Autenticação de Usuário: Usa email/senha com atualização automática de JWT
  • Segurança em Nível de Linha: Todas as operações respeitam as políticas RLS do seu Supabase
  • Seguro por Padrão: Sem acesso de administrador, foca em operações no nível do usuário
  • Atualização Automática de Token: Lida com a expiração do JWT automaticamente

Solução de Problemas

Problemas Comuns

  1. Erros de Autenticação: Verifique se sua combinação de email/senha está correta
  2. Permissão Negada: Verifique suas políticas RLS e permissões de usuário
  3. Ferramenta Não Encontrada: Verifique a sintaxe da sua configuração JSON
  4. Problemas de Conexão: Confirme sua URL do Supabase e chaves de API

Modo de Depuração

Ative o registro de depuração:

DEBUG=supamcpbuilder supamcpbuilder --url ... --anon-key ...

Exemplos

Consulte o diretório examples/ para:

  • Exemplos de configuração de ferramentas
  • Exemplos de configuração de clientes MCP
  • Casos de uso comuns

Contribuindo

  1. Faça um fork do repositório
  2. Crie sua branch de recurso (git checkout -b feature/amazing-feature)
  3. Faça commit das suas alterações (git commit -m 'Add some amazing feature')
  4. Envie para a branch (git push origin feature/amazing-feature)
  5. Abra um Pull Request

Licença

Este projeto está licenciado sob a Licença MIT - consulte o arquivo LICENÇA para detalhes.

Suporte

Changelog

v1.0.0

  • Lançamento inicial
  • Funcionalidade básica do servidor MCP
  • Suporte a configuração JSON
  • Suporte a codificação Base64
  • Tratamento de autenticação
  • Suporte a variáveis de template