@calybur/mcp 0.2.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
 {
@@ -26,7 +33,7 @@ Add to `.cursor/mcp.json`:
 }
 ```
 
-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
 
@@ -41,16 +48,27 @@ Restart Cursor and enable the Calybur MCP tools.
 
 | 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,7 +84,7 @@ npm run build
 CALYBUR_API_KEY=ezg_live_... npm run dev
 ```
 
-## Rate Limits
+## Rate limits
 
 | Plan | API limit | MCP client budget (90%) |
 |------|-----------|-------------------------|

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-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.2.0",
+  "version": "0.2.2",
   "description": "MCP server for Calybur payroll and HR Partner API",
   "type": "module",
   "license": "MIT",