@t4dhg/mcp-factorial 1.1.0 → 3.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

@@ -1,44 +1,68 @@
 # MCP FactorialHR
 
-> **Secure, privacy-focused access to FactorialHR data for AI assistants**
+> **The definitive Model Context Protocol server for FactorialHR**
 
 [![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.
+A comprehensive Model Context Protocol (MCP) server that provides AI assistants like Claude with full access to FactorialHR. Manage employees, teams, time off, projects, training, recruiting, and more - all with built-in safety guardrails.
 
 ## Why This MCP Server?
 
-- **Privacy-First Design**: Deliberately excludes payroll, compensation, and sensitive financial data. Your salary information stays private.
-- **Read-Only Access**: No write operations - Claude can view but never modify your HR data.
-- **Organizational Focus**: Optimized for team structure, employee directories, and location lookups - the data you actually need for AI-assisted workflows.
-- **Enterprise Ready**: Built for companies who need AI integration without compromising data security.
-
-## Security by Design
-
-This MCP server intentionally **does NOT expose**:
-- Payroll and salary information
-- Bank account details
-- Tax documents
-- Compensation packages
-- Benefits enrollment data
-- Personal identification numbers
-
-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. Returns name, email, role, manager, hire date, and more. |
-| `get_employee` | Get detailed information about a specific employee by ID |
-| `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 contract effective dates for an employee |
+- **Comprehensive Coverage**: 80+ tools spanning employees, teams, time off, attendance, projects, training, recruiting (ATS), and payroll
+- **Full CRUD Operations**: Create, read, update, and delete across all major entities
+- **Safety Guardrails**: High-risk operations require explicit confirmation
+- **Audit Logging**: All write operations are logged for compliance
+- **Enterprise Ready**: Built for companies who need AI integration with proper controls
+
+## Features
+
+### 80+ Tools
+
+| Category        | Tools | Operations                                                              |
+| --------------- | ----- | ----------------------------------------------------------------------- |
+| **Employees**   | 6     | List, get, search, create, update, terminate                            |
+| **Teams**       | 5     | List, get, create, update, delete                                       |
+| **Locations**   | 5     | List, get, create, update, delete                                       |
+| **Time Off**    | 10    | List leaves/types/allowances, create, update, cancel, approve, reject   |
+| **Attendance**  | 5     | List shifts, create, update, delete                                     |
+| **Projects**    | 17    | Full CRUD for projects, tasks, workers, time records                    |
+| **Training**    | 14    | Full CRUD for trainings, sessions, enrollments                          |
+| **Work Areas**  | 6     | List, get, create, update, archive, unarchive                           |
+| **ATS**         | 16    | Job postings, candidates, applications, hiring stages, advance workflow |
+| **Payroll**     | 6     | List/get supplements, tax identifiers, family situations (read-only)    |
+| **Documents**   | 4     | List/get folders and documents (read-only)                              |
+| **Job Catalog** | 3     | List/get job roles and levels (read-only)                               |
+| **Contracts**   | 1     | Get employee contract history (read-only)                               |
+
+### 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
+
+- **Safety Guardrails**: High-risk operations (terminate, delete) marked for confirmation
+- **Audit Logging**: All write operations logged with timestamps and context
+- **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,36 +107,91 @@ 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?"_
+- _"Create a new employee John Smith with email john@company.com"_
+- _"Approve the pending time off request for employee 42"_
+- _"Create a new project called Q1 Marketing Campaign"_
+- _"Enroll Sarah in the Leadership Training program"_
+- _"Show me all open job postings"_
+- _"What candidates applied for the Senior Developer position?"_
 
 ## Getting an API Key
 
+You'll need a FactorialHR API key to use this MCP server. Here's how to get one:
+
 1. Log in to [FactorialHR](https://app.factorialhr.com) as an administrator
-2. Navigate to **Settings → Integrations → API**
-3. Generate a new API key
-4. Add it to your `.env` file
+2. Go to [**Settings → API keys**](https://app.factorialhr.com/settings/api-keys)
+3. Click the **"New API key"** button
+4. Give your key a descriptive name (e.g., "Claude Code" or "MCP Server")
+5. Click **Create** - your API key will be displayed
+6. **Copy the key immediately** - it's only shown once and cannot be retrieved later
+7. Add the key to your `.env` file or MCP configuration
 
-> **Important**: API keys have full access to FactorialHR and never expire. Store them securely and rotate them periodically.
+> **Important**: API keys have full access to your FactorialHR data and never expire. Store them securely, never commit them to version control, and rotate them periodically.
 
 ## Use Cases
 
 ### For Managers
-- Quickly look up team member contact information
-- Understand org chart and reporting structures
-- Find employees by skill or department
+
+- Create and manage team structures
+- Approve or reject time off requests
+- Assign employees to projects
+- Track project time records
+- Monitor training enrollments
 
 ### For HR
-- Power AI-assisted employee directory searches
-- Streamline onboarding information lookups
-- Support with organizational queries
+
+- Onboard new employees with full data entry
+- Manage job postings and recruiting pipeline
+- Track candidate applications through hiring stages
+- Generate org structure analysis
+- Manage training programs and enrollments
 
 ### For Developers
+
 - Build AI workflows that need employee context
 - Create custom Claude integrations
-- Automate org-chart-aware processes
+- Automate HR processes with AI assistance
+- Generate reports and analytics
+
+## 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`      |
+
+## Safety & Security
+
+### High-Risk Operations
+
+The following operations are marked as high-risk and should be used with care:
+
+- `terminate_employee` - Terminates an employee (sets termination date)
+- `delete_team` - Permanently deletes a team
+- `delete_location` - Permanently deletes a location
+- `delete_project` - Permanently deletes a project
+- `delete_candidate` - Permanently deletes a candidate
+
+### Read-Only Categories
+
+Some categories are intentionally read-only for security:
+
+- **Payroll**: Supplements, tax identifiers, family situations
+- **Documents**: Folder and document metadata only
+- **Contracts**: Historical contract data
+
+### Audit Logging
+
+All write operations (create, update, delete, approve, reject) are logged with:
+
+- Timestamp
+- Operation type
+- Entity type and ID
+- Changes made
 
 ## Development
 
@@ -127,6 +206,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,27 +225,53 @@ 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: Payroll data (supplements, tax identifiers, family situations) is available read-only. No write operations for payroll are supported.
+
+**Q: Can Claude modify data in Factorial?**
+A: Yes! Full CRUD operations are available for employees, teams, locations, time off, projects, training, and recruiting. High-risk operations are clearly marked.
 
-| Environment Variable | Description | Required |
-|---------------------|-------------|----------|
-| `FACTORIAL_API_KEY` | Your FactorialHR API key | Yes |
-| `DEBUG` | Enable debug logging (`true`/`false`) | No |
+**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).
 
-## Known Limitations
+**Q: What FactorialHR API version is used?**
+A: Version `2025-10-01` by default. Override with `FACTORIAL_API_VERSION` environment variable.
 
-- **`hired_on` field**: The FactorialHR API may not populate the `hired_on` field for all employees. If you need hire dates, you may need to use contract effective dates as a proxy.
-- **Contract filtering**: The `get_employee_contracts` tool fetches all contracts and filters client-side, which may be slow for organizations with many employees.
-- **Employee IDs**: Higher employee IDs generally indicate more recent additions, but this is not guaranteed.
+**Q: Are write operations logged?**
+A: Yes, all write operations are logged via the audit module for compliance and debugging.
 
 ## 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_