@calybur/mcp 0.1.0 → 0.2.2

package/README.md

@@ -1,16 +1,23 @@
 # @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.
+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.
+
+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.
 
 ## Requirements
 
 - Node.js 20+
 - Calybur **Starter** plan or above
-- API key with `read` scope (create at **Settings → API Keys**)
+- API key with `read` scope — create at **Settings → API Keys** in Calybur
+- Optional MCP setup copy at **Settings → Integrations**
+
+## Setup in Calybur
 
-## Quick Start (Cursor)
+1. Create a Partner API key (`ezg_live_*`) with read scope.
+2. Open **Settings → Integrations** and copy the MCP config snippet, or use the example below.
+3. Paste the config into your MCP client (stdio transport).
 
-Add to `.cursor/mcp.json`:
+## Connect any MCP client
 
 ```json
 {
@@ -19,41 +26,49 @@ Add to `.cursor/mcp.json`:
       "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"
+        "CALYBUR_API_KEY": "ezg_live_your_key_here"
       }
     }
   }
 }
 ```
 
-Restart Cursor and enable the Calybur MCP tools.
+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.
 
 ## 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` |
+| `CALYBUR_API_BASE_URL` | No | Defaults to `https://api.calybur.com` |
+| `CALYBUR_SUPABASE_PUBLISHABLE_KEY` | No | Only if bypassing the gateway with a direct Supabase URL |
 
 ## 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 |
+| `calybur_workforce` | Query employees, departments, positions, and work locations from Calybur. |
+| `calybur_leave` | Query leave balances, requests, policies, and public holidays. |
+| `calybur_payroll` | Query payroll periods, run status, and payslips. |
+| `calybur_attendance` | Query attendance events and summaries. |
+| `calybur_commission` | Query commission rules and calculation results. |
+| `calybur_reports` | Fetch payroll summary or statutory export metadata for a period. |
+| `calybur_status` | Check API key validity and remaining MCP client rate budget. |
+| `calybur_docs` | Search bundled Calybur API and Malaysia statutory documentation. |
+
+### Actions by tool
+
+- **calybur_workforce**: list_employees, get_employee, list_departments, list_positions, list_work_locations
+- **calybur_leave**: list_balances, list_requests, list_policies, list_holidays
+- **calybur_payroll**: list_periods, get_run, list_payslips
+- **calybur_attendance**: list_events, list_summaries
+- **calybur_commission**: list_rules, list_calculations
+- **calybur_reports**: payroll_summary, statutory_metadata
+
+`calybur_status` and `calybur_docs` have dedicated input shapes (no `action` enum).
 
-## Example Prompts
+## Example prompts
 
 - "Use calybur_status to verify my API connection"
 - "List active employees with calybur_workforce"
@@ -66,10 +81,10 @@ cd packages/calybur-mcp
 npm install
 npm test
 npm run build
