@calybur/mcp 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @calybur/mcp
+
+Official MCP server for [Calybur](https://www.calybur.com) — connect Cursor, Claude Desktop, or any MCP client to your Malaysian payroll and HR data.
+
+## Requirements
+
+- Node.js 20+
+- Calybur **Starter** plan or above
+- API key with `read` scope (create at **Settings → API Keys**)
+
+## Quick Start (Cursor)
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "calybur": {
+      "command": "npx",
+      "args": ["-y", "@calybur/mcp@latest"],
+      "env": {
+        "CALYBUR_API_KEY": "ezg_live_your_key_here",
+        "CALYBUR_API_BASE_URL": "https://YOUR_PROJECT.supabase.co/functions/v1",
+        "CALYBUR_SUPABASE_PUBLISHABLE_KEY": "your_supabase_publishable_key",
+        "CALYBUR_PLAN": "starter"
+      }
+    }
+  }
+}
+```
+
+Restart Cursor and enable the Calybur MCP tools.
+
+## Environment Variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `CALYBUR_API_KEY` | Yes | Partner API key (`ezg_live_*`) |
+| `CALYBUR_API_BASE_URL` | Yes | Supabase Edge Functions base URL |
+| `CALYBUR_SUPABASE_PUBLISHABLE_KEY` | Yes | Supabase publishable key (same as app frontend) |
+| `CALYBUR_PLAN` | No | `starter` (default), `professional`, or `enterprise` |
+
+## Tools (MVP — read-only)
+
+| Tool | Purpose |
+|------|---------|
+| `calybur_workforce` | Employees, departments, positions, locations |
+| `calybur_leave` | Balances, requests, policies, holidays |
+| `calybur_payroll` | Periods, runs, payslips |
+| `calybur_attendance` | Events and summaries |
+| `calybur_commission` | Rules and calculations |
+| `calybur_reports` | Payroll summary / statutory metadata |
+| `calybur_status` | API key + rate budget check |
+| `calybur_docs` | API and Malaysia statutory cheat sheet |
+
+## Example Prompts
+
+- "Use calybur_status to verify my API connection"
+- "List active employees with calybur_workforce"
+- "Show March payroll periods with calybur_payroll"
+
+## Development
+
+```bash
+cd packages/calybur-mcp
+npm install
+npm test
+npm run build
+CALYBUR_API_KEY=... CALYBUR_API_BASE_URL=... npm run dev
+```
+
+## Rate Limits
+
+| Plan | API limit | MCP client budget (90%) |
+|------|-----------|-------------------------|
+| Starter | 100/min | 90/min |
+| Professional | 500/min | 450/min |
+| Enterprise | 2000/min | 1800/min |
+
+## License
+
+MIT
+
+## Publishing
+
+See [PUBLISHING.md](./PUBLISHING.md). Published package: `@calybur/mcp` on npm.

package/dist/client.d.ts

@@ -0,0 +1,13 @@
+import type { CalyburConfig } from './config.js';
+import type { RateBudget } from './rate-budget.js';
+export declare class CalyburClient {
+    private readonly config;
+    private readonly budget;
+    constructor(config: CalyburConfig, budget: RateBudget);
+    get(functionPath: string, params?: Record<string, string>): Promise<unknown>;
+    statusSnapshot(): {
+        plan: import("./config.js").CalyburPlan;
+        budget_remaining: number;
+        budget_reset_at: string;
+    };
+}

package/dist/client.js

@@ -0,0 +1,37 @@
+import { CalyburApiError } from './errors.js';
+export class CalyburClient {
+    config;
+    budget;
+    constructor(config, budget) {
+        this.config = config;
+        this.budget = budget;
+    }
+    async get(functionPath, params = {}) {
+        if (!this.budget.tryConsume()) {
+            throw new CalyburApiError('Client rate budget exceeded. Wait for window reset.', 429);
+        }
+        const query = new URLSearchParams(params).toString();
+        const url = `${this.config.baseUrl}/${functionPath}${query ? `?${query}` : ''}`;
+        const response = await fetch(url, {
+            method: 'GET',
+            headers: {
+                'x-api-key': this.config.apiKey,
+                apikey: this.config.publishableKey,
+                Authorization: `Bearer ${this.config.publishableKey}`,
+                Accept: 'application/json',
+            },
+        });
+        const body = await response.json().catch(() => ({}));
+        if (!response.ok) {
+            throw new CalyburApiError(body.error || `HTTP ${response.status}`, response.status, body);
+        }
+        return body;
+    }
+    statusSnapshot() {
+        return {
+            plan: this.config.plan,
+            budget_remaining: this.budget.remaining(),
+            budget_reset_at: this.budget.resetAt().toISOString(),
+        };
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,9 @@
+export type CalyburPlan = 'starter' | 'professional' | 'enterprise';
+export interface CalyburConfig {
+    apiKey: string;
+    baseUrl: string;
+    publishableKey: string;
+    plan: CalyburPlan;
+}
+export declare function loadConfig(env?: NodeJS.ProcessEnv): CalyburConfig;
+export declare function defaultLimitForPlan(plan: CalyburPlan): number;

package/dist/config.js

@@ -0,0 +1,32 @@
+const VALID_PLANS = ['starter', 'professional', 'enterprise'];
+export function loadConfig(env = process.env) {
+    const apiKey = env.CALYBUR_API_KEY?.trim();
+    const baseUrl = env.CALYBUR_API_BASE_URL?.trim().replace(/\/$/, '');
+    const publishableKey = env.CALYBUR_SUPABASE_PUBLISHABLE_KEY?.trim() ||
+        env.CALYBUR_SUPABASE_ANON_KEY?.trim() ||
+        '';
+    const planRaw = (env.CALYBUR_PLAN?.trim().toLowerCase() || 'starter');
+    if (!apiKey) {
+        throw new Error('CALYBUR_API_KEY is required');
+    }
+    if (!apiKey.startsWith('ezg_')) {
+        throw new Error('CALYBUR_API_KEY must start with ezg_');
+    }
+    if (!baseUrl) {
+        throw new Error('CALYBUR_API_BASE_URL is required');
+    }
+    if (!publishableKey) {
+        throw new Error('CALYBUR_SUPABASE_PUBLISHABLE_KEY is required (Supabase gateway auth for Edge Functions)');
+    }
+    if (!VALID_PLANS.includes(planRaw)) {
+        throw new Error(`CALYBUR_PLAN must be one of: ${VALID_PLANS.join(', ')}`);
+    }
+    return { apiKey, baseUrl, publishableKey, plan: planRaw };
+}
+export function defaultLimitForPlan(plan) {
+    if (plan === 'enterprise')
+        return 100;
+    if (plan === 'professional')
+        return 50;
+    return 20;
+}

package/dist/errors.d.ts

@@ -0,0 +1,6 @@
+export declare class CalyburApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+export declare function formatApiError(error: CalyburApiError): string;

package/dist/errors.js

@@ -0,0 +1,33 @@
+export class CalyburApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'CalyburApiError';
+    }
+}
+export function formatApiError(error) {
+    if (error.status === 401) {
+        const body = error.body;
+        if (body?.code === 'UNAUTHORIZED_NO_AUTH_HEADER') {
+            return 'Missing Supabase publishable key. Set CALYBUR_SUPABASE_PUBLISHABLE_KEY in MCP config.';
+        }
+        return 'API key invalid or expired. Regenerate at Calybur Settings → API Keys.';
+    }
+    if (error.status === 403) {
+        const body = error.body;
+        if (body?.upgrade_required) {
+            return 'API access requires Starter plan or higher. Upgrade at Calybur Settings → Billing.';
+        }
+        return body?.error || 'Insufficient permissions. Check API key scopes in Settings → API Keys.';
+    }
+    if (error.status === 429) {
+        return 'Rate limit exceeded. Wait 60 seconds and reduce parallel tool calls.';
+    }
+    if (error.status === 404) {
+        return 'Resource not found.';
+    }
+    return error.message || 'Calybur API error. Retry once or contact support@calybur.com.';
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { CalyburClient } from './client.js';
+export declare function createCalyburMcpServer(client: CalyburClient): McpServer;

package/dist/index.js

@@ -0,0 +1,131 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { CalyburClient } from './client.js';
+import { loadConfig } from './config.js';
+import { RateBudget } from './rate-budget.js';
+import { handleAttendance } from './tools/attendance.js';
+import { handleCommission } from './tools/commission.js';
+import { handleDocs } from './tools/docs.js';
+import { handleLeave } from './tools/leave.js';
+import { handlePayroll } from './tools/payroll.js';
+import { handleReports } from './tools/reports.js';
+import { handleStatus } from './tools/status.js';
+import { handleWorkforce } from './tools/workforce.js';
+const SERVER_INSTRUCTIONS = `Calybur MCP connects AI clients to Malaysian payroll and HR data via the Calybur Partner API.
+
+Guidelines:
+- Prefer read tools before write operations (write tools ship in a later release).
+- Batch queries; avoid redundant parallel tool calls.
+- Default PII masking is on — IC, bank, and email fields are partially redacted.
+- Starter plan: 100 API req/min — use list limits of 20 or lower.
+- Malaysian statutory terms: EPF, SOCSO, EIS, PCB.
+- Requires Starter+ plan and an API key with appropriate scopes from Calybur Settings → API Keys.`;
+const sharedPaginationSchema = {
+    page: z.number().int().min(1).optional().describe('Page number (default 1)'),
+    limit: z.number().int().min(1).max(100).optional().describe('Page size (Starter default 20)'),
+    mask_pii: z.boolean().optional().describe('Mask IC, bank, email fields (default true)'),
+};
+export function createCalyburMcpServer(client) {
+    const server = new McpServer({
+        name: 'calybur',
+        version: '0.1.0',
+    }, {
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    server.registerTool('calybur_workforce', {
+        title: 'Calybur Workforce',
+        description: 'Query employees, departments, positions, and work locations from Calybur.',
+        inputSchema: z.object({
+            action: z.enum([
+                'list_employees',
+                'get_employee',
+                'list_departments',
+                'list_positions',
+                'list_work_locations',
+            ]),
+            employee_id: z.string().uuid().optional(),
+            ...sharedPaginationSchema,
+        }),
+    }, async (input) => handleWorkforce(client, input));
+    server.registerTool('calybur_leave', {
+        title: 'Calybur Leave',
+        description: 'Query leave balances, requests, policies, and public holidays.',
+        inputSchema: z.object({
+            action: z.enum(['list_balances', 'list_requests', 'list_policies', 'list_holidays']),
+            employee_id: z.string().uuid().optional(),
+            status: z.string().optional(),
+            year: z.number().int().optional(),
+            ...sharedPaginationSchema,
+        }),
+    }, async (input) => handleLeave(client, input));
+    server.registerTool('calybur_payroll', {
+        title: 'Calybur Payroll',
+        description: 'Query payroll periods, run status, and payslips.',
+        inputSchema: z.object({
+            action: z.enum(['list_periods', 'get_run', 'list_payslips']),
+            period_id: z.string().uuid().optional(),
+            status: z.string().optional(),
+            ...sharedPaginationSchema,
+        }),
+    }, async (input) => handlePayroll(client, input));
+    server.registerTool('calybur_attendance', {
+        title: 'Calybur Attendance',
+        description: 'Query attendance events and summaries.',
+        inputSchema: z.object({
+            action: z.enum(['list_events', 'list_summaries']),
+            employee_id: z.string().uuid().optional(),
+            status: z.string().optional(),
+            from: z.string().optional().describe('YYYY-MM-DD'),
+            to: z.string().optional().describe('YYYY-MM-DD'),
+            ...sharedPaginationSchema,
+        }),
+    }, async (input) => handleAttendance(client, input));
+    server.registerTool('calybur_commission', {
+        title: 'Calybur Commission',
+        description: 'Query commission rules and calculation results.',
+        inputSchema: z.object({
+            action: z.enum(['list_rules', 'list_calculations']),
+            status: z.string().optional(),
+            ...sharedPaginationSchema,
+        }),
+    }, async (input) => handleCommission(client, input));
+    server.registerTool('calybur_reports', {
+        title: 'Calybur Reports',
+        description: 'Fetch payroll summary or statutory export metadata for a period.',
+        inputSchema: z.object({
+            action: z.enum(['payroll_summary', 'statutory_metadata']),
+            period_id: z.string().uuid(),
+            mask_pii: z.boolean().optional(),
+        }),
+    }, async (input) => handleReports(client, input));
+    server.registerTool('calybur_status', {
+        title: 'Calybur Status',
+        description: 'Check API key validity and remaining MCP client rate budget.',
+        inputSchema: z.object({}),
+    }, async () => handleStatus(client));
+    server.registerTool('calybur_docs', {
+        title: 'Calybur Docs',
+        description: 'Search bundled Calybur API and Malaysia statutory documentation.',
+        inputSchema: z.object({
+            query: z.string().min(1),
+        }),
+    }, async ({ query }) => handleDocs(query));
+    return server;
+}
+async function main() {
+    const config = loadConfig();
+    const budget = new RateBudget(config.plan);
+    const client = new CalyburClient(config, budget);
+    const server = createCalyburMcpServer(client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+const isDirectRun = process.argv[1]?.includes('index');
+if (isDirectRun) {
+    main().catch((error) => {
+        console.error(error);
+        process.exit(1);
+    });
+}

package/dist/pii-mask.d.ts

@@ -0,0 +1,3 @@
+export declare function maskValue(field: string, value: unknown): unknown;
+export declare function maskRecord(record: Record<string, unknown>): Record<string, unknown>;
+export declare function maybeMask(data: unknown, enabled: boolean): unknown;

package/dist/pii-mask.js

@@ -0,0 +1,66 @@
+const PII_FIELDS = new Set([
+    'ic_number',
+    'nric',
+    'bank_account',
+    'bank_account_number',
+    'epf_number',
+    'socso_number',
+]);
+function shouldMaskField(key) {
+    const normalized = key.toLowerCase();
+    return (PII_FIELDS.has(normalized) ||
+        normalized.includes('ic') ||
+        normalized.includes('bank') ||
+        normalized.includes('email'));
+}
+export function maskValue(field, value) {
+    if (typeof value !== 'string' || !value)
+        return value;
+    const key = field.toLowerCase();
+    if (key.includes('ic') || key === 'nric') {
+        return value.replace(/^(\d{6})-?\d{2}-?(\d{4})$/, '$1-**-$2');
+    }
+    if (key.includes('bank')) {
+        return value.length <= 4 ? '****' : `${'*'.repeat(value.length - 4)}${value.slice(-4)}`;
+    }
+    if (key.includes('email')) {
+        const [local, domain] = value.split('@');
+        if (!domain)
+            return value;
+        return `${local.slice(0, 2)}***@${domain}`;
+    }
+    return value;
+}
+export function maskRecord(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (Array.isArray(value)) {
+            out[key] = value.map((item) => typeof item === 'object' && item !== null
+                ? maskRecord(item)
+                : item);
+        }
+        else if (typeof value === 'object' && value !== null) {
+            out[key] = maskRecord(value);
+        }
+        else if (shouldMaskField(key)) {
+            out[key] = maskValue(key, value);
+        }
+        else {
+            out[key] = value;
+        }
+    }
+    return out;
+}
+export function maybeMask(data, enabled) {
+    if (!enabled)
+        return data;
+    if (Array.isArray(data)) {
+        return data.map((row) => typeof row === 'object' && row !== null
+            ? maskRecord(row)
+            : row);
+    }
+    if (typeof data === 'object' && data !== null) {
+        return maskRecord(data);
+    }
+    return data;
+}

package/dist/rate-budget.d.ts

@@ -0,0 +1,11 @@
+import type { CalyburPlan } from './config.js';
+export declare class RateBudget {
+    private used;
+    private windowStart;
+    private readonly max;
+    constructor(plan: CalyburPlan);
+    private rollWindow;
+    tryConsume(): boolean;
+    remaining(): number;
+    resetAt(): Date;
+}

package/dist/rate-budget.js

@@ -0,0 +1,35 @@
+const PLAN_LIMITS = {
+    starter: 100,
+    professional: 500,
+    enterprise: 2000,
+};
+const HEADROOM = 0.9;
+const WINDOW_MS = 60_000;
+export class RateBudget {
+    used = 0;
+    windowStart = Date.now();
+    max;
+    constructor(plan) {
+        this.max = Math.floor(PLAN_LIMITS[plan] * HEADROOM);
+    }
+    rollWindow(now = Date.now()) {
+        if (now - this.windowStart >= WINDOW_MS) {
+            this.used = 0;
+            this.windowStart = now;
+        }
+    }
+    tryConsume() {
+        this.rollWindow();
+        if (this.used >= this.max)
+            return false;
+        this.used += 1;
+        return true;
+    }
+    remaining() {
+        this.rollWindow();
+        return Math.max(0, this.max - this.used);
+    }
+    resetAt() {
+        return new Date(this.windowStart + WINDOW_MS);
+    }
+}

package/dist/scope-guard.d.ts

@@ -0,0 +1,2 @@
+export declare function hasScope(scopes: string[], required: string): boolean;
+export declare function assertScope(scopes: string[], required: string): void;

package/dist/scope-guard.js

@@ -0,0 +1,8 @@
+export function hasScope(scopes, required) {
+    return scopes.includes('admin') || scopes.includes(required);
+}
+export function assertScope(scopes, required) {
+    if (!hasScope(scopes, required)) {
+        throw new Error(`Missing required scope "${required}". Update your API key scopes at Calybur Settings → API Keys.`);
+    }
+}

package/dist/tools/attendance.d.ts

@@ -0,0 +1,14 @@
+import type { CalyburClient } from '../client.js';
+import { type ToolTextResult } from './shared.js';
+export type AttendanceAction = 'list_events' | 'list_summaries';
+export interface AttendanceInput {
+    action: AttendanceAction;
+    employee_id?: string;
+    status?: string;
+    from?: string;
+    to?: string;
+    page?: number;
+    limit?: number;
+    mask_pii?: boolean;
+}
+export declare function handleAttendance(client: CalyburClient, input: AttendanceInput): Promise<ToolTextResult>;

package/dist/tools/attendance.js

@@ -0,0 +1,19 @@
+import { extractApiData, maskToolPayload, paginationParams, withToolHandler, } from './shared.js';
+export async function handleAttendance(client, input) {
+    return withToolHandler(async () => {
+        const params = paginationParams(input.page, input.limit);
+        if (input.employee_id)
+            params.employee_id = input.employee_id;
+        if (input.status)
+            params.status = input.status;
+        if (input.from)
+            params.from = input.from;
+        if (input.to)
+            params.to = input.to;
+        const route = input.action === 'list_events'
+            ? 'api-v1-attendance/events'
+            : 'api-v1-attendance/summaries';
+        const raw = await client.get(route, params);
+        return maskToolPayload(extractApiData(raw), input.mask_pii, input.action);
+    });
+}

package/dist/tools/commission.d.ts

@@ -0,0 +1,11 @@
+import type { CalyburClient } from '../client.js';
+import { type ToolTextResult } from './shared.js';
+export type CommissionAction = 'list_rules' | 'list_calculations';
+export interface CommissionInput {
+    action: CommissionAction;
+    status?: string;
+    page?: number;
+    limit?: number;
+    mask_pii?: boolean;
+}
+export declare function handleCommission(client: CalyburClient, input: CommissionInput): Promise<ToolTextResult>;

package/dist/tools/commission.js

@@ -0,0 +1,13 @@
+import { extractApiData, maskToolPayload, paginationParams, withToolHandler, } from './shared.js';
+export async function handleCommission(client, input) {
+    return withToolHandler(async () => {
+        const params = paginationParams(input.page, input.limit);
+        if (input.status)
+            params.status = input.status;
+        const route = input.action === 'list_rules'
+            ? 'api-v1-commission/rules'
+            : 'api-v1-commission/calculations';
+        const raw = await client.get(route, params);
+        return maskToolPayload(extractApiData(raw), input.mask_pii, input.action);
+    });
+}

package/dist/tools/docs.d.ts

@@ -0,0 +1,2 @@
+import { type ToolTextResult } from './shared.js';
+export declare function handleDocs(query: string): ToolTextResult;

package/dist/tools/docs.js

@@ -0,0 +1,41 @@
+import { okResult } from './shared.js';
+const DOC_SNIPPETS = [
+    {
+        title: 'API Quickstart',
+        keywords: ['api', 'key', 'auth', 'scope', 'starter'],
+        body: `Calybur Partner API uses x-api-key header. Requires Starter plan or above.
+Scopes: read (query), write (create/update), admin (full), plus domain scopes like payroll:run, leave:approve.
+Create keys at Calybur Settings → API Keys.`,
+    },
+    {
+        title: 'Malaysia Statutory (EPF/SOCSO/EIS/PCB)',
+        keywords: ['epf', 'socso', 'eis', 'pcb', 'statutory', 'malaysia', 'kwsp', 'perkeso'],
+        body: `Malaysia payroll statutory components:
+- EPF (KWSP): employee + employer provident fund
+- SOCSO (Perkeso): social security
+- EIS (SIP): employment insurance
+- PCB (MTD): monthly tax deduction via LHDN schedules`,
+    },
+    {
+        title: 'MCP Setup',
+        keywords: ['mcp', 'cursor', 'claude', 'setup', 'config'],
+        body: `Configure Cursor MCP with npx @calybur/mcp and env vars:
+CALYBUR_API_KEY, CALYBUR_API_BASE_URL (Supabase functions/v1 base), optional CALYBUR_PLAN (starter|professional|enterprise).`,
+    },
+    {
+        title: 'Rate Limits',
+        keywords: ['rate', 'limit', '429', 'starter', 'professional', 'enterprise'],
+        body: `API rate limits per company: Starter 100/min, Professional 500/min, Enterprise 2000/min.
+MCP client reserves 10% headroom. Prefer read tools and batch queries on Starter.`,
+    },
+];
+export function handleDocs(query) {
+    const haystack = query.toLowerCase();
+    const matches = DOC_SNIPPETS.filter((doc) => doc.title.toLowerCase().includes(haystack) ||
+        doc.keywords.some((keyword) => haystack.includes(keyword) || keyword.includes(haystack)));
+    const results = (matches.length > 0 ? matches : DOC_SNIPPETS).map((doc) => ({
+        title: doc.title,
+        body: doc.body,
+    }));
+    return okResult({ query, results });
+}

package/dist/tools/leave.d.ts

@@ -0,0 +1,13 @@
+import type { CalyburClient } from '../client.js';
+import { type ToolTextResult } from './shared.js';
+export type LeaveAction = 'list_balances' | 'list_requests' | 'list_policies' | 'list_holidays';
+export interface LeaveInput {
+    action: LeaveAction;
+    employee_id?: string;
+    status?: string;
+    year?: number;
+    page?: number;
+    limit?: number;
+    mask_pii?: boolean;
+}
+export declare function handleLeave(client: CalyburClient, input: LeaveInput): Promise<ToolTextResult>;

package/dist/tools/leave.js

@@ -0,0 +1,20 @@
+import { extractApiData, maskToolPayload, paginationParams, withToolHandler, } from './shared.js';
+const ROUTE_MAP = {
+    list_balances: 'api-v1-leave/balances',
+    list_requests: 'api-v1-leave/requests',
+    list_policies: 'api-v1-leave/policies',
+    list_holidays: 'api-v1-leave/public-holidays',
+};
+export async function handleLeave(client, input) {
+    return withToolHandler(async () => {
+        const params = paginationParams(input.page, input.limit);
+        if (input.employee_id)
+            params.employee_id = input.employee_id;
+        if (input.status)
+            params.status = input.status;
+        if (input.year)
+            params.year = String(input.year);
+        const raw = await client.get(ROUTE_MAP[input.action], params);
+        return maskToolPayload(extractApiData(raw), input.mask_pii, input.action);
+    });
+}

package/dist/tools/payroll.d.ts

@@ -0,0 +1,12 @@
+import type { CalyburClient } from '../client.js';
+import { type ToolTextResult } from './shared.js';
+export type PayrollAction = 'list_periods' | 'get_run' | 'list_payslips';
+export interface PayrollInput {
+    action: PayrollAction;
+    period_id?: string;
+    status?: string;
+    page?: number;
+    limit?: number;
+    mask_pii?: boolean;
+}
+export declare function handlePayroll(client: CalyburClient, input: PayrollInput): Promise<ToolTextResult>;

package/dist/tools/payroll.js

@@ -0,0 +1,27 @@
+import { extractApiData, maskToolPayload, paginationParams, withToolHandler, } from './shared.js';
+export async function handlePayroll(client, input) {
+    return withToolHandler(async () => {
+        const params = paginationParams(input.page, input.limit);
+        if (input.status)
+            params.status = input.status;
+        if (input.action === 'list_periods') {
+            const raw = await client.get('api-v1-payroll/periods', params);
+            return maskToolPayload(extractApiData(raw), input.mask_pii, input.action);
+        }
+        if (input.action === 'get_run') {
+            const raw = await client.get('api-v1-payroll/runs', params);
+            let data = extractApiData(raw);
+            if (input.period_id && Array.isArray(data)) {
+                data = data.filter((row) => {
+                    if (!row || typeof row !== 'object')
+                        return false;
+                    const record = row;
+                    return record.id === input.period_id || record.payroll_period_id === input.period_id;
+                });
+            }
+            return maskToolPayload(data, input.mask_pii, input.action);
+        }
+        const raw = await client.get('api-v1-payroll/payslips', params);
+        return maskToolPayload(extractApiData(raw), input.mask_pii, input.action);
+    });
+}

package/dist/tools/reports.d.ts

@@ -0,0 +1,9 @@
+import type { CalyburClient } from '../client.js';
+import { type ToolTextResult } from './shared.js';
+export type ReportsAction = 'payroll_summary' | 'statutory_metadata';
+export interface ReportsInput {
+    action: ReportsAction;
+    period_id: string;
+    mask_pii?: boolean;
+}
+export declare function handleReports(client: CalyburClient, input: ReportsInput): Promise<ToolTextResult>;

package/dist/tools/reports.js

@@ -0,0 +1,11 @@
+import { extractApiData, maskToolPayload, withToolHandler, } from './shared.js';
+export async function handleReports(client, input) {
+    return withToolHandler(async () => {
+        if (!input.period_id) {
+            throw new Error('period_id is required for report actions');
+        }
+        const suffix = input.action === 'payroll_summary' ? 'summary' : 'statutory';
+        const raw = await client.get(`api-v1-payroll/reports/${input.period_id}/${suffix}`);
+        return maskToolPayload(extractApiData(raw), input.mask_pii, input.action);
+    });
+}

package/dist/tools/shared.d.ts

@@ -0,0 +1,16 @@
+export type ToolTextResult = {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+    isError?: boolean;
+};
+export declare function okResult(payload: unknown): ToolTextResult;
+export declare function errResult(message: string): ToolTextResult;
+export declare function withToolHandler(fn: () => Promise<unknown>): Promise<ToolTextResult>;
+export declare function extractApiData(body: unknown): unknown;
+export declare function paginationParams(page?: number, limit?: number): Record<string, string>;
+export declare function maskToolPayload(data: unknown, maskPii: boolean | undefined, action: string): {
+    action: string;
+    data: unknown;
+};

package/dist/tools/shared.js

@@ -0,0 +1,40 @@
+import { CalyburApiError, formatApiError } from '../errors.js';
+import { maybeMask } from '../pii-mask.js';
+export function okResult(payload) {
+    return { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+}
+export function errResult(message) {
+    return { content: [{ type: 'text', text: message }], isError: true };
+}
+export async function withToolHandler(fn) {
+    try {
+        return okResult(await fn());
+    }
+    catch (error) {
+        const message = error instanceof CalyburApiError ? formatApiError(error) : String(error);
+        return errResult(message);
+    }
+}
+export function extractApiData(body) {
+    if (!body || typeof body !== 'object')
+        return body;
+    const record = body;
+    if ('data' in record)
+        return record.data;
+    if ('employees' in record)
+        return record.employees;
+    return body;
+}
+export function paginationParams(page, limit) {
+    const params = {
+        page: String(page ?? 1),
+        limit: String(limit ?? 20),
+    };
+    return params;
+}
+export function maskToolPayload(data, maskPii, action) {
+    return {
+        action,
+        data: maybeMask(data, maskPii !== false),
+    };
+}

package/dist/tools/status.d.ts

@@ -0,0 +1,3 @@
+import type { CalyburClient } from '../client.js';
+import { type ToolTextResult } from './shared.js';
+export declare function handleStatus(client: CalyburClient): Promise<ToolTextResult>;

package/dist/tools/status.js

@@ -0,0 +1,12 @@
+import { CalyburApiError, formatApiError } from '../errors.js';
+import { okResult, errResult } from './shared.js';
+export async function handleStatus(client) {
+    try {
+        await client.get('api-v1-employees', { limit: '1', page: '1' });
+        return okResult({ ok: true, ...client.statusSnapshot() });
+    }
+    catch (error) {
+        const message = error instanceof CalyburApiError ? formatApiError(error) : String(error);
+        return errResult(JSON.stringify({ ok: false, error: message }, null, 2));
+    }
+}

package/dist/tools/workforce.d.ts

@@ -0,0 +1,11 @@
+import type { CalyburClient } from '../client.js';
+import { type ToolTextResult } from './shared.js';
+export type WorkforceAction = 'list_employees' | 'get_employee' | 'list_departments' | 'list_positions' | 'list_work_locations';
+export interface WorkforceInput {
+    action: WorkforceAction;
+    employee_id?: string;
+    page?: number;
+    limit?: number;
+    mask_pii?: boolean;
+}
+export declare function handleWorkforce(client: CalyburClient, input: WorkforceInput): Promise<ToolTextResult>;

package/dist/tools/workforce.js

@@ -0,0 +1,21 @@
+import { extractApiData, maskToolPayload, paginationParams, withToolHandler, } from './shared.js';
+const FUNCTION_MAP = {
+    list_employees: 'api-v1-employees',
+    list_departments: 'api-v1-departments',
+    list_positions: 'api-v1-positions',
+    list_work_locations: 'api-v1-work-locations',
+};
+export async function handleWorkforce(client, input) {
+    return withToolHandler(async () => {
+        const params = paginationParams(input.page, input.limit);
+        if (input.action === 'get_employee') {
+            if (!input.employee_id) {
+                throw new Error('employee_id is required for get_employee');
+            }
+            const raw = await client.get(`api-v1-employees/${input.employee_id}`);
+            return maskToolPayload(extractApiData(raw), input.mask_pii, input.action);
+        }
+        const raw = await client.get(FUNCTION_MAP[input.action], params);
+        return maskToolPayload(extractApiData(raw), input.mask_pii, input.action);
+    });
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@calybur/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Calybur payroll and HR Partner API",
+  "type": "module",
+  "license": "MIT",
+  "author": "Calybur",
+  "homepage": "https://www.calybur.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CreaiTechnology/ezgaji-payroll.git",
+    "directory": "packages/calybur-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/CreaiTechnology/ezgaji-payroll/issues"
+  },
+  "keywords": [
+    "mcp",
+    "calybur",
+    "payroll",
+    "hrms",
+    "malaysia",
+    "model-context-protocol"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "calybur-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run test && npm run build",
+    "pack:dry": "npm run build && npm pack --dry-run"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
+  }
+}