commit 57c191ee1fd6a767aad986156a323f519f0d9cab Author: Piers Macrae Cockram Date: Tue Apr 21 15:36:37 2026 +1000 feat: initial Halo PSA MCP server scaffold TypeScript MCP server exposing 18 tools for querying a Halo PSA instance via OAuth 2.0 Client Credentials: - Tickets / actions (list, get, time entries) - Clients / sites (list, get) - Contracts (list, get — recurring service agreements) - Invoices — both one-off (list, get) and recurring (list, get) - Projects (list, get) - Assets / configuration items (list, get) - Agents, reports (list) - revenue_breakdown — composite tool that cross-references contracts, recurring invoices, and one-off invoices to separate recurring (MRR) from non-recurring revenue per client Build artefacts verified: npm install clean (0 vulnerabilities, 107 pkgs), npm run build produces dist/*.js with no TS errors, server boots and announces 'Halo PSA MCP server running on stdio'. Shipping with Dockerfile (multi-stage, alpine), .env.example, README.md (user-facing), and CLAUDE.md (deployment briefing for downstream Claude Code setup on customer machines). Co-Authored-By: Claude Opus 4.7 (1M context) diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..efe14ef --- /dev/null +++ b/.env.example @@ -0,0 +1,11 @@ +# Halo PSA instance URL (e.g. https://yourcompany.halopsa.com) +HALO_INSTANCE_URL=https://yourcompany.halopsa.com + +# OAuth 2.0 Client Credentials — create these in Halo: +# Configuration > Integrations > Halo PSA API > Applications > New +# Auth method: "Client ID and Secret (Services)" +HALO_CLIENT_ID=your-client-id-guid +HALO_CLIENT_SECRET=your-client-secret + +# Optional: tenant name (required for multi-tenant Halo instances) +HALO_TENANT= diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..4274b51 --- /dev/null +++ b/.gitignore @@ -0,0 +1,5 @@ +node_modules/ +dist/ +.env +*.log +.DS_Store diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..04eeece --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,59 @@ +# Halo PSA MCP Server — Deployment Briefing + +You are setting up the Halo PSA MCP server on this machine. This MCP server connects you (Claude Code) to the customer's live Halo PSA instance so you can query their tickets, clients, contracts, invoices, projects, assets, and revenue data via natural language. + +## What this project is + +An MCP server built in TypeScript that authenticates against the Halo PSA REST API using OAuth 2.0 Client Credentials and exposes 18 tools for querying business data. The key differentiator is the `revenue_breakdown` tool which cross-references contracts, recurring invoices, and one-off invoices to distinguish recurring from non-recurring revenue per customer. + +## Autonomous Setup Instructions + +Follow these steps in order. Do NOT skip any step. + +### Step 1 — Clone and build + +cd ~ +git clone https://git.mineracks.com/mineracks/halo-psa-mcp.git +cd halo-psa-mcp +npm install +npm run build + +Verify the build succeeded (no TypeScript errors, dist/index.js exists). + +### Step 2 — Collect credentials + +Ask the user for these three values. Do NOT proceed without them: + +1. **HALO_INSTANCE_URL** — Their Halo PSA URL (e.g. https://companyname.halopsa.com) +2. **HALO_CLIENT_ID** — OAuth Client ID (GUID format) +3. **HALO_CLIENT_SECRET** — OAuth Client Secret + +Optional: +4. **HALO_TENANT** — Only needed for multi-tenant Halo instances + +If the user hasn't created API credentials yet, walk them through it: +- Log into Halo PSA as admin +- Configuration > Integrations > Halo PSA API > View Applications > New +- Auth method: Client ID and Secret (Services) +- Grant read permissions: read:tickets, read:customers, read:contracts, read:invoices, read:projects, read:assets, read:crm +- Save, copy the Client ID and Secret + +### Step 3 — Create the .env file + +Write a .env file in the project root with the credentials from Step 2. + +### Step 4 — Create a shell wrapper and register the MCP + +Create ~/halo-psa-mcp/start.sh that sources the .env and execs node dist/index.js. +chmod +x it, then run: claude mcp add halo-psa -- ~/halo-psa-mcp/start.sh + +### Step 5 — Verify + +Restart Claude Code, then test with list_clients (page_size: 5) and list_tickets (page_size: 5, open_only: true). + +## Key Concept: Recurring vs Non-Recurring + +- RECURRING = Contracts + Recurring Invoices (managed services, monthly/quarterly/annual billing) +- NON-RECURRING = Standard Invoices + Project charges (break-fix, ad-hoc, project work) + +The revenue_breakdown tool automates this analysis. diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..c4d7bea --- /dev/null +++ b/Dockerfile @@ -0,0 +1,20 @@ +FROM node:20-alpine AS builder +WORKDIR /app +COPY package.json package-lock.json* ./ +RUN npm ci +COPY tsconfig.json ./ +COPY src ./src +RUN npm run build + +FROM node:20-alpine +WORKDIR /app +COPY package.json package-lock.json* ./ +RUN npm ci --omit=dev +COPY --from=builder /app/dist ./dist + +ENV HALO_INSTANCE_URL="" +ENV HALO_CLIENT_ID="" +ENV HALO_CLIENT_SECRET="" +ENV HALO_TENANT="" + +ENTRYPOINT ["node", "dist/index.js"] diff --git a/README.md b/README.md new file mode 100644 index 0000000..f25c172 --- /dev/null +++ b/README.md @@ -0,0 +1,115 @@ +# Halo PSA MCP Server + +An MCP (Model Context Protocol) server that connects AI assistants to your Halo PSA instance, giving you natural-language access to tickets, clients, contracts, invoices, projects, assets, and revenue analytics. + +## Key Features + +- **Tickets & Actions** — Search, filter, and inspect tickets; view time entries and SLA status +- **Clients & Sites** — Browse customers, their sites, and contacts +- **Contracts** — View active contracts representing recurring managed services +- **Invoices (Recurring vs One-off)** — Separately query recurring invoices (MRR) and ad-hoc invoices +- **Revenue Breakdown** — Composite tool that categorises recurring vs non-recurring revenue per client +- **Projects** — View project status, budgets, and associated work +- **Assets** — Browse configuration items and their associations +- **Agents & Teams** — See who's working on what + +## Prerequisites + +- A Halo PSA instance with API access enabled +- An API application configured with **Client ID and Secret (Services)** auth method +- Docker (for container deployment) or Node.js 20+ (for local dev) + +## Setup: Creating API Credentials in Halo + +1. Log into your Halo PSA instance as an admin +2. Navigate to **Configuration > Integrations > Halo PSA API** +3. Click **View Applications** > **New** +4. Set the authentication method to **Client ID and Secret (Services)** +5. Under **Permissions**, grant read access to the scopes you need: + - `read:tickets` — Tickets and actions + - `read:customers` — Clients and sites + - `read:contracts` — Contracts + - `read:invoices` — Invoices (recurring and one-off) + - `read:projects` — Projects + - `read:assets` — Assets + - `read:crm` — CRM / reporting data +6. Save and note down the **Client ID** and **Client Secret** +7. Note your **instance URL** (e.g. `https://yourcompany.halopsa.com`) + +## Quick Start with Docker + +### Build the image + +docker build -t halo-psa-mcp . + +### Run interactively (for testing) + +docker run -it --rm \ + -e HALO_INSTANCE_URL=https://yourcompany.halopsa.com \ + -e HALO_CLIENT_ID=your-client-id \ + -e HALO_CLIENT_SECRET=your-client-secret \ + halo-psa-mcp + +## Connecting to Claude Desktop + +Add this to your claude_desktop_config.json: + +{ + "mcpServers": { + "halo-psa": { + "command": "docker", + "args": [ + "run", "-i", "--rm", + "-e", "HALO_INSTANCE_URL=https://yourcompany.halopsa.com", + "-e", "HALO_CLIENT_ID=your-client-id", + "-e", "HALO_CLIENT_SECRET=your-client-secret", + "halo-psa-mcp" + ] + } + } +} + +## Connecting to Claude Code + +claude mcp add halo-psa \ + -- docker run -i --rm \ + -e HALO_INSTANCE_URL=https://yourcompany.halopsa.com \ + -e HALO_CLIENT_ID=your-client-id \ + -e HALO_CLIENT_SECRET=your-client-secret \ + halo-psa-mcp + +## Available Tools + +| Tool | Description | +|------|-------------| +| `list_tickets` | Search/filter tickets by client, agent, status, type, team, priority | +| `get_ticket` | Full ticket details with actions/notes | +| `list_clients` | Browse customers with search | +| `get_client` | Client details with sites | +| `list_contracts` | Active contracts (recurring services) | +| `get_contract` | Contract details with billing lines | +| `list_invoices` | One-off/ad-hoc invoices (non-recurring charges) | +| `get_invoice` | Invoice line item details | +| `list_recurring_invoices` | Recurring invoices (MRR/recurring revenue) | +| `get_recurring_invoice` | Recurring invoice schedule and lines | +| `list_projects` | Projects with status/budget | +| `get_project` | Full project details | +| `list_actions` | Time entries, notes, billable work | +| `list_assets` | Configuration items / assets | +| `get_asset` | Asset details and associations | +| `revenue_breakdown` | **Recurring vs non-recurring revenue analysis** per client | +| `list_agents` | Technicians and team members | +| `list_reports` | Available Halo reports | + +## Recurring vs Non-Recurring Revenue + +The `revenue_breakdown` tool is specifically designed to answer the question: "What is recurring vs non-recurring for this customer?" + +It combines: +- **Recurring Invoices** — scheduled auto-billing (monthly/quarterly/annual managed services) +- **Contracts** — recurring service agreements with billing terms +- **Standard Invoices** — one-off project work, ad-hoc charges, break-fix billing + +## License + +MIT diff --git a/package-lock.json b/package-lock.json new file mode 100644 index 0000000..87fcdf3 --- /dev/null +++ b/package-lock.json @@ -0,0 +1,1330 @@ +{ + "name": "halo-psa-mcp", + "version": "1.0.0", + "lockfileVersion": 3, + "requires": true, + "packages": { + "": { + "name": "halo-psa-mcp", + "version": "1.0.0", + "dependencies": { + "@modelcontextprotocol/sdk": "^1.12.1", + "node-fetch": "^2.7.0" + }, + "devDependencies": { + "@types/node": "^20.11.0", + "@types/node-fetch": "^2.6.11", + "typescript": "^5.3.3" + } + }, + "node_modules/@hono/node-server": { + "version": "1.19.14", + "resolved": "https://registry.npmjs.org/@hono/node-server/-/node-server-1.19.14.tgz", + "integrity": "sha512-GwtvgtXxnWsucXvbQXkRgqksiH2Qed37H9xHZocE5sA3N8O8O8/8FA3uclQXxXVzc9XBZuEOMK7+r02FmSpHtw==", + "license": "MIT", + "engines": { + "node": ">=18.14.1" + }, + "peerDependencies": { + "hono": "^4" + } + }, + "node_modules/@modelcontextprotocol/sdk": { + "version": "1.29.0", + "resolved": "https://registry.npmjs.org/@modelcontextprotocol/sdk/-/sdk-1.29.0.tgz", + "integrity": "sha512-zo37mZA9hJWpULgkRpowewez1y6ML5GsXJPY8FI0tBBCd77HEvza4jDqRKOXgHNn867PVGCyTdzqpz0izu5ZjQ==", + "license": "MIT", + "dependencies": { + "@hono/node-server": "^1.19.9", + "ajv": "^8.17.1", + "ajv-formats": "^3.0.1", + "content-type": "^1.0.5", + "cors": "^2.8.5", + "cross-spawn": "^7.0.5", + "eventsource": "^3.0.2", + "eventsource-parser": "^3.0.0", + "express": "^5.2.1", + "express-rate-limit": "^8.2.1", + "hono": "^4.11.4", + "jose": "^6.1.3", + "json-schema-typed": "^8.0.2", + "pkce-challenge": "^5.0.0", + "raw-body": "^3.0.0", + "zod": "^3.25 || ^4.0", + "zod-to-json-schema": "^3.25.1" + }, + "engines": { + "node": ">=18" + }, + "peerDependencies": { + "@cfworker/json-schema": "^4.1.1", + "zod": "^3.25 || ^4.0" + }, + "peerDependenciesMeta": { + "@cfworker/json-schema": { + "optional": true + }, + "zod": { + "optional": false + } + } + }, + "node_modules/@types/node": { + "version": "20.19.39", + "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.39.tgz", + "integrity": "sha512-orrrD74MBUyK8jOAD/r0+lfa1I2MO6I+vAkmAWzMYbCcgrN4lCrmK52gRFQq/JRxfYPfonkr4b0jcY7Olqdqbw==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, + "node_modules/@types/node-fetch": { + "version": "2.6.13", + "resolved": "https://registry.npmjs.org/@types/node-fetch/-/node-fetch-2.6.13.tgz", + "integrity": "sha512-QGpRVpzSaUs30JBSGPjOg4Uveu384erbHBoT1zeONvyCfwQxIkUshLAOqN/k9EjGviPRmWTTe6aH2qySWKTVSw==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/node": "*", + "form-data": "^4.0.4" + } + }, + "node_modules/accepts": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/accepts/-/accepts-2.0.0.tgz", + "integrity": "sha512-5cvg6CtKwfgdmVqY1WIiXKc3Q1bkRqGLi+2W/6ao+6Y7gu/RCwRuAhGEzh5B4KlszSuTLgZYuqFqo5bImjNKng==", + "license": "MIT", + "dependencies": { + "mime-types": "^3.0.0", + "negotiator": "^1.0.0" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/ajv": { + "version": "8.18.0", + "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz", + "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==", + "license": "MIT", + "dependencies": { + "fast-deep-equal": "^3.1.3", + "fast-uri": "^3.0.1", + "json-schema-traverse": "^1.0.0", + "require-from-string": "^2.0.2" + }, + "funding": { + "type": "github", + "url": "https://github.com/sponsors/epoberezkin" + } + }, + "node_modules/ajv-formats": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/ajv-formats/-/ajv-formats-3.0.1.tgz", + "integrity": "sha512-8iUql50EUR+uUcdRQ3HDqa6EVyo3docL8g5WJ3FNcWmu62IbkGUue/pEyLBW8VGKKucTPgqeks4fIU1DA4yowQ==", + "license": "MIT", + "dependencies": { + "ajv": "^8.0.0" + }, + "peerDependencies": { + "ajv": "^8.0.0" + }, + "peerDependenciesMeta": { + "ajv": { + "optional": true + } + } + }, + "node_modules/asynckit": { + "version": "0.4.0", + "resolved": "https://registry.npmjs.org/asynckit/-/asynckit-0.4.0.tgz", + "integrity": "sha512-Oei9OH4tRh0YqU3GxhX79dM/mwVgvbZJaSNaRk+bshkj0S5cfHcgYakreBjrHwatXKbz+IoIdYLxrKim2MjW0Q==", + "dev": true, + "license": "MIT" + }, + "node_modules/body-parser": { + "version": "2.2.2", + "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-2.2.2.tgz", + "integrity": "sha512-oP5VkATKlNwcgvxi0vM0p/D3n2C3EReYVX+DNYs5TjZFn/oQt2j+4sVJtSMr18pdRr8wjTcBl6LoV+FUwzPmNA==", + "license": "MIT", + "dependencies": { + "bytes": "^3.1.2", + "content-type": "^1.0.5", + "debug": "^4.4.3", + "http-errors": "^2.0.0", + "iconv-lite": "^0.7.0", + "on-finished": "^2.4.1", + "qs": "^6.14.1", + "raw-body": "^3.0.1", + "type-is": "^2.0.1" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/bytes": { + "version": "3.1.2", + "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz", + "integrity": "sha512-/Nf7TyzTx6S3yRJObOAV7956r8cr2+Oj8AC5dt8wSP3BQAoeX58NoHyCU8P8zGkNXStjTSi6fzO6F0pBdcYbEg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/call-bind-apply-helpers": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/call-bind-apply-helpers/-/call-bind-apply-helpers-1.0.2.tgz", + "integrity": "sha512-Sp1ablJ0ivDkSzjcaJdxEunN5/XvksFJ2sMBFfq6x0ryhQV/2b/KwFe21cMpmHtPOSij8K99/wSfoEuTObmuMQ==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/call-bound": { + "version": "1.0.4", + "resolved": "https://registry.npmjs.org/call-bound/-/call-bound-1.0.4.tgz", + "integrity": "sha512-+ys997U96po4Kx/ABpBCqhA9EuxJaQWDQg7295H4hBphv3IZg0boBKuwYpt4YXp6MZ5AmZQnU/tyMTlRpaSejg==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "get-intrinsic": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/combined-stream": { + "version": "1.0.8", + "resolved": "https://registry.npmjs.org/combined-stream/-/combined-stream-1.0.8.tgz", + "integrity": "sha512-FQN4MRfuJeHf7cBbBMJFXhKSDq+2kAArBlmRBvcvFE5BB1HZKXtSFASDhdlz9zOYwxh8lDdnvmMOe/+5cdoEdg==", + "dev": true, + "license": "MIT", + "dependencies": { + "delayed-stream": "~1.0.0" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/content-disposition": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/content-disposition/-/content-disposition-1.1.0.tgz", + "integrity": "sha512-5jRCH9Z/+DRP7rkvY83B+yGIGX96OYdJmzngqnw2SBSxqCFPd0w2km3s5iawpGX8krnwSGmF0FW5Nhr0Hfai3g==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/content-type": { + "version": "1.0.5", + "resolved": "https://registry.npmjs.org/content-type/-/content-type-1.0.5.tgz", + "integrity": "sha512-nTjqfcBFEipKdXCv4YDQWCfmcLZKm81ldF0pAopTvyrFGVbcR6P/VAAd5G7N+0tTr8QqiU0tFadD6FK4NtJwOA==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie": { + "version": "0.7.2", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-0.7.2.tgz", + "integrity": "sha512-yki5XnKuf750l50uGTllt6kKILY4nQ1eNIQatoXEByZ5dWgnKqbnqmTrBE5B4N7lrMJKQ2ytWMiTO2o0v6Ew/w==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/cookie-signature": { + "version": "1.2.2", + "resolved": "https://registry.npmjs.org/cookie-signature/-/cookie-signature-1.2.2.tgz", + "integrity": "sha512-D76uU73ulSXrD1UXF4KE2TMxVVwhsnCgfAyTg9k8P6KGZjlXKrOLe4dJQKI3Bxi5wjesZoFXJWElNWBjPZMbhg==", + "license": "MIT", + "engines": { + "node": ">=6.6.0" + } + }, + "node_modules/cors": { + "version": "2.8.6", + "resolved": "https://registry.npmjs.org/cors/-/cors-2.8.6.tgz", + "integrity": "sha512-tJtZBBHA6vjIAaF6EnIaq6laBBP9aq/Y3ouVJjEfoHbRBcHBAHYcMh/w8LDrk2PvIMMq8gmopa5D4V8RmbrxGw==", + "license": "MIT", + "dependencies": { + "object-assign": "^4", + "vary": "^1" + }, + "engines": { + "node": ">= 0.10" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/cross-spawn": { + "version": "7.0.6", + "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", + "integrity": "sha512-uV2QOWP2nWzsy2aMp8aRibhi9dlzF5Hgh5SHaB9OiTGEyDTiJJyx0uy51QXdyWbtAHNua4XJzUKca3OzKUd3vA==", + "license": "MIT", + "dependencies": { + "path-key": "^3.1.0", + "shebang-command": "^2.0.0", + "which": "^2.0.1" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/debug": { + "version": "4.4.3", + "resolved": "https://registry.npmjs.org/debug/-/debug-4.4.3.tgz", + "integrity": "sha512-RGwwWnwQvkVfavKVt22FGLw+xYSdzARwm0ru6DhTVA3umU5hZc28V3kO4stgYryrTlLpuvgI9GiijltAjNbcqA==", + "license": "MIT", + "dependencies": { + "ms": "^2.1.3" + }, + "engines": { + "node": ">=6.0" + }, + "peerDependenciesMeta": { + "supports-color": { + "optional": true + } + } + }, + "node_modules/delayed-stream": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/delayed-stream/-/delayed-stream-1.0.0.tgz", + "integrity": "sha512-ZySD7Nf91aLB0RxL4KGrKHBXl7Eds1DAmEdcoVawXnLD7SDhpNgtuII2aAkg7a7QS41jxPSZ17p4VdGnMHk3MQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=0.4.0" + } + }, + "node_modules/depd": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/depd/-/depd-2.0.0.tgz", + "integrity": "sha512-g7nH6P6dyDioJogAAGprGpCtVImJhpPk/roCzdb3fIh61/s/nPsfR6onyMwkCAR/OlC3yBC0lESvUoQEAssIrw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/dunder-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/dunder-proto/-/dunder-proto-1.0.1.tgz", + "integrity": "sha512-KIN/nDJBQRcXw0MLVhZE9iQHmG68qAVIBg9CqmUYjmQIhgij9U5MFvrqkUL5FbtyyzZuOeOt0zdeRe4UY7ct+A==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.1", + "es-errors": "^1.3.0", + "gopd": "^1.2.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/ee-first": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/ee-first/-/ee-first-1.1.1.tgz", + "integrity": "sha512-WMwm9LhRUo+WUaRN+vRuETqG89IgZphVSNkdFgeb6sS/E4OrDIN7t48CAewSHXc6C8lefD8KKfr5vY61brQlow==", + "license": "MIT" + }, + "node_modules/encodeurl": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/encodeurl/-/encodeurl-2.0.0.tgz", + "integrity": "sha512-Q0n9HRi4m6JuGIV1eFlmvJB7ZEVxu93IrMyiMsGC0lrMJMWzRgx6WGquyfQgZVb31vhGgXnfmPNNXmxnOkRBrg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/es-define-property": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/es-define-property/-/es-define-property-1.0.1.tgz", + "integrity": "sha512-e3nRfgfUZ4rNGL232gUgX06QNyyez04KdjFrF+LTRoOXmrOgFKDg4BCdsjW8EnT69eqdYGmRpJwiPVYNrCaW3g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-errors": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/es-errors/-/es-errors-1.3.0.tgz", + "integrity": "sha512-Zf5H2Kxt2xjTvbJvP2ZWLEICxA6j+hAmMzIlypy4xcBg1vKVnx89Wy0GbS+kf5cwCVFFzdCFh2XSCFNULS6csw==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-object-atoms": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/es-object-atoms/-/es-object-atoms-1.1.1.tgz", + "integrity": "sha512-FGgH2h8zKNim9ljj7dankFPcICIK9Cp5bm+c2gQSYePhpaG5+esrLODihIorn+Pe6FGJzWhXQotPv73jTaldXA==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/es-set-tostringtag": { + "version": "2.1.0", + "resolved": "https://registry.npmjs.org/es-set-tostringtag/-/es-set-tostringtag-2.1.0.tgz", + "integrity": "sha512-j6vWzfrGVfyXxge+O0x5sh6cvxAog0a/4Rdd2K36zCMV5eJ+/+tOAngRO8cODMNWbVRdVlmGZQL2YS3yR8bIUA==", + "dev": true, + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.6", + "has-tostringtag": "^1.0.2", + "hasown": "^2.0.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/escape-html": { + "version": "1.0.3", + "resolved": "https://registry.npmjs.org/escape-html/-/escape-html-1.0.3.tgz", + "integrity": "sha512-NiSupZ4OeuGwr68lGIeym/ksIZMJodUGOSCZ/FSnTxcrekbvqrgdUxlJOMpijaKZVjAJrWrGs/6Jy8OMuyj9ow==", + "license": "MIT" + }, + "node_modules/etag": { + "version": "1.8.1", + "resolved": "https://registry.npmjs.org/etag/-/etag-1.8.1.tgz", + "integrity": "sha512-aIL5Fx7mawVa300al2BnEE4iNvo1qETxLrPI/o05L7z6go7fCw1J6EQmbK4FmJ2AS7kgVF/KEZWufBfdClMcPg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/eventsource": { + "version": "3.0.7", + "resolved": "https://registry.npmjs.org/eventsource/-/eventsource-3.0.7.tgz", + "integrity": "sha512-CRT1WTyuQoD771GW56XEZFQ/ZoSfWid1alKGDYMmkt2yl8UXrVR4pspqWNEcqKvVIzg6PAltWjxcSSPrboA4iA==", + "license": "MIT", + "dependencies": { + "eventsource-parser": "^3.0.1" + }, + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/eventsource-parser": { + "version": "3.0.8", + "resolved": "https://registry.npmjs.org/eventsource-parser/-/eventsource-parser-3.0.8.tgz", + "integrity": "sha512-70QWGkr4snxr0OXLRWsFLeRBIRPuQOvt4s8QYjmUlmlkyTZkRqS7EDVRZtzU3TiyDbXSzaOeF0XUKy8PchzukQ==", + "license": "MIT", + "engines": { + "node": ">=18.0.0" + } + }, + "node_modules/express": { + "version": "5.2.1", + "resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz", + "integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==", + "license": "MIT", + "dependencies": { + "accepts": "^2.0.0", + "body-parser": "^2.2.1", + "content-disposition": "^1.0.0", + "content-type": "^1.0.5", + "cookie": "^0.7.1", + "cookie-signature": "^1.2.1", + "debug": "^4.4.0", + "depd": "^2.0.0", + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "etag": "^1.8.1", + "finalhandler": "^2.1.0", + "fresh": "^2.0.0", + "http-errors": "^2.0.0", + "merge-descriptors": "^2.0.0", + "mime-types": "^3.0.0", + "on-finished": "^2.4.1", + "once": "^1.4.0", + "parseurl": "^1.3.3", + "proxy-addr": "^2.0.7", + "qs": "^6.14.0", + "range-parser": "^1.2.1", + "router": "^2.2.0", + "send": "^1.1.0", + "serve-static": "^2.2.0", + "statuses": "^2.0.1", + "type-is": "^2.0.1", + "vary": "^1.1.2" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/express-rate-limit": { + "version": "8.3.2", + "resolved": "https://registry.npmjs.org/express-rate-limit/-/express-rate-limit-8.3.2.tgz", + "integrity": "sha512-77VmFeJkO0/rvimEDuUC5H30oqUC4EyOhyGccfqoLebB0oiEYfM7nwPrsDsBL1gsTpwfzX8SFy2MT3TDyRq+bg==", + "license": "MIT", + "dependencies": { + "ip-address": "10.1.0" + }, + "engines": { + "node": ">= 16" + }, + "funding": { + "url": "https://github.com/sponsors/express-rate-limit" + }, + "peerDependencies": { + "express": ">= 4.11" + } + }, + "node_modules/fast-deep-equal": { + "version": "3.1.3", + "resolved": "https://registry.npmjs.org/fast-deep-equal/-/fast-deep-equal-3.1.3.tgz", + "integrity": "sha512-f3qQ9oQy9j2AhBe/H9VC91wLmKBCCU/gDOnKNAYG5hswO7BLKj09Hc5HYNz9cGI++xlpDCIgDaitVs03ATR84Q==", + "license": "MIT" + }, + "node_modules/fast-uri": { + "version": "3.1.0", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz", + "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==", + "funding": [ + { + "type": "github", + "url": "https://github.com/sponsors/fastify" + }, + { + "type": "opencollective", + "url": "https://opencollective.com/fastify" + } + ], + "license": "BSD-3-Clause" + }, + "node_modules/finalhandler": { + "version": "2.1.1", + "resolved": "https://registry.npmjs.org/finalhandler/-/finalhandler-2.1.1.tgz", + "integrity": "sha512-S8KoZgRZN+a5rNwqTxlZZePjT/4cnm0ROV70LedRHZ0p8u9fRID0hJUZQpkKLzro8LfmC8sx23bY6tVNxv8pQA==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.0", + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "on-finished": "^2.4.1", + "parseurl": "^1.3.3", + "statuses": "^2.0.1" + }, + "engines": { + "node": ">= 18.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/form-data": { + "version": "4.0.5", + "resolved": "https://registry.npmjs.org/form-data/-/form-data-4.0.5.tgz", + "integrity": "sha512-8RipRLol37bNs2bhoV67fiTEvdTrbMUYcFTiy3+wuuOnUog2QBHCZWXDRijWQfAkhBj2Uf5UnVaiWwA5vdd82w==", + "dev": true, + "license": "MIT", + "dependencies": { + "asynckit": "^0.4.0", + "combined-stream": "^1.0.8", + "es-set-tostringtag": "^2.1.0", + "hasown": "^2.0.2", + "mime-types": "^2.1.12" + }, + "engines": { + "node": ">= 6" + } + }, + "node_modules/form-data/node_modules/mime-db": { + "version": "1.52.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.52.0.tgz", + "integrity": "sha512-sPU4uV7dYlvtWJxwwxHD0PuihVNiE7TyAbQ5SWxDCB9mUYvOgroQOwYQQOKPJ8CIbE+1ETVlOoK1UC2nU3gYvg==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/form-data/node_modules/mime-types": { + "version": "2.1.35", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-2.1.35.tgz", + "integrity": "sha512-ZDY+bPm5zTTF+YpCrAU9nK0UgICYPT0QtT1NZWFv4s++TNkcgVaT0g6+4R2uI4MjQjzysHB1zxuWL50hzaeXiw==", + "dev": true, + "license": "MIT", + "dependencies": { + "mime-db": "1.52.0" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/forwarded": { + "version": "0.2.0", + "resolved": "https://registry.npmjs.org/forwarded/-/forwarded-0.2.0.tgz", + "integrity": "sha512-buRG0fpBtRHSTCOASe6hD258tEubFoRLb4ZNA6NxMVHNw2gOcwHo9wyablzMzOA5z9xA9L1KNjk/Nt6MT9aYow==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/fresh": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/fresh/-/fresh-2.0.0.tgz", + "integrity": "sha512-Rx/WycZ60HOaqLKAi6cHRKKI7zxWbJ31MhntmtwMoaTeF7XFH9hhBp8vITaMidfljRQ6eYWCKkaTK+ykVJHP2A==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/function-bind": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/function-bind/-/function-bind-1.1.2.tgz", + "integrity": "sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-intrinsic": { + "version": "1.3.0", + "resolved": "https://registry.npmjs.org/get-intrinsic/-/get-intrinsic-1.3.0.tgz", + "integrity": "sha512-9fSjSaos/fRIVIp+xSJlE6lfwhES7LNtKaCBIamHsjr2na1BiABJPo0mOjjz8GJDURarmCPGqaiVg5mfjb98CQ==", + "license": "MIT", + "dependencies": { + "call-bind-apply-helpers": "^1.0.2", + "es-define-property": "^1.0.1", + "es-errors": "^1.3.0", + "es-object-atoms": "^1.1.1", + "function-bind": "^1.1.2", + "get-proto": "^1.0.1", + "gopd": "^1.2.0", + "has-symbols": "^1.1.0", + "hasown": "^2.0.2", + "math-intrinsics": "^1.1.0" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/get-proto": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/get-proto/-/get-proto-1.0.1.tgz", + "integrity": "sha512-sTSfBjoXBp89JvIKIefqw7U2CCebsc74kiY6awiGogKtoSGbgjYE/G/+l9sF3MWFPNc9IcoOC4ODfKHfxFmp0g==", + "license": "MIT", + "dependencies": { + "dunder-proto": "^1.0.1", + "es-object-atoms": "^1.0.0" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/gopd": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/gopd/-/gopd-1.2.0.tgz", + "integrity": "sha512-ZUKRh6/kUFoAiTAtTYPZJ3hw9wNxx+BIBOijnlG9PnrJsCcSjs1wyyD6vJpaYtgnzDrKYRSqf3OO6Rfa93xsRg==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-symbols": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/has-symbols/-/has-symbols-1.1.0.tgz", + "integrity": "sha512-1cDNdwJ2Jaohmb3sg4OmKaMBwuC48sYni5HUw2DvsC8LjGTLK9h+eb1X6RyuOHe4hT0ULCW68iomhjUoKUqlPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/has-tostringtag": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/has-tostringtag/-/has-tostringtag-1.0.2.tgz", + "integrity": "sha512-NqADB8VjPFLM2V0VvHUewwwsw0ZWBaIdgo+ieHtK3hasLz4qeCRjYcqfB6AQrBggRKppKF8L52/VqdVsO47Dlw==", + "dev": true, + "license": "MIT", + "dependencies": { + "has-symbols": "^1.0.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/hasown": { + "version": "2.0.3", + "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.3.tgz", + "integrity": "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==", + "license": "MIT", + "dependencies": { + "function-bind": "^1.1.2" + }, + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/hono": { + "version": "4.12.14", + "resolved": "https://registry.npmjs.org/hono/-/hono-4.12.14.tgz", + "integrity": "sha512-am5zfg3yu6sqn5yjKBNqhnTX7Cv+m00ox+7jbaKkrLMRJ4rAdldd1xPd/JzbBWspqaQv6RSTrgFN95EsfhC+7w==", + "license": "MIT", + "engines": { + "node": ">=16.9.0" + } + }, + "node_modules/http-errors": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/http-errors/-/http-errors-2.0.1.tgz", + "integrity": "sha512-4FbRdAX+bSdmo4AUFuS0WNiPz8NgFt+r8ThgNWmlrjQjt1Q7ZR9+zTlce2859x4KSXrwIsaeTqDoKQmtP8pLmQ==", + "license": "MIT", + "dependencies": { + "depd": "~2.0.0", + "inherits": "~2.0.4", + "setprototypeof": "~1.2.0", + "statuses": "~2.0.2", + "toidentifier": "~1.0.1" + }, + "engines": { + "node": ">= 0.8" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/iconv-lite": { + "version": "0.7.2", + "resolved": "https://registry.npmjs.org/iconv-lite/-/iconv-lite-0.7.2.tgz", + "integrity": "sha512-im9DjEDQ55s9fL4EYzOAv0yMqmMBSZp6G0VvFyTMPKWxiSBHUj9NW/qqLmXUwXrrM7AvqSlTCfvqRb0cM8yYqw==", + "license": "MIT", + "dependencies": { + "safer-buffer": ">= 2.1.2 < 3.0.0" + }, + "engines": { + "node": ">=0.10.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/inherits": { + "version": "2.0.4", + "resolved": "https://registry.npmjs.org/inherits/-/inherits-2.0.4.tgz", + "integrity": "sha512-k/vGaX4/Yla3WzyMCvTQOXYeIHvqOKtnqBduzTHpzpQZzAskKMhZ2K+EnBiSM9zGSoIFeMpXKxa4dYeZIQqewQ==", + "license": "ISC" + }, + "node_modules/ip-address": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/ip-address/-/ip-address-10.1.0.tgz", + "integrity": "sha512-XXADHxXmvT9+CRxhXg56LJovE+bmWnEWB78LB83VZTprKTmaC5QfruXocxzTZ2Kl0DNwKuBdlIhjL8LeY8Sf8Q==", + "license": "MIT", + "engines": { + "node": ">= 12" + } + }, + "node_modules/ipaddr.js": { + "version": "1.9.1", + "resolved": "https://registry.npmjs.org/ipaddr.js/-/ipaddr.js-1.9.1.tgz", + "integrity": "sha512-0KI/607xoxSToH7GjN1FfSbLoU0+btTicjsQSWQlh/hZykN8KpmMf7uYwPW3R+akZ6R/w18ZlXSHBYXiYUPO3g==", + "license": "MIT", + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/is-promise": { + "version": "4.0.0", + "resolved": "https://registry.npmjs.org/is-promise/-/is-promise-4.0.0.tgz", + "integrity": "sha512-hvpoI6korhJMnej285dSg6nu1+e6uxs7zG3BYAm5byqDsgJNWwxzM6z6iZiAgQR4TJ30JmBTOwqZUw3WlyH3AQ==", + "license": "MIT" + }, + "node_modules/isexe": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/isexe/-/isexe-2.0.0.tgz", + "integrity": "sha512-RHxMLp9lnKHGHRng9QFhRCMbYAcVpn69smSGcq3f36xjgVVWThj4qqLbTLlq7Ssj8B+fIQ1EuCEGI2lKsyQeIw==", + "license": "ISC" + }, + "node_modules/jose": { + "version": "6.2.2", + "resolved": "https://registry.npmjs.org/jose/-/jose-6.2.2.tgz", + "integrity": "sha512-d7kPDd34KO/YnzaDOlikGpOurfF0ByC2sEV4cANCtdqLlTfBlw2p14O/5d/zv40gJPbIQxfES3nSx1/oYNyuZQ==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/panva" + } + }, + "node_modules/json-schema-traverse": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz", + "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==", + "license": "MIT" + }, + "node_modules/json-schema-typed": { + "version": "8.0.2", + "resolved": "https://registry.npmjs.org/json-schema-typed/-/json-schema-typed-8.0.2.tgz", + "integrity": "sha512-fQhoXdcvc3V28x7C7BMs4P5+kNlgUURe2jmUT1T//oBRMDrqy1QPelJimwZGo7Hg9VPV3EQV5Bnq4hbFy2vetA==", + "license": "BSD-2-Clause" + }, + "node_modules/math-intrinsics": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/math-intrinsics/-/math-intrinsics-1.1.0.tgz", + "integrity": "sha512-/IXtbwEk5HTPyEwyKX6hGkYXxM9nbj64B+ilVJnC/R6B0pH5G4V3b0pVbL7DBj4tkhBAppbQUlf6F6Xl9LHu1g==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + } + }, + "node_modules/media-typer": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/media-typer/-/media-typer-1.1.0.tgz", + "integrity": "sha512-aisnrDP4GNe06UcKFnV5bfMNPBUw4jsLGaWwWfnH3v02GnBuXX2MCVn5RbrWo0j3pczUilYblq7fQ7Nw2t5XKw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/merge-descriptors": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/merge-descriptors/-/merge-descriptors-2.0.0.tgz", + "integrity": "sha512-Snk314V5ayFLhp3fkUREub6WtjBfPdCPY1Ln8/8munuLuiYhsABgBVWsozAG+MWMbVEvcdcpbi9R7ww22l9Q3g==", + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "url": "https://github.com/sponsors/sindresorhus" + } + }, + "node_modules/mime-db": { + "version": "1.54.0", + "resolved": "https://registry.npmjs.org/mime-db/-/mime-db-1.54.0.tgz", + "integrity": "sha512-aU5EJuIN2WDemCcAp2vFBfp/m4EAhWJnUNSSw0ixs7/kXbd6Pg64EmwJkNdFhB8aWt1sH2CTXrLxo/iAGV3oPQ==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/mime-types": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/mime-types/-/mime-types-3.0.2.tgz", + "integrity": "sha512-Lbgzdk0h4juoQ9fCKXW4by0UJqj+nOOrI9MJ1sSj4nI8aI2eo1qmvQEie4VD1glsS250n15LsWsYtCugiStS5A==", + "license": "MIT", + "dependencies": { + "mime-db": "^1.54.0" + }, + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/ms": { + "version": "2.1.3", + "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz", + "integrity": "sha512-6FlzubTLZG3J2a/NVCAleEhjzq5oxgHyaCU9yYXvcLsvoVaHJq/s5xXI6/XXP6tz7R9xAOtHnSO/tXtF3WRTlA==", + "license": "MIT" + }, + "node_modules/negotiator": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/negotiator/-/negotiator-1.0.0.tgz", + "integrity": "sha512-8Ofs/AUQh8MaEcrlq5xOX0CQ9ypTF5dl78mjlMNfOK08fzpgTHQRQPBxcPlEtIw0yRpws+Zo/3r+5WRby7u3Gg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/node-fetch": { + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.7.0.tgz", + "integrity": "sha512-c4FRfUm/dbcWZ7U+1Wq0AwCyFL+3nt2bEw05wfxSz+DWpWsitgmSgYmy2dQdWyKC1694ELPqMs/YzUSNozLt8A==", + "license": "MIT", + "dependencies": { + "whatwg-url": "^5.0.0" + }, + "engines": { + "node": "4.x || >=6.0.0" + }, + "peerDependencies": { + "encoding": "^0.1.0" + }, + "peerDependenciesMeta": { + "encoding": { + "optional": true + } + } + }, + "node_modules/object-assign": { + "version": "4.1.1", + "resolved": "https://registry.npmjs.org/object-assign/-/object-assign-4.1.1.tgz", + "integrity": "sha512-rJgTQnkUnH1sFw8yT6VSU3zD3sWmu6sZhIseY8VX+GRu3P6F7Fu+JNDoXfklElbLJSnc3FUQHVe4cU5hj+BcUg==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/object-inspect": { + "version": "1.13.4", + "resolved": "https://registry.npmjs.org/object-inspect/-/object-inspect-1.13.4.tgz", + "integrity": "sha512-W67iLl4J2EXEGTbfeHCffrjDfitvLANg0UlX3wFUUSTx92KXRFegMHUVgSqE+wvhAbi4WqjGg9czysTV2Epbew==", + "license": "MIT", + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/on-finished": { + "version": "2.4.1", + "resolved": "https://registry.npmjs.org/on-finished/-/on-finished-2.4.1.tgz", + "integrity": "sha512-oVlzkg3ENAhCk2zdv7IJwd/QUD4z2RxRwpkcGY8psCVcCYZNq4wYnVWALHM+brtuJjePWiYF/ClmuDr8Ch5+kg==", + "license": "MIT", + "dependencies": { + "ee-first": "1.1.1" + }, + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/once": { + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/once/-/once-1.4.0.tgz", + "integrity": "sha512-lNaJgI+2Q5URQBkccEKHTQOPaXdUxnZZElQTZY0MFUAuaEqe1E+Nyvgdz/aIyNi6Z9MzO5dv1H8n58/GELp3+w==", + "license": "ISC", + "dependencies": { + "wrappy": "1" + } + }, + "node_modules/parseurl": { + "version": "1.3.3", + "resolved": "https://registry.npmjs.org/parseurl/-/parseurl-1.3.3.tgz", + "integrity": "sha512-CiyeOxFT/JZyN5m0z9PfXw4SCBJ6Sygz1Dpl0wqjlhDEGGBP1GnsUVEL0p63hoG1fcj3fHynXi9NYO4nWOL+qQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/path-key": { + "version": "3.1.1", + "resolved": "https://registry.npmjs.org/path-key/-/path-key-3.1.1.tgz", + "integrity": "sha512-ojmeN0qd+y0jszEtoY48r0Peq5dwMEkIlCOu6Q5f41lfkswXuKtYrhgoTpLnyIcHm24Uhqx+5Tqm2InSwLhE6Q==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/path-to-regexp": { + "version": "8.4.2", + "resolved": "https://registry.npmjs.org/path-to-regexp/-/path-to-regexp-8.4.2.tgz", + "integrity": "sha512-qRcuIdP69NPm4qbACK+aDogI5CBDMi1jKe0ry5rSQJz8JVLsC7jV8XpiJjGRLLol3N+R5ihGYcrPLTno6pAdBA==", + "license": "MIT", + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/pkce-challenge": { + "version": "5.0.1", + "resolved": "https://registry.npmjs.org/pkce-challenge/-/pkce-challenge-5.0.1.tgz", + "integrity": "sha512-wQ0b/W4Fr01qtpHlqSqspcj3EhBvimsdh0KlHhH8HRZnMsEa0ea2fTULOXOS9ccQr3om+GcGRk4e+isrZWV8qQ==", + "license": "MIT", + "engines": { + "node": ">=16.20.0" + } + }, + "node_modules/proxy-addr": { + "version": "2.0.7", + "resolved": "https://registry.npmjs.org/proxy-addr/-/proxy-addr-2.0.7.tgz", + "integrity": "sha512-llQsMLSUDUPT44jdrU/O37qlnifitDP+ZwrmmZcoSKyLKvtZxpyV0n2/bD/N4tBAAZ/gJEdZU7KMraoK1+XYAg==", + "license": "MIT", + "dependencies": { + "forwarded": "0.2.0", + "ipaddr.js": "1.9.1" + }, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/qs": { + "version": "6.15.1", + "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz", + "integrity": "sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==", + "license": "BSD-3-Clause", + "dependencies": { + "side-channel": "^1.1.0" + }, + "engines": { + "node": ">=0.6" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/range-parser": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/range-parser/-/range-parser-1.2.1.tgz", + "integrity": "sha512-Hrgsx+orqoygnmhFbKaHE6c296J+HTAQXoxEF6gNupROmmGJRoyzfG3ccAveqCBrwr/2yxQ5BVd/GTl5agOwSg==", + "license": "MIT", + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/raw-body": { + "version": "3.0.2", + "resolved": "https://registry.npmjs.org/raw-body/-/raw-body-3.0.2.tgz", + "integrity": "sha512-K5zQjDllxWkf7Z5xJdV0/B0WTNqx6vxG70zJE4N0kBs4LovmEYWJzQGxC9bS9RAKu3bgM40lrd5zoLJ12MQ5BA==", + "license": "MIT", + "dependencies": { + "bytes": "~3.1.2", + "http-errors": "~2.0.1", + "iconv-lite": "~0.7.0", + "unpipe": "~1.0.0" + }, + "engines": { + "node": ">= 0.10" + } + }, + "node_modules/require-from-string": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz", + "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==", + "license": "MIT", + "engines": { + "node": ">=0.10.0" + } + }, + "node_modules/router": { + "version": "2.2.0", + "resolved": "https://registry.npmjs.org/router/-/router-2.2.0.tgz", + "integrity": "sha512-nLTrUKm2UyiL7rlhapu/Zl45FwNgkZGaCpZbIHajDYgwlJCOzLSk+cIPAnsEqV955GjILJnKbdQC1nVPz+gAYQ==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.0", + "depd": "^2.0.0", + "is-promise": "^4.0.0", + "parseurl": "^1.3.3", + "path-to-regexp": "^8.0.0" + }, + "engines": { + "node": ">= 18" + } + }, + "node_modules/safer-buffer": { + "version": "2.1.2", + "resolved": "https://registry.npmjs.org/safer-buffer/-/safer-buffer-2.1.2.tgz", + "integrity": "sha512-YZo3K82SD7Riyi0E1EQPojLz7kpepnSQI9IyPbHHg1XXXevb5dJI7tpyN2ADxGcQbHG7vcyRHk0cbwqcQriUtg==", + "license": "MIT" + }, + "node_modules/send": { + "version": "1.2.1", + "resolved": "https://registry.npmjs.org/send/-/send-1.2.1.tgz", + "integrity": "sha512-1gnZf7DFcoIcajTjTwjwuDjzuz4PPcY2StKPlsGAQ1+YH20IRVrBaXSWmdjowTJ6u8Rc01PoYOGHXfP1mYcZNQ==", + "license": "MIT", + "dependencies": { + "debug": "^4.4.3", + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "etag": "^1.8.1", + "fresh": "^2.0.0", + "http-errors": "^2.0.1", + "mime-types": "^3.0.2", + "ms": "^2.1.3", + "on-finished": "^2.4.1", + "range-parser": "^1.2.1", + "statuses": "^2.0.2" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/serve-static": { + "version": "2.2.1", + "resolved": "https://registry.npmjs.org/serve-static/-/serve-static-2.2.1.tgz", + "integrity": "sha512-xRXBn0pPqQTVQiC8wyQrKs2MOlX24zQ0POGaj0kultvoOCstBQM5yvOhAVSUwOMjQtTvsPWoNCHfPGwaaQJhTw==", + "license": "MIT", + "dependencies": { + "encodeurl": "^2.0.0", + "escape-html": "^1.0.3", + "parseurl": "^1.3.3", + "send": "^1.2.0" + }, + "engines": { + "node": ">= 18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, + "node_modules/setprototypeof": { + "version": "1.2.0", + "resolved": "https://registry.npmjs.org/setprototypeof/-/setprototypeof-1.2.0.tgz", + "integrity": "sha512-E5LDX7Wrp85Kil5bhZv46j8jOeboKq5JMmYM3gVGdGH8xFpPWXUMsNrlODCrkoxMEeNi/XZIwuRvY4XNwYMJpw==", + "license": "ISC" + }, + "node_modules/shebang-command": { + "version": "2.0.0", + "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", + "integrity": "sha512-kHxr2zZpYtdmrN1qDjrrX/Z1rR1kG8Dx+gkpK1G4eXmvXswmcE1hTWBWYUzlraYw1/yZp6YuDY77YtvbN0dmDA==", + "license": "MIT", + "dependencies": { + "shebang-regex": "^3.0.0" + }, + "engines": { + "node": ">=8" + } + }, + "node_modules/shebang-regex": { + "version": "3.0.0", + "resolved": "https://registry.npmjs.org/shebang-regex/-/shebang-regex-3.0.0.tgz", + "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==", + "license": "MIT", + "engines": { + "node": ">=8" + } + }, + "node_modules/side-channel": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.1.0.tgz", + "integrity": "sha512-ZX99e6tRweoUXqR+VBrslhda51Nh5MTQwou5tnUDgbtyM0dBgmhEDtWGP/xbKn6hqfPRHujUNwz5fy/wbbhnpw==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.3", + "side-channel-list": "^1.0.0", + "side-channel-map": "^1.0.1", + "side-channel-weakmap": "^1.0.2" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-list": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz", + "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==", + "license": "MIT", + "dependencies": { + "es-errors": "^1.3.0", + "object-inspect": "^1.13.4" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-map": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/side-channel-map/-/side-channel-map-1.0.1.tgz", + "integrity": "sha512-VCjCNfgMsby3tTdo02nbjtM/ewra6jPHmpThenkTYh8pG9ucZ/1P8So4u4FGBek/BjpOVsDCMoLA/iuBKIFXRA==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/side-channel-weakmap": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/side-channel-weakmap/-/side-channel-weakmap-1.0.2.tgz", + "integrity": "sha512-WPS/HvHQTYnHisLo9McqBHOJk2FkHO/tlpvldyrnem4aeQp4hai3gythswg6p01oSoTl58rcpiFAjF2br2Ak2A==", + "license": "MIT", + "dependencies": { + "call-bound": "^1.0.2", + "es-errors": "^1.3.0", + "get-intrinsic": "^1.2.5", + "object-inspect": "^1.13.3", + "side-channel-map": "^1.0.1" + }, + "engines": { + "node": ">= 0.4" + }, + "funding": { + "url": "https://github.com/sponsors/ljharb" + } + }, + "node_modules/statuses": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/statuses/-/statuses-2.0.2.tgz", + "integrity": "sha512-DvEy55V3DB7uknRo+4iOGT5fP1slR8wQohVdknigZPMpMstaKJQWhwiYBACJE3Ul2pTnATihhBYnRhZQHGBiRw==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/toidentifier": { + "version": "1.0.1", + "resolved": "https://registry.npmjs.org/toidentifier/-/toidentifier-1.0.1.tgz", + "integrity": "sha512-o5sSPKEkg/DIQNmH43V0/uerLrpzVedkUh8tGNvaeXpfpuwjKenlSox/2O/BTlZUtEe+JG7s5YhEz608PlAHRA==", + "license": "MIT", + "engines": { + "node": ">=0.6" + } + }, + "node_modules/tr46": { + "version": "0.0.3", + "resolved": "https://registry.npmjs.org/tr46/-/tr46-0.0.3.tgz", + "integrity": "sha512-N3WMsuqV66lT30CrXNbEjx4GEwlow3v6rr4mCcv6prnfwhS01rkgyFdjPNBYd9br7LpXV1+Emh01fHnq2Gdgrw==", + "license": "MIT" + }, + "node_modules/type-is": { + "version": "2.0.1", + "resolved": "https://registry.npmjs.org/type-is/-/type-is-2.0.1.tgz", + "integrity": "sha512-OZs6gsjF4vMp32qrCbiVSkrFmXtG/AZhY3t0iAMrMBiAZyV9oALtXO8hsrHbMXF9x6L3grlFuwW2oAz7cav+Gw==", + "license": "MIT", + "dependencies": { + "content-type": "^1.0.5", + "media-typer": "^1.1.0", + "mime-types": "^3.0.0" + }, + "engines": { + "node": ">= 0.6" + } + }, + "node_modules/typescript": { + "version": "5.9.3", + "resolved": "https://registry.npmjs.org/typescript/-/typescript-5.9.3.tgz", + "integrity": "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw==", + "dev": true, + "license": "Apache-2.0", + "bin": { + "tsc": "bin/tsc", + "tsserver": "bin/tsserver" + }, + "engines": { + "node": ">=14.17" + } + }, + "node_modules/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/unpipe": { + "version": "1.0.0", + "resolved": "https://registry.npmjs.org/unpipe/-/unpipe-1.0.0.tgz", + "integrity": "sha512-pjy2bYhSsufwWlKwPc+l3cN7+wuJlK6uz0YdJEOlQDbl6jo/YlPi4mb8agUkVC8BF7V8NuzeyPNqRksA3hztKQ==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/vary": { + "version": "1.1.2", + "resolved": "https://registry.npmjs.org/vary/-/vary-1.1.2.tgz", + "integrity": "sha512-BNGbWLfd0eUPabhkXUVm0j8uuvREyTh5ovRa/dyow/BqAbZJyC+5fU+IzQOzmAKzYqYRAISoRhdQr3eIZ/PXqg==", + "license": "MIT", + "engines": { + "node": ">= 0.8" + } + }, + "node_modules/webidl-conversions": { + "version": "3.0.1", + "resolved": "https://registry.npmjs.org/webidl-conversions/-/webidl-conversions-3.0.1.tgz", + "integrity": "sha512-2JAn3z8AR6rjK8Sm8orRC0h/bcl/DqL7tRPdGZ4I1CjdF+EaMLmYxBHyXuKL849eucPFhvBoxMsflfOb8kxaeQ==", + "license": "BSD-2-Clause" + }, + "node_modules/whatwg-url": { + "version": "5.0.0", + "resolved": "https://registry.npmjs.org/whatwg-url/-/whatwg-url-5.0.0.tgz", + "integrity": "sha512-saE57nupxk6v3HY35+jzBwYa0rKSy0XR8JSxZPwgLr7ys0IBzhGviA1/TUGJLmSVqs8pb9AnvICXEuOHLprYTw==", + "license": "MIT", + "dependencies": { + "tr46": "~0.0.3", + "webidl-conversions": "^3.0.0" + } + }, + "node_modules/which": { + "version": "2.0.2", + "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz", + "integrity": "sha512-BLI3Tl1TW3Pvl70l3yq3Y64i+awpwXqsGBYWkkqMtnbXgrMD+yj7rhW0kuEDxzJaYXGjEW5ogapKNMEKNMjibA==", + "license": "ISC", + "dependencies": { + "isexe": "^2.0.0" + }, + "bin": { + "node-which": "bin/node-which" + }, + "engines": { + "node": ">= 8" + } + }, + "node_modules/wrappy": { + "version": "1.0.2", + "resolved": "https://registry.npmjs.org/wrappy/-/wrappy-1.0.2.tgz", + "integrity": "sha512-l4Sp/DRseor9wL6EvV2+TuQn63dMkPjZ/sp9XkghTEbV9KlPS1xUsZ3u7/IQO4wxtcFB4bgpQPRcR3QCvezPcQ==", + "license": "ISC" + }, + "node_modules/zod": { + "version": "4.3.6", + "resolved": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz", + "integrity": "sha512-rftlrkhHZOcjDwkGlnUtZZkvaPHCsDATp4pGpuOOMDaTdDDXF91wuVDJoWoPsKX/3YPQ5fHuF3STjcYyKr+Qhg==", + "license": "MIT", + "funding": { + "url": "https://github.com/sponsors/colinhacks" + } + }, + "node_modules/zod-to-json-schema": { + "version": "3.25.2", + "resolved": "https://registry.npmjs.org/zod-to-json-schema/-/zod-to-json-schema-3.25.2.tgz", + "integrity": "sha512-O/PgfnpT1xKSDeQYSCfRI5Gy3hPf91mKVDuYLUHZJMiDFptvP41MSnWofm8dnCm0256ZNfZIM7DSzuSMAFnjHA==", + "license": "ISC", + "peerDependencies": { + "zod": "^3.25.28 || ^4" + } + } + } +} diff --git a/package.json b/package.json new file mode 100644 index 0000000..f58fd4d --- /dev/null +++ b/package.json @@ -0,0 +1,20 @@ +{ + "name": "halo-psa-mcp", + "version": "1.0.0", + "description": "MCP server for Halo PSA — query tickets, clients, contracts, invoices, projects and more", + "main": "dist/index.js", + "scripts": { + "build": "tsc", + "start": "node dist/index.js", + "dev": "ts-node src/index.ts" + }, + "dependencies": { + "@modelcontextprotocol/sdk": "^1.12.1", + "node-fetch": "^2.7.0" + }, + "devDependencies": { + "@types/node": "^20.11.0", + "@types/node-fetch": "^2.6.11", + "typescript": "^5.3.3" + } +} diff --git a/src/halo-client.ts b/src/halo-client.ts new file mode 100644 index 0000000..6015eca --- /dev/null +++ b/src/halo-client.ts @@ -0,0 +1,117 @@ +import fetch from "node-fetch"; + +interface TokenResponse { + access_token: string; + token_type: string; + expires_in: number; +} + +export interface HaloClientConfig { + instanceUrl: string; + clientId: string; + clientSecret: string; + tenant?: string; +} + +export class HaloClient { + private config: HaloClientConfig; + private accessToken: string | null = null; + private tokenExpiresAt: number = 0; + + constructor(config: HaloClientConfig) { + this.config = config; + } + + private get authUrl(): string { + return `${this.config.instanceUrl}/auth/token`; + } + + private get apiUrl(): string { + return `${this.config.instanceUrl}/api`; + } + + private async authenticate(): Promise { + const now = Date.now(); + // Refresh if token expires within 60 seconds + if (this.accessToken && this.tokenExpiresAt > now + 60_000) { + return; + } + + const params = new URLSearchParams({ + grant_type: "client_credentials", + client_id: this.config.clientId, + client_secret: this.config.clientSecret, + }); + + if (this.config.tenant) { + params.append("tenant", this.config.tenant); + } + + const response = await fetch(this.authUrl, { + method: "POST", + headers: { "Content-Type": "application/x-www-form-urlencoded" }, + body: params.toString(), + }); + + if (!response.ok) { + const body = await response.text(); + throw new Error( + `Halo auth failed (${response.status}): ${body}` + ); + } + + const data = (await response.json()) as TokenResponse; + this.accessToken = data.access_token; + this.tokenExpiresAt = now + data.expires_in * 1000; + } + + async request( + method: string, + path: string, + params?: Record, + body?: any + ): Promise { + await this.authenticate(); + + let url = `${this.apiUrl}${path}`; + if (params && Object.keys(params).length > 0) { + const query = new URLSearchParams(); + for (const [key, value] of Object.entries(params)) { + if (value !== undefined && value !== null && value !== "") { + query.append(key, String(value)); + } + } + const qs = query.toString(); + if (qs) url += `?${qs}`; + } + + const headers: Record = { + Authorization: `Bearer ${this.accessToken}`, + "Content-Type": "application/json", + }; + + const response = await fetch(url, { + method, + headers, + body: body ? JSON.stringify(body) : undefined, + }); + + if (!response.ok) { + const text = await response.text(); + throw new Error( + `Halo API error ${response.status} ${method} ${path}: ${text}` + ); + } + + if (response.status === 204) return {} as T; + return (await response.json()) as T; + } + + async get(path: string, params?: Record): Promise { + return this.request("GET", path, params); + } + + async post(path: string, body?: any, params?: Record): Promise { + return this.request("POST", path, params, body); + } +} diff --git a/src/index.ts b/src/index.ts new file mode 100644 index 0000000..88fa456 --- /dev/null +++ b/src/index.ts @@ -0,0 +1,98 @@ +#!/usr/bin/env node + +import { Server } from "@modelcontextprotocol/sdk/server/index.js"; +import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; +import { + CallToolRequestSchema, + ListToolsRequestSchema, +} from "@modelcontextprotocol/sdk/types.js"; +import { HaloClient, HaloClientConfig } from "./halo-client"; +import { TOOL_DEFINITIONS, handleTool } from "./tools"; + +// ─── Configuration ─────────────────────────────────────────────────────────── + +function loadConfig(): HaloClientConfig { + const instanceUrl = process.env.HALO_INSTANCE_URL; + const clientId = process.env.HALO_CLIENT_ID; + const clientSecret = process.env.HALO_CLIENT_SECRET; + + if (!instanceUrl || !clientId || !clientSecret) { + console.error( + "Missing required environment variables:\n" + + " HALO_INSTANCE_URL — e.g. https://yourcompany.halopsa.com\n" + + " HALO_CLIENT_ID — OAuth client ID from Halo API config\n" + + " HALO_CLIENT_SECRET — OAuth client secret\n\n" + + "Optional:\n" + + " HALO_TENANT — tenant name (multi-tenant instances only)" + ); + process.exit(1); + } + + return { + instanceUrl: instanceUrl.replace(/\/+$/, ""), // strip trailing slash + clientId, + clientSecret, + tenant: process.env.HALO_TENANT || undefined, + }; +} + +// ─── Server Setup ──────────────────────────────────────────────────────────── + +async function main() { + const config = loadConfig(); + const haloClient = new HaloClient(config); + + const server = new Server( + { + name: "halo-psa-mcp", + version: "1.0.0", + }, + { + capabilities: { + tools: {}, + }, + } + ); + + // List tools + server.setRequestHandler(ListToolsRequestSchema, async () => ({ + tools: TOOL_DEFINITIONS, + })); + + // Handle tool calls + server.setRequestHandler(CallToolRequestSchema, async (request) => { + const { name, arguments: args = {} } = request.params; + + try { + const result = await handleTool(haloClient, name, args); + return { + content: [ + { + type: "text", + text: JSON.stringify(result, null, 2), + }, + ], + }; + } catch (error: any) { + return { + content: [ + { + type: "text", + text: `Error: ${error.message}`, + }, + ], + isError: true, + }; + } + }); + + // Start + const transport = new StdioServerTransport(); + await server.connect(transport); + console.error("Halo PSA MCP server running on stdio"); +} + +main().catch((err) => { + console.error("Fatal error:", err); + process.exit(1); +}); diff --git a/src/tools.ts b/src/tools.ts new file mode 100644 index 0000000..dde23bd --- /dev/null +++ b/src/tools.ts @@ -0,0 +1,480 @@ +import { HaloClient } from "./halo-client"; + +// ─── Tool Definitions ──────────────────────────────────────────────────────── + +export const TOOL_DEFINITIONS = [ + // ── Tickets ── + { + name: "list_tickets", + description: + "List tickets with optional filters. Returns paginated results. Use to see open work, SLA status, assignments etc.", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", description: "Page number (starts at 1)", default: 1 }, + page_size: { type: "number", description: "Results per page (max 100)", default: 50 }, + client_id: { type: "number", description: "Filter by client ID" }, + agent_id: { type: "number", description: "Filter by assigned agent ID" }, + status_id: { type: "number", description: "Filter by status ID" }, + ticket_type_id: { type: "number", description: "Filter by ticket type ID" }, + team_id: { type: "number", description: "Filter by team ID" }, + priority_id: { type: "number", description: "Filter by priority ID" }, + search: { type: "string", description: "Search term across ticket summary and details" }, + open_only: { type: "boolean", description: "Only return open/active tickets", default: true }, + }, + }, + }, + { + name: "get_ticket", + description: "Get full details of a specific ticket by ID, including actions/notes", + inputSchema: { + type: "object" as const, + properties: { + ticket_id: { type: "number", description: "The ticket ID" }, + include_actions: { type: "boolean", description: "Include ticket actions/notes", default: true }, + }, + required: ["ticket_id"], + }, + }, + + // ── Clients ── + { + name: "list_clients", + description: "List clients/customers with optional search. Returns company name, ID, status, and key info.", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", default: 1 }, + page_size: { type: "number", default: 50 }, + search: { type: "string", description: "Search by client name" }, + toplevel_id: { type: "number", description: "Filter by top-level/parent client ID" }, + active_only: { type: "boolean", default: true }, + }, + }, + }, + { + name: "get_client", + description: "Get full details of a specific client including sites, contacts, and key metadata", + inputSchema: { + type: "object" as const, + properties: { + client_id: { type: "number", description: "The client ID" }, + include_sites: { type: "boolean", default: true }, + }, + required: ["client_id"], + }, + }, + + // ── Contracts & Recurring Billing ── + { + name: "list_contracts", + description: + "List contracts/agreements. Contracts define recurring services, SLAs, and billing terms per client. Use to identify recurring revenue.", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", default: 1 }, + page_size: { type: "number", default: 50 }, + client_id: { type: "number", description: "Filter by client ID" }, + active_only: { type: "boolean", default: true }, + search: { type: "string", description: "Search contract name/ref" }, + }, + }, + }, + { + name: "get_contract", + description: "Get full details of a contract including billing lines, schedule, and coverage", + inputSchema: { + type: "object" as const, + properties: { + contract_id: { type: "number", description: "The contract ID" }, + }, + required: ["contract_id"], + }, + }, + + // ── Invoices ── + { + name: "list_invoices", + description: + "List invoices (one-off charges). These represent non-recurring billing for ad-hoc work, project charges etc.", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", default: 1 }, + page_size: { type: "number", default: 50 }, + client_id: { type: "number", description: "Filter by client ID" }, + status: { type: "string", description: "Filter: Draft, Sent, Paid, Overdue" }, + date_from: { type: "string", description: "Filter from date (ISO format YYYY-MM-DD)" }, + date_to: { type: "string", description: "Filter to date (ISO format YYYY-MM-DD)" }, + }, + }, + }, + { + name: "get_invoice", + description: "Get full invoice details including line items", + inputSchema: { + type: "object" as const, + properties: { + invoice_id: { type: "number", description: "The invoice ID" }, + }, + required: ["invoice_id"], + }, + }, + + // ── Recurring Invoices ── + { + name: "list_recurring_invoices", + description: + "List recurring invoices — these represent the RECURRING revenue streams. Each has a schedule (monthly/quarterly/annual) and line items that auto-bill.", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", default: 1 }, + page_size: { type: "number", default: 50 }, + client_id: { type: "number", description: "Filter by client ID" }, + active_only: { type: "boolean", default: true }, + }, + }, + }, + { + name: "get_recurring_invoice", + description: "Get full details of a recurring invoice including schedule, lines, and billing frequency", + inputSchema: { + type: "object" as const, + properties: { + recurring_invoice_id: { type: "number", description: "The recurring invoice ID" }, + }, + required: ["recurring_invoice_id"], + }, + }, + + // ── Projects ── + { + name: "list_projects", + description: "List projects. Projects typically represent non-recurring, scoped work for a client.", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", default: 1 }, + page_size: { type: "number", default: 50 }, + client_id: { type: "number", description: "Filter by client ID" }, + status: { type: "string", description: "Filter by project status" }, + search: { type: "string", description: "Search project name" }, + }, + }, + }, + { + name: "get_project", + description: "Get full project details including budget, progress, and associated tickets", + inputSchema: { + type: "object" as const, + properties: { + project_id: { type: "number", description: "The project ID" }, + }, + required: ["project_id"], + }, + }, + + // ── Actions / Time Entries ── + { + name: "list_actions", + description: + "List actions (time entries, notes, updates on tickets). Use to see billable time, who worked on what, and charge types.", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", default: 1 }, + page_size: { type: "number", default: 50 }, + ticket_id: { type: "number", description: "Filter by ticket ID" }, + agent_id: { type: "number", description: "Filter by agent/technician ID" }, + client_id: { type: "number", description: "Filter by client ID" }, + date_from: { type: "string", description: "From date (ISO YYYY-MM-DD)" }, + date_to: { type: "string", description: "To date (ISO YYYY-MM-DD)" }, + billable_only: { type: "boolean", description: "Only return billable actions" }, + }, + }, + }, + + // ── Assets ── + { + name: "list_assets", + description: "List assets/configuration items tracked in Halo", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", default: 1 }, + page_size: { type: "number", default: 50 }, + client_id: { type: "number", description: "Filter by client ID" }, + asset_type_id: { type: "number", description: "Filter by asset type" }, + search: { type: "string", description: "Search asset name/tag" }, + }, + }, + }, + { + name: "get_asset", + description: "Get full asset details including linked tickets and contracts", + inputSchema: { + type: "object" as const, + properties: { + asset_id: { type: "number", description: "The asset ID" }, + }, + required: ["asset_id"], + }, + }, + + // ── Revenue Analysis ── + { + name: "revenue_breakdown", + description: + "Get a breakdown of recurring vs non-recurring revenue for a client or across all clients. Combines data from contracts, recurring invoices, and one-off invoices to categorise revenue streams.", + inputSchema: { + type: "object" as const, + properties: { + client_id: { + type: "number", + description: "Specific client ID, or omit for all clients", + }, + date_from: { type: "string", description: "From date (ISO YYYY-MM-DD)" }, + date_to: { type: "string", description: "To date (ISO YYYY-MM-DD)" }, + }, + }, + }, + + // ── Agents / Teams ── + { + name: "list_agents", + description: "List agents/technicians in the Halo instance", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", default: 1 }, + page_size: { type: "number", default: 50 }, + team_id: { type: "number", description: "Filter by team ID" }, + search: { type: "string", description: "Search by agent name" }, + }, + }, + }, + + // ── Reports ── + { + name: "list_reports", + description: "List available reports in Halo PSA", + inputSchema: { + type: "object" as const, + properties: { + page: { type: "number", default: 1 }, + page_size: { type: "number", default: 50 }, + }, + }, + }, +]; + +// ─── Tool Handlers ─────────────────────────────────────────────────────────── + +export async function handleTool( + client: HaloClient, + toolName: string, + args: Record +): Promise { + switch (toolName) { + // ── Tickets ── + case "list_tickets": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + order: "id_desc", + }; + if (args.client_id) params.client_id = args.client_id; + if (args.agent_id) params.agent_id = args.agent_id; + if (args.status_id) params.status_id = args.status_id; + if (args.ticket_type_id) params.tickettype_id = args.ticket_type_id; + if (args.team_id) params.team_id = args.team_id; + if (args.priority_id) params.priority_id = args.priority_id; + if (args.search) params.search = args.search; + if (args.open_only !== false) params.open_only = true; + return client.get("/Tickets", params); + } + + case "get_ticket": { + const params: Record = {}; + if (args.include_actions !== false) params.includeactions = true; + return client.get(`/Tickets/${args.ticket_id}`, params); + } + + // ── Clients ── + case "list_clients": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + }; + if (args.search) params.search = args.search; + if (args.toplevel_id) params.toplevel_id = args.toplevel_id; + if (args.active_only !== false) params.inactive = false; + return client.get("/Client", params); + } + + case "get_client": { + const result = await client.get(`/Client/${args.client_id}`); + if (args.include_sites !== false) { + try { + const sites = await client.get("/Site", { client_id: args.client_id }); + result.sites = sites; + } catch { + // Sites endpoint may not be available + } + } + return result; + } + + // ── Contracts ── + case "list_contracts": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + }; + if (args.client_id) params.client_id = args.client_id; + if (args.search) params.search = args.search; + if (args.active_only !== false) params.active_only = true; + return client.get("/ClientContract", params); + } + + case "get_contract": { + return client.get(`/ClientContract/${args.contract_id}`); + } + + // ── Invoices (non-recurring) ── + case "list_invoices": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + }; + if (args.client_id) params.client_id = args.client_id; + if (args.status) params.payment_status = args.status; + if (args.date_from) params.start_date = args.date_from; + if (args.date_to) params.end_date = args.date_to; + return client.get("/Invoice", params); + } + + case "get_invoice": { + return client.get(`/Invoice/${args.invoice_id}`); + } + + // ── Recurring Invoices ── + case "list_recurring_invoices": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + }; + if (args.client_id) params.client_id = args.client_id; + if (args.active_only !== false) params.active_only = true; + return client.get("/RecurringInvoice", params); + } + + case "get_recurring_invoice": { + return client.get(`/RecurringInvoice/${args.recurring_invoice_id}`); + } + + // ── Projects ── + case "list_projects": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + }; + if (args.client_id) params.client_id = args.client_id; + if (args.status) params.status = args.status; + if (args.search) params.search = args.search; + return client.get("/Projects", params); + } + + case "get_project": { + return client.get(`/Projects/${args.project_id}`); + } + + // ── Actions / Time Entries ── + case "list_actions": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + }; + if (args.ticket_id) params.ticket_id = args.ticket_id; + if (args.agent_id) params.agent_id = args.agent_id; + if (args.client_id) params.client_id = args.client_id; + if (args.date_from) params.start_date = args.date_from; + if (args.date_to) params.end_date = args.date_to; + if (args.billable_only) params.billable_only = true; + return client.get("/Actions", params); + } + + // ── Assets ── + case "list_assets": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + }; + if (args.client_id) params.client_id = args.client_id; + if (args.asset_type_id) params.assettype_id = args.asset_type_id; + if (args.search) params.search = args.search; + return client.get("/Asset", params); + } + + case "get_asset": { + return client.get(`/Asset/${args.asset_id}`); + } + + // ── Revenue Breakdown (composite tool) ── + case "revenue_breakdown": { + const params: Record = { page_size: 100 }; + if (args.client_id) params.client_id = args.client_id; + + // Fetch recurring invoices + const recurringParams = { ...params, active_only: true }; + const recurring = await client.get("/RecurringInvoice", recurringParams); + + // Fetch one-off invoices + const invoiceParams: Record = { ...params }; + if (args.date_from) invoiceParams.start_date = args.date_from; + if (args.date_to) invoiceParams.end_date = args.date_to; + const oneOff = await client.get("/Invoice", invoiceParams); + + // Fetch contracts for context + const contractParams = { ...params, active_only: true }; + const contracts = await client.get("/ClientContract", contractParams); + + return { + summary: { + recurring_invoices_count: Array.isArray(recurring?.invoices) ? recurring.invoices.length : (recurring?.record_count || 0), + one_off_invoices_count: Array.isArray(oneOff?.invoices) ? oneOff.invoices.length : (oneOff?.record_count || 0), + active_contracts_count: Array.isArray(contracts?.contracts) ? contracts.contracts.length : (contracts?.record_count || 0), + }, + recurring_invoices: recurring, + one_off_invoices: oneOff, + contracts: contracts, + note: "Recurring invoices and contracts represent RECURRING revenue. Standard invoices represent NON-RECURRING / ad-hoc charges.", + }; + } + + // ── Agents ── + case "list_agents": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + }; + if (args.team_id) params.team_id = args.team_id; + if (args.search) params.search = args.search; + return client.get("/Agent", params); + } + + // ── Reports ── + case "list_reports": { + const params: Record = { + page_no: args.page || 1, + page_size: args.page_size || 50, + }; + return client.get("/Report", params); + } + + default: + throw new Error(`Unknown tool: ${toolName}`); + } +} diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..50572da --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,19 @@ +{ + "compilerOptions": { + "target": "ES2020", + "module": "commonjs", + "lib": ["ES2020"], + "outDir": "./dist", + "rootDir": "./src", + "strict": true, + "esModuleInterop": true, + "skipLibCheck": true, + "forceConsistentCasingInFileNames": true, + "resolveJsonModule": true, + "declaration": true, + "declarationMap": true, + "sourceMap": true + }, + "include": ["src/**/*"], + "exclude": ["node_modules", "dist"] +}