-CALYBUR_API_KEY=... CALYBUR_API_BASE_URL=... npm run dev
+CALYBUR_API_KEY=ezg_live_... npm run dev
 ```
 
-## Rate Limits
+## Rate limits
 
 | Plan | API limit | MCP client budget (90%) |
 |------|-----------|-------------------------|

package/dist/client.js

@@ -12,14 +12,17 @@ export class CalyburClient {
         }
         const query = new URLSearchParams(params).toString();
         const url = `${this.config.baseUrl}/${functionPath}${query ? `?${query}` : ''}`;
+        const headers = {
+            'x-api-key': this.config.apiKey,
+            Accept: 'application/json',
+        };
+        if (!this.config.gatewayMode) {
+            headers.apikey = this.config.publishableKey;
+            headers.Authorization = `Bearer ${this.config.publishableKey}`;
+        }
         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',
-            },
+            headers,
         });
         const body = await response.json().catch(() => ({}));
         if (!response.ok) {

package/dist/config.d.ts

@@ -1,9 +1,12 @@
 export type CalyburPlan = 'starter' | 'professional' | 'enterprise';
+export declare const DEFAULT_PARTNER_API_BASE_URL = "https://api.calybur.com";
 export interface CalyburConfig {
     apiKey: string;
     baseUrl: string;
     publishableKey: string;
     plan: CalyburPlan;
+    gatewayMode: boolean;
 }
+export declare function isGatewayBaseUrl(baseUrl: string): boolean;
 export declare function loadConfig(env?: NodeJS.ProcessEnv): CalyburConfig;
 export declare function defaultLimitForPlan(plan: CalyburPlan): number;

package/dist/config.js

@@ -1,27 +1,34 @@
+export const DEFAULT_PARTNER_API_BASE_URL = 'https://api.calybur.com';
 const VALID_PLANS = ['starter', 'professional', 'enterprise'];
+export function isGatewayBaseUrl(baseUrl) {
+    try {
+        return new URL(baseUrl).hostname === 'api.calybur.com';
+    }
+    catch {
+        return false;
+    }
+}
 export function loadConfig(env = process.env) {
     const apiKey = env.CALYBUR_API_KEY?.trim();
-    const baseUrl = env.CALYBUR_API_BASE_URL?.trim().replace(/\/$/, '');
+    const baseUrl = (env.CALYBUR_API_BASE_URL?.trim() || DEFAULT_PARTNER_API_BASE_URL).replace(/\/$/, '');
     const publishableKey = env.CALYBUR_SUPABASE_PUBLISHABLE_KEY?.trim() ||
         env.CALYBUR_SUPABASE_ANON_KEY?.trim() ||
         '';
     const planRaw = (env.CALYBUR_PLAN?.trim().toLowerCase() || 'starter');
+    const gatewayMode = isGatewayBaseUrl(baseUrl);
     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 (!gatewayMode && !publishableKey) {
+        throw new Error('CALYBUR_SUPABASE_PUBLISHABLE_KEY is required when using a direct Supabase API URL');
     }
     if (!VALID_PLANS.includes(planRaw)) {
         throw new Error(`CALYBUR_PLAN must be one of: ${VALID_PLANS.join(', ')}`);
     }
-    return { apiKey, baseUrl, publishableKey, plan: planRaw };
+    return { apiKey, baseUrl, publishableKey, plan: planRaw, gatewayMode };
 }
 export function defaultLimitForPlan(plan) {
     if (plan === 'enterprise')

package/dist/errors.js

@@ -12,7 +12,7 @@ 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 'Gateway misconfigured. Use https://api.calybur.com or set CALYBUR_SUPABASE_PUBLISHABLE_KEY for direct Supabase access.';
         }
         return 'API key invalid or expired. Regenerate at Calybur Settings → API Keys.';
     }

package/dist/index.js

@@ -5,6 +5,7 @@ import { z } from 'zod';
 import { CalyburClient } from './client.js';
 import { loadConfig } from './config.js';
 import { RateBudget } from './rate-budget.js';
+import { CALYBUR_MCP_SERVER_VERSION, CALYBUR_MCP_TOOLS_MANIFEST, } from './tools-manifest.js';
 import { handleAttendance } from './tools/attendance.js';
 import { handleCommission } from './tools/commission.js';
 import { handleDocs } from './tools/docs.js';
@@ -13,7 +14,7 @@ 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.
+const SERVER_INSTRUCTIONS = `Calybur MCP connects external MCP-compatible agents 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).
@@ -21,60 +22,73 @@ Guidelines:
 - 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.`;
+- Requires Starter+ plan and an API key with appropriate scopes from Calybur Settings → API Keys.
+- In-app AI Workspace inside Calybur does not use this MCP server.`;
 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)'),
 };
