captahub-mcp

Servidor MCP (Model Context Protocol) somente-leitura que expõe os editais abertos do CaptaHub pro Claude Desktop.

Permite que o Claude liste e busque editais usando linguagem natural — sem precisar abrir o painel do CaptaHub.

Funcionalidade

Uma única tool:

list_open_editais

Lista editais ABERTOS, ordenados por deadline ascendente. Um edital é considerado aberto quando:

status = 'aberto'  AND  (is_continuous = true  OR  deadline >= hoje)

Parâmetros (todos opcionais):

| Parâmetro | Tipo | Descrição | | ------------- | ------ | ----------------------------------------------------------------- | | category | string | Categoria exata (ex.: cultura, inovação). | | scope | string | Escopo exato (ex.: federal, estadual, municipal). | | institution | string | Busca parcial e case-insensitive na instituição. | | search | string | Busca textual em title e description (case-insensitive). | | limit | number | Máximo de resultados. Padrão 50, máximo 100. |

Campos retornados por edital:

id, title, institution, category, scope, value, deadline, is_continuous, url, description, tags, data_publicacao.

Pré-requisitos

• Node.js >= 18 (nodejs.org)
• Claude Desktop instalado (claude.ai/download)

Como instalar

Tem dois modos. Escolha um.

Modo A — via npx (para usar em qualquer máquina)

Não precisa clonar repo, instalar dependências nem buildar. O npx baixa o pacote do npm e executa.

Cole o bloco abaixo no arquivo claude_desktop_config.json do Claude Desktop (veja onde fica na seção Localização do config):

{
  "mcpServers": {
    "captahub": {
      "command": "npx",
      "args": ["-y", "captahub-mcp"],
      "env": {
        "SUPABASE_URL": "https://pkwwnajskprfutfavylq.supabase.co",
        "SUPABASE_ANON_KEY": "eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}

Windows: dependendo da versão do Node, pode ser necessário usar "command": "npx.cmd" no lugar de "command": "npx".

Reinicie o Claude Desktop e pronto.

Modo B — build local (para desenvolvimento)

Use durante desenvolvimento do próprio MCP.

git clone <url-deste-repo> captahub-mcp
cd captahub-mcp
npm install
cp .env.example .env
# preencha SUPABASE_URL e SUPABASE_ANON_KEY no .env
npm run build

Depois cole o bloco abaixo no claude_desktop_config.json (ajustando o caminho do args pro absoluto da sua máquina):

{
  "mcpServers": {
    "captahub": {
      "command": "node",
      "args": [
        "/caminho/absoluto/ate/captahub-mcp/dist/index.js"
      ],
      "env": {
        "SUPABASE_URL": "https://pkwwnajskprfutfavylq.supabase.co",
        "SUPABASE_ANON_KEY": "eyJhbGciOiJIUzI1NiIs..."
      }
    }
  }
}

Localização do config

macOS

open -a "TextEdit" "$HOME/Library/Application Support/Claude/claude_desktop_config.json"

Atalho pela UI: Settings > Developer > Edit Config.

Windows

notepad "$env:APPDATA\Claude\claude_desktop_config.json"

Atalho pela UI: Settings > Developer > Edit Config.

Se o arquivo não existir, crie ele com o JSON do Modo A ou B.

Já tem outros servidores MCP?

Se o arquivo já existir, adicione apenas a chave "captahub": { ... } dentro do objeto mcpServers existente — não substitua o arquivo inteiro.

Reiniciar o Claude Desktop

Mudanças no config só carregam quando o Claude Desktop é reaberto por completo:

• macOS: Cmd+Q (fechar a janela não basta), depois abrir de novo.
• Windows: clicar com o botão direito no ícone da bandeja do sistema, Quit, depois abrir de novo.

Pra confirmar que carregou, clique no ícone de ferramentas (🔧) na tela de chat. Deve aparecer list_open_editais.

Como usar no Claude

Em linguagem natural:

• "Liste os editais de cultura abertos"
• "Tem algum edital federal de inovação aberto?"
• "Quais editais do CNPq estão abertos?"
• "Busque editais que mencionem 'audiovisual'"

O Claude chama list_open_editais automaticamente com os filtros que fizerem sentido.

Scripts

| Script | Descrição | | --------------- | ------------------------------------------------------------ | | npm run dev | Modo desenvolvimento com tsx watch (recarrega ao salvar). | | npm run build | Compila TypeScript pra dist/. | | npm run start | Roda dist/index.js (precisa ter buildado antes). |

Debug

Logs saem em stderr (stdout é reservado pro protocolo MCP).

Ver logs no Claude Desktop

• macOS: tail -f "$HOME/Library/Logs/Claude/mcp-server-captahub.log"
• Windows: Get-Content "$env:APPDATA\Claude\Logs\mcp-server-captahub.log" -Wait

Erros comuns

| Erro | Causa provável | | ----------------------------------------------- | ------------------------------------------------------------------------- | | variável de ambiente "X" não está definida | Falta o campo env no claude_desktop_config.json. | | Tool desconhecida | Reinicie o Claude Desktop completamente. | | Falha ao consultar editais: <RLS error> | Policy do Supabase bloqueou — verifique RLS de editais pra anon. | | Servidor não aparece | Modo A: rede sem internet? Modo B: caminho do args errado / faltou build. | | Windows: erro tipo 'npx' is not recognized | Troque pra "command": "npx.cmd" no JSON. |

Publicação no npm (mantenedor)

Para publicar uma nova versão (necessário pra que npx -y captahub-mcp baixe atualizações):

# 1. Logar no npm (uma vez por máquina)
npm login

# 2. Bumpar a versão
npm version patch   # ou minor / major

# 3. Publicar (o prepublishOnly roda npm run build automaticamente)
npm publish

Pacote é público (publishConfig.access: "public") e gratuito. Usuários finais não precisam de nenhuma config no npm — só ter Node 18+.

Segurança

• Usa ANON KEY do Supabase — mesmas permissões de qualquer usuário não logado do app.
• Segurança real é garantida pelas policies de RLS na tabela editais. A policy atual é Anyone can view editais USING (true).
• Nenhuma escrita: só SELECT. Não tem tools de insert/update/delete.
• A chave anon é passada via env no claude_desktop_config.json — não fica no pacote npm.

Licença

Uso interno CaptaHub.