{"_id":"@avantguardllc/mcp-halopsa","name":"@avantguardllc/mcp-halopsa","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@avantguardllc/mcp-halopsa","version":"1.0.0","description":"HaloPSA MCP server with decision tree architecture for Claude","type":"module","main":"dist/index.js","types":"dist/index.d.ts","bin":{"halopsa-mcp":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsc --watch","start":"node dist/index.js","lint":"eslint src --ext .ts","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","pack:mcpb":"node scripts/pack-mcpb.js","validate:mcpb":"mcpb validate manifest.json"},"repository":{"type":"git","url":"git+https://AvantGuardITContractors@dev.azure.com/AvantGuardITContractors/AvantGuard_MCP/_git/HaloPSA"},"keywords":["mcp","claude","halopsa","halo","psa","msp","itsm","decision-tree"],"author":{"name":"Wyre Technology"},"license":"Apache-2.0","bugs":{"url":"https://github.com/wyre-technology/halopsa-mcp/issues"},"homepage":"https://github.com/wyre-technology/halopsa-mcp#readme","dependencies":{"@modelcontextprotocol/sdk":"^1.12.0","@wyre-technology/node-halopsa":"npm:@avantguardllc/node-halopsa@^1.0.1"},"devDependencies":{"@types/node":"^20.11.0","eslint":"^8.56.0","@typescript-eslint/eslint-plugin":"^6.19.0","@typescript-eslint/parser":"^6.19.0","typescript":"^5.3.3","vitest":"^1.2.0","semantic-release":"^25.0.0","@semantic-release/changelog":"^6.0.3","@semantic-release/git":"^10.0.1","@semantic-release/github":"^11.0.0"},"engines":{"node":">=20.0.0"},"_id":"@avantguardllc/mcp-halopsa@1.0.0","gitHead":"2fba0e01fcf930aa285d48d92f2aa605c83a07f5","_nodeVersion":"20.20.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-wSRLh4lnT//ZA6CnXfxc1s4IeeqUzaDM9ZPGhkUgLR2KpJqK6/Ym7W8HvxPJreECq6HYOIyP3WSJ2JflocsORA==","shasum":"92b6f60e25631973664b879417574e8b7739da53","tarball":"https://registry.npmjs.org/@avantguardllc/mcp-halopsa/-/mcp-halopsa-1.0.0.tgz","fileCount":87,"unpackedSize":240775,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQC/+yIl/3DpHfCAMcb9Woxf23MDGlYalSgWYImakfUfbQIhAIGzHONOYg/VyiWpedmVBYyW0x+KFHV5mTSMeS0BzTNa"}]},"_npmUser":{"name":"avantguardllc","email":"appadmin@avantguard.it"},"directories":{},"maintainers":[{"name":"avantguardllc","email":"appadmin@avantguard.it"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-halopsa_1.0.0_1777948682889_0.2661194379441394"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-05T02:38:02.797Z","1.0.0":"2026-05-05T02:38:03.040Z","modified":"2026-05-05T02:38:03.221Z"},"maintainers":[{"name":"avantguardllc","email":"appadmin@avantguard.it"}],"description":"HaloPSA MCP server with decision tree architecture for Claude","homepage":"https://github.com/wyre-technology/halopsa-mcp#readme","keywords":["mcp","claude","halopsa","halo","psa","msp","itsm","decision-tree"],"repository":{"type":"git","url":"git+https://AvantGuardITContractors@dev.azure.com/AvantGuardITContractors/AvantGuard_MCP/_git/HaloPSA"},"author":{"name":"Wyre Technology"},"bugs":{"url":"https://github.com/wyre-technology/halopsa-mcp/issues"},"license":"Apache-2.0","readme":"# HaloPSA MCP Server\n\nA Model Context Protocol (MCP) server for interacting with HaloPSA, featuring a decision tree architecture for efficient tool loading.\n\n## One-Click Deployment\n\n[![Deploy to DO](https://www.deploytodo.com/do-btn-blue.svg)](https://cloud.digitalocean.com/apps/new?repo=https://github.com/wyre-technology/halopsa-mcp/tree/main)\n\n[![Deploy to Cloudflare Workers](https://deploy.workers.cloudflare.com/button)](https://deploy.workers.cloudflare.com/?url=https://github.com/wyre-technology/halopsa-mcp)\n\n## Architecture\n\nThis MCP server uses a **hierarchical tool loading approach** instead of exposing all tools upfront:\n\n1. **Navigation Phase**: Initially exposes only a navigation tool (`halopsa_navigate`)\n2. **Domain Selection**: User selects a domain (tickets, clients, assets, agents, invoices)\n3. **Domain Tools**: Server exposes domain-specific tools after selection\n4. **Lazy Loading**: Domain handlers and the HaloPSA client are loaded on-demand\n\nThis architecture provides:\n- Reduced cognitive load (fewer tools to choose from)\n- Faster initial load times\n- Better organization of related operations\n- Clear navigation state\n\n## Installation\n\n```bash\nnpm install @wyre-technology/halopsa-mcp\n```\n\n## Configuration\n\nSet the following environment variables:\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `HALOPSA_CLIENT_ID` | Yes | OAuth 2.0 Client ID |\n| `HALOPSA_CLIENT_SECRET` | Yes | OAuth 2.0 Client Secret |\n| `HALOPSA_TENANT` | One of | Tenant name (e.g., `yourcompany`) |\n| `HALOPSA_BASE_URL` | these | Explicit base URL (e.g., `https://yourcompany.halopsa.com`) |\n\n## Usage\n\n### Running Standalone\n\n```bash\n# Set credentials\nexport HALOPSA_CLIENT_ID=\"your-client-id\"\nexport HALOPSA_CLIENT_SECRET=\"your-client-secret\"\nexport HALOPSA_TENANT=\"yourcompany\"\n\n# Run the server\nnpx @wyre-technology/halopsa-mcp\n```\n\n### Claude Desktop Configuration\n\nAdd to your Claude Desktop `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"halopsa\": {\n      \"command\": \"npx\",\n      \"args\": [\"@wyre-technology/halopsa-mcp\"],\n      \"env\": {\n        \"HALOPSA_CLIENT_ID\": \"your-client-id\",\n        \"HALOPSA_CLIENT_SECRET\": \"your-client-secret\",\n        \"HALOPSA_TENANT\": \"yourcompany\"\n      }\n    }\n  }\n}\n```\n\n### Docker\n\n```bash\ndocker build -t halopsa-mcp .\ndocker run -e HALOPSA_CLIENT_ID=xxx -e HALOPSA_CLIENT_SECRET=xxx -e HALOPSA_TENANT=yourcompany halopsa-mcp\n```\n\n## Available Domains\n\n### Tickets\nManage support tickets, create new tickets, update status, add actions/notes.\n\nTools:\n- `halopsa_tickets_list` - List tickets with filters\n- `halopsa_tickets_get` - Get ticket details\n- `halopsa_tickets_create` - Create a new ticket\n- `halopsa_tickets_update` - Update an existing ticket\n- `halopsa_tickets_add_action` - Add a note/action to a ticket\n\n### Clients\nManage companies/clients in HaloPSA.\n\nTools:\n- `halopsa_clients_list` - List clients\n- `halopsa_clients_get` - Get client details\n- `halopsa_clients_create` - Create a new client\n- `halopsa_clients_search` - Search clients by name\n\n### Assets\nManage configuration items/assets.\n\nTools:\n- `halopsa_assets_list` - List assets with filters\n- `halopsa_assets_get` - Get asset details\n- `halopsa_assets_search` - Search assets\n- `halopsa_assets_list_types` - List available asset types\n\n### Agents\nView technicians and teams.\n\nTools:\n- `halopsa_agents_list` - List agents/technicians\n- `halopsa_agents_get` - Get agent details\n- `halopsa_teams_list` - List teams\n\n### Invoices\nView billing and invoices.\n\nTools:\n- `halopsa_invoices_list` - List invoices with filters\n- `halopsa_invoices_get` - Get invoice details\n\n## Navigation Tools\n\nAlways available:\n- `halopsa_navigate` - Select a domain to work with\n- `halopsa_status` - Show current state and credential status\n- `halopsa_back` - Return to main menu (when in a domain)\n\n## Example Workflow\n\n```\nUser: Check my tickets\nClaude: [calls halopsa_navigate with domain=\"tickets\"]\n       -> Navigated to tickets domain. Available tools: ...\n\nUser: List open tickets\nClaude: [calls halopsa_tickets_list with open_only=true]\n       -> [ticket list results]\n\nUser: Now show me clients\nClaude: [calls halopsa_back]\n       -> Navigated back to main menu.\n       [calls halopsa_navigate with domain=\"clients\"]\n       -> Navigated to clients domain.\n```\n\n## Rate Limiting\n\nHaloPSA has a rate limit of 500 requests per 3-minute window. The underlying `@asachs01/node-halopsa` client handles this automatically with request throttling.\n\n## License\n\nApache-2.0\n","readmeFilename":"README.md","_rev":"1-79a5bd1189311f7185c11950453d453e"}