pipeyard

Mercado de conectores MCP selecionados para setores verticais — Construção, Finanças, Saúde e Logística, com documentação completa, exemplos curl e testes em sandbox.

GitHub
4
Experimente este MCPPatrocinado

Documentação

Servidor MCP do Procore

Este projeto implementa um servidor Model Context Protocol (MCP) que conecta o Claude (e outros clientes compatíveis com MCP) à API do Procore. Ele expõe ferramentas para trabalhar com:

  • Projetos
  • RFIs
  • Submissões (Submittals)
  • Documentos
  • Orçamento e custos

Todas as ferramentas retornam respostas JSON limpas, validam entradas com zod e incluem tratamento robusto de erros para respostas 401, 403, 404 e 429 (limite de taxa) do Procore.

Pré-requisitos

  • Node.js: v18+ (recomendado)
  • npm: v9+ (acompanha o Node.js recente)
  • Conta de desenvolvedor Procore com:
    • Um cliente OAuth2 registrado usando o fluxo Client Credentials
    • Acesso à API para os projetos/módulos relevantes (RFIs, Submissões, Documentos, Orçamento, etc.)

Instalação

cd C:\Procore
npm install

Se você criou a pasta em outro local, ajuste o caminho cd de acordo.

Obtendo credenciais da API do Procore

  • Acesse o Portal do Desenvolvedor Procore.
  • Crie um Cliente OAuth usando o tipo de concessão Client Credentials.
  • Anote os seguintes valores:
    • Client ID
    • Client Secret
  • Garanta que o cliente tenha escopos de acesso apropriados para:
    • Projetos
    • RFIs
    • Submissões
    • Documentos
    • Gerenciamento de orçamento e custos

Você usará esses valores no seu arquivo .env.

Configuração de variáveis de ambiente

Crie um arquivo .env na raiz do projeto (ao lado de package.json) com base em .env.example:

cp .env.example .env

Em seguida, edite .env:

PROCORE_CLIENT_ID=your_real_client_id
PROCORE_CLIENT_SECRET=your_real_client_secret
PROCORE_BASE_URL=https://api.procore.com
  • PROCORE_CLIENT_ID: Do portal do desenvolvedor Procore.
  • PROCORE_CLIENT_SECRET: Do portal do desenvolvedor Procore.
  • PROCORE_BASE_URL: Normalmente https://api.procore.com (você pode substituir para ambientes de sandbox/teste).

Compilar e executar localmente

Instale as dependências:

npm install

Execute em modo de desenvolvimento (TypeScript via tsx):

npm run dev

Compile o TypeScript para dist/:

npm run build

Execute o servidor compilado:

npm start

O servidor MCP usa stdio (entrada/saída padrão), portanto normalmente é iniciado e gerenciado por um cliente MCP, como o Claude Desktop. Geralmente você não o chama diretamente no terminal, exceto para depuração.

Ferramentas disponíveis

Todas as ferramentas retornam JSON. Os argumentos mostrados abaixo são os argumentos das ferramentas, não chamadas HTTP brutas.

  • Projetos

    • list_projects
      • Descrição: Lista projetos do Procore para o cliente autenticado, opcionalmente filtrados por company_id.
      • Entradas:
        • company_id (opcional, inteiro): Filtra projetos por empresa.
    • get_project
      • Descrição: Obtém detalhes de um único projeto por ID.
      • Entradas:
        • id (obrigatório, inteiro): ID do projeto.

  • RFIs

    • list_rfis
      • Descrição: Lista RFIs de um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.
    • get_rfi
      • Descrição: Obtém um único RFI por ID em um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.
        • id (obrigatório, inteiro): ID do RFI.
    • create_rfi
      • Descrição: Cria um novo RFI em um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.
        • payload (obrigatório, objeto): Payload JSON bruto correspondente ao corpo da API create RFI do Procore.

  • Submissões (Submittals)

    • list_submittals
      • Descrição: Lista submissões de um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.
    • get_submittal
      • Descrição: Obtém uma única submissão por ID em um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.
        • id (obrigatório, inteiro): ID da submissão.
    • create_submittal
      • Descrição: Cria uma nova submissão em um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.
        • payload (obrigatório, objeto): Payload JSON bruto correspondente ao corpo da API create Submittal do Procore.

  • Documentos

    • list_folders
      • Descrição: Lista pastas de documentos de um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.
    • list_files
      • Descrição: Lista arquivos de documentos de um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.

  • Orçamento

    • list_budget_line_items
      • Descrição: Lista itens de linha do orçamento de um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.
    • get_budget_summary
      • Descrição: Obtém o resumo geral do orçamento de um projeto.
      • Entradas:
        • project_id (obrigatório, inteiro): ID do projeto.

