{"_id":"@ai-staff/crm-mcp-server","_rev":"5-8016bdacd3412f1d82ec8a70a50f5a89","name":"@ai-staff/crm-mcp-server","dist-tags":{"latest":"2.0.4"},"versions":{"1.0.0":{"name":"@ai-staff/crm-mcp-server","version":"1.0.0","_id":"@ai-staff/crm-mcp-server@1.0.0","maintainers":[{"name":"haikg","email":"guyk.stav@gmail.com"}],"bin":{"crm-mcp-server":"dist/index.js"},"dist":{"shasum":"a59486c34d09496ef2951cebda9ada8ce4ea165b","tarball":"https://registry.npmjs.org/@ai-staff/crm-mcp-server/-/crm-mcp-server-1.0.0.tgz","fileCount":126,"integrity":"sha512-QAVeLUtDWks2bhx8z9rqhUB3whkF6NlqOC1EIIIghY+DZyzc2OakBNRZ8DPeE1jHWbNgQVt7L1nVWMgdC2Kz5w==","signatures":[{"sig":"MEUCIFLNuMScVp4VkdYuyl31WJNZvxFycmM/3L+BwTxhdBTkAiEAxYEZXmmXY2C4O2AGsK4rzQjhE6LPMbr4wqHFkpg0M8M=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":240934},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"1c0b24f836398b172d2cd2fd18cbe207b0c5db63","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","test:watch":"vitest"},"_npmUser":{"name":"haikg","email":"guyk.stav@gmail.com"},"_npmVersion":"11.9.0","description":"MCP Server for Build Your App CRM — provides AI agents with typed access to leads, companies, proposals, analysis, and more","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^3.24.0","axios":"^1.7.0","form-data":"^4.0.0","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/crm-mcp-server_1.0.0_1780358781166_0.15420980495484216","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@ai-staff/crm-mcp-server","version":"1.0.1","_id":"@ai-staff/crm-mcp-server@1.0.1","maintainers":[{"name":"haikg","email":"guyk.stav@gmail.com"}],"bin":{"crm-mcp-server":"dist/index.js"},"dist":{"shasum":"899e96c0da0ae431f7702946e1ca17408b78b3b9","tarball":"https://registry.npmjs.org/@ai-staff/crm-mcp-server/-/crm-mcp-server-1.0.1.tgz","fileCount":136,"integrity":"sha512-cAbOhFUZNsVYTW0VpdMvHeMQw2W5JZMk+JNZQiifG8rWLcczEc7jszXfpDBFuc1B9Rxlbll4md39lirUcOHEHA==","signatures":[{"sig":"MEUCIQDIJrB/zjszgQGkhfhLCfHrpqyf+2Q8qIUlGurrWG+fFQIgJJG7GOaHz5qaeuZ0aLjFzlQwwhVEqVS9VFTSY5cOGOI=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":290807},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"009477d5c7e0b2de22094db273eea08f5ab464d6","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","test:watch":"vitest"},"_npmUser":{"name":"haikg","email":"guyk.stav@gmail.com"},"_npmVersion":"11.9.0","description":"MCP Server for Build Your App CRM — provides AI agents with typed access to leads, companies, proposals, analysis, and more","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^3.24.0","axios":"^1.7.0","form-data":"^4.0.0","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/crm-mcp-server_1.0.1_1780364050243_0.5256417181020783","host":"s3://npm-registry-packages-npm-production"}},"2.0.2":{"name":"@ai-staff/crm-mcp-server","version":"2.0.2","_id":"@ai-staff/crm-mcp-server@2.0.2","maintainers":[{"name":"haikg","email":"guyk.stav@gmail.com"}],"bin":{"crm-mcp-server":"dist/index.js"},"dist":{"shasum":"7eba6824f0c0072725535426da69253f0cbfeba0","tarball":"https://registry.npmjs.org/@ai-staff/crm-mcp-server/-/crm-mcp-server-2.0.2.tgz","fileCount":177,"integrity":"sha512-U+N3ZiJY/+D1MwkgeTREJK/4f10J/2YSA065jRzws4QUPtn1H9i3gk8stP/OSeiEaF8l3Xe/6hcQdwjbj6NV/w==","signatures":[{"sig":"MEYCIQC+Q7s05vQFvoVCJEZuJPsbrRhDnXuq15UxxKHsmtSR1wIhAI98GcQ200HQZPjqDTTYCE2OR9Nw4aAgA8ZSLAkbjzN+","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":495434},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"0df7e048a56e2b21fe575434fa19669ab81a8e1d","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","test:watch":"vitest"},"_npmUser":{"name":"haikg","email":"guyk.stav@gmail.com"},"_npmVersion":"11.9.0","description":"MCP Server for Build Your App CRM — provides AI agents with typed access to leads, companies, proposals, analysis, and more","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^3.24.0","axios":"^1.7.0","form-data":"^4.0.0","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/crm-mcp-server_2.0.2_1780380983765_0.9043689894681217","host":"s3://npm-registry-packages-npm-production"}},"2.0.3":{"name":"@ai-staff/crm-mcp-server","version":"2.0.3","_id":"@ai-staff/crm-mcp-server@2.0.3","maintainers":[{"name":"haikg","email":"guyk.stav@gmail.com"}],"bin":{"crm-mcp-server":"dist/index.js"},"dist":{"shasum":"43c721f7ffc5659109d236b9171c91064097bf31","tarball":"https://registry.npmjs.org/@ai-staff/crm-mcp-server/-/crm-mcp-server-2.0.3.tgz","fileCount":177,"integrity":"sha512-akzxpq/m+OO1j/P9AFp+UyVWR666thJudpeCWGQJ8DvgW8/OjnPw9E8JMGGUP9VhFAu5OcoFN5GT6XCsEsHHSg==","signatures":[{"sig":"MEQCIBSd71LykjRWyCe9dJHzQkqtS5v2YQdf9xunT8Upgof5AiBVO4HalcFhWJSF1aURVIFQpLyBxinKdxtzpQZN+NCiRA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":496441},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"0df7e048a56e2b21fe575434fa19669ab81a8e1d","scripts":{"dev":"tsc --watch","test":"vitest run","build":"tsc","start":"node dist/index.js","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","test:watch":"vitest"},"_npmUser":{"name":"haikg","email":"guyk.stav@gmail.com"},"_npmVersion":"11.9.0","description":"MCP Server for Build Your App CRM — provides AI agents with typed access to leads, companies, proposals, analysis, and more","directories":{},"_nodeVersion":"24.14.0","dependencies":{"zod":"^3.24.0","axios":"^1.7.0","form-data":"^4.0.0","@modelcontextprotocol/sdk":"^1.12.0"},"_hasShrinkwrap":false,"devDependencies":{"vitest":"^3.1.0","typescript":"^5.7.0","@types/node":"^22.0.0"},"_npmOperationalInternal":{"tmp":"tmp/crm-mcp-server_2.0.3_1780381412447_0.23861159262984732","host":"s3://npm-registry-packages-npm-production"}},"2.0.4":{"name":"@ai-staff/crm-mcp-server","version":"2.0.4","description":"MCP Server for Build Your App CRM — provides AI agents with typed access to leads, companies, proposals, analysis, and more","type":"module","main":"dist/index.js","bin":{"crm-mcp-server":"dist/index.js"},"scripts":{"build":"tsc","start":"node dist/index.js","dev":"tsc --watch","inspect":"npx @modelcontextprotocol/inspector node dist/index.js","test":"vitest run","test:watch":"vitest"},"dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","axios":"^1.7.0","form-data":"^4.0.0","zod":"^3.24.0"},"engines":{"node":">=18.0.0"},"devDependencies":{"@types/node":"^22.0.0","typescript":"^5.7.0","vitest":"^3.1.0"},"gitHead":"1cc68a68aa07af246bbca96ab26be3878aa5a271","types":"./dist/index.d.ts","_id":"@ai-staff/crm-mcp-server@2.0.4","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-PaarjiDwijwEMtsuSRDbJtAOAK1Bvw7V8ZaXUSRuRU0SJGalgbqhRn+Y7MtZSAQ+c3w7YWxsB5u9Odq1x5cbNw==","shasum":"c3eb75af36331869811ada9f8a10f4af3e450311","tarball":"https://registry.npmjs.org/@ai-staff/crm-mcp-server/-/crm-mcp-server-2.0.4.tgz","fileCount":177,"unpackedSize":497674,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIDihNpkZaa905iQefi2bzkV+lmvG4zNDripVGPac/awjAiAWi+5DgRIsIq2CXdF0IKtxmVujimJATef/9f9sfO7dMA=="}]},"_npmUser":{"name":"haikg","email":"guyk.stav@gmail.com"},"directories":{},"maintainers":[{"name":"haikg","email":"guyk.stav@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/crm-mcp-server_2.0.4_1780398412369_0.2592954464119135"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-02T00:06:20.982Z","modified":"2026-06-02T11:06:52.702Z","1.0.0":"2026-06-02T00:06:21.301Z","1.0.1":"2026-06-02T01:34:10.387Z","2.0.2":"2026-06-02T06:16:23.889Z","2.0.3":"2026-06-02T06:23:32.602Z","2.0.4":"2026-06-02T11:06:52.562Z"},"description":"MCP Server for Build Your App CRM — provides AI agents with typed access to leads, companies, proposals, analysis, and more","maintainers":[{"name":"haikg","email":"guyk.stav@gmail.com"}],"readme":"# @ai-staff/crm-mcp-server\r\n\r\nMCP Server for **Build Your App CRM** — provides AI agents with typed access to leads, companies, proposals, analysis, and more.\r\n\r\n## Overview\r\n\r\nThis package implements a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects AI agents (e.g., Paperclip) to the Build Your App CRM system. It exposes **8 dispatcher tools + 1 standalone health check** covering all CRM domains: leads, companies, proposals, analysis, tasks, notifications, and admin.\r\n\r\nEach dispatcher uses an `action` + `params` pattern: one tool per domain, with `action` selecting the specific operation. This reduces context tokens by ~89% compared to exposing all operations as individual tools.\r\n\r\nThe server uses **stdio transport** and is configured via environment variables. A single server instance serves all API roles (CEO, ManagerAPI, AnalystAPI) — the role is determined from the JWT token in `CRM_API_KEY`.\r\n\r\n## Installation\r\n\r\n```bash\r\nnpx -y @ai-staff/crm-mcp-server\r\n```\r\n\r\nOr install globally:\r\n\r\n```bash\r\nnpm install -g @ai-staff/crm-mcp-server\r\ncrm-mcp-server\r\n```\r\n\r\n## Configuration\r\n\r\nSet environment variables before starting:\r\n\r\n| Variable | Required | Default | Description |\r\n|----------|----------|---------|-------------|\r\n| `CRM_API_URL` | No | `https://crm.ai-staff.pro/api/v1` | Base URL of the CRM API |\r\n| `CRM_API_KEY` | Yes | — | JWT API key with appropriate role (CEO, MANAGER_API, ANALYST_API) |\r\n\r\n### Paperclip Configuration\r\n\r\nAdd to your Paperclip agent's `adapterConfig`:\r\n\r\n```json\r\n{\r\n  \"mcpServers\": {\r\n    \"crm\": {\r\n      \"command\": \"npx\",\r\n      \"args\": [\"-y\", \"@ai-staff/crm-mcp-server@latest\"],\r\n      \"env\": {\r\n        \"CRM_API_URL\": \"https://crm.ai-staff.pro/api/v1\",\r\n        \"CRM_API_KEY\": \"<your-api-key>\"\r\n      }\r\n    }\r\n  }\r\n}\r\n```\r\n\r\n### Role-Based Access\r\n\r\n| Role | CRM_API_KEY | Access Level |\r\n|------|-------------|--------------|\r\n| CEO | Token with `apiRole: CEO` | Full access (except delete operations) |\r\n| ManagerAPI | Token with `apiRole: MANAGER_API` | Own leads only, limited write |\r\n| AnalystAPI | Token with `apiRole: ANALYST_API` | Read all data, run analyses, no business writes |\r\n\r\n## Tools (9 total)\r\n\r\n### Dispatchers (8)\r\n\r\nEach dispatcher accepts `action` + `params`. Call with `action: \"list\"` to discover all available actions.\r\n\r\n#### `crm_leads` — Leads & Notes (14 actions)\r\n- `list_leads` — List leads with filtering and pagination\r\n- `get_lead` — Get lead details by ID\r\n- `create_lead` — Create a new lead\r\n- `update_lead` — Update lead fields\r\n- `update_lead_status` — Change lead status\r\n- `archive_lead` — Archive a lead\r\n- `delete_lead` — Soft-delete a lead (ADMIN only)\r\n- `get_lead_history` — Get lead change history\r\n- `add_lead_manual_event` — Add manual event to history\r\n- `get_users_for_lead_assignment` — Get users for assignment\r\n- `list_lead_notes` — List notes for a lead\r\n- `add_lead_note` — Add a note to a lead\r\n- `update_lead_note` — Update a note\r\n- `delete_lead_note` — Delete a note\r\n\r\n#### `crm_companies` — Companies & Search (11 actions)\r\n- `search_companies` — Search companies directory\r\n- `search_companies_full` — Advanced company search with filters\r\n- `get_company` — Get company by ID\r\n- `count_companies` — Count companies by filters\r\n- `autocomplete` — Company name autocomplete\r\n- `get_taxonomy` — Get all categories (niches)\r\n- `get_locations` — Get cities/regions\r\n- `add_companies_to_leads` — Add companies as leads\r\n- `link_company_to_lead` — Link company to lead\r\n- `unlink_company_from_lead` — Unlink company from lead\r\n- `copy_company_data_to_lead` — Copy company data to lead\r\n\r\n#### `crm_proposals` — Proposals, Research & Generation (12 actions)\r\n- `list_proposals_by_lead` — List proposals for a lead\r\n- `get_proposal_context` — Get context for proposal creation\r\n- `create_proposal` — Create a new proposal\r\n- `update_proposal` — Update a proposal\r\n- `preview_proposal` — Preview a proposal\r\n- `start_proposal_research` — Start research for a proposal\r\n- `get_research_job_status` — Check research job status\r\n- `get_research_steps` — Get research step cache\r\n- `get_research_step_history` — Get step version history\r\n- `invalidate_research_cache` — Invalidate research cache (ADMIN only)\r\n- `generate_proposal_draft` — Generate proposal draft via AI\r\n- `regenerate_proposal_section` — Regenerate a proposal section\r\n\r\n#### `crm_analysis` — Analysis & SEO (9 actions)\r\n- `run_lead_structure_analysis` — Run structure analysis (sitemap, crawl)\r\n- `run_ai_scoring` — Run AI scoring for a lead\r\n- `run_pagespeed_analysis` — Run PageSpeed analysis\r\n- `generate_ai_audit` — Generate AI audit for a site\r\n- `start_seo_research` — Start SEO research\r\n- `get_seo_results` — Get SEO results\r\n- `get_seo_history` — Get SEO analysis history\r\n- `save_seo_results` — Save SEO results\r\n- `get_analysis_job_status` — Check analysis job status\r\n\r\n#### `crm_batch` — Batch Operations & Uploads (9 actions)\r\n- `batch_lead_structure` — Batch structure analysis for leads\r\n- `batch_lead_programmatic` — Batch programmatic analysis for leads\r\n- `batch_lead_ai_score` — Batch AI scoring for leads\r\n- `batch_company_programmatic` — Batch programmatic analysis for companies\r\n- `batch_company_structure` — Batch structure analysis for companies\r\n- `reanalyze_lead` — Re-analyze a lead (selective: tech, mobile, speed)\r\n- `start_batch_analysis` — Start batch URL analysis\r\n- `upload_screenshot` — Upload a screenshot (base64)\r\n- `upload_prototype` — Upload a prototype file (base64)\r\n\r\n#### `crm_tasks` — Tasks (5 actions)\r\n- `list_tasks` — List tasks with filtering\r\n- `create_task` — Create a task\r\n- `update_task` — Update a task\r\n- `delete_task` — Delete a task\r\n- `get_leads_for_task_select` — Get leads for task assignment\r\n\r\n#### `crm_notifications` — Notifications (4 actions)\r\n- `list_notifications` — List user notifications\r\n- `get_unread_notification_count` — Get unread count\r\n- `mark_all_notifications_read` — Mark all as read\r\n- `mark_notification_read` — Mark one as read\r\n\r\n#### `crm_admin` — Users, Settings & Audit (9 actions)\r\n- `register_user` — Register a new user (ADMIN only)\r\n- `update_user` — Update user data (ADMIN only)\r\n- `list_users` — List all users\r\n- `get_ai_settings` — Get AI settings (ADMIN/CEO/AnalystAPI)\r\n- `update_ai_settings` — Update AI settings (ADMIN/CEO only)\r\n- `list_audit_logs` — List audit logs with filtering\r\n- `get_audit_log` — Get audit log details\r\n- `cleanup_audit_logs` — Cleanup old audit logs (ADMIN only)\r\n- `cleanup_audit_log_details` — Cleanup old audit log details (ADMIN only)\r\n\r\n### Standalone (1)\r\n\r\n#### `crm_health_check` — Health Check\r\n- No params. Returns `{ status, latency, version }`.\r\n\r\n---\r\n\r\n## Discovery\r\n\r\nCall any dispatcher with `action: \"list\"` (and empty `params`) to see all available actions with their HTTP methods and endpoints:\r\n\r\n```json\r\n{\r\n  \"tool\": \"crm_leads\",\r\n  \"params\": {\r\n    \"action\": \"list\",\r\n    \"params\": {}\r\n  }\r\n}\r\n```\r\n\r\nResponse:\r\n```json\r\n{\r\n  \"available_actions\": [\r\n    { \"name\": \"list_leads\", \"description\": \"...\", \"method\": \"GET\", \"endpoint\": \"/leads\" },\r\n    ...\r\n  ],\r\n  \"hint\": \"Pass action='name' and params={...} to execute.\"\r\n}\r\n```\r\n\r\n---\r\n\r\n## Migration from v1.x\r\n\r\n**Before (v1.x):**\r\n```json\r\n{ \"tool\": \"crm_list_leads\", \"params\": { \"status\": \"NEW\", \"limit\": 20 } }\r\n```\r\n\r\n**After (v2.0):**\r\n```json\r\n{ \"tool\": \"crm_leads\", \"params\": { \"action\": \"list_leads\", \"params\": { \"status\": \"NEW\", \"limit\": 20 } } }\r\n```\r\n\r\nSee [CHANGELOG.md](./CHANGELOG.md) for full migration guide.\r\n\r\n## Development\r\n\r\n```bash\r\ncd packages/crm-mcp-server\r\nnpm install\r\nnpm run build\r\nnpm run inspect  # Test with MCP Inspector\r\n```\r\n\r\n## Error Handling\r\n\r\nAll errors are transformed into actionable messages for AI agents:\r\n\r\n| HTTP Code | Message |\r\n|-----------|---------|\r\n| 400 | Invalid request: [details]. Check the parameters and try again. |\r\n| 401 | Authentication failed. The API key is invalid or expired. |\r\n| 403 | You don't have permission to perform this action. |\r\n| 404 | Resource not found. |\r\n| 409 | This resource is locked by another user or has been modified. |\r\n| 429 | Rate limit exceeded. Retry after N seconds. |\r\n| 500 | CRM is temporarily unavailable. Please try again later. |\r\n\r\n## Pagination\r\n\r\nAll list endpoints support pagination with `page` and `limit` parameters. Default limit is 20, maximum is 100. Responses exceeding 25,000 characters are truncated with a message indicating how to get more data.\r\n\r\n## License\r\n\r\nPrivate — Internal use only.","readmeFilename":"README.md"}