{"_id":"@agasalhem/pipedrive-mcp","name":"@agasalhem/pipedrive-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agasalhem/pipedrive-mcp","version":"0.1.0","description":"MCP server local (stdio) que expõe a API inteira do Pipedrive via search + execute.","type":"module","bin":{"pipedrive-mcp":"dist/server.js"},"scripts":{"fetch-specs":"curl -sSL https://developers.pipedrive.com/docs/api/v1/openapi.yaml -o openapi/pipedrive-v1.yaml && curl -sSL https://developers.pipedrive.com/docs/api/v1/openapi-v2.yaml -o openapi/pipedrive-v2.yaml && echo specs atualizados","generate":"node scripts/generate-catalog.mjs","build":"npm run generate && tsc","start":"node dist/server.js","dev":"tsx src/server.ts","inspect":"npm run build && npx @modelcontextprotocol/inspector node dist/server.js"},"engines":{"node":">=18"},"license":"MIT","private":false,"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","yaml":"^2.9.0","zod":"^4.4.3"},"devDependencies":{"@types/node":"^25.9.1","tsx":"^4.22.4","typescript":"^6.0.3"},"gitHead":"b9bbb6e3b080d5a570f1706308e77bbb904d8f22","_id":"@agasalhem/pipedrive-mcp@0.1.0","_nodeVersion":"25.8.1","_npmVersion":"11.11.0","dist":{"integrity":"sha512-CUqcvvNVs4GZfuvT2QNLB+oUDOnlbXyjncOSWJmm0nvh7XxLHsBDqkJwLs1Zm3lKXY94pg8NhKpu5MapGgg38A==","shasum":"bb52d384dfae49d8589b9df68ad57535aea6c65e","tarball":"https://registry.npmjs.org/@agasalhem/pipedrive-mcp/-/pipedrive-mcp-0.1.0.tgz","fileCount":8,"unpackedSize":3320278,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIAWm8Afkn+yEqr5OA7InH34TTacLjrg1g0XFmZTgYblpAiEAx5TQWMGGyfohTKy4QKqFO1U9i7FC7qhAPf+2LlKEtzY="}]},"_npmUser":{"name":"agasalhem","email":"gmagalhaes9652@gmail.com"},"directories":{},"maintainers":[{"name":"agasalhem","email":"gmagalhaes9652@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/pipedrive-mcp_0.1.0_1780336928330_0.3716793751533767"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-01T18:02:08.059Z","0.1.0":"2026-06-01T18:02:08.532Z","modified":"2026-06-01T18:02:08.810Z"},"maintainers":[{"name":"agasalhem","email":"gmagalhaes9652@gmail.com"}],"description":"MCP server local (stdio) que expõe a API inteira do Pipedrive via search + execute.","license":"MIT","readme":"# @agasalhem/pipedrive-mcp\n\nMCP server stdio que expõe a API inteira do Pipedrive (v1 + v2) pro Claude, via padrão **search + execute**. Reaproveitável entre clientes: o que muda é só o token por conta.\n\n## Instalação\n\n### Via npx (recomendado — zero instalação)\n\nAdicione ao `.mcp.json` do seu projeto:\n\n```json\n{\n  \"mcpServers\": {\n    \"pipedrive\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@agasalhem/pipedrive-mcp\"],\n      \"env\": {\n        \"PIPEDRIVE_API_TOKEN\": \"seu-token-aqui\"\n      }\n    }\n  }\n}\n```\n\n> O token fica em **Settings → Personal preferences → API** no Pipedrive.\n\n### Via npm global\n\n```bash\nnpm install -g @agasalhem/pipedrive-mcp\n```\n\nE no `.mcp.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"pipedrive\": {\n      \"command\": \"pipedrive-mcp\",\n      \"env\": {\n        \"PIPEDRIVE_API_TOKEN\": \"seu-token-aqui\"\n      }\n    }\n  }\n}\n```\n\n### Variáveis de ambiente\n\n| Variável | Obrigatória | Descrição |\n|---|---|---|\n| `PIPEDRIVE_API_TOKEN` | sim | Token da API do Pipedrive |\n| `PIPEDRIVE_BASE_URL` | não | Substitui só o domínio (ex: `https://suaempresa.pipedrive.com`) |\n\n---\n\n## Como funciona\n\nA API do Pipedrive tem ~370 operações. Registrar uma tool por endpoint estouraria o contexto do Claude, então o catálogo fica interno e o server expõe só três tools:\n\n- **`search_actions`** — acha a operação por intenção em linguagem natural (PT ou EN). Retorna o ID, método, rota, qual tool de execução usar e os schemas de path/query/body. Chamar isto primeiro.\n- **`execute_read_action`** — executa uma operação de leitura (GET). Marcada `readOnlyHint`, então o Claude Code pode auto-aprovar.\n- **`execute_write_action`** — executa escrita (POST/PUT/PATCH/DELETE). Marcada `destructiveHint`, então pede confirmação antes de alterar o CRM.\n\nSeparar leitura de escrita é a regra de annotations do MCP e dá uma UX de permissão mais segura num CRM em produção.\n\n### Por que dois specs (v1 + v2)\n\nO Pipedrive migrou o CRUD central (deals, persons, organizations, activities, products) pra **API v2** e tirou do spec v1. O v1 guarda a cauda longa (fields, followers, participants, filters, pipelines, stages, notes, leads). O catálogo mescla os dois e, em colisão de `operationId`, o v2 vence. Cada ação carrega seu próprio `server` porque as bases diferem (`/v1` vs `/api/v2`).\n\n### Ranking da busca\n\nKeyword scoring com alguns ajustes pra qualidade: peso maior no primeiro termo da intenção, bônus quando a entidade bate com o recurso raiz da rota, mapa de verbo→método (criar→POST, atualizar→PATCH, etc.) e dicionário de sinônimos PT→EN (negócio→deal, pessoa→person, atividade→activity...). Não é semântico/embeddings, mas acerta a operação central no topo na maioria das intenções comuns de RevOps.\n\n## Desenvolvimento\n\n```bash\nnpm install\nnpm run build      # gera o catálogo a partir dos specs e compila\n```\n\n```bash\nnpm run fetch-specs   # rebaixa os OpenAPI v1 e v2 do Pipedrive\nnpm run build         # regenera o catálogo e recompila\n```\n\nOs specs ficam versionados em `openapi/`. Rodar `fetch-specs` quando o Pipedrive publicar mudanças na API.\n\n## Teste manual\n\n```bash\n# lista as tools\nnpx @modelcontextprotocol/inspector --cli node dist/server.js --method tools/list\n\n# busca (não precisa de token)\nnpx @modelcontextprotocol/inspector --cli node dist/server.js \\\n  --method tools/call --tool-name search_actions --tool-arg intent=\"criar um negócio\"\n```\n\n## Estrutura\n\n```\nopenapi/          specs v1 e v2 do Pipedrive (versionados)\nscripts/          gerador do catálogo (mescla os specs)\ndata/catalog.json catálogo enxuto consumido em runtime\nsrc/catalog.ts    tipos, carregamento e ranking\nsrc/client.ts     client HTTP (auth x-api-token, base por versão)\nsrc/server.ts     server stdio + as três tools\n```\n\n## Notas\n\n- O token nunca aparece na URL retornada pro Claude (auth vai no header).\n- Respostas grandes são truncadas em 60k caracteres com aviso pra paginar.\n- Read/write split: leitura auto-aprovável, escrita pede confirmação.\n\n## Licença\n\nMIT\n","readmeFilename":"README.md","_rev":"1-0581a517366a99e2c87006cad367df41"}