@teamnetwork-nz/payhero-mcp-server 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,91 @@
1
- # Temporary Holding Version
1
+ # PayHero MCP Server
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ A Model Context Protocol server for the [PayHero API](https://developer.payhero.co.nz/guide). It follows the same Node/TypeScript shape as the neighbouring TEAMnetwork MCP servers and supports stdio plus stateless Streamable HTTP.
4
+
5
+ ## What it exposes
6
+
7
+ The official API currently supports:
8
+
9
+ | Area | Read | Write (opt-in) |
10
+ |---|---|---|
11
+ | Employees | summary, info, full record, pay/tax settings, pay history, payslip PDF | create/update employee, info, pay and leave balances |
12
+ | Time and work | time entries, clock records, units, work/projects | save/delete time in bulk; create/update/archive work |
13
+ | Leave | requests, calculated info, daily breakdown, types and balances | create/update/delete requests and types; migrate balances |
14
+ | Payroll setup/results | pay cycles, pay items, finalised pay lines | create/update/archive pay items and cycles |
15
+ | Expenses | claims, attachments, approval/payment status | create/update/delete claims |
16
+ | Organisation | company settings, teams, memberships | update company; create/update/delete teams |
17
+ | Analytics | raw Power BI tables with paging/date filters | — |
18
+
19
+ There are 22 read-only tools (including connection tools). Setting `PAYHERO_READWRITE=true` exposes 13 additional mutation tools. Writes are both hidden and rejected by the client when read-only.
20
+
21
+ ## Authentication
22
+
23
+ PayHero private integrations use a two-stage flow:
24
+
25
+ 1. The MCP exchanges `PAYHERO_CLIENT_ID` and `PAYHERO_CLIENT_SECRET` at `POST /oauth/v1/token` using `client_credentials` and scope `api://payhero/.default`.
26
+ 2. It exchanges that bearer at `POST /v1/token`, selects the configured company, then sends both `Authorization: Bearer ...` and `x-company-token: ...` on API requests.
27
+
28
+ Both tokens are cached in memory and renewed before their one-hour expiry. Credentials and tokens are never returned by MCP tools or written to disk.
29
+
30
+ If your app can access multiple companies, set `PAYHERO_COMPANY_CODE`. Without it the server refuses to guess and reports the available company codes.
31
+
32
+ ## Setup
33
+
34
+ ```powershell
35
+ npm install
36
+ Copy-Item .env.example .env
37
+ npm run build
38
+ ```
39
+
40
+ Set the required environment variables in your MCP client configuration (the server does not automatically load `.env`):
41
+
42
+ ```json
43
+ {
44
+ "mcpServers": {
45
+ "payhero": {
46
+ "command": "node",
47
+ "args": ["C:/path/to/PayHero-MCP/dist/index.js"],
48
+ "env": {
49
+ "PAYHERO_CLIENT_ID": "...",
50
+ "PAYHERO_CLIENT_SECRET": "...",
51
+ "PAYHERO_COMPANY_CODE": "...",
52
+ "PAYHERO_READWRITE": "false"
53
+ }
54
+ }
55
+ }
56
+ }
57
+ ```
58
+
59
+ Use `payhero_connect` first. It confirms the selected company and granted scopes without exposing tokens.
60
+
61
+ ## HTTP transport
62
+
63
+ ```powershell
64
+ $env:PAYHERO_TRANSPORT='http'
65
+ $env:PAYHERO_HTTP_PORT='3000'
66
+ node dist/index.js
67
+ ```
68
+
69
+ The MCP endpoint is `POST /mcp`; `GET /health` is available for probes. Loopback binding is the default. Binding to a non-loopback address requires both `PAYHERO_HTTP_BEARER_TOKEN` and `PAYHERO_HTTP_ALLOWED_HOSTS`. Set `PAYHERO_HTTP_ALLOWED_ORIGINS` when browser clients need CORS-origin validation.
70
+
71
+ ## Important data-handling notes
72
+
73
+ PayHero can return payroll, tax, bank-account, leave, identity and contact data. Grant only required scopes, keep the server read-only unless mutations are needed, restrict MCP access, and avoid placing sensitive results into logs or broad-context prompts. `payhero_get_employee_payslip` returns PDF bytes as base64 rather than writing payroll files to disk.
74
+
75
+ ## API caveats
76
+
77
+ - Available operations depend on the scopes PayHero approved for the application.
78
+ - Date formats vary by endpoint; use `YYYY-MM-DD` for documented date query fields unless an endpoint requires a date-time.
79
+ - Power BI table names are: `employees`, `pays`, `pay_codes`, `work`, `expenses`, `teams`, `team_employee`, `pay_accounts`, `pay_cycles`, `segments`, `team_work`, `leave_requests`, `pay_employees`, and `pay_lines`. Calls are capped at 5,000 rows.
80
+ - Public/multi-customer integrations additionally require PayHero's user-authorisation/code flow. This initial server is optimized for the private-integration credentials described by the user.
81
+
82
+ ## Development
83
+
84
+ ```powershell
85
+ npm test
86
+ npm run dev
87
+ npm run smoke # live read-only API checks using .env
88
+ npm run smoke:mcp # stdio discovery + connection check
89
+ ```
90
+
91
+ The test command compiles TypeScript and verifies the HTTP transport's external-binding security checks. Both smoke commands force read-only mode even if `.env` enables writes, and print only response shapes/counts rather than employee or payroll values.
@@ -0,0 +1,26 @@
1
+ import { PayHeroConfig } from './config.js';
2
+ export declare class PayHeroClient {
3
+ private readonly config;
4
+ private bearer?;
5
+ private bearerExpiresAt;
6
+ private company?;
7
+ private companyExpiresAt;
8
+ constructor(config: PayHeroConfig);
9
+ getInfo(): {
10
+ apiUrl: string;
11
+ authUrl: string;
12
+ companyCode: string | undefined;
13
+ readWrite: boolean;
14
+ authenticated: boolean;
15
+ };
16
+ private authenticate;
17
+ private companyToken;
18
+ connect(force?: boolean): Promise<{
19
+ company_code: string;
20
+ company_name: string | undefined;
21
+ scopes: string | undefined;
22
+ expires_in: number | undefined;
23
+ }>;
24
+ request(method: 'GET' | 'POST', path: string, query?: Record<string, unknown>, body?: unknown): Promise<unknown>;
25
+ }
26
+ //# sourceMappingURL=client.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAK5C,qBAAa,aAAa;IAGZ,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,MAAM,CAAC,CAAS;IAAC,OAAO,CAAC,eAAe,CAAK;IACrD,OAAO,CAAC,OAAO,CAAC,CAAe;IAAC,OAAO,CAAC,gBAAgB,CAAK;gBAChC,MAAM,EAAE,aAAa;IAElD,OAAO;;;;;;;YAEO,YAAY;YASZ,YAAY;IAYpB,OAAO,CAAC,KAAK,UAAQ;;;;;;IAErB,OAAO,CAAC,MAAM,EAAE,KAAK,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;CAgBvH"}
package/dist/client.js ADDED
@@ -0,0 +1,58 @@
1
+ import axios, { AxiosError } from 'axios';
2
+ export class PayHeroClient {
3
+ config;
4
+ bearer;
5
+ bearerExpiresAt = 0;
6
+ company;
7
+ companyExpiresAt = 0;
8
+ constructor(config) {
9
+ this.config = config;
10
+ }
11
+ getInfo() { return { apiUrl: this.config.apiUrl, authUrl: this.config.authUrl, companyCode: this.config.companyCode, readWrite: this.config.readWrite, authenticated: Boolean(this.bearer && this.company) }; }
12
+ async authenticate() {
13
+ if (this.bearer && Date.now() < this.bearerExpiresAt - 60_000)
14
+ return this.bearer;
15
+ const form = new URLSearchParams({ grant_type: 'client_credentials', client_id: this.config.clientId, client_secret: this.config.clientSecret, scope: 'api://payhero/.default' });
16
+ const { data } = await axios.post(this.config.authUrl, form.toString(), { headers: { 'content-type': 'application/x-www-form-urlencoded', accept: 'application/json' } });
17
+ this.bearer = data.access_token;
18
+ this.bearerExpiresAt = Date.now() + (data.expires_in ?? 3599) * 1000;
19
+ return this.bearer;
20
+ }
21
+ async companyToken(force = false) {
22
+ const bearer = await this.authenticate();
23
+ if (!force && this.company && Date.now() < this.companyExpiresAt - 60_000)
24
+ return { bearer, token: this.company };
25
+ const { data } = await axios.post(`${this.config.apiUrl}/token`, { grant_type: 'client_credentials' }, { headers: { authorization: `Bearer ${bearer}`, accept: 'application/json', 'content-type': 'application/json' } });
26
+ const choices = Array.isArray(data) ? data : [data];
27
+ const selected = this.config.companyCode ? choices.find(v => v.company_code === this.config.companyCode) : choices[0];
28
+ if (!selected)
29
+ throw new Error(`PAYHERO_COMPANY_CODE ${this.config.companyCode} was not returned. Available: ${choices.map(v => v.company_code).join(', ')}`);
30
+ if (!this.config.companyCode && choices.length > 1)
31
+ throw new Error(`Credentials access multiple companies. Set PAYHERO_COMPANY_CODE to one of: ${choices.map(v => `${v.company_code} (${v.company_name ?? 'unnamed'})`).join(', ')}`);
32
+ this.company = selected;
33
+ this.companyExpiresAt = Date.now() + (selected.expires_in ?? 3599) * 1000;
34
+ return { bearer, token: selected };
35
+ }
36
+ async connect(force = false) { const value = await this.companyToken(force); return { company_code: value.token.company_code, company_name: value.token.company_name, scopes: value.token.scopes, expires_in: value.token.expires_in }; }
37
+ async request(method, path, query, body) {
38
+ if (method === 'POST' && !this.config.readWrite)
39
+ throw new Error('Write operations are disabled. Set PAYHERO_READWRITE=true to enable them.');
40
+ const { bearer, token } = await this.companyToken();
41
+ try {
42
+ const response = await axios.request({ method, url: `${this.config.apiUrl}${path}`, params: query, data: body, responseType: path === '/employee/payslip' ? 'arraybuffer' : 'json', headers: { authorization: `Bearer ${bearer}`, 'x-company-token': token.access_token, accept: path === '/employee/payslip' ? 'application/pdf' : 'application/json', 'content-type': 'application/json' } });
43
+ if (path === '/employee/payslip')
44
+ return { content_type: response.headers['content-type'], byte_length: response.data.byteLength, base64: Buffer.from(response.data).toString('base64') };
45
+ return response.data;
46
+ }
47
+ catch (cause) {
48
+ if (cause instanceof AxiosError) {
49
+ const status = cause.response?.status;
50
+ const data = cause.response?.data;
51
+ const detail = typeof data === 'string' ? data : JSON.stringify(data ?? cause.message);
52
+ throw new Error(`PayHero API error [${status ?? '?'}]: ${detail}${status === 401 || status === 403 ? ' (check credentials, company code, and approved scopes)' : ''}`);
53
+ }
54
+ throw cause;
55
+ }
56
+ }
57
+ }
58
+ //# sourceMappingURL=client.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAM1C,MAAM,OAAO,aAAa;IAGK;IAFrB,MAAM,CAAU;IAAS,eAAe,GAAG,CAAC,CAAC;IAC7C,OAAO,CAAgB;IAAS,gBAAgB,GAAG,CAAC,CAAC;IAC7D,YAA6B,MAAqB;QAArB,WAAM,GAAN,MAAM,CAAe;IAAG,CAAC;IAEtD,OAAO,KAAK,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,WAAW,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,EAAE,aAAa,EAAE,OAAO,CAAC,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;IAEvM,KAAK,CAAC,YAAY;QACxB,IAAI,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,eAAe,GAAG,MAAM;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QAClF,MAAM,IAAI,GAAG,IAAI,eAAe,CAAC,EAAE,UAAU,EAAE,oBAAoB,EAAE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,aAAa,EAAE,IAAI,CAAC,MAAM,CAAC,YAAY,EAAE,KAAK,EAAE,wBAAwB,EAAE,CAAC,CAAC;QAClL,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,KAAK,CAAC,IAAI,CAAe,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,cAAc,EAAE,mCAAmC,EAAE,MAAM,EAAE,kBAAkB,EAAE,EAAE,CAAC,CAAC;QACxL,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,YAAY,CAAC;QAChC,IAAI,CAAC,eAAe,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC;QACrE,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAEO,KAAK,CAAC,YAAY,CAAC,KAAK,GAAG,KAAK;QACtC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QACzC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,OAAO,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,gBAAgB,GAAG,MAAM;YAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;QAClH,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,KAAK,CAAC,IAAI,CAAgC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,QAAQ,EAAE,EAAE,UAAU,EAAE,oBAAoB,EAAE,EAAE,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE,MAAM,EAAE,kBAAkB,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,CAAC,CAAC;QAC1P,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QACpD,MAAM,QAAQ,GAAG,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,KAAK,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACtH,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,wBAAwB,IAAI,CAAC,MAAM,CAAC,WAAW,iCAAiC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAC9J,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,8EAA8E,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,YAAY,KAAK,CAAC,CAAC,YAAY,IAAI,SAAS,GAAG,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACvO,IAAI,CAAC,OAAO,GAAG,QAAQ,CAAC;QAAC,IAAI,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,QAAQ,CAAC,UAAU,IAAI,IAAI,CAAC,GAAG,IAAI,CAAC;QACnG,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;IACrC,CAAC;IAED,KAAK,CAAC,OAAO,CAAC,KAAK,GAAG,KAAK,IAAI,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,YAAY,EAAE,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC;IAEzO,KAAK,CAAC,OAAO,CAAC,MAAsB,EAAE,IAAY,EAAE,KAA+B,EAAE,IAAc;QACjG,IAAI,MAAM,KAAK,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,2EAA2E,CAAC,CAAC;QAC9I,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,YAAY,EAAE,CAAC;QACpD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,YAAY,EAAE,IAAI,KAAK,mBAAmB,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE,iBAAiB,EAAE,KAAK,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,KAAK,mBAAmB,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,kBAAkB,EAAE,cAAc,EAAE,kBAAkB,EAAE,EAAE,CAAC,CAAC;YAChY,IAAI,IAAI,KAAK,mBAAmB;gBAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,WAAW,EAAE,QAAQ,CAAC,IAAI,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC1L,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,KAAK,YAAY,UAAU,EAAE,CAAC;gBAChC,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAAC,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,EAAE,IAAI,CAAC;gBACzE,MAAM,MAAM,GAAG,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC;gBACvF,MAAM,IAAI,KAAK,CAAC,sBAAsB,MAAM,IAAI,GAAG,MAAM,MAAM,GAAG,MAAM,KAAK,GAAG,IAAI,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,yDAAyD,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzK,CAAC;YACD,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;CACF"}
@@ -0,0 +1,10 @@
1
+ export interface PayHeroConfig {
2
+ clientId: string;
3
+ clientSecret: string;
4
+ companyCode?: string;
5
+ authUrl: string;
6
+ apiUrl: string;
7
+ readWrite: boolean;
8
+ }
9
+ export declare function loadConfig(): PayHeroConfig;
10
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC7D,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAC;CACrD;AAID,wBAAgB,UAAU,IAAI,aAAa,CAY1C"}
package/dist/config.js ADDED
@@ -0,0 +1,17 @@
1
+ const cleanUrl = (value) => value.replace(/\/+$/, '');
2
+ export function loadConfig() {
3
+ const clientId = process.env.PAYHERO_CLIENT_ID?.trim();
4
+ const clientSecret = process.env.PAYHERO_CLIENT_SECRET?.trim();
5
+ if (!clientId)
6
+ throw new Error('Missing required environment variable: PAYHERO_CLIENT_ID');
7
+ if (!clientSecret)
8
+ throw new Error('Missing required environment variable: PAYHERO_CLIENT_SECRET');
9
+ return {
10
+ clientId, clientSecret,
11
+ companyCode: process.env.PAYHERO_COMPANY_CODE?.trim() || undefined,
12
+ authUrl: cleanUrl(process.env.PAYHERO_AUTH_URL?.trim() || 'https://publicapi.payhero.co.nz/oauth/v1/token'),
13
+ apiUrl: cleanUrl(process.env.PAYHERO_API_URL?.trim() || 'https://publicapi.payhero.co.nz/v1'),
14
+ readWrite: process.env.PAYHERO_READWRITE?.toLowerCase() === 'true',
15
+ };
16
+ }
17
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAKA,MAAM,QAAQ,GAAG,CAAC,KAAa,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAE9D,MAAM,UAAU,UAAU;IACxB,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC;IACvD,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,qBAAqB,EAAE,IAAI,EAAE,CAAC;IAC/D,IAAI,CAAC,QAAQ;QAAE,MAAM,IAAI,KAAK,CAAC,0DAA0D,CAAC,CAAC;IAC3F,IAAI,CAAC,YAAY;QAAE,MAAM,IAAI,KAAK,CAAC,8DAA8D,CAAC,CAAC;IACnG,OAAO;QACL,QAAQ,EAAE,YAAY;QACtB,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,oBAAoB,EAAE,IAAI,EAAE,IAAI,SAAS;QAClE,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,EAAE,IAAI,EAAE,IAAI,gDAAgD,CAAC;QAC3G,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,eAAe,EAAE,IAAI,EAAE,IAAI,oCAAoC,CAAC;QAC7F,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,EAAE,WAAW,EAAE,KAAK,MAAM;KACnE,CAAC;AACJ,CAAC"}
@@ -0,0 +1,17 @@
1
+ import http from 'node:http';
2
+ interface Connectable {
3
+ connect(transport: any): Promise<void>;
4
+ close(): Promise<void>;
5
+ }
6
+ export interface HttpOptions {
7
+ host: string;
8
+ port: number;
9
+ serverName: string;
10
+ bearerToken?: string;
11
+ allowedHosts?: string[];
12
+ allowedOrigins?: string[];
13
+ }
14
+ export declare function validateHttpOptions(o: HttpOptions): void;
15
+ export declare function createHttpServer(factory: () => Connectable, o: HttpOptions): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
16
+ export {};
17
+ //# sourceMappingURL=http-server.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"http-server.d.ts","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"AACA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,UAAU,WAAW;IAAG,OAAO,CAAC,SAAS,EAAE,GAAG,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE;AACxF,MAAM,WAAW,WAAW;IAAG,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE;AAEzJ,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,WAAW,QAAoX;AAGta,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,WAAW,EAAE,CAAC,EAAE,WAAW,wEAA2yC"}
@@ -0,0 +1,30 @@
1
+ import { timingSafeEqual } from 'node:crypto';
2
+ import http from 'node:http';
3
+ import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
4
+ const loopback = new Set(['127.0.0.1', '::1', 'localhost']);
5
+ export function validateHttpOptions(o) { if (!Number.isInteger(o.port) || o.port < 1 || o.port > 65535)
6
+ throw new Error(`Invalid HTTP port: ${o.port}`); if (!loopback.has(o.host) && !o.bearerToken)
7
+ throw new Error('A bearer token is required when binding beyond loopback'); if (!loopback.has(o.host) && !o.allowedHosts?.length)
8
+ throw new Error('HTTP_ALLOWED_HOSTS is required when binding beyond loopback'); }
9
+ const send = (res, status, body) => res.writeHead(status, { 'content-type': 'application/json' }).end(JSON.stringify(body));
10
+ const authOk = (header, expected) => { if (!header?.startsWith('Bearer '))
11
+ return false; const a = Buffer.from(header.slice(7)), b = Buffer.from(expected); return a.length === b.length && timingSafeEqual(a, b); };
12
+ export function createHttpServer(factory, o) { validateHttpOptions(o); const hosts = new Set(o.allowedHosts?.map(v => v.toLowerCase())); const origins = new Set(o.allowedOrigins?.map(v => v.toLowerCase())); return http.createServer(async (req, res) => { const path = new URL(req.url ?? '/', 'http://localhost').pathname; if (path === '/health')
13
+ return send(res, 200, { status: 'ok', server: o.serverName }); if (path !== '/mcp')
14
+ return void res.writeHead(404).end(); if (hosts.size && !hosts.has((req.headers.host ?? '').toLowerCase()))
15
+ return send(res, 403, { error: 'Host not allowed' }); if (req.headers.origin && !origins.has(req.headers.origin.toLowerCase()))
16
+ return send(res, 403, { error: 'Origin not allowed' }); if (o.bearerToken && !authOk(req.headers.authorization, o.bearerToken))
17
+ return send(res, 401, { error: 'Unauthorized' }); if (req.method !== 'POST')
18
+ return send(res, 405, { error: 'Method not allowed' }); const chunks = []; for await (const c of req)
19
+ chunks.push(c); const server = factory(), transport = new StreamableHTTPServerTransport({ sessionIdGenerator: undefined }); try {
20
+ await server.connect(transport);
21
+ await transport.handleRequest(req, res, JSON.parse(Buffer.concat(chunks).toString('utf8')));
22
+ }
23
+ catch (e) {
24
+ if (!res.headersSent)
25
+ send(res, 500, { error: e instanceof Error ? e.message : String(e) });
26
+ }
27
+ finally {
28
+ res.once('close', () => { void transport.close(); void server.close(); });
29
+ } }); }
30
+ //# sourceMappingURL=http-server.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"http-server.js","sourceRoot":"","sources":["../src/http-server.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,3 @@
1
+ #!/usr/bin/env node
2
+ export {};
3
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
package/dist/index.js ADDED
@@ -0,0 +1,27 @@
1
+ #!/usr/bin/env node
2
+ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
3
+ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
4
+ import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
5
+ import { zodToJsonSchema } from 'zod-to-json-schema';
6
+ import { loadConfig } from './config.js';
7
+ import { PayHeroClient } from './client.js';
8
+ import { makeTools } from './tools.js';
9
+ import { createHttpServer } from './http-server.js';
10
+ const config = loadConfig(), client = new PayHeroClient(config), tools = makeTools(client, config.readWrite);
11
+ const factory = () => { const server = new Server({ name: 'payhero-mcp-server', version: '0.1.1' }, { capabilities: { tools: {} }, instructions: 'PayHero payroll API MCP. Read-only by default. Call payhero_connect first to verify authentication/company selection. Dates use PayHero formats documented per endpoint. Write tools appear only when PAYHERO_READWRITE=true. Employee pay/bank/tax and payroll data are sensitive; disclose minimally.' }); server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: tools.map(t => ({ name: t.name, description: t.description, inputSchema: zodToJsonSchema(t.inputSchema) })) })); server.setRequestHandler(CallToolRequestSchema, async (req) => { const tool = tools.find(t => t.name === req.params.name); if (!tool)
12
+ return { isError: true, content: [{ type: 'text', text: `Unknown or disabled tool: ${req.params.name}` }] }; try {
13
+ const args = tool.inputSchema.parse(req.params.arguments ?? {});
14
+ const result = await tool.handler(args);
15
+ return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
16
+ }
17
+ catch (e) {
18
+ return { isError: true, content: [{ type: 'text', text: e instanceof Error ? e.message : String(e) }] };
19
+ } }); return server; };
20
+ if ((process.env.PAYHERO_TRANSPORT ?? 'stdio') === 'http') {
21
+ const host = process.env.PAYHERO_HTTP_HOST ?? '127.0.0.1', port = Number.parseInt(process.env.PAYHERO_HTTP_PORT ?? '3000', 10);
22
+ createHttpServer(factory, { host, port, serverName: 'payhero-mcp-server', bearerToken: process.env.PAYHERO_HTTP_BEARER_TOKEN, allowedHosts: process.env.PAYHERO_HTTP_ALLOWED_HOSTS?.split(',').map(v => v.trim()).filter(Boolean), allowedOrigins: process.env.PAYHERO_HTTP_ALLOWED_ORIGINS?.split(',').map(v => v.trim()).filter(Boolean) }).listen(port, host);
23
+ }
24
+ else
25
+ await factory().connect(new StdioServerTransport());
26
+ process.stderr.write(`PayHero MCP started: ${tools.length} tools (${config.readWrite ? 'read-write' : 'read-only'})\n`);
27
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,53 @@
1
+ import { z } from 'zod';
2
+ import { PayHeroClient } from './client.js';
3
+ export declare const makeTools: (client: PayHeroClient, readWrite: boolean) => ({
4
+ name: string;
5
+ description: string;
6
+ inputSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
7
+ handler: () => Promise<{
8
+ apiUrl: string;
9
+ authUrl: string;
10
+ companyCode: string | undefined;
11
+ readWrite: boolean;
12
+ authenticated: boolean;
13
+ }>;
14
+ } | {
15
+ name: string;
16
+ description: string;
17
+ inputSchema: z.ZodObject<{
18
+ force: z.ZodDefault<z.ZodBoolean>;
19
+ }, "strip", z.ZodTypeAny, {
20
+ force: boolean;
21
+ }, {
22
+ force?: boolean | undefined;
23
+ }>;
24
+ handler: (a: {
25
+ force: boolean;
26
+ }) => Promise<{
27
+ company_code: string;
28
+ company_name: string | undefined;
29
+ scopes: string | undefined;
30
+ expires_in: number | undefined;
31
+ }>;
32
+ } | {
33
+ name: string;
34
+ description: string;
35
+ inputSchema: z.ZodObject<{
36
+ query: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnion<[z.ZodString, z.ZodNumber, z.ZodBoolean]>>>;
37
+ }, "strip", z.ZodTypeAny, {
38
+ query?: Record<string, string | number | boolean> | undefined;
39
+ }, {
40
+ query?: Record<string, string | number | boolean> | undefined;
41
+ }> | z.ZodObject<{
42
+ body: z.ZodUnknown;
43
+ }, "strip", z.ZodTypeAny, {
44
+ body?: unknown;
45
+ }, {
46
+ body?: unknown;
47
+ }>;
48
+ handler: (a: {
49
+ query?: Record<string, unknown>;
50
+ body?: unknown;
51
+ }) => Promise<unknown>;
52
+ })[];
53
+ //# sourceMappingURL=tools.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAyC5C,eAAO,MAAM,SAAS,GAAI,QAAQ,aAAa,EAAE,WAAW,OAAO;;;;;;;;;;;;;;;;;;;;;iBAGuJ;QAAC,KAAK,EAAC,OAAO,CAAA;KAAC;;;;;;;;;;;;;;;;;;;;;;iBAMxN;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAAC,IAAI,CAAC,EAAE,OAAO,CAAA;KAAC;IAGjE,CAAC"}
package/dist/tools.js ADDED
@@ -0,0 +1,52 @@
1
+ import { z } from 'zod';
2
+ const operations = [
3
+ ['get_employee_info', 'GET', '/employee/info', 'Employee identity, contact, employment and work pattern', ['employee_key', 'load_finished']],
4
+ ['get_employee_pay_info', 'GET', '/employee/pay_info', 'Employee tax, pay, bank and KiwiSaver settings', ['employee_key', 'load_finished']],
5
+ ['get_employees', 'GET', '/employee', 'Complete employee records', ['employee_key', 'load_finished']],
6
+ ['get_employee_leave', 'GET', '/employee/leave', 'Employee leave balances and valuation figures', ['employee_key']],
7
+ ['get_employee_payslip', 'GET', '/employee/payslip', 'Payslip PDF returned as base64', ['pay_key', 'employee_key']],
8
+ ['get_employee_pay_history', 'GET', '/employee/pay_history', 'Pay totals by pay period', ['employee_key', 'start_date', 'end_date']],
9
+ ['get_employee_summary', 'GET', '/employee/summary', 'Core employee and headline pay details', ['employee_key', 'load_finished']],
10
+ ['get_expenses', 'GET', '/expense', 'Expense claims and approval/payment state', ['expense_key', 'employee_key', 'project_key', 'start_date', 'end_date']],
11
+ ['get_work', 'GET', '/work', 'Work/projects and defaults', ['work_key']],
12
+ ['get_pay_items', 'GET', '/pay_item', 'Earning and deduction definitions', ['pay_item_key']],
13
+ ['get_leave_types', 'GET', '/leave_type', 'Leave type definitions', ['leave_type_key']],
14
+ ['get_pay_cycles', 'GET', '/pay_cycle', 'Pay cycles, upcoming dates and assigned employees', ['pay_cycle_key']],
15
+ ['get_leave_info', 'GET', '/leave/info', 'Calculate/inspect a leave request', ['employee_key', 'start_date', 'end_date', 'part_day', 'request_hours', 'leave_type_key', 'leave_request_key', 'approver_employee_key']],
16
+ ['get_leave', 'GET', '/leave', 'Leave requests', ['leave_key', 'start_date', 'end_date', 'employee_key']],
17
+ ['get_leave_days', 'GET', '/leave/days', 'Day-by-day leave breakdown', ['start_date', 'end_date', 'employee_key']],
18
+ ['get_time', 'GET', '/time', 'Worked time, units and clock records', ['start_date', 'end_date', 'employee_key', 'time_key']],
19
+ ['get_power_bi_data', 'GET', '/power_bi', 'Raw analytics tables, paged to 5000 rows', ['table_name', 'from_date', 'to_date', 'updated_since', 'from_row', 'to_row']],
20
+ ['get_company', 'GET', '/company', 'Company payroll settings and configuration'],
21
+ ['get_teams', 'GET', '/team', 'Teams, members and assigned work', ['employee_key', 'team_key']],
22
+ ['get_pay_lines', 'GET', '/pay_line', 'Finalised individual pay lines', ['start_date', 'end_date', 'employee_key', 'pay_key']],
23
+ ['save_employee_info', 'POST', '/employee/info', 'Create/update non-financial employee details'],
24
+ ['save_employee_pay', 'POST', '/employee/pay', 'Update employee pay and tax configuration'],
25
+ ['save_employee', 'POST', '/employee', 'Create/update a complete employee record'],
26
+ ['save_employee_leave', 'POST', '/employee/leave', 'Update employee leave balances'],
27
+ ['save_expense', 'POST', '/expense', 'Create/update/delete an expense'],
28
+ ['save_work', 'POST', '/work', 'Create/update/archive work'],
29
+ ['save_pay_item', 'POST', '/pay_item', 'Create/update/archive a pay item'],
30
+ ['save_leave_type', 'POST', '/leave_type', 'Create/update/archive/delete a leave type'],
31
+ ['save_pay_cycle', 'POST', '/pay_cycle', 'Create/update/delete a pay cycle'],
32
+ ['save_leave', 'POST', '/leave', 'Create/update/delete leave'],
33
+ ['save_time', 'POST', '/time', 'Create/update/delete time entries in bulk'],
34
+ ['save_company', 'POST', '/company', 'Update company settings'],
35
+ ['save_team', 'POST', '/team', 'Create/update/delete a team'],
36
+ ].map(([id, method, path, summary, query]) => ({ id, method, path, summary, query }));
37
+ const querySchema = z.record(z.union([z.string(), z.number(), z.boolean()])).optional().describe('Query parameters supported by this endpoint');
38
+ const bodySchema = z.unknown().describe('JSON request body matching the PayHero API schema');
39
+ export const makeTools = (client, readWrite) => {
40
+ const base = [
41
+ { name: 'payhero_connection_status', description: 'Show configuration and cached authentication status (never reveals secrets).', inputSchema: z.object({}), handler: async () => client.getInfo() },
42
+ { name: 'payhero_connect', description: 'Authenticate and select the configured PayHero company. Use force=true to refresh tokens.', inputSchema: z.object({ force: z.boolean().default(false) }), handler: async (a) => client.connect(a.force) },
43
+ ];
44
+ const api = operations.filter(o => readWrite || o.method === 'GET').map(o => ({
45
+ name: `payhero_${o.id}`,
46
+ description: `${o.method === 'POST' ? '[write] ' : ''}${o.summary}. API: ${o.method} ${o.path}${o.query?.length ? `. Query fields: ${o.query.join(', ')}` : ''}`,
47
+ inputSchema: o.method === 'GET' ? z.object({ query: querySchema }) : z.object({ body: bodySchema }),
48
+ handler: (a) => client.request(o.method, o.path, a.query, a.body),
49
+ }));
50
+ return [...base, ...api];
51
+ };
52
+ //# sourceMappingURL=tools.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,29 @@
1
1
  {
2
2
  "name": "@teamnetwork-nz/payhero-mcp-server",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.1",
4
+ "description": "MCP server for the PayHero payroll API",
5
+ "type": "module",
6
+ "main": "dist/index.js",
7
+ "bin": { "payhero-mcp-server": "dist/index.js" },
8
+ "scripts": {
9
+ "build": "tsc",
10
+ "dev": "tsx src/index.ts",
11
+ "test": "npm run build && node --test tests/*.test.mjs",
12
+ "smoke": "npm run build && node scripts/smoke-test.mjs",
13
+ "smoke:mcp": "npm run build && node scripts/mcp-protocol-test.mjs"
14
+ },
15
+ "files": ["dist"],
16
+ "license": "MIT",
17
+ "dependencies": {
18
+ "@modelcontextprotocol/sdk": "^1.10.0",
19
+ "axios": "^1.7.0",
20
+ "zod": "^3.23.0",
21
+ "zod-to-json-schema": "^3.25.2"
22
+ },
23
+ "devDependencies": {
24
+ "@types/node": "^20.0.0",
25
+ "tsx": "^4.15.0",
26
+ "typescript": "^5.5.0"
27
+ },
28
+ "engines": { "node": ">=20.0.0" }
29
+ }