@t4dhg/mcp-factorial 3.2.0 → 5.0.0

package/dist/index.js

@@ -21,6 +21,7 @@ loadEnv();
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import * as z from 'zod';
+import { cache } from './cache.js';
 import { 
 // Employees - Read
 listEmployees, getEmployee, searchEmployees, 
@@ -65,6 +66,7 @@ createJobPosting, updateJobPosting, deleteJobPosting, createCandidate, updateCan
 // Payroll (Read-only)
 listPayrollSupplements, getPayrollSupplement, listTaxIdentifiers, getTaxIdentifier, listFamilySituations, getFamilySituation, } from './api.js';
 import { formatPaginationInfo } from './pagination.js';
+import { wrapHighRiskToolHandler, textResponse } from './tool-utils.js';
 const server = new McpServer({
     name: 'factorial-hr',
     version: '3.0.0',
@@ -272,36 +274,17 @@ server.registerTool('update_employee', {
 });
 server.registerTool('terminate_employee', {
     title: 'Terminate Employee',
-    description: 'Terminate an employee (soft delete). This is a high-risk operation that sets the termination date.',
+    description: 'Terminate an employee (soft delete). This is a HIGH-RISK operation that requires confirmation.',
     inputSchema: {
         id: z.number().describe('The employee ID to terminate'),
         terminated_on: z.string().describe('Termination date (YYYY-MM-DD)'),
         reason: z.string().max(500).optional().describe('Termination reason'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this high-risk operation'),
     },
-}, async ({ id, terminated_on, reason }) => {
-    try {
-        const employee = await terminateEmployee(id, terminated_on, reason);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Employee terminated successfully. Termination date: ${terminated_on}\n\n${JSON.stringify(employee, null, 2)}`,
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('terminate_employee', async ({ id, terminated_on, reason }) => {
+    const employee = await terminateEmployee(id, terminated_on, reason);
+    return textResponse(`Employee terminated successfully. Termination date: ${terminated_on}\n\n${JSON.stringify(employee, null, 2)}`);
+}));
 // ============================================================================
 // Team Tools
 // ============================================================================
@@ -441,34 +424,15 @@ server.registerTool('update_team', {
 });
 server.registerTool('delete_team', {
     title: 'Delete Team',
-    description: 'Delete a team. This is a high-risk operation.',
+    description: 'Delete a team. This is a HIGH-RISK operation that requires confirmation.',
     inputSchema: {
         id: z.number().describe('The team ID to delete'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this high-risk operation'),
     },
-}, async ({ id }) => {
-    try {
-        await deleteTeam(id);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Team ${id} deleted successfully.`,
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('delete_team', async ({ id }) => {
+    await deleteTeam(id);
+    return textResponse(`Team ${id} deleted successfully.`);
+}));
 // ============================================================================
 // Location Tools
 // ============================================================================
@@ -616,51 +580,41 @@ server.registerTool('update_location', {
 });
 server.registerTool('delete_location', {
     title: 'Delete Location',
-    description: 'Delete a location. This is a high-risk operation.',
+    description: 'Delete a location. This is a HIGH-RISK operation that requires confirmation.',
     inputSchema: {
         id: z.number().describe('The location ID to delete'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this high-risk operation'),
     },
-}, async ({ id }) => {
-    try {
-        await deleteLocation(id);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Location ${id} deleted successfully.`,
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('delete_location', async ({ id }) => {
+    await deleteLocation(id);
+    return textResponse(`Location ${id} deleted successfully.`);
+}));
 // ============================================================================
 // Contract Tools
 // ============================================================================
 server.registerTool('get_employee_contracts', {
     title: 'Get Employee Contracts',
-    description: 'Get contract versions for an employee, including job title and effective date.',
+    description: 'Get contract versions for an employee. Returns contract summary (id, employee_id, job_title, effective_on).',
     inputSchema: {
         employee_id: z.number().describe('The employee ID'),
+        page: z.number().optional().default(1).describe('Page number'),
+        limit: z.number().optional().default(20).describe('Items per page (max: 100, default: 20)'),
     },
-}, async ({ employee_id }) => {
+}, async ({ employee_id, page, limit }) => {
     try {
-        const result = await listContracts(employee_id);
+        const result = await listContracts(employee_id, { page, limit });
+        // Create summary format
+        const summary = result.data.map(c => ({
+            id: c.id,
+            employee_id: c.employee_id,
+            job_title: c.job_title,
+            effective_on: c.effective_on,
+        }));
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Found ${result.data.length} contracts:\n\n${JSON.stringify(result.data, null, 2)}`,
+                    text: `Found ${result.data.length} contracts for employee ${employee_id} (${formatPaginationInfo(result.meta)}):\n\n${JSON.stringify(summary, null, 2)}`,
                 },
             ],
         };
@@ -942,34 +896,15 @@ server.registerTool('update_leave', {
 });
 server.registerTool('cancel_leave', {
     title: 'Cancel Leave Request',
-    description: 'Cancel a leave request.',
+    description: 'Cancel a leave request. This operation requires confirmation.',
     inputSchema: {
         id: z.number().describe('The leave ID to cancel'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this operation'),
     },
-}, async ({ id }) => {
-    try {
-        await cancelLeave(id);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Leave request ${id} cancelled successfully.`,
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('cancel_leave', async ({ id }) => {
+    await cancelLeave(id);
+    return textResponse(`Leave request ${id} cancelled successfully.`);
+}));
 server.registerTool('approve_leave', {
     title: 'Approve Leave Request',
     description: 'Approve a pending leave request.',
@@ -1003,35 +938,16 @@ server.registerTool('approve_leave', {
 });
 server.registerTool('reject_leave', {
     title: 'Reject Leave Request',
-    description: 'Reject a pending leave request.',
+    description: 'Reject a pending leave request. This operation requires confirmation.',
     inputSchema: {
         id: z.number().describe('The leave ID to reject'),
         reason: z.string().max(500).optional().describe('Rejection reason'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this operation'),
     },
-}, async ({ id, reason }) => {
-    try {
-        const leave = await rejectLeave(id, reason ? { reason } : undefined);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Leave request rejected:\n\n${JSON.stringify(leave, null, 2)}`,
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('reject_leave', async ({ id, reason }) => {
+    const leave = await rejectLeave(id, reason ? { reason } : undefined);
+    return textResponse(`Leave request rejected:\n\n${JSON.stringify(leave, null, 2)}`);
+}));
 // ============================================================================
 // Attendance / Shift Tools
 // ============================================================================
@@ -1185,34 +1101,15 @@ server.registerTool('update_shift', {
 });
 server.registerTool('delete_shift', {
     title: 'Delete Shift',
-    description: 'Delete a shift record.',
+    description: 'Delete a shift record. This operation requires confirmation.',
     inputSchema: {
         id: z.number().describe('The shift ID to delete'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this operation'),
     },
-}, async ({ id }) => {
-    try {
-        await deleteShift(id);
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Shift ${id} deleted successfully.`,
-                },
-            ],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('delete_shift', async ({ id }) => {
+    await deleteShift(id);
+    return textResponse(`Shift ${id} deleted successfully.`);
+}));
 // ============================================================================
 // Document Tools (Read-Only)
 // ============================================================================
@@ -1348,20 +1245,30 @@ server.registerTool('get_document', {
 });
 server.registerTool('get_employee_documents', {
     title: 'Get Employee Documents',
-    description: 'Get all documents for a specific employee. Returns document metadata including file URLs.',
+    description: 'Get all documents for a specific employee. Returns document summary (id, name, folder_id, employee_id, author_id, mime_type, size_bytes). Use get_document for full details.',
     inputSchema: {
         employee_id: z.number().describe('The employee ID'),
         page: z.number().optional().default(1).describe('Page number'),
-        limit: z.number().optional().default(100).describe('Items per page (max: 100)'),
+        limit: z.number().optional().default(20).describe('Items per page (max: 100, default: 20)'),
     },
 }, async ({ employee_id, page, limit }) => {
     try {
         const result = await listDocuments({ employee_ids: [employee_id], page, limit });
+        // Create summary format aligned with list_documents tool
+        const summary = result.data.map(d => ({
+            id: d.id,
+            name: d.name,
+            folder_id: d.folder_id,
+            employee_id: d.employee_id,
+            author_id: d.author_id,
+            mime_type: d.mime_type,
+            size_bytes: d.size_bytes,
+        }));
         return {
             content: [
                 {
                     type: 'text',
-                    text: `Found ${result.data.length} documents for employee ${employee_id} (${formatPaginationInfo(result.meta)}):\n\n${JSON.stringify(result.data, null, 2)}`,
+                    text: `Found ${result.data.length} documents for employee ${employee_id} (${formatPaginationInfo(result.meta)}):\n\n${JSON.stringify(summary, null, 2)}`,
                 },
             ],
         };
@@ -1589,29 +1496,15 @@ server.registerTool('update_project', {
 });
 server.registerTool('delete_project', {
     title: 'Delete Project',
-    description: 'Delete a project. This is a high-risk operation.',
+    description: 'Delete a project. This is a HIGH-RISK operation that requires confirmation.',
     inputSchema: {
         id: z.number().describe('The project ID to delete'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this high-risk operation'),
     },
-}, async ({ id }) => {
-    try {
-        await deleteProject(id);
-        return {
-            content: [{ type: 'text', text: `Project ${id} deleted successfully.` }],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('delete_project', async ({ id }) => {
+    await deleteProject(id);
+    return textResponse(`Project ${id} deleted successfully.`);
+}));
 server.registerTool('list_project_tasks', {
     title: 'List Project Tasks',
     description: 'Get tasks for a project.',
@@ -2048,29 +1941,15 @@ server.registerTool('update_training', {
 });
 server.registerTool('delete_training', {
     title: 'Delete Training',
-    description: 'Delete a training program.',
+    description: 'Delete a training program. This is a HIGH-RISK operation that requires confirmation.',
     inputSchema: {
         id: z.number().describe('The training ID to delete'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this high-risk operation'),
     },
-}, async ({ id }) => {
-    try {
-        await deleteTraining(id);
-        return {
-            content: [{ type: 'text', text: `Training ${id} deleted successfully.` }],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('delete_training', async ({ id }) => {
+    await deleteTraining(id);
+    return textResponse(`Training ${id} deleted successfully.`);
+}));
 server.registerTool('list_training_sessions', {
     title: 'List Training Sessions',
     description: 'Get sessions for a training program.',
@@ -2575,29 +2454,15 @@ server.registerTool('update_job_posting', {
 });
 server.registerTool('delete_job_posting', {
     title: 'Delete Job Posting',
-    description: 'Delete a job posting.',
+    description: 'Delete a job posting. This is a HIGH-RISK operation that requires confirmation.',
     inputSchema: {
         id: z.number().describe('Job posting ID to delete'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this high-risk operation'),
     },
-}, async ({ id }) => {
-    try {
-        await deleteJobPosting(id);
-        return {
-            content: [{ type: 'text', text: `Job posting ${id} deleted successfully.` }],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('delete_job_posting', async ({ id }) => {
+    await deleteJobPosting(id);
+    return textResponse(`Job posting ${id} deleted successfully.`);
+}));
 server.registerTool('list_candidates', {
     title: 'List Candidates',
     description: 'Get all candidates.',
@@ -2721,29 +2586,15 @@ server.registerTool('update_candidate', {
 });
 server.registerTool('delete_candidate', {
     title: 'Delete Candidate',
-    description: 'Delete a candidate.',
+    description: 'Delete a candidate. This is a HIGH-RISK operation that requires confirmation.',
     inputSchema: {
         id: z.number().describe('Candidate ID to delete'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this high-risk operation'),
     },
-}, async ({ id }) => {
-    try {
-        await deleteCandidate(id);
-        return {
-            content: [{ type: 'text', text: `Candidate ${id} deleted successfully.` }],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('delete_candidate', async ({ id }) => {
+    await deleteCandidate(id);
+    return textResponse(`Candidate ${id} deleted successfully.`);
+}));
 server.registerTool('list_applications', {
     title: 'List Applications',
     description: 'Get job applications.',
@@ -2862,29 +2713,15 @@ server.registerTool('update_application', {
 });
 server.registerTool('delete_application', {
     title: 'Delete Application',
-    description: 'Delete a job application.',
+    description: 'Delete a job application. This is a HIGH-RISK operation that requires confirmation.',
     inputSchema: {
         id: z.number().describe('Application ID to delete'),
+        confirm: z.boolean().optional().describe('Set to true to confirm this high-risk operation'),
     },
-}, async ({ id }) => {
-    try {
-        await deleteApplication(id);
-        return {
-            content: [{ type: 'text', text: `Application ${id} deleted successfully.` }],
-        };
-    }
-    catch (error) {
-        return {
-            content: [
-                {
-                    type: 'text',
-                    text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}`,
-                },
-            ],
-            isError: true,
-        };
-    }
-});
+}, wrapHighRiskToolHandler('delete_application', async ({ id }) => {
+    await deleteApplication(id);
+    return textResponse(`Application ${id} deleted successfully.`);
+}));
 server.registerTool('advance_application', {
     title: 'Advance Application',
     description: 'Move an application to the next hiring stage.',
@@ -3532,6 +3369,18 @@ Please provide:
     };
 });
 // ============================================================================
+// Graceful Shutdown
+// ============================================================================
+/**
+ * Clean up resources on process termination
+ */
+function shutdown() {
+    cache.destroy();
+    process.exit(0);
+}
+process.on('SIGINT', shutdown);
+process.on('SIGTERM', shutdown);
+// ============================================================================
 // Start Server
 // ============================================================================
 async function main() {