+function manifestEntry(name) {
+    const entry = CALYBUR_MCP_TOOLS_MANIFEST.find((tool) => tool.name === name);
+    if (!entry) {
+        throw new Error(`Missing MCP tool manifest entry: ${name}`);
+    }
+    return entry;
+}
+function actionsFor(name) {
+    const actions = manifestEntry(name).actions;
+    if (!actions?.length) {
+        throw new Error(`Tool ${name} has no actions in manifest`);
+    }
+    return [...actions];
+}
 export function createCalyburMcpServer(client) {
     const server = new McpServer({
         name: 'calybur',
-        version: '0.1.0',
+        version: CALYBUR_MCP_SERVER_VERSION,
     }, {
         instructions: SERVER_INSTRUCTIONS,
     });
-    server.registerTool('calybur_workforce', {
-        title: 'Calybur Workforce',
-        description: 'Query employees, departments, positions, and work locations from Calybur.',
+    const workforce = manifestEntry('calybur_workforce');
+    server.registerTool(workforce.name, {
+        title: workforce.title,
+        description: workforce.description,
         inputSchema: z.object({
-            action: z.enum([
-                'list_employees',
-                'get_employee',
-                'list_departments',
-                'list_positions',
-                'list_work_locations',
-            ]),
+            action: z.enum(actionsFor(workforce.name)),
             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.',
+    const leave = manifestEntry('calybur_leave');
+    server.registerTool(leave.name, {
+        title: leave.title,
+        description: leave.description,
         inputSchema: z.object({
-            action: z.enum(['list_balances', 'list_requests', 'list_policies', 'list_holidays']),
+            action: z.enum(actionsFor(leave.name)),
             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.',
+    const payroll = manifestEntry('calybur_payroll');
+    server.registerTool(payroll.name, {
+        title: payroll.title,
+        description: payroll.description,
         inputSchema: z.object({
-            action: z.enum(['list_periods', 'get_run', 'list_payslips']),
+            action: z.enum(actionsFor(payroll.name)),
             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.',
+    const attendance = manifestEntry('calybur_attendance');
+    server.registerTool(attendance.name, {
+        title: attendance.title,
+        description: attendance.description,
         inputSchema: z.object({
-            action: z.enum(['list_events', 'list_summaries']),
+            action: z.enum(actionsFor(attendance.name)),
             employee_id: z.string().uuid().optional(),
             status: z.string().optional(),
             from: z.string().optional().describe('YYYY-MM-DD'),
@@ -82,32 +96,36 @@ export function createCalyburMcpServer(client) {
             ...sharedPaginationSchema,
         }),
     }, async (input) => handleAttendance(client, input));
-    server.registerTool('calybur_commission', {
-        title: 'Calybur Commission',
-        description: 'Query commission rules and calculation results.',
+    const commission = manifestEntry('calybur_commission');
+    server.registerTool(commission.name, {
+        title: commission.title,
+        description: commission.description,
         inputSchema: z.object({
-            action: z.enum(['list_rules', 'list_calculations']),
+            action: z.enum(actionsFor(commission.name)),
             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.',
+    const reports = manifestEntry('calybur_reports');
+    server.registerTool(reports.name, {
+        title: reports.title,
+        description: reports.description,
         inputSchema: z.object({
-            action: z.enum(['payroll_summary', 'statutory_metadata']),
+            action: z.enum(actionsFor(reports.name)),
             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.',
+    const status = manifestEntry('calybur_status');
+    server.registerTool(status.name, {
+        title: status.title,
+        description: status.description,
         inputSchema: z.object({}),
     }, async () => handleStatus(client));
-    server.registerTool('calybur_docs', {
-        title: 'Calybur Docs',
-        description: 'Search bundled Calybur API and Malaysia statutory documentation.',
+    const docs = manifestEntry('calybur_docs');
+    server.registerTool(docs.name, {
+        title: docs.title,
+        description: docs.description,
         inputSchema: z.object({
             query: z.string().min(1),
         }),

package/dist/tools/docs.js

@@ -19,8 +19,9 @@ Create keys at Calybur Settings → API Keys.`,
     {
         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).`,
+        body: `Configure Cursor MCP with npx @calybur/mcp and env:
+CALYBUR_API_KEY (required). Optional: CALYBUR_PLAN (starter|professional|enterprise).
+Uses https://api.calybur.com gateway — no Supabase keys needed.`,
     },
     {
         title: 'Rate Limits',

package/dist/tools-manifest.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Single source of truth for external Calybur MCP tools (read-only MVP).
+ * Used by server registration, README validation, and product-surface drift checks.
+ */
+export declare const CALYBUR_MCP_SERVER_VERSION = "0.2.2";
+export declare const CALYBUR_MCP_PACKAGE_NAME = "@calybur/mcp@latest";
+export type CalyburMcpToolManifestEntry = {
+    name: string;
+    title: string;
+    description: string;
+    actions?: readonly string[];
+    readOnly: true;
+};
+export declare const CALYBUR_MCP_TOOLS_MANIFEST: readonly [{
+    readonly name: "calybur_workforce";
+    readonly title: "Calybur Workforce";
+    readonly description: "Query employees, departments, positions, and work locations from Calybur.";
+    readonly actions: readonly ["list_employees", "get_employee", "list_departments", "list_positions", "list_work_locations"];
+    readonly readOnly: true;
+}, {
+    readonly name: "calybur_leave";
+    readonly title: "Calybur Leave";
+    readonly description: "Query leave balances, requests, policies, and public holidays.";
+    readonly actions: readonly ["list_balances", "list_requests", "list_policies", "list_holidays"];
+    readonly readOnly: true;
+}, {
+    readonly name: "calybur_payroll";
+    readonly title: "Calybur Payroll";
+    readonly description: "Query payroll periods, run status, and payslips.";
+    readonly actions: readonly ["list_periods", "get_run", "list_payslips"];
+    readonly readOnly: true;
+}, {
+    readonly name: "calybur_attendance";
+    readonly title: "Calybur Attendance";
+    readonly description: "Query attendance events and summaries.";
+    readonly actions: readonly ["list_events", "list_summaries"];
+    readonly readOnly: true;
+}, {
+    readonly name: "calybur_commission";
+    readonly title: "Calybur Commission";
+    readonly description: "Query commission rules and calculation results.";
+    readonly actions: readonly ["list_rules", "list_calculations"];
+    readonly readOnly: true;
+}, {
+    readonly name: "calybur_reports";
+    readonly title: "Calybur Reports";
+    readonly description: "Fetch payroll summary or statutory export metadata for a period.";
+    readonly actions: readonly ["payroll_summary", "statutory_metadata"];
+    readonly readOnly: true;
+}, {
+    readonly name: "calybur_status";
+    readonly title: "Calybur Status";
+    readonly description: "Check API key validity and remaining MCP client rate budget.";
+    readonly readOnly: true;
+}, {
+    readonly name: "calybur_docs";
+    readonly title: "Calybur Docs";
+    readonly description: "Search bundled Calybur API and Malaysia statutory documentation.";
+    readonly readOnly: true;
+}];
+export declare const CALYBUR_MCP_TOOL_NAMES: ("calybur_workforce" | "calybur_leave" | "calybur_payroll" | "calybur_attendance" | "calybur_commission" | "calybur_reports" | "calybur_status" | "calybur_docs")[];
+export declare function formatToolsMarkdownTable(): string;
+export declare function formatActionsMarkdownList(): string;

package/dist/tools-manifest.js

@@ -0,0 +1,79 @@
+/**
+ * Single source of truth for external Calybur MCP tools (read-only MVP).
+ * Used by server registration, README validation, and product-surface drift checks.
+ */
+export const CALYBUR_MCP_SERVER_VERSION = '0.2.2';
+export const CALYBUR_MCP_PACKAGE_NAME = '@calybur/mcp@latest';
+export const CALYBUR_MCP_TOOLS_MANIFEST = [
+    {
+        name: 'calybur_workforce',
+        title: 'Calybur Workforce',
+        description: 'Query employees, departments, positions, and work locations from Calybur.',
+        actions: [
+            'list_employees',
+            'get_employee',
+            'list_departments',
+            'list_positions',
+            'list_work_locations',
+        ],
+        readOnly: true,
+    },
+    {
+        name: 'calybur_leave',
+        title: 'Calybur Leave',
+        description: 'Query leave balances, requests, policies, and public holidays.',
+        actions: ['list_balances', 'list_requests', 'list_policies', 'list_holidays'],
+        readOnly: true,
+    },
+    {
+        name: 'calybur_payroll',
+        title: 'Calybur Payroll',
+        description: 'Query payroll periods, run status, and payslips.',
+        actions: ['list_periods', 'get_run', 'list_payslips'],
+        readOnly: true,
+    },
+    {
+        name: 'calybur_attendance',
+        title: 'Calybur Attendance',
+        description: 'Query attendance events and summaries.',
+        actions: ['list_events', 'list_summaries'],
+        readOnly: true,
+    },
+    {
+        name: 'calybur_commission',
+        title: 'Calybur Commission',
+        description: 'Query commission rules and calculation results.',
+        actions: ['list_rules', 'list_calculations'],
+        readOnly: true,
+    },
+    {
+        name: 'calybur_reports',
+        title: 'Calybur Reports',
+        description: 'Fetch payroll summary or statutory export metadata for a period.',
+        actions: ['payroll_summary', 'statutory_metadata'],
+        readOnly: true,
+    },
+    {
+        name: 'calybur_status',
+        title: 'Calybur Status',
+        description: 'Check API key validity and remaining MCP client rate budget.',
+        readOnly: true,
+    },
+    {
+        name: 'calybur_docs',
+        title: 'Calybur Docs',
+        description: 'Search bundled Calybur API and Malaysia statutory documentation.',
+        readOnly: true,
+    },
+];
+export const CALYBUR_MCP_TOOL_NAMES = CALYBUR_MCP_TOOLS_MANIFEST.map((tool) => tool.name);
+export function formatToolsMarkdownTable() {
+    const header = '| Tool | Purpose |\n|------|---------|';
+    const rows = CALYBUR_MCP_TOOLS_MANIFEST.map((tool) => `| \`${tool.name}\` | ${tool.description} |`);
+    return [header, ...rows].join('\n');
+}
+export function formatActionsMarkdownList() {
+    return CALYBUR_MCP_TOOLS_MANIFEST.flatMap((tool) => 'actions' in tool && tool.actions?.length
+        ? [`- **${tool.name}**: ${tool.actions.join(', ')}`]
+        : []).join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@calybur/mcp",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "MCP server for Calybur payroll and HR Partner API",
   "type": "module",
   "license": "MIT",
@@ -26,10 +26,13 @@
     "access": "public"
   },
   "bin": {
-    "calybur-mcp": "./dist/index.js"
+    "calybur-mcp": "dist/index.js"
   },
   "main": "./dist/index.js",
-  "files": ["dist", "README.md"],
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/index.ts",