Exemplos de chamadas de ferramentas no estilo curl (via MCP JSON-RPC)

Servidores MCP falam JSON-RPC via stdio; normalmente você não os chama diretamente com curl. Esses exemplos ilustram a estrutura do payload que um cliente como o Claude Desktop enviaria.

Substitua 123 / 456 etc. pelos seus IDs reais.

  • Listar projetos
echo '{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {
      "company_id": 123
    }
  }
}' | node dist/index.js
  • Obter um projeto
echo '{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "get_project",
    "arguments": {
      "id": 123
    }
  }
}' | node dist/index.js
  • Listar RFIs
echo '{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "list_rfis",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Criar RFI
echo '{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "create_rfi",
    "arguments": {
      "project_id": 123,
      "payload": {
        "subject": "RFI subject here",
        "question": "Describe the question...",
        "responsible_contractor_id": 456
      }
    }
  }
}' | node dist/index.js
  • Listar submissões
echo '{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "tools/call",
  "params": {
    "name": "list_submittals",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Criar submissão
echo '{
  "jsonrpc": "2.0",
  "id": 6,
  "method": "tools/call",
  "params": {
    "name": "create_submittal",
    "arguments": {
      "project_id": 123,
      "payload": {
        "subject": "Submittal subject",
        "spec_section": "01 30 00",
        "responsible_contractor_id": 456
      }
    }
  }
}' | node dist/index.js
  • Listar pastas
echo '{
  "jsonrpc": "2.0",
  "id": 7,
  "method": "tools/call",
  "params": {
    "name": "list_folders",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Listar arquivos
echo '{
  "jsonrpc": "2.0",
  "id": 8,
  "method": "tools/call",
  "params": {
    "name": "list_files",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Listar itens de linha do orçamento
echo '{
  "jsonrpc": "2.0",
  "id": 9,
  "method": "tools/call",
  "params": {
    "name": "list_budget_line_items",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js
  • Obter resumo do orçamento
echo '{
  "jsonrpc": "2.0",
  "id": 10,
  "method": "tools/call",
  "params": {
    "name": "get_budget_summary",
    "arguments": {
      "project_id": 123
    }
  }
}' | node dist/index.js

Comportamento de tratamento de erros

Todas as ferramentas incluem respostas de erro JSON consistentes. Formato típico:

{
  "error": "unauthorized",
  "message": "Procore API returned 401 Unauthorized.",
  "status": 401,
  "statusText": "Unauthorized",
  "url": "/rest/v1.0/projects",
  "method": "get",
  "data": { /* raw Procore response body, if any */ }
}

Status HTTP tratados:

  • 401: unauthorized
  • 403: forbidden
  • 404: not_found
  • 429: rate_limited
  • Outros 4xx/5xx: procore_api_error
  • Validação / outros erros: tool_error

Como conectar ao Claude Desktop (configuração MCP)

No Claude Desktop, adicione uma nova configuração de servidor MCP no seu claude_desktop_config.json (o caminho pode variar conforme o sistema operacional).

Exemplo de entrada:

{
  "mcp_servers": {
    "procore": {
      "command": "node",
      "args": [
        "C:/Procore/procore-mcp-server/dist/index.js"
      ],
      "env": {
        "PROCORE_CLIENT_ID": "your_real_client_id",
        "PROCORE_CLIENT_SECRET": "your_real_client_secret",
        "PROCORE_BASE_URL": "https://api.procore.com"
      }
    }
  }
}
  • command: node (ou um caminho explícito para o seu binário Node).
  • args: Caminho para o index.js compilado em dist/.
  • env: Você pode:
    • Inserir seus segredos aqui (com cautela), ou
    • Omitir env para que o Claude Desktop herde as variáveis de ambiente do seu sistema.

Após salvar a configuração, reinicie o Claude Desktop. O servidor MCP procore deve aparecer como um conjunto de ferramentas disponível, e as ferramentas listadas acima (list_projects, get_project, list_rfis, etc.) poderão ser chamadas diretamente de dentro do Claude.