@t4dhg/mcp-factorial 1.0.0 → 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Taig Mac Carthy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -5,6 +5,7 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 [![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
 [![Node.js](https://img.shields.io/badge/Node.js-18%2B-brightgreen.svg)](https://nodejs.org/)
+[![npm version](https://img.shields.io/npm/v/@t4dhg/mcp-factorial.svg)](https://www.npmjs.com/package/@t4dhg/mcp-factorial)
 
 A Model Context Protocol (MCP) server that provides AI assistants like Claude with secure, read-only access to your FactorialHR employee and organizational data. Built with privacy and security as core principles.
 
@@ -18,6 +19,7 @@ A Model Context Protocol (MCP) server that provides AI assistants like Claude wi
 ## Security by Design
 
 This MCP server intentionally **does NOT expose**:
+
 - Payroll and salary information
 - Bank account details
 - Tax documents
@@ -27,18 +29,59 @@ This MCP server intentionally **does NOT expose**:
 
 We believe AI assistants should help with organizational tasks without having access to your most sensitive HR data.
 
-## Available Tools
-
-| Tool | Description |
-|------|-------------|
-| `list_employees` | Get all employees with optional team/location filters |
-| `get_employee` | Get employee details (name, role, contact, team assignments) |
-| `search_employees` | Search employees by name or email |
-| `list_teams` | View organizational team structure |
-| `get_team` | Get team details and member list |
-| `list_locations` | Get company office locations |
-| `get_location` | Get location details (address, contact info) |
-| `get_employee_contracts` | View job titles and employment dates |
+## Features
+
+### 22 Tools
+
+| Category        | Tool                     | Description                                                      |
+| --------------- | ------------------------ | ---------------------------------------------------------------- |
+| **Employees**   | `list_employees`         | Get employees with optional team/location filters and pagination |
+|                 | `get_employee`           | Get detailed information about a specific employee               |
+|                 | `search_employees`       | Search employees by name or email                                |
+| **Teams**       | `list_teams`             | View organizational team structure                               |
+|                 | `get_team`               | Get team details and member list                                 |
+| **Locations**   | `list_locations`         | Get company office locations                                     |
+|                 | `get_location`           | Get location details (address, contact info)                     |
+| **Contracts**   | `get_employee_contracts` | View job titles and contract effective dates                     |
+| **Time Off**    | `list_leaves`            | List time off requests with filters                              |
+|                 | `get_leave`              | Get leave request details                                        |
+|                 | `list_leave_types`       | Get all leave types (vacation, sick, etc.)                       |
+|                 | `get_leave_type`         | Get leave type details                                           |
+|                 | `list_allowances`        | Get time off balances                                            |
+| **Attendance**  | `list_shifts`            | List employee shifts                                             |
+|                 | `get_shift`              | Get shift details                                                |
+| **Documents**   | `list_folders`           | List document folders                                            |
+|                 | `get_folder`             | Get folder details                                               |
+|                 | `list_documents`         | List documents                                                   |
+|                 | `get_document`           | Get document metadata                                            |
+| **Job Catalog** | `list_job_roles`         | List job roles                                                   |
+|                 | `get_job_role`           | Get job role details                                             |
+|                 | `list_job_levels`        | List job levels                                                  |
+
+### 5 MCP Resources
+
+| Resource URI                      | Description                                        |
+| --------------------------------- | -------------------------------------------------- |
+| `factorial://org-chart`           | Complete organizational hierarchy (Markdown)       |
+| `factorial://employees/directory` | Employee directory by team (Markdown)              |
+| `factorial://locations/directory` | Location directory with employee counts (Markdown) |
+| `factorial://timeoff/policies`    | All leave types and policies (JSON)                |
+| `factorial://teams/{team_id}`     | Team details with member list (JSON, templated)    |
+
+### 3 MCP Prompts
+
+| Prompt                  | Description                                                       |
+| ----------------------- | ----------------------------------------------------------------- |
+| `onboard-employee`      | Generate personalized onboarding checklists                       |
+| `analyze-org-structure` | Analyze org structure (reporting lines, team sizes, distribution) |
+| `timeoff-report`        | Generate time off reports by team or date range                   |
+
+### Architecture Features
+
+- **Caching**: In-memory TTL-based caching (configurable by resource type)
+- **Pagination**: All list operations support pagination
+- **Retry Logic**: Exponential backoff with rate limit handling
+- **Validation**: Runtime validation with Zod schemas
 
 ## Quick Start
 
@@ -83,10 +126,12 @@ Or pass it directly in the MCP config:
 
 Once configured, ask Claude things like:
 
-- *"Who's on the Engineering team?"*
-- *"Find the email for John Smith"*
-- *"What offices do we have?"*
-- *"Show me the org structure"*
+- _"Who's on the Engineering team?"_
+- _"Find the email for John Smith"_
+- _"What offices do we have?"_
+- _"Show me the org structure"_
+- _"How much PTO does employee 42 have left?"_
+- _"Generate an onboarding checklist for the new hire"_
 
 ## Getting an API Key
 
@@ -100,20 +145,33 @@ Once configured, ask Claude things like:
 ## Use Cases
 
 ### For Managers
+
 - Quickly look up team member contact information
 - Understand org chart and reporting structures
-- Find employees by skill or department
+- Monitor time off schedules for coverage planning
 
 ### For HR
+
 - Power AI-assisted employee directory searches
 - Streamline onboarding information lookups
-- Support with organizational queries
+- Generate time off reports and analyze patterns
 
 ### For Developers
+
 - Build AI workflows that need employee context
 - Create custom Claude integrations
 - Automate org-chart-aware processes
 
+## Configuration Options
+
+| Environment Variable    | Description              | Default      |
+| ----------------------- | ------------------------ | ------------ |
+| `FACTORIAL_API_KEY`     | Your FactorialHR API key | Required     |
+| `FACTORIAL_API_VERSION` | API version              | `2025-10-01` |
+| `FACTORIAL_TIMEOUT`     | Request timeout (ms)     | `30000`      |
+| `FACTORIAL_MAX_RETRIES` | Max retry attempts       | `3`          |
+| `DEBUG`                 | Enable debug logging     | `false`      |
+
 ## Development
 
 ```bash
@@ -127,6 +185,18 @@ npm install
 # Build
 npm run build
 
+# Run tests
+npm test
+
+# Run tests with coverage
+npm run test:coverage
+
+# Lint
+npm run lint
+
+# Format
+npm run format
+
 # Run locally
 FACTORIAL_API_KEY=your-key npm start
 
@@ -134,21 +204,50 @@ FACTORIAL_API_KEY=your-key npm start
 npx @modelcontextprotocol/inspector
 ```
 
-## Configuration Options
+## Troubleshooting
+
+### API Key Not Working
+
+- Ensure the API key has appropriate permissions
+- Check if the key has been revoked or expired
+- Verify the key is set correctly in environment variables
+
+### Rate Limiting
+
+The server implements exponential backoff for rate limits. If you're hitting limits frequently:
+
+- Reduce request frequency
+- Use pagination with smaller page sizes
+- Enable caching by avoiding cache-busting parameters
+
+### Missing Data
+
+- **`hired_on` field**: The FactorialHR API may not populate this for all employees
+- **Team membership**: Some employees may not be assigned to teams
+- **Empty responses**: Check if the resource exists in your Factorial account
+
+## FAQ
+
+**Q: Does this expose salary/payroll data?**
+A: No. This MCP server deliberately excludes all payroll, compensation, and financial data.
+
+**Q: Can Claude modify data in Factorial?**
+A: No. This is a read-only integration. No write operations are supported.
+
+**Q: How is data cached?**
+A: Data is cached in-memory with TTLs: employees (5 min), teams (10 min), locations (15 min), contracts (3 min).
 
-| Environment Variable | Description | Required |
-|---------------------|-------------|----------|
-| `FACTORIAL_API_KEY` | Your FactorialHR API key | Yes |
-| `DEBUG` | Enable debug logging (`true`/`false`) | No |
+**Q: What FactorialHR API version is used?**
+A: Version `2025-10-01` by default. Override with `FACTORIAL_API_VERSION` environment variable.
 
 ## Contributing
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
 
 ## License
 
-MIT © [t4dhg](https://github.com/t4dhg)
+MIT © [Taig Mac Carthy](https://taigmaccarthy.com/)
 
 ---
 
-*Built with the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic*
+_Built with the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic_

package/dist/api.d.ts

@@ -1,13 +1,109 @@
-import type { Employee, Team, Location, Contract } from './types.js';
-export declare function listEmployees(options?: {
-    team_id?: number;
-    location_id?: number;
-}): Promise<Employee[]>;
+/**
+ * FactorialHR API Client
+ *
+ * Provides access to FactorialHR API endpoints with caching, pagination, and retry logic.
+ */
+import { type PaginatedResponse, type PaginationInput } from './pagination.js';
+import { type Employee, type Team, type Location, type Contract, type Leave, type LeaveType, type Allowance, type Shift, type Folder, type Document, type JobRole, type JobLevel } from './schemas.js';
+import type { ListEmployeesOptions, ListLeavesOptions, ListAllowancesOptions, ListShiftsOptions, ListDocumentsOptions } from './types.js';
+/**
+ * List all employees with optional filtering and pagination
+ */
+export declare function listEmployees(options?: ListEmployeesOptions): Promise<PaginatedResponse<Employee>>;
+/**
+ * Get a specific employee by ID
+ */
 export declare function getEmployee(id: number): Promise<Employee>;
+/**
+ * Search employees by name or email
+ */
 export declare function searchEmployees(query: string): Promise<Employee[]>;
-export declare function listTeams(): Promise<Team[]>;
+/**
+ * List all teams
+ */
+export declare function listTeams(options?: PaginationInput): Promise<PaginatedResponse<Team>>;
+/**
+ * Get a specific team by ID
+ */
 export declare function getTeam(id: number): Promise<Team>;
-export declare function listLocations(): Promise<Location[]>;
+/**
+ * List all locations
+ */
+export declare function listLocations(options?: PaginationInput): Promise<PaginatedResponse<Location>>;
+/**
+ * Get a specific location by ID
+ */
 export declare function getLocation(id: number): Promise<Location>;
-export declare function listContracts(employeeId?: number): Promise<Contract[]>;
+/**
+ * List contracts, optionally filtered by employee ID
+ */
+export declare function listContracts(employeeId?: number, options?: PaginationInput): Promise<PaginatedResponse<Contract>>;
+/**
+ * List leaves with optional filtering
+ */
+export declare function listLeaves(options?: ListLeavesOptions): Promise<PaginatedResponse<Leave>>;
+/**
+ * Get a specific leave by ID
+ */
+export declare function getLeave(id: number): Promise<Leave>;
+/**
+ * List all leave types
+ */
+export declare function listLeaveTypes(): Promise<LeaveType[]>;
+/**
+ * Get a specific leave type by ID
+ */
+export declare function getLeaveType(id: number): Promise<LeaveType>;
+/**
+ * List allowances with optional filtering by employee
+ */
+export declare function listAllowances(options?: ListAllowancesOptions): Promise<PaginatedResponse<Allowance>>;
+/**
+ * List shifts with optional filtering
+ */
+export declare function listShifts(options?: ListShiftsOptions): Promise<PaginatedResponse<Shift>>;
+/**
+ * Get a specific shift by ID
+ */
+export declare function getShift(id: number): Promise<Shift>;
+/**
+ * List all folders
+ */
+export declare function listFolders(): Promise<Folder[]>;
+/**
+ * Get a specific folder by ID
+ */
+export declare function getFolder(id: number): Promise<Folder>;
+/**
+ * List documents with optional filtering by folder
+ */
+export declare function listDocuments(options?: ListDocumentsOptions): Promise<PaginatedResponse<Document>>;
+/**
+ * Get a specific document by ID
+ */
+export declare function getDocument(id: number): Promise<Document>;
+/**
+ * List all job roles
+ */
+export declare function listJobRoles(): Promise<JobRole[]>;
+/**
+ * Get a specific job role by ID
+ */
+export declare function getJobRole(id: number): Promise<JobRole>;
+/**
+ * List all job levels
+ */
+export declare function listJobLevels(): Promise<JobLevel[]>;
+/**
+ * Get a specific job level by ID
+ */
+export declare function getJobLevel(id: number): Promise<JobLevel>;
+/**
+ * Invalidate all cached data
+ */
+export declare function clearCache(): void;
+/**
+ * Invalidate cached data for a specific resource type
+ */
+export declare function invalidateCache(resourceType: string): void;
 //# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAmGrE,wBAAsB,aAAa,CAAC,OAAO,CAAC,EAAE;IAC5C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAGtB;AAED,wBAAsB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAM/D;AAED,wBAAsB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAcxE;AAGD,wBAAsB,SAAS,IAAI,OAAO,CAAC,IAAI,EAAE,CAAC,CAGjD;AAED,wBAAsB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAMvD;AAGD,wBAAsB,aAAa,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC,CAGzD;AAED,wBAAsB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAM/D;AAGD,wBAAsB,aAAa,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC,CAO5E"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"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"}