@t4dhg/mcp-factorial 1.0.0

package/README.md

@@ -0,0 +1,154 @@
+# MCP FactorialHR
+
+> **Secure, privacy-focused access to FactorialHR data for AI assistants**
+
+[![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/)
+
+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.
+
+## 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 |
+| `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 |
+
+## Quick Start
+
+### 1. Add to your MCP configuration
+
+```json
+{
+  "mcpServers": {
+    "factorial": {
+      "command": "npx",
+      "args": ["-y", "@t4dhg/mcp-factorial"]
+    }
+  }
+}
+```
+
+### 2. Set your API key
+
+Create a `.env` file in your project root:
+
+```env
+FACTORIAL_API_KEY=your-api-key-here
+```
+
+Or pass it directly in the MCP config:
+
+```json
+{
+  "mcpServers": {
+    "factorial": {
+      "command": "npx",
+      "args": ["-y", "@t4dhg/mcp-factorial"],
+      "env": {
+        "FACTORIAL_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+### 3. Start using it!
+
+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"*
+
+## Getting an API Key
+
+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
+
+> **Important**: API keys have full access to FactorialHR and never expire. Store them securely 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
+
+### For HR
+- Power AI-assisted employee directory searches
+- Streamline onboarding information lookups
+- Support with organizational queries
+
+### For Developers
+- Build AI workflows that need employee context
+- Create custom Claude integrations
+- Automate org-chart-aware processes
+
+## Development
+
+```bash
+# Clone the repository
+git clone https://github.com/t4dhg/mcp-factorial.git
+cd mcp-factorial
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run locally
+FACTORIAL_API_KEY=your-key npm start
+
+# Test with MCP Inspector
+npx @modelcontextprotocol/inspector
+```
+
+## Configuration Options
+
+| Environment Variable | Description | Required |
+|---------------------|-------------|----------|
+| `FACTORIAL_API_KEY` | Your FactorialHR API key | Yes |
+| `DEBUG` | Enable debug logging (`true`/`false`) | No |
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+MIT © [t4dhg](https://github.com/t4dhg)
+
+---
+
+*Built with the [Model Context Protocol](https://modelcontextprotocol.io/) by Anthropic*

package/dist/api.d.ts

@@ -0,0 +1,13 @@
+import type { Employee, Team, Location, Contract } from './types.js';
+export declare function listEmployees(options?: {
+    team_id?: number;
+    location_id?: number;
+}): Promise<Employee[]>;
+export declare function getEmployee(id: number): Promise<Employee>;
+export declare function searchEmployees(query: string): Promise<Employee[]>;
+export declare function listTeams(): Promise<Team[]>;
+export declare function getTeam(id: number): Promise<Team>;
+export declare function listLocations(): Promise<Location[]>;
+export declare function getLocation(id: number): Promise<Location>;
+export declare function listContracts(employeeId?: number): Promise<Contract[]>;
+//# sourceMappingURL=api.d.ts.map

package/dist/api.d.ts.map

@@ -0,0 +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"}

package/dist/api.js

@@ -0,0 +1,136 @@
+// FactorialHR API Client
+const FACTORIAL_BASE_URL = 'https://api.factorialhr.com/api/2025-10-01/resources';
+const DEFAULT_TIMEOUT = 30000; // 30 seconds
+const DEBUG = process.env.DEBUG === 'true';
+function debug(message, data) {
+    if (DEBUG) {
+        const timestamp = new Date().toISOString();
+        if (data) {
+            console.error(`[${timestamp}] [mcp-factorial] ${message}`, JSON.stringify(data, null, 2));
+        }
+        else {
+            console.error(`[${timestamp}] [mcp-factorial] ${message}`);
+        }
+    }
+}
+function getApiKey() {
+    const apiKey = process.env.FACTORIAL_API_KEY;
+    if (!apiKey) {
+        throw new Error('FACTORIAL_API_KEY is not set. ' +
+            'Please add it to your .env file or pass it via the MCP configuration. ' +
+            'See https://github.com/t4dhg/mcp-factorial for setup instructions.');
+    }
+    return apiKey;
+}
+async function factorialFetch(endpoint, params) {
+    const url = new URL(`${FACTORIAL_BASE_URL}${endpoint}`);
+    if (params) {
+        Object.entries(params).forEach(([key, value]) => {
+            if (value !== undefined) {
+                url.searchParams.append(key, String(value));
+            }
+        });
+    }
+    debug(`Fetching: ${url.toString()}`);
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT);
+    try {
+        const response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                'x-api-key': getApiKey(),
+                'Accept': 'application/json',
+            },
+            signal: controller.signal,
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok) {
+            const errorText = await response.text();
+            debug(`API error (${response.status}):`, errorText);
+            // Provide user-friendly error messages
+            if (response.status === 401) {
+                throw new Error('Invalid API key. Please check your FACTORIAL_API_KEY.');
+            }
+            if (response.status === 403) {
+                throw new Error('Access denied. Your API key may not have permission for this operation.');
+            }
+            if (response.status === 404) {
+                throw new Error('Resource not found. The requested employee, team, or location may not exist.');
+            }
+            if (response.status === 429) {
+                throw new Error('Rate limit exceeded. Please wait a moment before trying again.');
+            }
+            throw new Error(`FactorialHR API error (${response.status}): ${errorText}`);
+        }
+        const data = await response.json();
+        debug('Response received', { endpoint, itemCount: Array.isArray(data) ? data.length : 1 });
+        return data;
+    }
+    catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof Error) {
+            if (error.name === 'AbortError') {
+                throw new Error(`Request timed out after ${DEFAULT_TIMEOUT / 1000} seconds. Please try again.`);
+            }
+            throw error;
+        }
+        throw new Error('An unexpected error occurred while fetching data from FactorialHR.');
+    }
+}
+// Employee endpoints
+export async function listEmployees(options) {
+    const data = await factorialFetch('/employees/employees', options);
+    return data.data || [];
+}
+export async function getEmployee(id) {
+    if (!id || id <= 0) {
+        throw new Error('Invalid employee ID. Please provide a positive number.');
+    }
+    const data = await factorialFetch(`/employees/employees/${id}`);
+    return data.data;
+}
+export async function searchEmployees(query) {
+    if (!query || query.trim().length < 2) {
+        throw new Error('Search query must be at least 2 characters long.');
+    }
+    const employees = await listEmployees();
+    const lowerQuery = query.toLowerCase().trim();
+    return employees.filter(emp => emp.full_name?.toLowerCase().includes(lowerQuery) ||
+        emp.email?.toLowerCase().includes(lowerQuery) ||
+        emp.first_name?.toLowerCase().includes(lowerQuery) ||
+        emp.last_name?.toLowerCase().includes(lowerQuery));
+}
+// Team endpoints
+export async function listTeams() {
+    const data = await factorialFetch('/teams/teams');
+    return data.data || [];
+}
+export async function getTeam(id) {
+    if (!id || id <= 0) {
+        throw new Error('Invalid team ID. Please provide a positive number.');
+    }
+    const data = await factorialFetch(`/teams/teams/${id}`);
+    return data.data;
+}
+// Location endpoints
+export async function listLocations() {
+    const data = await factorialFetch('/locations/locations');
+    return data.data || [];
+}
+export async function getLocation(id) {
+    if (!id || id <= 0) {
+        throw new Error('Invalid location ID. Please provide a positive number.');
+    }
+    const data = await factorialFetch(`/locations/locations/${id}`);
+    return data.data;
+}
+// Contract endpoints
+export async function listContracts(employeeId) {
+    if (employeeId !== undefined && employeeId <= 0) {
+        throw new Error('Invalid employee ID. Please provide a positive number.');
+    }
+    const params = employeeId ? { employee_id: employeeId } : undefined;
+    const data = await factorialFetch('/contracts/contract-versions', params);
+    return data.data || [];
+}
+//# sourceMappingURL=api.js.map

package/dist/api.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for FactorialHR
+ *
+ * Provides access to employee and organizational data from FactorialHR
+ * through the Model Context Protocol for use with Claude Code and other MCP clients.
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;;;GAKG"}

package/dist/index.js

@@ -0,0 +1,306 @@
+#!/usr/bin/env node
+/**
+ * MCP Server for FactorialHR
+ *
+ * Provides access to employee and organizational data from FactorialHR
+ * through the Model Context Protocol for use with Claude Code and other MCP clients.
+ */
+import { config } from 'dotenv';
+import { existsSync } from 'fs';
+import { join } from 'path';
+// Load environment variables from .env file
+// Priority: ENV_FILE_PATH > cwd/.env > home/.env
+function loadEnv() {
+    // 1. Check if explicit path provided
+    if (process.env.ENV_FILE_PATH && existsSync(process.env.ENV_FILE_PATH)) {
+        config({ path: process.env.ENV_FILE_PATH });
+        return;
+    }
+    // 2. Check current working directory
+    const cwdEnv = join(process.cwd(), '.env');
+    if (existsSync(cwdEnv)) {
+        config({ path: cwdEnv });
+        return;
+    }
+    // 3. Check home directory
+    const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+    const homeEnv = join(homeDir, '.env');
+    if (existsSync(homeEnv)) {
+        config({ path: homeEnv });
+        return;
+    }
+    // 4. Check common project locations
+    const commonPaths = [
+        join(homeDir, 'turborepo', '.env'),
+        join(homeDir, 'projects', '.env'),
+    ];
+    for (const envPath of commonPaths) {
+        if (existsSync(envPath)) {
+            config({ path: envPath });
+            return;
+        }
+    }
+    // Fall back to default dotenv behavior
+    config();
+}
+loadEnv();
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import * as z from 'zod';
+import { listEmployees, getEmployee, searchEmployees, listTeams, getTeam, listLocations, getLocation, listContracts, } from './api.js';
+const server = new McpServer({
+    name: 'factorial-hr',
+    version: '1.0.0',
+});
+// ============================================================================
+// Employee Tools
+// ============================================================================
+server.registerTool('list_employees', {
+    title: 'List Employees',
+    description: 'Get all employees from FactorialHR. Can filter by team or location.',
+    inputSchema: {
+        team_id: z.number().optional().describe('Filter by team ID'),
+        location_id: z.number().optional().describe('Filter by location ID'),
+    },
+}, async ({ team_id, location_id }) => {
+    try {
+        const employees = await listEmployees({ team_id, location_id });
+        const summary = employees.map(e => ({
+            id: e.id,
+            name: e.full_name,
+            email: e.email,
+            role: e.role,
+            team_ids: e.team_ids,
+            location_id: e.location_id,
+        }));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${employees.length} employees:\n\n${JSON.stringify(summary, null, 2)}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('get_employee', {
+    title: 'Get Employee',
+    description: 'Get detailed information about a specific employee by their ID.',
+    inputSchema: {
+        id: z.number().describe('The employee ID'),
+    },
+}, async ({ id }) => {
+    try {
+        const employee = await getEmployee(id);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(employee, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('search_employees', {
+    title: 'Search Employees',
+    description: 'Search for employees by name or email.',
+    inputSchema: {
+        query: z.string().describe('Search query (name or email)'),
+    },
+}, async ({ query }) => {
+    try {
+        const employees = await searchEmployees(query);
+        if (employees.length === 0) {
+            return {
+                content: [{ type: 'text', text: `No employees found matching "${query}"` }],
+            };
+        }
+        const summary = employees.map(e => ({
+            id: e.id,
+            name: e.full_name,
+            email: e.email,
+            role: e.role,
+        }));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${employees.length} employees matching "${query}":\n\n${JSON.stringify(summary, null, 2)}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// ============================================================================
+// Team Tools
+// ============================================================================
+server.registerTool('list_teams', {
+    title: 'List Teams',
+    description: 'Get all teams in the organization.',
+    inputSchema: {},
+}, async () => {
+    try {
+        const teams = await listTeams();
+        const summary = teams.map(t => ({
+            id: t.id,
+            name: t.name,
+            description: t.description,
+            employee_count: t.employee_ids?.length || 0,
+        }));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${teams.length} teams:\n\n${JSON.stringify(summary, null, 2)}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('get_team', {
+    title: 'Get Team',
+    description: 'Get detailed information about a specific team by its ID.',
+    inputSchema: {
+        id: z.number().describe('The team ID'),
+    },
+}, async ({ id }) => {
+    try {
+        const team = await getTeam(id);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(team, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// ============================================================================
+// Location Tools
+// ============================================================================
+server.registerTool('list_locations', {
+    title: 'List Locations',
+    description: 'Get all company locations.',
+    inputSchema: {},
+}, async () => {
+    try {
+        const locations = await listLocations();
+        const summary = locations.map(l => ({
+            id: l.id,
+            name: l.name,
+            city: l.city,
+            country: l.country,
+        }));
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${locations.length} locations:\n\n${JSON.stringify(summary, null, 2)}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+server.registerTool('get_location', {
+    title: 'Get Location',
+    description: 'Get detailed information about a specific location by its ID.',
+    inputSchema: {
+        id: z.number().describe('The location ID'),
+    },
+}, async ({ id }) => {
+    try {
+        const location = await getLocation(id);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(location, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// ============================================================================
+// Contract Tools
+// ============================================================================
+server.registerTool('get_employee_contracts', {
+    title: 'Get Employee Contracts',
+    description: 'Get contract versions for an employee, including job title and effective date.',
+    inputSchema: {
+        employee_id: z.number().describe('The employee ID'),
+    },
+}, async ({ employee_id }) => {
+    try {
+        const contracts = await listContracts(employee_id);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Found ${contracts.length} contracts:\n\n${JSON.stringify(contracts, null, 2)}`,
+                },
+            ],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: 'text', text: `Error: ${error instanceof Error ? error.message : 'Unknown error'}` }],
+            isError: true,
+        };
+    }
+});
+// ============================================================================
+// Start Server
+// ============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+export interface Employee {
+    id: number;
+    first_name: string;
+    last_name: string;
+    full_name: string;
+    email: string;
+    birthday_on: string | null;
+    terminated_on: string | null;
+    gender: string | null;
+    nationality: string | null;
+    manager_id: number | null;
+    role: string | null;
+    timeoff_manager_id: number | null;
+    company_id: number;
+    legal_entity_id: number | null;
+    team_ids: number[];
+    location_id: number | null;
+    created_at: string;
+    updated_at: string;
+}
+export interface Team {
+    id: number;
+    name: string;
+    description: string | null;
+    company_id: number;
+    employee_ids: number[];
+    lead_ids: number[];
+    created_at: string;
+    updated_at: string;
+}
+export interface Location {
+    id: number;
+    name: string;
+    country: string | null;
+    phone_number: string | null;
+    state: string | null;
+    city: string | null;
+    address_line_1: string | null;
+    address_line_2: string | null;
+    postal_code: string | null;
+    company_id: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface Contract {
+    id: number;
+    employee_id: number;
+    job_title: string | null;
+    effective_on: string;
+    created_at: string;
+    updated_at: string;
+}
+export interface ApiError {
+    error: string;
+    message: string;
+    status: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/types.js

@@ -0,0 +1,3 @@
+// FactorialHR API Response Types
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,iCAAiC"}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@t4dhg/mcp-factorial",
+  "version": "1.0.0",
+  "description": "MCP server for FactorialHR - Access employee and organizational data from FactorialHR in Claude Code and other MCP clients",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-factorial": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "factorial",
+    "factorialhr",
+    "hr",
+    "claude",
+    "anthropic"
+  ],
+  "author": "t4dhg",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/t4dhg/mcp-factorial.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.4.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}