@calybur/mcp 0.2.2 → 0.2.3
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 +101 -101
- package/dist/index.js +9 -9
- package/dist/tools/docs.js +9 -9
- package/package.json +57 -57
package/README.md
CHANGED
|
@@ -1,101 +1,101 @@
|
|
|
1
|
-
# @calybur/mcp
|
|
2
|
-
|
|
3
|
-
Official MCP server for [Calybur](https://www.calybur.com) — connect **external MCP-compatible agents** to your Malaysian payroll and HR data via the Partner API.
|
|
4
|
-
|
|
5
|
-
Most Calybur customers use **AI Workspace** inside the product for day-to-day questions. This package is for integrators who want Claude Desktop, custom agents, automation runners, or any MCP client to query Calybur with an API key.
|
|
6
|
-
|
|
7
|
-
## Requirements
|
|
8
|
-
|
|
9
|
-
- Node.js 20+
|
|
10
|
-
- Calybur **Starter** plan or above
|
|
11
|
-
- API key with `read` scope — create at **Settings → API Keys** in Calybur
|
|
12
|
-
- Optional MCP setup copy at **Settings → Integrations**
|
|
13
|
-
|
|
14
|
-
## Setup in Calybur
|
|
15
|
-
|
|
16
|
-
1. Create a Partner API key (`ezg_live_*`) with read scope.
|
|
17
|
-
2. Open **Settings → Integrations** and copy the MCP config snippet, or use the example below.
|
|
18
|
-
3. Paste the config into your MCP client (stdio transport).
|
|
19
|
-
|
|
20
|
-
## Connect any MCP client
|
|
21
|
-
|
|
22
|
-
```json
|
|
23
|
-
{
|
|
24
|
-
"mcpServers": {
|
|
25
|
-
"calybur": {
|
|
26
|
-
"command": "npx",
|
|
27
|
-
"args": ["-y", "@calybur/mcp@latest"],
|
|
28
|
-
"env": {
|
|
29
|
-
"CALYBUR_API_KEY": "ezg_live_your_key_here"
|
|
30
|
-
}
|
|
31
|
-
}
|
|
32
|
-
}
|
|
33
|
-
}
|
|
34
|
-
```
|
|
35
|
-
|
|
36
|
-
Restart your MCP client and enable the Calybur tools. Cursor, Claude Desktop, and other stdio MCP hosts use the same shape; only the config file location differs.
|
|
37
|
-
|
|
38
|
-
## Environment Variables
|
|
39
|
-
|
|
40
|
-
| Variable | Required | Description |
|
|
41
|
-
|----------|----------|-------------|
|
|
42
|
-
| `CALYBUR_API_KEY` | Yes | Partner API key (`ezg_live_*`) |
|
|
43
|
-
| `CALYBUR_PLAN` | No | `starter` (default), `professional`, or `enterprise` |
|
|
44
|
-
| `CALYBUR_API_BASE_URL` | No | Defaults to `https://api.calybur.com` |
|
|
45
|
-
| `CALYBUR_SUPABASE_PUBLISHABLE_KEY` | No | Only if bypassing the gateway with a direct Supabase URL |
|
|
46
|
-
|
|
47
|
-
## Tools (MVP — read-only)
|
|
48
|
-
|
|
49
|
-
| Tool | Purpose |
|
|
50
|
-
|------|---------|
|
|
51
|
-
| `calybur_workforce` | Query employees, departments, positions, and work locations from Calybur. |
|
|
52
|
-
| `calybur_leave` | Query leave balances, requests, policies, and public holidays. |
|
|
53
|
-
| `calybur_payroll` | Query payroll periods, run status, and payslips. |
|
|
54
|
-
| `calybur_attendance` | Query attendance events and summaries. |
|
|
55
|
-
| `calybur_commission` | Query commission rules and calculation results. |
|
|
56
|
-
| `calybur_reports` | Fetch payroll summary or statutory export metadata for a period. |
|
|
57
|
-
| `calybur_status` | Check API key validity and remaining MCP client rate budget. |
|
|
58
|
-
| `calybur_docs` | Search bundled Calybur API and Malaysia statutory documentation. |
|
|
59
|
-
|
|
60
|
-
### Actions by tool
|
|
61
|
-
|
|
62
|
-
- **calybur_workforce**: list_employees, get_employee, list_departments, list_positions, list_work_locations
|
|
63
|
-
- **calybur_leave**: list_balances, list_requests, list_policies, list_holidays
|
|
64
|
-
- **calybur_payroll**: list_periods, get_run, list_payslips
|
|
65
|
-
- **calybur_attendance**: list_events, list_summaries
|
|
66
|
-
- **calybur_commission**: list_rules, list_calculations
|
|
67
|
-
- **calybur_reports**: payroll_summary, statutory_metadata
|
|
68
|
-
|
|
69
|
-
`calybur_status` and `calybur_docs` have dedicated input shapes (no `action` enum).
|
|
70
|
-
|
|
71
|
-
## Example prompts
|
|
72
|
-
|
|
73
|
-
- "Use calybur_status to verify my API connection"
|
|
74
|
-
- "List active employees with calybur_workforce"
|
|
75
|
-
- "Show March payroll periods with calybur_payroll"
|
|
76
|
-
|
|
77
|
-
## Development
|
|
78
|
-
|
|
79
|
-
```bash
|
|
80
|
-
cd packages/calybur-mcp
|
|
81
|
-
npm install
|
|
82
|
-
npm test
|
|
83
|
-
npm run build
|
|
84
|
-
CALYBUR_API_KEY=ezg_live_... npm run dev
|
|
85
|
-
```
|
|
86
|
-
|
|
87
|
-
## Rate limits
|
|
88
|
-
|
|
89
|
-
| Plan | API limit | MCP client budget (90%) |
|
|
90
|
-
|------|-----------|-------------------------|
|
|
91
|
-
| Starter | 100/min | 90/min |
|
|
92
|
-
| Professional | 500/min | 450/min |
|
|
93
|
-
| Enterprise | 2000/min | 1800/min |
|
|
94
|
-
|
|
95
|
-
## License
|
|
96
|
-
|
|
97
|
-
MIT
|
|
98
|
-
|
|
99
|
-
## Publishing
|
|
100
|
-
|
|
101
|
-
See [PUBLISHING.md](./PUBLISHING.md). Published package: `@calybur/mcp` on npm.
|
|
1
|
+
# @calybur/mcp
|
|
2
|
+
|
|
3
|
+
Official MCP server for [Calybur](https://www.calybur.com) — connect **external MCP-compatible agents** to your Malaysian payroll and HR data via the Partner API.
|
|
4
|
+
|
|
5
|
+
Most Calybur customers use **AI Workspace** inside the product for day-to-day questions. This package is for integrators who want Claude Desktop, custom agents, automation runners, or any MCP client to query Calybur with an API key.
|
|
6
|
+
|
|
7
|
+
## Requirements
|
|
8
|
+
|
|
9
|
+
- Node.js 20+
|
|
10
|
+
- Calybur **Starter** plan or above
|
|
11
|
+
- API key with `read` scope — create at **Settings → API Keys** in Calybur
|
|
12
|
+
- Optional MCP setup copy at **Settings → Integrations**
|
|
13
|
+
|
|
14
|
+
## Setup in Calybur
|
|
15
|
+
|
|
16
|
+
1. Create a Partner API key (`ezg_live_*`) with read scope.
|
|
17
|
+
2. Open **Settings → Integrations** and copy the MCP config snippet, or use the example below.
|
|
18
|
+
3. Paste the config into your MCP client (stdio transport).
|
|
19
|
+
|
|
20
|
+
## Connect any MCP client
|
|
21
|
+
|
|
22
|
+
```json
|
|
23
|
+
{
|
|
24
|
+
"mcpServers": {
|
|
25
|
+
"calybur": {
|
|
26
|
+
"command": "npx",
|
|
27
|
+
"args": ["-y", "@calybur/mcp@latest"],
|
|
28
|
+
"env": {
|
|
29
|
+
"CALYBUR_API_KEY": "ezg_live_your_key_here"
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Restart your MCP client and enable the Calybur tools. Cursor, Claude Desktop, and other stdio MCP hosts use the same shape; only the config file location differs.
|
|
37
|
+
|
|
38
|
+
## Environment Variables
|
|
39
|
+
|
|
40
|
+
| Variable | Required | Description |
|
|
41
|
+
|----------|----------|-------------|
|
|
42
|
+
| `CALYBUR_API_KEY` | Yes | Partner API key (`ezg_live_*`) |
|
|
43
|
+
| `CALYBUR_PLAN` | No | `starter` (default), `professional`, or `enterprise` |
|
|
44
|
+
| `CALYBUR_API_BASE_URL` | No | Defaults to `https://api.calybur.com` |
|
|
45
|
+
| `CALYBUR_SUPABASE_PUBLISHABLE_KEY` | No | Only if bypassing the gateway with a direct Supabase URL |
|
|
46
|
+
|
|
47
|
+
## Tools (MVP — read-only)
|
|
48
|
+
|
|
49
|
+
| Tool | Purpose |
|
|
50
|
+
|------|---------|
|
|
51
|
+
| `calybur_workforce` | Query employees, departments, positions, and work locations from Calybur. |
|
|
52
|
+
| `calybur_leave` | Query leave balances, requests, policies, and public holidays. |
|
|
53
|
+
| `calybur_payroll` | Query payroll periods, run status, and payslips. |
|
|
54
|
+
| `calybur_attendance` | Query attendance events and summaries. |
|
|
55
|
+
| `calybur_commission` | Query commission rules and calculation results. |
|
|
56
|
+
| `calybur_reports` | Fetch payroll summary or statutory export metadata for a period. |
|
|
57
|
+
| `calybur_status` | Check API key validity and remaining MCP client rate budget. |
|
|
58
|
+
| `calybur_docs` | Search bundled Calybur API and Malaysia statutory documentation. |
|
|
59
|
+
|
|
60
|
+
### Actions by tool
|
|
61
|
+
|
|
62
|
+
- **calybur_workforce**: list_employees, get_employee, list_departments, list_positions, list_work_locations
|
|
63
|
+
- **calybur_leave**: list_balances, list_requests, list_policies, list_holidays
|
|
64
|
+
- **calybur_payroll**: list_periods, get_run, list_payslips
|
|
65
|
+
- **calybur_attendance**: list_events, list_summaries
|
|
66
|
+
- **calybur_commission**: list_rules, list_calculations
|
|
67
|
+
- **calybur_reports**: payroll_summary, statutory_metadata
|
|
68
|
+
|
|
69
|
+
`calybur_status` and `calybur_docs` have dedicated input shapes (no `action` enum).
|
|
70
|
+
|
|
71
|
+
## Example prompts
|
|
72
|
+
|
|
73
|
+
- "Use calybur_status to verify my API connection"
|
|
74
|
+
- "List active employees with calybur_workforce"
|
|
75
|
+
- "Show March payroll periods with calybur_payroll"
|
|
76
|
+
|
|
77
|
+
## Development
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
cd packages/calybur-mcp
|
|
81
|
+
npm install
|
|
82
|
+
npm test
|
|
83
|
+
npm run build
|
|
84
|
+
CALYBUR_API_KEY=ezg_live_... npm run dev
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
## Rate limits
|
|
88
|
+
|
|
89
|
+
| Plan | API limit | MCP client budget (90%) |
|
|
90
|
+
|------|-----------|-------------------------|
|
|
91
|
+
| Starter | 100/min | 90/min |
|
|
92
|
+
| Professional | 500/min | 450/min |
|
|
93
|
+
| Enterprise | 2000/min | 1800/min |
|
|
94
|
+
|
|
95
|
+
## License
|
|
96
|
+
|
|
97
|
+
MIT
|
|
98
|
+
|
|
99
|
+
## Publishing
|
|
100
|
+
|
|
101
|
+
See [PUBLISHING.md](./PUBLISHING.md). Published package: `@calybur/mcp` on npm.
|
package/dist/index.js
CHANGED
|
@@ -14,15 +14,15 @@ import { handlePayroll } from './tools/payroll.js';
|
|
|
14
14
|
import { handleReports } from './tools/reports.js';
|
|
15
15
|
import { handleStatus } from './tools/status.js';
|
|
16
16
|
import { handleWorkforce } from './tools/workforce.js';
|
|
17
|
-
const SERVER_INSTRUCTIONS = `Calybur MCP connects external MCP-compatible agents to Malaysian payroll and HR data via the Calybur Partner API.
|
|
18
|
-
|
|
19
|
-
Guidelines:
|
|
20
|
-
- Prefer read tools before write operations (write tools ship in a later release).
|
|
21
|
-
- Batch queries; avoid redundant parallel tool calls.
|
|
22
|
-
- Default PII masking is on — IC, bank, and email fields are partially redacted.
|
|
23
|
-
- Starter plan: 100 API req/min — use list limits of 20 or lower.
|
|
24
|
-
- Malaysian statutory terms: EPF, SOCSO, EIS, PCB.
|
|
25
|
-
- Requires Starter+ plan and an API key with appropriate scopes from Calybur Settings → API Keys.
|
|
17
|
+
const SERVER_INSTRUCTIONS = `Calybur MCP connects external MCP-compatible agents to Malaysian payroll and HR data via the Calybur Partner API.
|
|
18
|
+
|
|
19
|
+
Guidelines:
|
|
20
|
+
- Prefer read tools before write operations (write tools ship in a later release).
|
|
21
|
+
- Batch queries; avoid redundant parallel tool calls.
|
|
22
|
+
- Default PII masking is on — IC, bank, and email fields are partially redacted.
|
|
23
|
+
- Starter plan: 100 API req/min — use list limits of 20 or lower.
|
|
24
|
+
- Malaysian statutory terms: EPF, SOCSO, EIS, PCB.
|
|
25
|
+
- Requires Starter+ plan and an API key with appropriate scopes from Calybur Settings → API Keys.
|
|
26
26
|
- In-app AI Workspace inside Calybur does not use this MCP server.`;
|
|
27
27
|
const sharedPaginationSchema = {
|
|
28
28
|
page: z.number().int().min(1).optional().describe('Page number (default 1)'),
|
package/dist/tools/docs.js
CHANGED
|
@@ -3,30 +3,30 @@ const DOC_SNIPPETS = [
|
|
|
3
3
|
{
|
|
4
4
|
title: 'API Quickstart',
|
|
5
5
|
keywords: ['api', 'key', 'auth', 'scope', 'starter'],
|
|
6
|
-
body: `Calybur Partner API uses x-api-key header. Requires Starter plan or above.
|
|
7
|
-
Scopes: read (query), write (create/update), admin (full), plus domain scopes like payroll:run, leave:approve.
|
|
6
|
+
body: `Calybur Partner API uses x-api-key header. Requires Starter plan or above.
|
|
7
|
+
Scopes: read (query), write (create/update), admin (full), plus domain scopes like payroll:run, leave:approve.
|
|
8
8
|
Create keys at Calybur Settings → API Keys.`,
|
|
9
9
|
},
|
|
10
10
|
{
|
|
11
11
|
title: 'Malaysia Statutory (EPF/SOCSO/EIS/PCB)',
|
|
12
12
|
keywords: ['epf', 'socso', 'eis', 'pcb', 'statutory', 'malaysia', 'kwsp', 'perkeso'],
|
|
13
|
-
body: `Malaysia payroll statutory components:
|
|
14
|
-
- EPF (KWSP): employee + employer provident fund
|
|
15
|
-
- SOCSO (Perkeso): social security
|
|
16
|
-
- EIS (SIP): employment insurance
|
|
13
|
+
body: `Malaysia payroll statutory components:
|
|
14
|
+
- EPF (KWSP): employee + employer provident fund
|
|
15
|
+
- SOCSO (Perkeso): social security
|
|
16
|
+
- EIS (SIP): employment insurance
|
|
17
17
|
- PCB (MTD): monthly tax deduction via LHDN schedules`,
|
|
18
18
|
},
|
|
19
19
|
{
|
|
20
20
|
title: 'MCP Setup',
|
|
21
21
|
keywords: ['mcp', 'cursor', 'claude', 'setup', 'config'],
|
|
22
|
-
body: `Configure Cursor MCP with npx @calybur/mcp and env:
|
|
23
|
-
CALYBUR_API_KEY (required). Optional: CALYBUR_PLAN (starter|professional|enterprise).
|
|
22
|
+
body: `Configure Cursor MCP with npx @calybur/mcp and env:
|
|
23
|
+
CALYBUR_API_KEY (required). Optional: CALYBUR_PLAN (starter|professional|enterprise).
|
|
24
24
|
Uses https://api.calybur.com gateway — no Supabase keys needed.`,
|
|
25
25
|
},
|
|
26
26
|
{
|
|
27
27
|
title: 'Rate Limits',
|
|
28
28
|
keywords: ['rate', 'limit', '429', 'starter', 'professional', 'enterprise'],
|
|
29
|
-
body: `API rate limits per company: Starter 100/min, Professional 500/min, Enterprise 2000/min.
|
|
29
|
+
body: `API rate limits per company: Starter 100/min, Professional 500/min, Enterprise 2000/min.
|
|
30
30
|
MCP client reserves 10% headroom. Prefer read tools and batch queries on Starter.`,
|
|
31
31
|
},
|
|
32
32
|
];
|
package/package.json
CHANGED
|
@@ -1,57 +1,57 @@
|
|
|
1
|
-
{
|
|
2
|
-
"name": "@calybur/mcp",
|
|
3
|
-
"version": "0.2.
|
|
4
|
-
"description": "MCP server for Calybur payroll and HR Partner API",
|
|
5
|
-
"type": "module",
|
|
6
|
-
"license": "MIT",
|
|
7
|
-
"author": "Calybur",
|
|
8
|
-
"homepage": "https://www.calybur.com",
|
|
9
|
-
"repository": {
|
|
10
|
-
"type": "git",
|
|
11
|
-
"url": "git+https://github.com/CreaiTechnology/ezgaji-payroll.git",
|
|
12
|
-
"directory": "packages/calybur-mcp"
|
|
13
|
-
},
|
|
14
|
-
"bugs": {
|
|
15
|
-
"url": "https://github.com/CreaiTechnology/ezgaji-payroll/issues"
|
|
16
|
-
},
|
|
17
|
-
"keywords": [
|
|
18
|
-
"mcp",
|
|
19
|
-
"calybur",
|
|
20
|
-
"payroll",
|
|
21
|
-
"hrms",
|
|
22
|
-
"malaysia",
|
|
23
|
-
"model-context-protocol"
|
|
24
|
-
],
|
|
25
|
-
"publishConfig": {
|
|
26
|
-
"access": "public"
|
|
27
|
-
},
|
|
28
|
-
"bin": {
|
|
29
|
-
"calybur-mcp": "dist/index.js"
|
|
30
|
-
},
|
|
31
|
-
"main": "./dist/index.js",
|
|
32
|
-
"files": [
|
|
33
|
-
"dist",
|
|
34
|
-
"README.md"
|
|
35
|
-
],
|
|
36
|
-
"scripts": {
|
|
37
|
-
"build": "tsc -p tsconfig.json",
|
|
38
|
-
"dev": "tsx src/index.ts",
|
|
39
|
-
"test": "vitest run",
|
|
40
|
-
"test:watch": "vitest",
|
|
41
|
-
"prepublishOnly": "npm run test && npm run build",
|
|
42
|
-
"pack:dry": "npm run build && npm pack --dry-run"
|
|
43
|
-
},
|
|
44
|
-
"engines": {
|
|
45
|
-
"node": ">=20"
|
|
46
|
-
},
|
|
47
|
-
"dependencies": {
|
|
48
|
-
"@modelcontextprotocol/sdk": "^1.12.1",
|
|
49
|
-
"zod": "^3.24.0"
|
|
50
|
-
},
|
|
51
|
-
"devDependencies": {
|
|
52
|
-
"@types/node": "^22.10.0",
|
|
53
|
-
"tsx": "^4.19.0",
|
|
54
|
-
"typescript": "^5.7.0",
|
|
55
|
-
"vitest": "^3.0.0"
|
|
56
|
-
}
|
|
57
|
-
}
|
|
1
|
+
{
|
|
2
|
+
"name": "@calybur/mcp",
|
|
3
|
+
"version": "0.2.3",
|
|
4
|
+
"description": "MCP server for Calybur payroll and HR Partner API",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"author": "Calybur",
|
|
8
|
+
"homepage": "https://www.calybur.com",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/CreaiTechnology/ezgaji-payroll.git",
|
|
12
|
+
"directory": "packages/calybur-mcp"
|
|
13
|
+
},
|
|
14
|
+
"bugs": {
|
|
15
|
+
"url": "https://github.com/CreaiTechnology/ezgaji-payroll/issues"
|
|
16
|
+
},
|
|
17
|
+
"keywords": [
|
|
18
|
+
"mcp",
|
|
19
|
+
"calybur",
|
|
20
|
+
"payroll",
|
|
21
|
+
"hrms",
|
|
22
|
+
"malaysia",
|
|
23
|
+
"model-context-protocol"
|
|
24
|
+
],
|
|
25
|
+
"publishConfig": {
|
|
26
|
+
"access": "public"
|
|
27
|
+
},
|
|
28
|
+
"bin": {
|
|
29
|
+
"calybur-mcp": "dist/index.js"
|
|
30
|
+
},
|
|
31
|
+
"main": "./dist/index.js",
|
|
32
|
+
"files": [
|
|
33
|
+
"dist",
|
|
34
|
+
"README.md"
|
|
35
|
+
],
|
|
36
|
+
"scripts": {
|
|
37
|
+
"build": "tsc -p tsconfig.json",
|
|
38
|
+
"dev": "tsx src/index.ts",
|
|
39
|
+
"test": "vitest run",
|
|
40
|
+
"test:watch": "vitest",
|
|
41
|
+
"prepublishOnly": "npm run test && npm run build",
|
|
42
|
+
"pack:dry": "npm run build && npm pack --dry-run"
|
|
43
|
+
},
|
|
44
|
+
"engines": {
|
|
45
|
+
"node": ">=20"
|
|
46
|
+
},
|
|
47
|
+
"dependencies": {
|
|
48
|
+
"@modelcontextprotocol/sdk": "^1.12.1",
|
|
49
|
+
"zod": "^3.24.0"
|
|
50
|
+
},
|
|
51
|
+
"devDependencies": {
|
|
52
|
+
"@types/node": "^22.10.0",
|
|
53
|
+
"tsx": "^4.19.0",
|
|
54
|
+
"typescript": "^5.7.0",
|
|
55
|
+
"vitest": "^3.0.0"
|
|
56
|
+
}
|
|
57
|
+
}
|