@t4dhg/mcp-factorial 3.2.0 → 5.0.0

package/dist/tool-utils.js

@@ -0,0 +1,71 @@
+/**
+ * Tool utilities for MCP FactorialHR
+ *
+ * Provides helper functions for consistent tool handler implementation.
+ */
+import { getOperationPolicy, getWarningMessage } from './write-safety.js';
+/**
+ * Format an error into a consistent tool error response
+ */
+export function formatToolError(error) {
+    const message = error instanceof Error ? error.message : 'Unknown error';
+    return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+/**
+ * Create a successful text response
+ */
+export function textResponse(text) {
+    return {
+        content: [{ type: 'text', text }],
+    };
+}
+/**
+ * Wrap a tool handler with consistent error handling
+ *
+ * @param handler - The async handler function
+ * @returns A wrapped handler that catches errors and formats them consistently
+ */
+export function wrapToolHandler(handler) {
+    return async (args) => {
+        try {
+            return await handler(args);
+        }
+        catch (error) {
+            return formatToolError(error);
+        }
+    };
+}
+/**
+ * Wrap a high-risk tool handler with confirmation requirement
+ *
+ * @param operationName - The operation name (e.g., 'delete_team') for policy lookup
+ * @param handler - The async handler function
+ * @returns A wrapped handler that requires confirmation for high-risk operations
+ */
+export function wrapHighRiskToolHandler(operationName, handler) {
+    return wrapToolHandler(async (args) => {
+        const policy = getOperationPolicy(operationName);
+        if (policy.requiresConfirmation && !args.confirm) {
+            const warning = getWarningMessage(operationName);
+            return textResponse(`${warning}\n\nTo proceed, call this tool again with \`confirm: true\`.`);
+        }
+        return handler(args);
+    });
+}
+/**
+ * Format JSON data for display in a tool response
+ */
+export function formatJson(data, prefix) {
+    const json = JSON.stringify(data, null, 2);
+    return prefix ? `${prefix}\n\n${json}` : json;
+}
+/**
+ * Format a list result with pagination info
+ */
+export function formatListResult(items, entityName, paginationInfo) {
+    return `Found ${items.length} ${entityName}${items.length !== 1 ? 's' : ''} (${paginationInfo}):\n\n${JSON.stringify(items, null, 2)}`;
+}
+//# sourceMappingURL=tool-utils.js.map

package/dist/tool-utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-utils.js","sourceRoot":"","sources":["../src/tool-utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAmB1E;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,KAAc;IAC5C,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IACzE,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,OAAO,EAAE,EAAE,CAAC;QACtD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,OAAO;QACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;KAClC,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAyC;IAEzC,OAAO,KAAK,EAAE,IAAO,EAAE,EAAE;QACvB,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,OAAO,eAAe,CAAC,KAAK,CAAC,CAAC;QAChC,CAAC;IACH,CAAC,CAAC;AACJ,CAAC;AASD;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,aAAqB,EACrB,OAAyC;IAEzC,OAAO,eAAe,CAAC,KAAK,EAAE,IAAO,EAAE,EAAE;QACvC,MAAM,MAAM,GAAG,kBAAkB,CAAC,aAAa,CAAC,CAAC;QAEjD,IAAI,MAAM,CAAC,oBAAoB,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;YACjD,MAAM,OAAO,GAAG,iBAAiB,CAAC,aAAa,CAAC,CAAC;YACjD,OAAO,YAAY,CAAC,GAAG,OAAO,8DAA8D,CAAC,CAAC;QAChG,CAAC;QAED,OAAO,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa,EAAE,MAAe;IACvD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAC3C,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,OAAO,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAAgB,EAChB,UAAkB,EAClB,cAAsB;IAEtB,OAAO,SAAS,KAAK,CAAC,MAAM,IAAI,UAAU,GAAG,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,cAAc,SAAS,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC;AACzI,CAAC"}

package/dist/utils.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared utilities for MCP FactorialHR
+ *
+ * Provides common validation and helper functions used across the codebase.
+ */
+/**
+ * Validate that a value is a positive integer ID
+ *
+ * @param id - The value to validate
+ * @param resourceType - The type of resource for error messages (e.g., "employee", "team")
+ * @returns The validated ID as a number
+ * @throws Error if the ID is invalid
+ */
+export declare function validateId(id: unknown, resourceType: string): number;
+/**
+ * Validate that a value is a positive number
+ *
+ * @param value - The value to validate
+ * @param fieldName - The field name for error messages
+ * @returns The validated number
+ * @throws Error if the value is invalid
+ */
+export declare function validatePositiveNumber(value: unknown, fieldName: string): number;
+/**
+ * Validate that a value is a non-empty string
+ *
+ * @param value - The value to validate
+ * @param fieldName - The field name for error messages
+ * @returns The validated string
+ * @throws Error if the value is invalid
+ */
+export declare function validateNonEmptyString(value: unknown, fieldName: string): string;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,CAKpE;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKhF;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAKhF"}

package/dist/utils.js

@@ -0,0 +1,48 @@
+/**
+ * Shared utilities for MCP FactorialHR
+ *
+ * Provides common validation and helper functions used across the codebase.
+ */
+/**
+ * Validate that a value is a positive integer ID
+ *
+ * @param id - The value to validate
+ * @param resourceType - The type of resource for error messages (e.g., "employee", "team")
+ * @returns The validated ID as a number
+ * @throws Error if the ID is invalid
+ */
+export function validateId(id, resourceType) {
+    if (typeof id !== 'number' || !id || id <= 0 || !Number.isInteger(id)) {
+        throw new Error(`Invalid ${resourceType} ID. Please provide a positive integer.`);
+    }
+    return id;
+}
+/**
+ * Validate that a value is a positive number
+ *
+ * @param value - The value to validate
+ * @param fieldName - The field name for error messages
+ * @returns The validated number
+ * @throws Error if the value is invalid
+ */
+export function validatePositiveNumber(value, fieldName) {
+    if (typeof value !== 'number' || value <= 0) {
+        throw new Error(`Invalid ${fieldName}. Please provide a positive number.`);
+    }
+    return value;
+}
+/**
+ * Validate that a value is a non-empty string
+ *
+ * @param value - The value to validate
+ * @param fieldName - The field name for error messages
+ * @returns The validated string
+ * @throws Error if the value is invalid
+ */
+export function validateNonEmptyString(value, fieldName) {
+    if (typeof value !== 'string' || value.trim().length === 0) {
+        throw new Error(`Invalid ${fieldName}. Please provide a non-empty string.`);
+    }
+    return value.trim();
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,EAAW,EAAE,YAAoB;IAC1D,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CAAC,WAAW,YAAY,yCAAyC,CAAC,CAAC;IACpF,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc,EAAE,SAAiB;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QAC5C,MAAM,IAAI,KAAK,CAAC,WAAW,SAAS,qCAAqC,CAAC,CAAC;IAC7E,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,sBAAsB,CAAC,KAAc,EAAE,SAAiB;IACtE,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3D,MAAM,IAAI,KAAK,CAAC,WAAW,SAAS,sCAAsC,CAAC,CAAC;IAC9E,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,EAAE,CAAC;AACtB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t4dhg/mcp-factorial",
-  "version": "3.2.0",
+  "version": "5.0.0",
   "description": "The definitive MCP server for FactorialHR - Full CRUD operations for employees, teams, time off, projects, training, recruiting (ATS), and payroll. 80+ tools with safety guardrails.",
   "type": "module",
   "main": "dist/index.js",