@t4dhg/mcp-factorial 2.0.0 → 3.1.0

package/dist/write-safety.js

@@ -0,0 +1,239 @@
+/**
+ * Write operation safety and risk classification
+ *
+ * Provides risk levels and policies for write operations to help
+ * determine which operations require confirmation or special handling.
+ */
+/**
+ * Risk levels for write operations
+ */
+export var OperationRisk;
+(function (OperationRisk) {
+    /** Low risk - minor updates, safe to execute without confirmation */
+    OperationRisk["LOW"] = "low";
+    /** Medium risk - creates or significant updates, preview recommended */
+    OperationRisk["MEDIUM"] = "medium";
+    /** High risk - deletes, terminates, affects multiple records */
+    OperationRisk["HIGH"] = "high";
+    /** Critical risk - irreversible bulk operations, require explicit confirmation */
+    OperationRisk["CRITICAL"] = "critical";
+})(OperationRisk || (OperationRisk = {}));
+/**
+ * Default policies for write operations
+ */
+export const OPERATION_POLICIES = {
+    // Employee operations
+    create_employee: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Creates a new employee record in the system',
+    },
+    update_employee: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Updates employee information',
+    },
+    terminate_employee: {
+        risk: OperationRisk.HIGH,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Terminates employee, revoking access and removing from active lists',
+    },
+    // Team operations
+    create_team: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Creates a new team',
+    },
+    update_team: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Updates team information',
+    },
+    delete_team: {
+        risk: OperationRisk.HIGH,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Deletes the team and removes all member associations',
+    },
+    add_team_member: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: false,
+        impactDescription: 'Adds an employee to the team',
+    },
+    remove_team_member: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: false,
+        impactDescription: 'Removes an employee from the team',
+    },
+    // Location operations
+    create_location: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Creates a new office location',
+    },
+    update_location: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Updates location information',
+    },
+    delete_location: {
+        risk: OperationRisk.HIGH,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Deletes the location and removes employee associations',
+    },
+    // Leave operations
+    create_leave: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Creates a new leave request',
+    },
+    update_leave: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Updates leave request details',
+    },
+    cancel_leave: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Cancels the leave request',
+    },
+    approve_leave: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Approves the leave request, deducting from allowance',
+    },
+    reject_leave: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Rejects the leave request',
+    },
+    // Shift operations
+    create_shift: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: false,
+        impactDescription: 'Creates an attendance shift record',
+    },
+    update_shift: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: false,
+        impactDescription: 'Updates shift clock in/out times',
+    },
+    delete_shift: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Deletes the shift record',
+    },
+    // Document operations
+    upload_document: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Uploads a new document',
+    },
+    update_document: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: false,
+        impactDescription: 'Updates document metadata',
+    },
+    delete_document: {
+        risk: OperationRisk.HIGH,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Permanently deletes the document',
+    },
+    // Project operations
+    create_project: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Creates a new project',
+    },
+    update_project: {
+        risk: OperationRisk.LOW,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Updates project details',
+    },
+    delete_project: {
+        risk: OperationRisk.HIGH,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Deletes the project and all associated tasks/time records',
+    },
+    // ATS operations
+    create_job_posting: {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Creates a new job posting',
+    },
+    delete_job_posting: {
+        risk: OperationRisk.HIGH,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Deletes the job posting and all applications',
+    },
+    delete_candidate: {
+        risk: OperationRisk.HIGH,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Permanently deletes the candidate record',
+    },
+    // Training operations
+    delete_training: {
+        risk: OperationRisk.HIGH,
+        requiresConfirmation: true,
+        requiresPreview: true,
+        impactDescription: 'Deletes the training program and all enrollments',
+    },
+};
+/**
+ * Get the policy for an operation
+ */
+export function getOperationPolicy(operationName) {
+    return (OPERATION_POLICIES[operationName] ?? {
+        risk: OperationRisk.MEDIUM,
+        requiresConfirmation: false,
+        requiresPreview: true,
+        impactDescription: 'Modifies data in FactorialHR',
+    });
+}
+/**
+ * Check if an operation requires confirmation
+ */
+export function requiresConfirmation(operationName) {
+    return getOperationPolicy(operationName).requiresConfirmation;
+}
+/**
+ * Get a warning message for high-risk operations
+ */
+export function getWarningMessage(operationName) {
+    const policy = getOperationPolicy(operationName);
+    if (policy.risk === OperationRisk.HIGH || policy.risk === OperationRisk.CRITICAL) {
+        return (`**Warning:** This is a ${policy.risk}-risk operation. ${policy.impactDescription}. ` +
+            (policy.requiresConfirmation
+                ? 'Please confirm by setting `confirm: true`.'
+                : 'Please review carefully before proceeding.'));
+    }
+    return null;
+}
+//# sourceMappingURL=write-safety.js.map

package/dist/write-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-safety.js","sourceRoot":"","sources":["../src/write-safety.ts"],"names":[],"mappings":"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"}

package/llms.txt

