@mindstone-engineering/mcp-server-humaans 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Humaans authentication module.
+ *
+ * Manages the API key lifecycle — env var on startup, runtime update via
+ * configure tool, and bridge integration for host-app credential management.
+ */
+/**
+ * Returns the current API key.
+ */
+export declare function getApiKey(): string;
+/**
+ * Returns true if an API key is configured.
+ */
+export declare function isConfigured(): boolean;
+/**
+ * Update the API key at runtime (e.g. after configure_humaans_api_key).
+ */
+export declare function setApiKey(key: string): void;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,26 @@
+/**
+ * Humaans authentication module.
+ *
+ * Manages the API key lifecycle — env var on startup, runtime update via
+ * configure tool, and bridge integration for host-app credential management.
+ */
+let apiKey = process.env.HUMAANS_API_KEY || '';
+/**
+ * Returns the current API key.
+ */
+export function getApiKey() {
+    return apiKey;
+}
+/**
+ * Returns true if an API key is configured.
+ */
+export function isConfigured() {
+    return apiKey.length > 0;
+}
+/**
+ * Update the API key at runtime (e.g. after configure_humaans_api_key).
+ */
+export function setApiKey(key) {
+    apiKey = key;
+}
+//# sourceMappingURL=auth.js.map

package/dist/bridge.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export declare const BRIDGE_STATE_PATH: string;
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export declare const bridgeRequest: (urlPath: string, body: Record<string, unknown>) => Promise<{
+    success: boolean;
+    warning?: string;
+    error?: string;
+}>;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.js

