{"_id":"@alludium/harmonic-mcp-server","_rev":"3-859ee4940b2b864d43a1f33a90b92a9c","name":"@alludium/harmonic-mcp-server","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@alludium/harmonic-mcp-server","version":"1.0.0","keywords":["mcp","harmonic","enrichment","vc","model-context-protocol"],"author":{"name":"Alludium"},"license":"MIT","_id":"@alludium/harmonic-mcp-server@1.0.0","maintainers":[{"name":"donal_alludium","email":"donal@alludium.ai"},{"name":"markalludium","email":"mark@alludium.ai"}],"homepage":"https://github.com/alludium/harmonic-mcp-server#readme","bugs":{"url":"https://github.com/alludium/harmonic-mcp-server/issues"},"bin":{"harmonic-mcp":"dist/index.js"},"dist":{"shasum":"4803df345daa2840512b0060eb70e0b64eb867ea","tarball":"https://registry.npmjs.org/@alludium/harmonic-mcp-server/-/harmonic-mcp-server-1.0.0.tgz","fileCount":43,"integrity":"sha512-o/cN3qm2uyNKG+hC/zNQeSqBqF+5NWqas+r4zboq1POfutRxIhu+kSNP9t8TR8gW6SdsaePaXJIFLipTKOw0Bw==","signatures":[{"sig":"MEYCIQC5JObM/w9RO1XmrR+9UyMRXi1o3AIh7j4xiRZWB/Gx9AIhALFPZWywaq8FoEyN9yU2nuPi1ee5MBRFTeKQAjtJ111y","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":190744},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"92a3813cf31b7c0366f820c8bd51ec70a8356676","scripts":{"dev":"tsx src/index.ts","build":"tsc","start":"node dist/index.js","typecheck":"tsc --noEmit"},"_npmUser":{"name":"donal_alludium","email":"donal@alludium.ai"},"repository":{"url":"git+https://github.com/alludium/harmonic-mcp-server.git","type":"git"},"_npmVersion":"10.9.2","description":"MCP server for Harmonic AI API - company and person enrichment for VC deal flow","directories":{},"_nodeVersion":"22.17.1","dependencies":{"zod":"^4.1.13","dotenv":"^17.2.3","@modelcontextprotocol/sdk":"^1.24.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","typescript":"^5.7.2","@types/node":"^22.10.1"},"_npmOperationalInternal":{"tmp":"tmp/harmonic-mcp-server_1.0.0_1765203313186_0.8756228309441829","host":"s3://npm-registry-packages-npm-production"}}},"time":{"created":"2025-12-08T14:15:13.106Z","modified":"2025-12-15T11:58:32.753Z","1.0.0":"2025-12-08T14:15:13.356Z"},"bugs":{"url":"https://github.com/alludium/harmonic-mcp-server/issues"},"author":{"name":"Alludium"},"license":"MIT","homepage":"https://github.com/alludium/harmonic-mcp-server#readme","keywords":["mcp","harmonic","enrichment","vc","model-context-protocol"],"repository":{"url":"git+https://github.com/alludium/harmonic-mcp-server.git","type":"git"},"description":"MCP server for Harmonic AI API - company and person enrichment for VC deal flow","maintainers":[{"email":"donal@alludium.ai","name":"donal_alludium"},{"email":"mark@alludium.ai","name":"markalludium"},{"email":"john@alludium.ai","name":"john-alludium"},{"email":"juber@alludium.ai","name":"jubernunes"}],"readme":"# Harmonic MCP Server\n\nMCP (Model Context Protocol) server for the [Harmonic AI API](https://harmonic.ai) - company and person enrichment for VC deal flow.\n\n## Features\n\nThis MCP server provides 13 tools for interacting with Harmonic's API:\n\n### Search Tools\n- **harmonic_search_companies** - Natural language search for companies (e.g., \"AI startups in San Francisco\")\n- **harmonic_search_typeahead** - Quick autocomplete search by company name or domain\n- **harmonic_find_similar_companies** - Find companies similar to a given company\n\n### Company Tools\n- **harmonic_lookup_company** - Look up company by domain, LinkedIn URL, or other identifiers\n- **harmonic_get_company** - Get full company details by ID\n- **harmonic_get_company_employees** - Get employees with filtering (founders, executives, etc.)\n- **harmonic_get_company_connections** - Find team network connections to a company\n\n### Person Tools\n- **harmonic_lookup_person** - Look up person by LinkedIn URL\n- **harmonic_get_person** - Get full person details by ID\n\n### Saved Search Tools\n- **harmonic_list_saved_searches** - List all saved searches/views\n- **harmonic_get_saved_search_results** - Get results from a saved search\n- **harmonic_get_saved_search_net_new_results** - Get only new results since last check (for deal flow monitoring)\n- **harmonic_clear_saved_search_net_new** - Mark net new results as \"seen\"\n\n## Installation\n\nNo installation required when using `npx` (see Usage below).\n\n### Optional: Global Install\n\n```bash\nnpm install -g @alludium/harmonic-mcp-server\n```\n\n### Optional: From Source\n\n```bash\ngit clone https://github.com/alludium/harmonic-mcp-server.git\ncd harmonic-mcp-server\nnpm install\nnpm run build\n```\n\n## Configuration\n\nSet your Harmonic API key as an environment variable:\n\n```bash\nexport HARMONIC_API_KEY=your_api_key_here\n```\n\nWhen using with Claude Desktop or Claude Code, set the key in the MCP server configuration's `env` block (see Usage section below).\n\n## Usage\n\n### With Claude Desktop\n\nAdd to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"harmonic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alludium/harmonic-mcp-server\"],\n      \"env\": {\n        \"HARMONIC_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### With Claude Code\n\nAdd to your Claude Code MCP settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"harmonic\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@alludium/harmonic-mcp-server\"],\n      \"env\": {\n        \"HARMONIC_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n### Development Mode\n\n```bash\n# Run with tsx for development\nHARMONIC_API_KEY=your_key npm run dev\n```\n\n## API Coverage\n\nBased on the [Harmonic API documentation](https://api.harmonic.ai), this MCP covers:\n\n| Endpoint | Tool | Type |\n|----------|------|------|\n| GET /search/search_agent | harmonic_search_companies | Entry point |\n| GET /search/typeahead | harmonic_search_typeahead | Entry point |\n| GET /search/similar_companies/{id} | harmonic_find_similar_companies | Discovery |\n| POST /companies | harmonic_lookup_company | Entry point |\n| GET /companies/{id} | harmonic_get_company | Detail |\n| GET /companies/{id}/employees | harmonic_get_company_employees | Detail |\n| GET /companies/{id}/userConnections | harmonic_get_company_connections | Detail |\n| POST /persons | harmonic_lookup_person | Entry point |\n| GET /persons/{id} | harmonic_get_person | Detail |\n| GET /savedSearches | harmonic_list_saved_searches | Entry point |\n| GET /savedSearches:results/{id} | harmonic_get_saved_search_results | Detail |\n| GET /savedSearches:netNewResults/{id} | harmonic_get_saved_search_net_new_results | Monitoring |\n| POST /savedSearches:clearNetNew/{id} | harmonic_clear_saved_search_net_new | Monitoring |\n\n## Response Formats\n\nAll tools support two response formats:\n\n- **json** (default): Structured data for programmatic use\n- **markdown**: Human-readable formatted output\n\nUse the `response_format` parameter to switch between formats.\n\n## Rate Limiting\n\nThe Harmonic API has a rate limit of 10 requests per second. This MCP server implements automatic throttling and retry logic for rate-limited requests.\n\n## Error Handling\n\nThe server provides clear, actionable error messages:\n\n- **400**: Bad request with parameter guidance\n- **401**: Authentication failure with API key setup instructions\n- **404**: Resource not found with alternative lookup suggestions\n- **429**: Rate limit exceeded with retry guidance\n- **5xx**: Server errors with wait/retry suggestions\n\n## Example Workflows\n\n### Find and Research a Company\n\n```\n1. harmonic_lookup_company { website_domain: \"stripe.com\" }\n2. harmonic_get_company_employees { company_id: \"142540\", employee_group_type: \"FOUNDERS_AND_CEO\" }\n3. harmonic_get_person { person_id: \"person_id_from_step_2\" }\n```\n\n### Find Similar Companies\n\n```\n1. harmonic_search_companies { query: \"fintech payment processing\" }\n2. harmonic_find_similar_companies { company_id: \"id_from_step_1\", size: 10 }\n3. harmonic_get_company { company_id: \"each_similar_company_id\" }\n```\n\n### Monitor Deal Flow\n\n```\n1. harmonic_list_saved_searches {}\n2. harmonic_get_saved_search_results { search_id: \"search_id_from_step_1\", size: 50 }\n```\n\n## License\n\nMIT\n","readmeFilename":"README.md"}