@@ -0,0 +1,115 @@
+# MCP FactorialHR
+
+> The definitive Model Context Protocol server for FactorialHR
+
+## Overview
+
+MCP FactorialHR provides comprehensive access to FactorialHR data through the Model Context Protocol. It enables AI assistants like Claude to interact with your HR system for employees, teams, time off, attendance, projects, training, recruiting, and payroll.
+
+## Key Features
+
+- **80+ Tools**: Full CRUD operations for all major HR entities
+- **Safety Guardrails**: High-risk operations (terminate, delete) require confirmation
+- **Audit Logging**: All write operations are logged
+- **Read-only Payroll**: Payroll data is accessible but read-only for security
+- **Pagination**: All list operations support pagination
+- **Caching**: TTL-based caching for performance
+- **Validation**: Runtime validation with Zod schemas
+
+## Categories
+
+### Employees (6 tools)
+- list_employees, get_employee, search_employees
+- create_employee, update_employee, terminate_employee
+
+### Teams (5 tools)
+- list_teams, get_team
+- create_team, update_team, delete_team
+
+### Locations (5 tools)
+- list_locations, get_location
+- create_location, update_location, delete_location
+
+### Time Off (10 tools)
+- list_leaves, get_leave, list_leave_types, get_leave_type, list_allowances
+- create_leave, update_leave, cancel_leave, approve_leave, reject_leave
+
+### Attendance (5 tools)
+- list_shifts, get_shift
+- create_shift, update_shift, delete_shift
+
+### Projects (17 tools)
+- list_projects, get_project, create_project, update_project, delete_project
+- list_project_tasks, create_project_task, update_project_task, delete_project_task
+- list_project_workers, assign_project_worker, remove_project_worker
+- list_time_records, create_time_record, update_time_record, delete_time_record
+
+### Training (14 tools)
+- list_trainings, get_training, create_training, update_training, delete_training
+- list_training_sessions, create_training_session, update_training_session, delete_training_session
+- list_training_enrollments, enroll_in_training, unenroll_from_training
+
+### Work Areas (6 tools)
+- list_work_areas, get_work_area
+- create_work_area, update_work_area, archive_work_area, unarchive_work_area
+
+### ATS/Recruiting (16 tools)
+- list_job_postings, get_job_posting, create_job_posting, update_job_posting, delete_job_posting
+- list_candidates, get_candidate, create_candidate, update_candidate, delete_candidate
+- list_applications, get_application, create_application, update_application, delete_application
+- advance_application, list_hiring_stages
+
+### Payroll (6 tools, read-only)
+- list_payroll_supplements, get_payroll_supplement
+- list_tax_identifiers, get_tax_identifier
+- list_family_situations, get_family_situation
+
+### Documents (4 tools, read-only)
+- list_folders, get_folder, list_documents, get_document
+
+### Job Catalog (3 tools, read-only)
+- list_job_roles, get_job_role, list_job_levels
+
+### Contracts (1 tool, read-only)
+- get_employee_contracts
+
+## MCP Resources
+
+- factorial://org-chart - Organization hierarchy
+- factorial://employees/directory - Employee directory by team
+- factorial://locations/directory - Location directory
+- factorial://timeoff/policies - Leave types and policies
+- factorial://teams/{team_id} - Team details (templated)
+
+## MCP Prompts
+
+- onboard-employee - Generate onboarding checklists
+- analyze-org-structure - Analyze organizational structure
+- timeoff-report - Generate time off reports
+
+## Installation
+
+```json
+{
+  "mcpServers": {
+    "factorial": {
+      "command": "npx",
+      "args": ["-y", "@t4dhg/mcp-factorial"],
+      "env": {
+        "FACTORIAL_API_KEY": "your-api-key"
+      }
+    }
+  }
+}
+```
+
+## Links
+
+- npm: https://www.npmjs.com/package/@t4dhg/mcp-factorial
+- GitHub: https://github.com/t4dhg/mcp-factorial
+- FactorialHR API: https://apidoc.factorialhr.com/
+
+## Contact
+
+Author: Taig Mac Carthy
+Website: https://taigmaccarthy.com/

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@t4dhg/mcp-factorial",
-  "version": "2.0.0",
-  "description": "MCP server for FactorialHR - Access employee and organizational data from FactorialHR in Claude Code and other MCP clients",
+  "version": "3.1.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",
   "bin": {
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist/",
-    "README.md"
+    "README.md",
+    "llms.txt"
   ],
   "exports": {
     ".": {
@@ -47,13 +48,31 @@
   "keywords": [
     "mcp",
     "model-context-protocol",
+    "mcp-server",
     "factorial",
     "factorialhr",
+    "factorial-hr",
+    "hris",
     "hr",
+    "hrm",
+    "human-resources",
+    "employee-management",
+    "time-off",
+    "attendance",
+    "pto",
+    "recruiting",
+    "ats",
+    "applicant-tracking",
+    "training",
+    "projects",
+    "payroll",
     "claude",
+    "claude-code",
     "anthropic",
     "ai",
-    "llm"
+    "llm",
+    "ai-integration",
+    "enterprise"
   ],
   "author": "Taig Mac Carthy <https://taigmaccarthy.com/>",
   "license": "MIT",
@@ -71,6 +90,7 @@
     "zod": "^3.24.0"
   },
   "devDependencies": {
+    "@codecov/vite-plugin": "^1.9.1",
     "@eslint/js": "^9.17.0",
     "@types/node": "^22.10.0",
     "@vitest/coverage-v8": "^2.1.8",