@@ -0,0 +1,43 @@
+import * as fs from 'fs';
+import { REQUEST_TIMEOUT_MS } from './types.js';
+/**
+ * Path to bridge state file, supporting both current and legacy env vars.
+ */
+export const BRIDGE_STATE_PATH = process.env.MCP_HOST_BRIDGE_STATE || process.env.MINDSTONE_REBEL_BRIDGE_STATE || '';
+const loadBridgeState = () => {
+    if (!BRIDGE_STATE_PATH)
+        return null;
+    try {
+        const raw = fs.readFileSync(BRIDGE_STATE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+};
+/**
+ * Send a request to the host app bridge.
+ *
+ * The bridge is an HTTP server running inside the host app (e.g. Rebel)
+ * that handles credential management and other cross-process operations.
+ */
+export const bridgeRequest = async (urlPath, body) => {
+    const bridge = loadBridgeState();
+    if (!bridge) {
+        return { success: false, error: 'Bridge not available' };
+    }
+    const response = await fetch(`http://127.0.0.1:${bridge.port}${urlPath}`, {
+        method: 'POST',
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${bridge.token}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (response.status === 401 || response.status === 403) {
+        return { success: false, error: `Bridge returned ${response.status}: unauthorized. Check host app authentication.` };
+    }
+    return response.json();
+};
+//# sourceMappingURL=bridge.js.map

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Humaans API HTTP client.
+ *
+ * Centralises Bearer auth header injection, error handling, rate-limit
+ * messaging, and timeout handling for all Humaans API calls.
+ */
+/**
+ * Make an authenticated request to the Humaans API.
+ *
+ * @param path  API path relative to base, e.g. `/people`
+ * @param options  Additional fetch options
+ * @returns Parsed JSON response
+ */
+export declare function humaansFetch<T>(path: string, options?: RequestInit): Promise<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,79 @@
+/**
+ * Humaans API HTTP client.
+ *
+ * Centralises Bearer auth header injection, error handling, rate-limit
+ * messaging, and timeout handling for all Humaans API calls.
+ */
+import { getApiKey } from './auth.js';
+import { HumaansError, HUMAANS_API_BASE, REQUEST_TIMEOUT_MS, } from './types.js';
+/**
+ * Format a Humaans API error response into a human-readable message.
+ */
+function formatApiError(error) {
+    let msg = `${error.name} (${error.code}): ${error.message}`;
+    if (error.issues && error.issues.length > 0) {
+        const issueLines = error.issues.map((i) => `  - ${i.name}: ${i.reason}${i.forbidden ? ' (insufficient permissions)' : ''}`);
+        msg += '\n' + issueLines.join('\n');
+    }
+    return msg;
+}
+/**
+ * Make an authenticated request to the Humaans API.
+ *
+ * @param path  API path relative to base, e.g. `/people`
+ * @param options  Additional fetch options
+ * @returns Parsed JSON response
+ */
+export async function humaansFetch(path, options = {}) {
+    const key = getApiKey();
+    if (!key) {
+        throw new HumaansError('Humaans API key not configured', 'AUTH_REQUIRED', 'Use configure_humaans_api_key to set your API key first.');
+    }
+    const url = `${HUMAANS_API_BASE}${path}`;
+    const headers = {
+        Authorization: `Bearer ${key}`,
+        'Content-Type': 'application/json',
+        ...options.headers,
+    };
+    let response;
+    try {
+        response = await fetch(url, {
+            ...options,
+            signal: options.signal ?? AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers,
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new HumaansError('Request to Humaans API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the Humaans API is available.');
+        }
+        throw error;
+    }
+    if (response.status === 401 || response.status === 403) {
+        throw new HumaansError('Authentication failed', 'AUTH_FAILED', 'Your Humaans API token is invalid or lacks required scopes. Use configure_humaans_api_key to set a new token.');
+    }
+    if (response.status === 429) {
+        const retryAfter = response.headers.get('Retry-After');
+        const waitTime = retryAfter ? `${retryAfter} seconds` : 'a moment';
+        throw new HumaansError(`Rate limited by Humaans API. Please wait ${waitTime} before retrying.`, 'RATE_LIMITED', `Wait ${waitTime} and try again.`);
+    }
+    if (response.status === 404) {
+        throw new HumaansError('Resource not found', 'NOT_FOUND', 'The requested resource does not exist or you do not have permission to access it.');
+    }
+    if (!response.ok) {
+        let errorBody;
+        try {
+            errorBody = (await response.json());
+        }
+        catch {
+            // Response may not be JSON
+        }
+        if (errorBody) {
+            throw new HumaansError(formatApiError(errorBody), 'API_ERROR', 'Check the request parameters and try again.');
+        }
+        const errorText = await response.text().catch(() => 'Unknown error');
+        throw new HumaansError(`Humaans API error (${response.status}): ${errorText}`, 'API_ERROR', 'Check the request parameters and try again.');
+    }
+    return response.json();
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * Humaans MCP Server
+ *
+ * Provides Humaans HR platform integration via Model Context Protocol.
+ * Covers core HR data: people, job roles, locations, company, time away.
+ *
+ * Environment variables:
+ * - HUMAANS_API_KEY: User's Humaans API access token
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+/**
+ * Humaans MCP Server
+ *
+ * Provides Humaans HR platform integration via Model Context Protocol.
+ * Covers core HR data: people, job roles, locations, company, time away.
+ *
+ * Environment variables:
+ * - HUMAANS_API_KEY: User's Humaans API access token
+ * - MCP_HOST_BRIDGE_STATE: Path to host app bridge state file (optional)
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path (optional)
+ */
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createServer } from './server.js';
+async function main() {
+    const server = createServer();
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Humaans MCP server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): McpServer;
+//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,15 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerPeopleTools, registerJobRoleTools, registerCompanyTools, registerTimeAwayTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'humaans-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerPeopleTools(server);
+    registerJobRoleTools(server);
+    registerCompanyTools(server);
+    registerTimeAwayTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/company.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerCompanyTools(server: McpServer): void;
+//# sourceMappingURL=company.d.ts.map

package/dist/tools/company.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { humaansFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function paginationHint(total, skip, count) {
+    if (count >= total)
+        return `Showing all ${total} results.`;
+    const remaining = total - skip - count;
+    return `Showing ${count} of ${total} total (skip=${skip}). ${remaining > 0 ? `Use skip=${skip + count} to see more.` : ''}`;
+}
+function noApiKeyError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Humaans API key not configured',
+        resolution: 'Use configure_humaans_api_key to set your API key first.',
+    });
+}
+export function registerCompanyTools(server) {
+    server.registerTool('list_humaans_locations', {
+        description: `List company locations/offices from Humaans.
+
+Returns: label, city, country, timezone for each office location.
+Note: Remote employees have locationId="remote" with remoteCity/remoteCountry fields on their person profile.
+
+Example: {}`,
+        inputSchema: z.object({
+            limit: z.number().min(1).max(250).optional()
+                .describe('Max results (default 100, max 250)'),
+            skip: z.number().min(0).optional()
+                .describe('Number of results to skip'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const limit = Math.min(Math.max(args.limit ?? 100, 1), 250);
+        const skip = Math.max(args.skip ?? 0, 0);
+        const params = new URLSearchParams();
+        params.set('$limit', String(limit));
+        params.set('$skip', String(skip));
+        const result = await humaansFetch(`/locations?${params.toString()}`);
+        const hint = paginationHint(result.total, result.skip, result.data.length);
+        return JSON.stringify({
+            ok: true,
+            locations: result.data,
+            count: result.data.length,
+            total: result.total,
+            pagination: hint,
+        });
+    }));
+    server.registerTool('get_humaans_company', {
+        description: `Get company information from Humaans.
+
+Returns: company name, status, trial info, timesheet settings.
+
+Example: {}`,
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const result = await humaansFetch('/companies');
+        if (result.data.length === 0) {
+            return JSON.stringify({ ok: false, error: 'No company found.' });
+        }
+        return JSON.stringify({ ok: true, company: result.data[0] });
+    }));
+}
+//# sourceMappingURL=company.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerConfigureTools(server: McpServer): void;
+//# sourceMappingURL=configure.d.ts.map

package/dist/tools/configure.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+import { setApiKey } from '../auth.js';
+import { bridgeRequest, BRIDGE_STATE_PATH } from '../bridge.js';
+import { HumaansError } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_humaans_api_key', {
+        description: 'Configure the Humaans API access token. Call this when the user provides their token. ' +
+            'Get a token from https://app.humaans.io/settings/home?tokens=1 — ' +
+            'click "Generate new token", name it (e.g., "Rebel"), select scopes: public:read, private:read, private:write.',
+        inputSchema: z.object({
+            api_key: z.string().min(1).describe('The Humaans API access token'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const trimmedKey = args.api_key.trim();
+        // If bridge is available, persist via bridge
+        if (BRIDGE_STATE_PATH) {
+            try {
+                const result = await bridgeRequest('/bundled/humaans/configure', { apiKey: trimmedKey });
+                if (result.success) {
+                    setApiKey(trimmedKey);
+                    const message = result.warning
+                        ? `Humaans API key configured successfully. Note: ${result.warning}`
+                        : 'Humaans API key configured successfully! You can now use list_humaans_people to browse your team.';
+                    return JSON.stringify({ ok: true, message });
+                }
+                // Bridge returned failure — surface as error, do NOT fall through
+                throw new HumaansError(result.error || 'Bridge configuration failed', 'BRIDGE_ERROR', 'The host app bridge rejected the configuration request. Check the host app logs.');
+            }
+            catch (error) {
+                if (error instanceof HumaansError)
+                    throw error;
+                // Bridge request failed (network, timeout, etc.) — surface as error
+                throw new HumaansError(`Bridge request failed: ${error instanceof Error ? error.message : String(error)}`, 'BRIDGE_ERROR', 'Could not reach the host app bridge. Ensure the host app is running.');
+            }
+        }
+        // No bridge configured — configure in-memory only
+        setApiKey(trimmedKey);
+        return JSON.stringify({
+            ok: true,
+            message: 'Humaans API key configured successfully! You can now use list_humaans_people to browse your team.',
+        });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,6 @@
+export { registerConfigureTools } from './configure.js';
+export { registerPeopleTools } from './people.js';
+export { registerJobRoleTools } from './job-roles.js';
+export { registerCompanyTools } from './company.js';
+export { registerTimeAwayTools } from './time-away.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,6 @@
+export { registerConfigureTools } from './configure.js';
+export { registerPeopleTools } from './people.js';
+export { registerJobRoleTools } from './job-roles.js';
+export { registerCompanyTools } from './company.js';
+export { registerTimeAwayTools } from './time-away.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/job-roles.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerJobRoleTools(server: McpServer): void;
+//# sourceMappingURL=job-roles.d.ts.map

package/dist/tools/job-roles.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { humaansFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function paginationHint(total, skip, count) {
+    if (count >= total)
+        return `Showing all ${total} results.`;
+    const remaining = total - skip - count;
+    return `Showing ${count} of ${total} total (skip=${skip}). ${remaining > 0 ? `Use skip=${skip + count} to see more.` : ''}`;
+}
+function noApiKeyError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Humaans API key not configured',
+        resolution: 'Use configure_humaans_api_key to set your API key first.',
+    });
+}
+export function registerJobRoleTools(server) {
+    server.registerTool('list_humaans_job_roles', {
+        description: `List job role history for employees in Humaans.
+
+Each person can have multiple job roles over time. The role with the most recent
+effectiveDate that is not in the future is the current active role.
+
+Use the asOf parameter to find what role someone had at a specific date.
+
+Example: { "personId": "VMB1yzL5uL8VvNNCJc9rykJz" }
+
+RELATED TOOLS:
+- list_humaans_people: Find personId to filter by`,
+        inputSchema: z.object({
+            personId: z.string().optional()
+                .describe('Filter by person ID (from list_humaans_people)'),
+            asOf: z.string().optional()
+                .describe('Find the role in effect on this date (YYYY-MM-DD format)'),
+            limit: z.number().min(1).max(250).optional()
+                .describe('Max results (default 100, max 250)'),
+            skip: z.number().min(0).optional()
+                .describe('Number of results to skip'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const limit = Math.min(Math.max(args.limit ?? 100, 1), 250);
+        const skip = Math.max(args.skip ?? 0, 0);
+        const params = new URLSearchParams();
+        params.set('$limit', String(limit));
+        params.set('$skip', String(skip));
+        if (args.personId)
+            params.set('personId', args.personId);
+        if (args.asOf)
+            params.set('$asOf', args.asOf);
+        const result = await humaansFetch(`/job-roles?${params.toString()}`);
+        const hint = paginationHint(result.total, result.skip, result.data.length);
+        return JSON.stringify({
+            ok: true,
+            jobRoles: result.data,
+            count: result.data.length,
+            total: result.total,
+            pagination: hint,
+        });
+    }));
+    server.registerTool('get_humaans_job_role', {
+        description: `Get a specific job role by ID from Humaans.
+
+Returns: job title, department, manager (reportingTo), effectiveDate, endDate, note.
+
+Example: { "jobRoleId": "hmA5GnUq9ojK86LLKKWbiuKG" }`,
+        inputSchema: z.object({
+            jobRoleId: z.string().min(1).describe('The job role ID (from list_humaans_job_roles)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const jobRole = await humaansFetch(`/job-roles/${encodeURIComponent(args.jobRoleId)}`);
+        return JSON.stringify({ ok: true, jobRole });
+    }));
+}
+//# sourceMappingURL=job-roles.js.map

package/dist/tools/people.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerPeopleTools(server: McpServer): void;
+//# sourceMappingURL=people.d.ts.map

package/dist/tools/people.js

@@ -0,0 +1,151 @@
+import { z } from 'zod';
+import { humaansFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+// Fields to include in compact person list responses (allowlist for security)
+const PERSON_LIST_FIELDS = [
+    'id', 'firstName', 'lastName', 'preferredName', 'email',
+    'status', 'contractType', 'teams', 'locationId',
+    'employmentStartDate', 'employmentEndDate', 'timezone',
+];
+// Fields to strip from full person responses (sensitive data)
+const PERSON_SENSITIVE_FIELDS = [
+    'calendarFeedToken', 'taxId', 'taxCode',
+    'personalEmail', 'personalPhoneNumber', 'formattedPersonalPhoneNumber',
+    'birthday', 'address', 'city', 'state', 'postcode', 'countryCode',
+    'profilePhoto', 'profilePhotoId',
+    'nationality', 'nationalities', 'gender',
+    'dietaryPreference', 'foodAllergies',
+];
+function compactPerson(person) {
+    const compact = {};
+    for (const field of PERSON_LIST_FIELDS) {
+        compact[field] = person[field];
+    }
+    // Include inline job role info if present
+    const jobRole = person.jobRole;
+    if (jobRole) {
+        compact.jobTitle = jobRole.jobTitle;
+        compact.department = jobRole.department;
+    }
+    return compact;
+}
+function sanitizePerson(person) {
+    const sanitized = { ...person };
+    for (const field of PERSON_SENSITIVE_FIELDS) {
+        delete sanitized[field];
+    }
+    return sanitized;
+}
+function paginationHint(total, skip, count) {
+    if (count >= total)
+        return `Showing all ${total} results.`;
+    const remaining = total - skip - count;
+    return `Showing ${count} of ${total} total (skip=${skip}). ${remaining > 0 ? `Use skip=${skip + count} to see more.` : ''}`;
+}
+function noApiKeyError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Humaans API key not configured',
+        resolution: 'To use Humaans, you need to configure an API access token first.',
+        next_step: {
+            action: 'Ask the user for their Humaans API token, then call configure_humaans_api_key',
+            tool_to_call: 'configure_humaans_api_key',
+            tool_parameters: { api_key: '<user_provided_token>' },
+            get_key_from: 'https://app.humaans.io/settings/home?tokens=1',
+        },
+    });
+}
+export function registerPeopleTools(server) {
+    server.registerTool('get_humaans_me', {
+        description: `Get the current authenticated user's profile from Humaans.
+
+Returns: name, email, job title, department, teams, location, status.
+Use this to get your own personId for other operations (e.g., creating time away).
+
+RELATED TOOLS:
+- create_humaans_time_away: Use the returned id as personId
+- list_humaans_time_away: Filter by your personId`,
+        inputSchema: z.object({}),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async () => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const me = await humaansFetch('/me');
+        return JSON.stringify({ ok: true, person: sanitizePerson(me) });
+    }));
+    server.registerTool('list_humaans_people', {
+        description: `List employees from Humaans HR.
+
+By default returns only active employees. Use status filter for other groups.
+Returns compact summaries: id, name, email, job title, department, teams, location, status.
+
+Example: { "status": "active", "team": "Engineering", "limit": 50 }
+
+Pagination: Returns up to 'limit' results (default 50, max 250). Use 'skip' for next page.
+
+RELATED TOOLS:
+- get_humaans_person: Pass an employee's id to get their full profile
+- list_humaans_job_roles: Pass personId to see job role history`,
+        inputSchema: z.object({
+            status: z.enum(['active', 'offboarded', 'newHire', 'all']).optional()
+                .describe('Filter by employment status. Default: active'),
+            email: z.string().optional()
+                .describe('Filter by exact work email address'),
+            team: z.string().optional()
+                .describe('Filter by team name (e.g., "Engineering", "Sales")'),
+            limit: z.number().min(1).max(250).optional()
+                .describe('Max results per page (default 50, max 250)'),
+            skip: z.number().min(0).optional()
+                .describe('Number of results to skip (for pagination)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const limit = Math.min(Math.max(args.limit ?? 50, 1), 250);
+        const skip = Math.max(args.skip ?? 0, 0);
+        const params = new URLSearchParams();
+        params.set('$limit', String(limit));
+        params.set('$skip', String(skip));
+        if (args.status)
+            params.set('status', args.status);
+        if (args.email)
+            params.set('email', args.email);
+        if (args.team)
+            params.set('teams', args.team);
+        const result = await humaansFetch(`/people?${params.toString()}`);
+        const people = result.data.map(compactPerson);
+        const hint = paginationHint(result.total, result.skip, people.length);
+        return JSON.stringify({
+            ok: true,
+            people,
+            count: people.length,
+            total: result.total,
+            pagination: hint,
+        });
+    }));
+    server.registerTool('get_humaans_person', {
+        description: `Get full employee profile from Humaans by their ID.
+
+Returns detailed profile including: name, email, job role, department, teams,
+location, employment dates, contract type, working days, manager, bio, social links.
+Sensitive fields (tax ID, personal email, home address) are redacted for privacy.
+
+Example: { "personId": "VMB1yzL5uL8VvNNCJc9rykJz" }
+
+WORKFLOW - To find a person:
+1. Call list_humaans_people to search (filter by email or team)
+2. Use the person's id from the results here`,
+        inputSchema: z.object({
+            personId: z.string().min(1).describe('The person ID (from list_humaans_people)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const person = await humaansFetch(`/people/${encodeURIComponent(args.personId)}`);
+        return JSON.stringify({ ok: true, person: sanitizePerson(person) });
+    }));
+}
+//# sourceMappingURL=people.js.map

package/dist/tools/time-away.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerTimeAwayTools(server: McpServer): void;
+//# sourceMappingURL=time-away.d.ts.map

package/dist/tools/time-away.js

@@ -0,0 +1,157 @@
+import { z } from 'zod';
+import { humaansFetch } from '../client.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+function paginationHint(total, skip, count) {
+    if (count >= total)
+        return `Showing all ${total} results.`;
+    const remaining = total - skip - count;
+    return `Showing ${count} of ${total} total (skip=${skip}). ${remaining > 0 ? `Use skip=${skip + count} to see more.` : ''}`;
+}
+function noApiKeyError() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Humaans API key not configured',
+        resolution: 'Use configure_humaans_api_key to set your API key first.',
+    });
+}
+export function registerTimeAwayTools(server) {
+    server.registerTool('list_humaans_time_away', {
+        description: `List time away (PTO, sick leave, etc.) entries from Humaans.
+
+Filter by person, date range, or approval status. Returns: dates, type, days count, approval status, notes.
+
+Example: { "personId": "VMB1yzL5uL8VvNNCJc9rykJz" }
+Example: { "startDateAfter": "2024-01-01", "startDateBefore": "2024-12-31" }
+
+RELATED TOOLS:
+- list_humaans_people: Find personId to filter by
+- list_humaans_time_away_types: See available time away types
+- create_humaans_time_away: Request new time away`,
+        inputSchema: z.object({
+            personId: z.string().optional()
+                .describe('Filter by person ID'),
+            startDateAfter: z.string().optional()
+                .describe('Only entries starting after this date (YYYY-MM-DD)'),
+            startDateBefore: z.string().optional()
+                .describe('Only entries starting before this date (YYYY-MM-DD)'),
+            requestStatus: z.enum(['pending', 'approved', 'declined']).optional()
+                .describe('Filter by approval status'),
+            limit: z.number().min(1).max(250).optional()
+                .describe('Max results (default 50, max 250)'),
+            skip: z.number().min(0).optional()
+                .describe('Number of results to skip'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const limit = Math.min(Math.max(args.limit ?? 50, 1), 250);
+        const skip = Math.max(args.skip ?? 0, 0);
+        const params = new URLSearchParams();
+        params.set('$limit', String(limit));
+        params.set('$skip', String(skip));
+        if (args.personId)
+            params.set('personId', args.personId);
+        if (args.requestStatus)
+            params.set('requestStatus', args.requestStatus);
+        if (args.startDateAfter)
+            params.set('startDate[$gte]', args.startDateAfter);
+        if (args.startDateBefore)
+            params.set('startDate[$lte]', args.startDateBefore);
+        const result = await humaansFetch(`/time-away?${params.toString()}`);
+        const hint = paginationHint(result.total, result.skip, result.data.length);
+        return JSON.stringify({
+            ok: true,
+            timeAway: result.data,
+            count: result.data.length,
+            total: result.total,
+            pagination: hint,
+        });
+    }));
+    server.registerTool('create_humaans_time_away', {
+        description: `Create a time away request in Humaans (PTO, sick leave, etc.).
+
+WORKFLOW - To request time off:
+1. Call get_humaans_me to get your personId
+2. Call list_humaans_time_away_types to find the timeAwayTypeId (e.g., "Paid time off")
+3. Call this tool with the details
+
+Dates must be in YYYY-MM-DD format. Use startPeriod/endPeriod for half days.
+
+COMMON MISTAKES:
+- Don't guess timeAwayTypeId - always get it from list_humaans_time_away_types first
+- Dates must be YYYY-MM-DD, not ISO datetime with time/timezone`,
+        inputSchema: z.object({
+            personId: z.string().min(1)
+                .describe('Person ID (from get_humaans_me or list_humaans_people)'),
+            startDate: z.string().min(1)
+                .describe('First day of time away (YYYY-MM-DD)'),
+            endDate: z.string().min(1)
+                .describe('Last day of time away (YYYY-MM-DD)'),
+            timeAwayTypeId: z.string().min(1)
+                .describe('Type ID (from list_humaans_time_away_types)'),
+            startPeriod: z.enum(['full', 'am', 'pm']).optional()
+                .describe('full (whole day), am (morning off), pm (afternoon off). Default: full'),
+            endPeriod: z.enum(['full', 'am']).optional()
+                .describe('full (whole day) or am (morning only). Default: full'),
+            note: z.string().optional()
+                .describe('Optional note (visible to employee, manager, admins)'),
+        }),
+        annotations: { readOnlyHint: false, destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const body = {
+            personId: args.personId,
+            startDate: args.startDate,
+            endDate: args.endDate,
+            timeAwayTypeId: args.timeAwayTypeId,
+        };
+        if (args.startPeriod)
+            body.startPeriod = args.startPeriod;
+        if (args.endPeriod)
+            body.endPeriod = args.endPeriod;
+        if (args.note)
+            body.note = args.note;
+        const created = await humaansFetch('/time-away', {
+            method: 'POST',
+            body: JSON.stringify(body),
+        });
+        return JSON.stringify({ ok: true, message: 'Time away request created.', timeAway: created });
+    }));
+    server.registerTool('list_humaans_time_away_types', {
+        description: `List available time away types in Humaans.
+
+Returns type names and IDs (e.g., "Paid time off", "Sick leave", "Working from home").
+You need the type ID to create a time away request.
+
+RELATED TOOLS:
+- create_humaans_time_away: Use the returned id as timeAwayTypeId`,
+        inputSchema: z.object({
+            limit: z.number().min(1).max(250).optional()
+                .describe('Max results (default 100, max 250)'),
+            skip: z.number().min(0).optional()
+                .describe('Number of results to skip'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return noApiKeyError();
+        const limit = Math.min(Math.max(args.limit ?? 100, 1), 250);
+        const skip = Math.max(args.skip ?? 0, 0);
+        const params = new URLSearchParams();
+        params.set('$limit', String(limit));
+        params.set('$skip', String(skip));
+        const result = await humaansFetch(`/time-away-types?${params.toString()}`);
+        const hint = paginationHint(result.total, result.skip, result.data.length);
+        return JSON.stringify({
+            ok: true,
+            timeAwayTypes: result.data,
+            count: result.data.length,
+            total: result.total,
+            pagination: hint,
+        });
+    }));
+}
+//# sourceMappingURL=time-away.js.map

package/dist/types.d.ts

@@ -0,0 +1,50 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare const HUMAANS_API_BASE = "https://app.humaans.io/api";
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class HumaansError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export interface HumaansListResponse<T> {
+    total: number;
+    limit: number;
+    skip: number;
+    data: T[];
+}
+export interface HumaansErrorResponse {
+    id?: string;
+    code: number;
+    name: string;
+    message: string;
+    issues?: Array<{
+        name: string;
+        reason: string;
+        forbidden?: boolean;
+    }>;
+}
+/**
+ * Compact person representation for list responses (allowlist for security).
+ */
+export interface PersonCompact {
+    id: string;
+    firstName: string;
+    lastName: string;
+    preferredName: string | null;
+    email: string;
+    status: string;
+    contractType: string | null;
+    teams: Array<{
+        name: string;
+    }>;
+    locationId: string | null;
+    jobTitle?: string;
+    department?: string;
+    employmentStartDate: string | null;
+    employmentEndDate: string | null;
+    timezone: string | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,13 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export const HUMAANS_API_BASE = 'https://app.humaans.io/api';
+export class HumaansError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'HumaansError';
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/utils.d.ts

@@ -0,0 +1,14 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+type ToolHandler<T> = (args: T, extra: unknown) => Promise<CallToolResult>;
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On HumaansError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export declare function withErrorHandling<T>(fn: (args: T, extra: unknown) => Promise<string>): ToolHandler<T>;
+export {};
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.js

@@ -0,0 +1,42 @@
+import { HumaansError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On HumaansError: returns a structured JSON error with code and resolution.
+ * - On unknown error: returns a generic error message.
+ *
+ * Secrets are never exposed in error messages.
+ */
+export function withErrorHandling(fn) {
+    return async (args, extra) => {
+        try {
+            const result = await fn(args, extra);
+            return { content: [{ type: 'text', text: result }] };
+        }
+        catch (error) {
+            if (error instanceof HumaansError) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                ok: false,
+                                error: error.message,
+                                code: error.code,
+                                resolution: error.resolution,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [{ type: 'text', text: JSON.stringify({ ok: false, error: errorMessage }) }],
+                isError: true,
+            };
+        }
+    };
+}
+//# sourceMappingURL=utils.js.map

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@mindstone-engineering/mcp-server-humaans",
+  "version": "0.1.0",
+  "description": "Humaans HR platform MCP server for Model Context Protocol hosts",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-humaans": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/humaans"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/humaans",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc && shx chmod +x dist/index.js",
+    "prepare": "npm run build",
+    "watch": "tsc --watch",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@mindstone-engineering/mcp-test-harness": "file:../../test-harness",
+    "@types/node": "^22",
+    "@vitest/coverage-v8": "^4.1.3",
+    "msw": "^2.13.2",
+    "shx": "^0.3.4",
+    "typescript": "^5.8.2",
+    "vitest": "^4.1.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}