{"_id":"@bullhornhub/mcp-server","_rev":"3-1b6f766f1bf531a9468c53624b8eb6fe","name":"@bullhornhub/mcp-server","dist-tags":{"latest":"0.1.2"},"versions":{"0.1.0":{"name":"@bullhornhub/mcp-server","version":"0.1.0","keywords":["mcp","model-context-protocol","bullhorn","bullhornhub","ats","crm","ai","assistant","claude","chatgpt"],"author":{"name":"BullhornHub"},"license":"MIT","_id":"@bullhornhub/mcp-server@0.1.0","maintainers":[{"name":"steveholloway","email":"steve@steveholloway.co.uk"}],"homepage":"https://github.com/your-org/bullhornhub-mcp#readme","bugs":{"url":"https://github.com/your-org/bullhornhub-mcp/issues"},"bin":{"bullhornhub-mcp":"dist/index.js"},"dist":{"shasum":"a2d1b533888c41973bbbfa04530094d875c20835","tarball":"https://registry.npmjs.org/@bullhornhub/mcp-server/-/mcp-server-0.1.0.tgz","fileCount":70,"integrity":"sha512-c4y0h1Pq99AHxf/092iF/0GC3wNGFqty/ZmXyhuk4KnMlKyCVxV8v9JlfgijLkAwHGR5NztyGXKBC1kKnyAfjw==","signatures":[{"sig":"MEUCIDquv1gW9IgWLjtxF7UYyzCxLCut9edXMm7/rRDz8CdZAiEAlW2wWRHBrneGT3/X21gAp/z2nP/1fJ2mFjVp0yfcSuk=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":119187},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"1b519d5f3a47be47a45eaa2510a9b7182fc2cd14","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint src tests --ext .ts","test":"vitest run","build":"tsc","start":"node dist/index.js","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","typecheck":"tsc --noEmit","docker:run":"docker run --rm -it -e BULLHORNHUB_API_KEY=$BULLHORNHUB_API_KEY bullhornhub-mcp:latest","test:watch":"vitest --watch","docker:build":"docker build -t bullhornhub-mcp:latest .","test:coverage":"vitest --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"steveholloway","email":"steve@steveholloway.co.uk"},"repository":{"url":"git+https://github.com/your-org/bullhornhub-mcp.git","type":"git"},"_npmVersion":"11.6.1","description":"MCP server providing AI assistants with standardized access to Bullhorn ATS/CRM REST API","directories":{},"_nodeVersion":"24.10.0","dependencies":{"zod":"^3.24.1","cors":"^2.8.5","axios":"^1.7.9","express":"^5.1.0","@types/cors":"^2.8.19","@types/express":"^5.0.5","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","eslint":"^9.17.0","vitest":"^2.1.8","prettier":"^3.4.2","typescript":"^5.7.2","@types/node":"^18.19.68","@typescript-eslint/parser":"^8.18.2","@typescript-eslint/eslint-plugin":"^8.18.2"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.1.0_1761850468687_0.7986228849119219","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@bullhornhub/mcp-server","version":"0.1.1","keywords":["mcp","model-context-protocol","bullhorn","bullhornhub","ats","crm","ai","assistant","claude","chatgpt"],"author":{"name":"BullhornHub"},"license":"MIT","_id":"@bullhornhub/mcp-server@0.1.1","maintainers":[{"name":"steveholloway","email":"steve@steveholloway.co.uk"}],"homepage":"https://github.com/your-org/bullhornhub-mcp#readme","bugs":{"url":"https://github.com/your-org/bullhornhub-mcp/issues"},"bin":{"bullhornhub-mcp":"dist/index.js"},"dist":{"shasum":"90a35f8e2958af1de6a9a224a03356de97c2ab85","tarball":"https://registry.npmjs.org/@bullhornhub/mcp-server/-/mcp-server-0.1.1.tgz","fileCount":70,"integrity":"sha512-VAij5r/rT68iA4YsixWFiYYtVpaTKe/d9U0rbAGd4vt0qim9SKkV6Y1jLAsEVzPctUNBL8a/T4HwV95ck9PEsw==","signatures":[{"sig":"MEUCIHkxdXLSWOEBrF16nVESQpZobeCQYknLQz7k5qi5Ti2CAiEArq4VTpj08sv4edLT+UTa3fZTpyvOSok45ibcnexkE48=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":119228},"main":"dist/index.js","type":"module","types":"dist/index.d.ts","engines":{"node":">=18.0.0"},"gitHead":"1b519d5f3a47be47a45eaa2510a9b7182fc2cd14","scripts":{"dev":"tsx watch src/index.ts","lint":"eslint src tests --ext .ts","test":"vitest run","build":"tsc","start":"node dist/index.js","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","typecheck":"tsc --noEmit","docker:run":"docker run --rm -it -e BULLHORNHUB_API_KEY=$BULLHORNHUB_API_KEY bullhornhub-mcp:latest","test:watch":"vitest --watch","docker:build":"docker build -t bullhornhub-mcp:latest .","test:coverage":"vitest --coverage","prepublishOnly":"npm run build && npm test"},"_npmUser":{"name":"steveholloway","email":"steve@steveholloway.co.uk"},"repository":{"url":"git+https://github.com/your-org/bullhornhub-mcp.git","type":"git"},"_npmVersion":"11.6.1","description":"MCP server providing AI assistants with standardized access to Bullhorn ATS/CRM REST API","directories":{},"_nodeVersion":"24.10.0","dependencies":{"zod":"^3.24.1","cors":"^2.8.5","axios":"^1.7.9","express":"^5.1.0","@types/cors":"^2.8.19","@types/express":"^5.0.5","@modelcontextprotocol/sdk":"^1.0.4"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.19.2","eslint":"^9.17.0","vitest":"^2.1.8","prettier":"^3.4.2","typescript":"^5.7.2","@types/node":"^18.19.68","@typescript-eslint/parser":"^8.18.2","@typescript-eslint/eslint-plugin":"^8.18.2"},"_npmOperationalInternal":{"tmp":"tmp/mcp-server_0.1.1_1761850647623_0.23350010567356927","host":"s3://npm-registry-packages-npm-production"}},"0.1.2":{"name":"@bullhornhub/mcp-server","version":"0.1.2","description":"MCP server providing AI assistants with standardized access to Bullhorn ATS/CRM REST API","type":"module","engines":{"node":">=18.0.0"},"main":"dist/index.js","types":"dist/index.d.ts","bin":{"bullhornhub-mcp":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx watch src/index.ts","start":"node dist/index.js","test":"vitest run","test:watch":"vitest --watch","test:coverage":"vitest --coverage","lint":"eslint src tests --ext .ts","format":"prettier --write \"src/**/*.ts\" \"tests/**/*.ts\"","typecheck":"tsc --noEmit","prepublishOnly":"npm run build && npm test","docker:build":"docker build -t bullhornhub-mcp:latest .","docker:run":"docker run --rm -it -e BULLHORNHUB_API_KEY=$BULLHORNHUB_API_KEY bullhornhub-mcp:latest"},"keywords":["mcp","model-context-protocol","bullhorn","bullhornhub","ats","crm","ai","assistant","claude","chatgpt"],"author":{"name":"BullhornHub"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/your-org/bullhornhub-mcp.git"},"bugs":{"url":"https://github.com/your-org/bullhornhub-mcp/issues"},"homepage":"https://github.com/your-org/bullhornhub-mcp#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.0.4","@types/cors":"^2.8.19","@types/express":"^5.0.5","axios":"^1.7.9","cors":"^2.8.5","express":"^5.1.0","zod":"^3.24.1"},"devDependencies":{"@types/node":"^18.19.68","@typescript-eslint/eslint-plugin":"^8.18.2","@typescript-eslint/parser":"^8.18.2","eslint":"^9.17.0","prettier":"^3.4.2","tsx":"^4.19.2","typescript":"^5.7.2","vitest":"^2.1.8"},"gitHead":"1b519d5f3a47be47a45eaa2510a9b7182fc2cd14","_id":"@bullhornhub/mcp-server@0.1.2","_nodeVersion":"24.10.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-lAaAGpAYcEEkOh1uc2l0LyThfuu6nnNBFb5iKAlVuDqT8nVPKKSKcM6soB49m34cHWGJ5+IuWpcx6xtqEM9Z5w==","shasum":"49ec98f43364f8bd584da54ce22ac6cb2cdae7d3","tarball":"https://registry.npmjs.org/@bullhornhub/mcp-server/-/mcp-server-0.1.2.tgz","fileCount":70,"unpackedSize":119229,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCkeDUgYjimnva35OVjUdqFcCbWSAZP6RyN716TBUQjrAIgJyzNY8Ff/4AagLtxfkgMcC+xQQNtaAiq2lhYM/CPeOA="}]},"_npmUser":{"name":"steveholloway","email":"steve@steveholloway.co.uk"},"directories":{},"maintainers":[{"name":"steveholloway","email":"steve@steveholloway.co.uk"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-server_0.1.2_1761852032662_0.19339855667637362"},"_hasShrinkwrap":false}},"time":{"created":"2025-10-30T18:54:28.571Z","modified":"2025-10-30T19:20:33.054Z","0.1.0":"2025-10-30T18:54:28.909Z","0.1.1":"2025-10-30T18:57:27.830Z","0.1.2":"2025-10-30T19:20:32.842Z"},"bugs":{"url":"https://github.com/your-org/bullhornhub-mcp/issues"},"author":{"name":"BullhornHub"},"license":"MIT","homepage":"https://github.com/your-org/bullhornhub-mcp#readme","keywords":["mcp","model-context-protocol","bullhorn","bullhornhub","ats","crm","ai","assistant","claude","chatgpt"],"repository":{"type":"git","url":"git+https://github.com/your-org/bullhornhub-mcp.git"},"description":"MCP server providing AI assistants with standardized access to Bullhorn ATS/CRM REST API","maintainers":[{"name":"steveholloway","email":"steve@steveholloway.co.uk"}],"readme":"# Bullhorn MCP Server\n\nA Model Context Protocol (MCP) server that provides AI assistants with standardized access to the Bullhorn ATS/CRM REST API through BullhornHub authentication.\n\n## Features\n\n- **🔐 Secure Authentication**: Integrates with BullhornHub's Supabase edge function for credential management\n- **🔍 Lucene Search**: Full-text search across Bullhorn entities with powerful query syntax\n- **📋 Metadata Discovery**: Retrieve comprehensive entity schemas, fields, and associations\n- **⚡ Session Caching**: In-memory caching with 48-hour TTL for optimal performance\n- **🛡️ Type-Safe**: Full TypeScript implementation with Zod validation\n\n## Available Tools\n\n### `bullhorn_authenticate`\nEstablishes an authenticated session with the Bullhorn API using your BullhornHub API key.\n\n**Parameters:**\n- `apiKey` (string, optional): Your BullhornHub API key (defaults to `BULLHORNHUB_API_KEY` environment variable)\n\n**Returns:**\n```json\n{\n  \"BhRestToken\": \"token_value\",\n  \"restUrl\": \"https://rest29.bullhornstaffing.com/rest-services/...\",\n  \"dataCenter\": \"29\",\n  \"expiresAt\": 1234567890,\n  \"environment\": \"production\",\n  \"cached\": false\n}\n```\n\n### `bullhorn_search`\nSearch for Bullhorn entities using Lucene query syntax with pagination and field selection.\n\n**Parameters:**\n- `entity` (string, required): Entity type (e.g., \"Candidate\", \"JobOrder\", \"ClientCorporation\")\n- `query` (string, required): Lucene search query\n- `fields` (string, optional): Comma-separated list of fields to return (default: \"id\")\n- `sort` (string, optional): Sort order (prefix with \"-\" for descending)\n- `start` (number, optional): Starting offset for pagination (default: 0)\n- `count` (number, optional): Number of results to return (max: 500, default: 20)\n- `apiKey` (string, optional): Your BullhornHub API key (defaults to `BULLHORNHUB_API_KEY` environment variable)\n\n**Query Examples:**\n```\n\"firstName:John AND lastName:Doe\"\n\"email:*@example.com\"\n\"status:Active OR status:Pending\"\n\"dateAdded:[20240101 TO 20241231]\"\n\"isDeleted:false\"\n```\n\n**Returns:**\n```json\n{\n  \"data\": [...],\n  \"total\": 100,\n  \"start\": 0,\n  \"count\": 20,\n  \"hasMore\": true\n}\n```\n\n### `bullhorn_get_entity_meta`\nRetrieve comprehensive metadata for a Bullhorn entity type.\n\n**Parameters:**\n- `entity` (string, required): Entity type\n- `fields` (array, optional): Specific field names to retrieve metadata for\n- `apiKey` (string, optional): Your BullhornHub API key (defaults to `BULLHORNHUB_API_KEY` environment variable)\n\n**Returns:**\n```json\n{\n  \"entity\": \"Candidate\",\n  \"fields\": [\n    {\n      \"name\": \"firstName\",\n      \"type\": \"String\",\n      \"dataType\": \"String\",\n      \"maxLength\": 100,\n      \"required\": false,\n      \"readOnly\": false,\n      \"label\": \"First Name\"\n    }\n  ],\n  \"associations\": [\n    {\n      \"name\": \"owner\",\n      \"type\": \"TO_ONE\",\n      \"associatedEntity\": \"CorporateUser\",\n      \"editable\": true\n    }\n  ],\n  \"cached\": false\n}\n```\n\n## Installation\n\n### Prerequisites\n- Node.js 18 or higher\n- npm or yarn\n- A BullhornHub API key\n\n### Quick Start (Recommended)\n\nInstall from npm:\n```bash\nnpm install -g @bullhornhub/mcp-server\n```\n\nThen add to your Claude Desktop configuration:\n\n**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"bullhornhub\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"@bullhornhub/mcp-server\"\n      ],\n      \"env\": {\n        \"BULLHORNHUB_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop and the Bullhorn tools will be available.\n\n### Install from Source\n\n1. **Clone and install dependencies:**\n```bash\ngit clone https://github.com/your-org/bullhornhub-mcp.git\ncd bullhornhub-mcp\nnpm install\n```\n\n2. **Build the server:**\n```bash\nnpm run build\n```\n\n3. **Configure Claude Desktop:**\n\nAdd the server to your Claude Desktop configuration file:\n\n**MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"bullhornhub\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/absolute/path/to/bullhornhub-mcp/dist/index.js\"\n      ],\n      \"env\": {\n        \"BULLHORNHUB_API_KEY\": \"your_api_key_here\"\n      }\n    }\n  }\n}\n```\n\n4. **Restart Claude Desktop**\n\nThe Bullhorn tools will now be available in Claude's tool palette.\n\n## Production Deployment\n\n### Railway (Recommended)\n\nDeploy to Railway for cloud-based AI agents and always-on availability:\n\n```bash\n# Install Railway CLI\nnpm install -g @railway/cli\n\n# Login and initialize\nrailway login\nrailway init\n\n# Set environment variables\nrailway variables set BULLHORNHUB_API_KEY=\"your_api_key_here\"\nrailway variables set NODE_ENV=\"production\"\n\n# Deploy\nrailway up\n```\n\n### Docker\n\nBuild and run with Docker:\n\n```bash\n# Build image\nnpm run docker:build\n\n# Run container\ndocker run --rm -it \\\n  -e BULLHORNHUB_API_KEY=your_api_key_here \\\n  bullhornhub-mcp:latest\n```\n\n### Deployment Modes\n\nThe server supports two transport modes:\n\n- **stdio** (default): For local development and Claude Desktop\n- **SSE** (planned): For HTTP-based streaming in production\n\nSee [DEPLOYMENT.md](DEPLOYMENT.md) for complete deployment instructions including:\n- Railway setup and configuration\n- Custom domain configuration\n- Environment variables\n- Monitoring and logs\n- Cost estimates\n- Troubleshooting\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `BULLHORNHUB_API_KEY` | Yes | Your BullhornHub API key |\n| `NODE_ENV` | No | Set to `production` for production deployments |\n| `TRANSPORT_MODE` | No | Transport mode: `stdio` (default) or `sse` (future) |\n\n## Development\n\n### Run Tests\n```bash\nnpm test\n```\n\n### Lint Code\n```bash\nnpm run lint\n```\n\n### Test with MCP Inspector\n```bash\nnpm run build\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## Architecture\n\n### Project Structure\n```\nsrc/\n├── index.ts                 # MCP server entry point\n├── tools/                   # Tool implementations\n│   ├── authenticate.ts\n│   ├── search.ts\n│   └── get-entity-meta.ts\n├── services/                # Core services\n│   ├── bullhorn-client.ts   # HTTP client with retry logic\n│   ├── session-cache.ts     # Session management\n│   └── metadata-cache.ts    # Metadata caching\n├── types/                   # TypeScript definitions\n│   ├── bullhorn.ts\n│   └── mcp.ts\n└── utils/                   # Utility functions\n    ├── error-formatter.ts\n    └── response-truncator.ts\n```\n\n### Key Design Decisions\n\n**Authentication**:\n- Uses Supabase edge function for credential lookup\n- Dual-header authentication: `apikey` (Supabase) + `X-API-Key` (BullhornHub)\n- Sessions cached for 48 hours with automatic expiration\n\n**Search**:\n- POST method with Lucene query in request body\n- Query parameters (fields, start, count, sort) in URL\n- Response returned directly (no data wrapper)\n\n**Metadata**:\n- GET method with parameters in query string\n- Session-linked caching for performance\n- Response returned directly from API\n\n## Common Entity Types\n\n- **Candidate**: Job seekers\n- **JobOrder**: Job openings\n- **ClientCorporation**: Client companies\n- **ClientContact**: Client contacts\n- **Placement**: Successful placements\n- **JobSubmission**: Candidate submissions to jobs\n- **Note**: Notes and comments\n- **Appointment**: Calendar appointments\n\n## Error Handling\n\nThe server provides detailed error messages with suggested actions:\n\n```json\n{\n  \"isError\": true,\n  \"content\": [{\n    \"type\": \"text\",\n    \"text\": \"Error: No authenticated session found\\n\\nPossible causes:\\n- No active authentication session\\n- Session expired (older than 48 hours)\\n- Invalid API key\\n\\nSuggested actions:\\n- Use bullhorn_authenticate tool to establish a new session\\n- Verify BULLHORNHUB_API_KEY is set correctly\"\n  }]\n}\n```\n\n## Performance\n\n- **Session Caching**: 90%+ cache hit rate expected\n- **Metadata Caching**: <100ms response time for cached entities\n- **Retry Logic**: Automatic retry on network errors and 5xx responses\n- **Timeout**: 30-second default timeout with exponential backoff\n\n## Security\n\n- API keys never logged or exposed in responses\n- Session tokens managed securely in memory\n- Supabase edge function handles credential storage\n- No persistent storage of sensitive data\n\n## License\n\nSee LICENSE file for details.\n\n## Support\n\nFor issues or questions:\n- GitHub Issues: [repository-url]/issues\n- Documentation: [BullhornHub docs]\n\n## Credits\n\nBuilt with:\n- [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)\n- [axios](https://axios-http.com/)\n- [zod](https://zod.dev/)\n","readmeFilename":"README.md"}