@mindstone-engineering/mcp-server-workday 0.1.0

package/dist/auth.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Workday authentication module.
+ *
+ * OAuth2 dual grant type: client_credentials (default) + refresh_token (when available).
+ * Credentials managed via env vars or configured at runtime.
+ *
+ * Environment variables:
+ * - WORKDAY_HOST: Workday API domain (e.g., wd5-impl-services1.workday.com)
+ * - WORKDAY_TENANT: Customer's Workday tenant name
+ * - WORKDAY_CLIENT_ID: OAuth client ID
+ * - WORKDAY_CLIENT_SECRET: OAuth client secret
+ * - WORKDAY_REFRESH_TOKEN: Optional refresh token (enables refresh_token grant)
+ */
+export declare function getHost(): string;
+export declare function setHost(h: string): void;
+export declare function getTenant(): string;
+export declare function setTenant(t: string): void;
+export declare function getClientId(): string;
+export declare function setClientId(id: string): void;
+export declare function getClientSecret(): string;
+export declare function setClientSecret(s: string): void;
+export declare function getRefreshToken(): string;
+export declare function setRefreshToken(t: string): void;
+export declare function clearTokenCache(): void;
+export declare function isConfigured(): boolean;
+export declare function getTokenUrl(): string;
+export declare function getApiBaseUrl(): string;
+export declare function validateHost(rawHost: string): {
+    valid: boolean;
+    host?: string;
+    error?: string;
+};
+export declare function getAccessToken(): Promise<string>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.js

@@ -0,0 +1,181 @@
+/**
+ * Workday authentication module.
+ *
+ * OAuth2 dual grant type: client_credentials (default) + refresh_token (when available).
+ * Credentials managed via env vars or configured at runtime.
+ *
+ * Environment variables:
+ * - WORKDAY_HOST: Workday API domain (e.g., wd5-impl-services1.workday.com)
+ * - WORKDAY_TENANT: Customer's Workday tenant name
+ * - WORKDAY_CLIENT_ID: OAuth client ID
+ * - WORKDAY_CLIENT_SECRET: OAuth client secret
+ * - WORKDAY_REFRESH_TOKEN: Optional refresh token (enables refresh_token grant)
+ */
+import { WorkdayError, USER_AGENT, REQUEST_TIMEOUT_MS } from './types.js';
+import { bridgeRequest } from './bridge.js';
+// ── Runtime credentials ──
+let workdayHost = '';
+let workdayTenant = process.env.WORKDAY_TENANT ?? '';
+let clientId = process.env.WORKDAY_CLIENT_ID ?? '';
+let clientSecret = process.env.WORKDAY_CLIENT_SECRET ?? '';
+let refreshToken = process.env.WORKDAY_REFRESH_TOKEN ?? '';
+// Validate WORKDAY_HOST from env at startup — reject private/localhost hosts
+const _envHost = process.env.WORKDAY_HOST ?? '';
+if (_envHost) {
+    const _hostResult = validateHost(_envHost);
+    if (_hostResult.valid) {
+        workdayHost = _hostResult.host;
+    }
+    else {
+        console.error(`[Workday] Ignoring invalid WORKDAY_HOST from env: ${_hostResult.error}`);
+    }
+}
+// ── Token cache ──
+let cachedAccessToken = null;
+let tokenExpiresAt = 0;
+// ── Getters / setters ──
+export function getHost() {
+    return workdayHost;
+}
+export function setHost(h) {
+    workdayHost = h;
+}
+export function getTenant() {
+    return workdayTenant;
+}
+export function setTenant(t) {
+    workdayTenant = t;
+}
+export function getClientId() {
+    return clientId;
+}
+export function setClientId(id) {
+    clientId = id;
+}
+export function getClientSecret() {
+    return clientSecret;
+}
+export function setClientSecret(s) {
+    clientSecret = s;
+}
+export function getRefreshToken() {
+    return refreshToken;
+}
+export function setRefreshToken(t) {
+    refreshToken = t;
+}
+export function clearTokenCache() {
+    cachedAccessToken = null;
+    tokenExpiresAt = 0;
+}
+export function isConfigured() {
+    return !!(workdayHost && workdayTenant && clientId && clientSecret);
+}
+export function getTokenUrl() {
+    return `https://${workdayHost}/ccx/oauth2/${workdayTenant}/token`;
+}
+export function getApiBaseUrl() {
+    return `https://${workdayHost}/ccx/api/v1/${workdayTenant}`;
+}
+// ── SSRF / Host validation ──
+function normalizeHost(raw) {
+    let host = raw.trim();
+    host = host.replace(/^https?:\/\//i, '');
+    host = host.replace(/\/+$/, '');
+    return host;
+}
+function isPrivateOrLocalhost(host) {
+    const lower = host.toLowerCase();
+    if (lower === 'localhost' || lower === '[::1]') {
+        return true;
+    }
+    const ipMatch = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (ipMatch) {
+        const [, a, b] = ipMatch.map(Number);
+        if (a === 127)
+            return true;
+        if (a === 10)
+            return true;
+        if (a === 172 && b >= 16 && b <= 31)
+            return true;
+        if (a === 192 && b === 168)
+            return true;
+        if (a === 169 && b === 254)
+            return true;
+        if (a === 0)
+            return true;
+    }
+    return false;
+}
+export function validateHost(rawHost) {
+    const host = normalizeHost(rawHost);
+    if (!host || host.length === 0) {
+        return { valid: false, error: 'Host is required.' };
+    }
+    if (isPrivateOrLocalhost(host)) {
+        return { valid: false, error: 'Host must not be localhost or a private IP address.' };
+    }
+    if (host.length < 2 || !/^[a-zA-Z0-9][a-zA-Z0-9.-]*[a-zA-Z0-9]$/.test(host)) {
+        return { valid: false, error: 'Host must be a valid hostname.' };
+    }
+    return { valid: true, host };
+}
+// ── Token exchange ──
+export async function getAccessToken() {
+    if (!clientId || !clientSecret) {
+        throw new WorkdayError('Workday not configured. Call configure_workday_credentials first.', 'NOT_CONFIGURED', 'Configure Workday with your OAuth credentials first.');
+    }
+    if (cachedAccessToken && Date.now() < tokenExpiresAt) {
+        return cachedAccessToken;
+    }
+    const authHeader = 'Basic ' + Buffer.from(`${clientId}:${clientSecret}`).toString('base64');
+    const bodyParams = refreshToken
+        ? { grant_type: 'refresh_token', refresh_token: refreshToken }
+        : { grant_type: 'client_credentials' };
+    const body = new URLSearchParams(bodyParams);
+    let response;
+    try {
+        response = await fetch(getTokenUrl(), {
+            method: 'POST',
+            signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            headers: {
+                Authorization: authHeader,
+                'Content-Type': 'application/x-www-form-urlencoded',
+                Accept: 'application/json',
+                'User-Agent': USER_AGENT,
+            },
+            body: body.toString(),
+        });
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'TimeoutError') {
+            throw new WorkdayError('OAuth token request timed out', 'TIMEOUT', 'The request took too long. Check your Workday host and network connectivity.');
+        }
+        throw error;
+    }
+    if (!response.ok) {
+        let errorText;
+        try {
+            const errorBody = await response.json();
+            errorText = errorBody?.error_description || errorBody?.error || JSON.stringify(errorBody);
+        }
+        catch {
+            errorText = await response.text().catch(() => 'Unknown error');
+        }
+        throw new WorkdayError(`OAuth token exchange failed (${response.status}): ${errorText}`, 'AUTH_FAILED', 'Re-configure with configure_workday_credentials. Check client ID, secret, and tenant.');
+    }
+    const tokenData = await response.json();
+    cachedAccessToken = tokenData.access_token;
+    tokenExpiresAt = Date.now() + (tokenData.expires_in - 60) * 1000;
+    // Handle refresh token rotation
+    if (tokenData.refresh_token && tokenData.refresh_token !== refreshToken) {
+        refreshToken = tokenData.refresh_token;
+        bridgeRequest('/bundled/workday/update-refresh-token', {
+            refreshToken: tokenData.refresh_token,
+        }).catch((err) => {
+            console.error('Failed to persist rotated refresh token:', err instanceof Error ? err.message : String(err));
+        });
+    }
+    return cachedAccessToken;
+}
+//# 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,14 @@
+/**
+ * Workday API HTTP client.
+ *
+ * Centralises Bearer auth injection, error handling,
+ * rate-limit retry with exponential backoff, and timeout handling.
+ *
+ * Auth: OAuth2 Bearer token via getAccessToken()
+ * Base URL: https://{host}/ccx/api/v1/{tenant}
+ */
+/**
+ * Make an authenticated JSON request to the Workday REST API.
+ */
+export declare function workdayFetch<T>(resourcePath: string, options?: RequestInit, retryCount?: number): Promise<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.js

@@ -0,0 +1,81 @@
+/**
+ * Workday API HTTP client.
+ *
+ * Centralises Bearer auth injection, error handling,
+ * rate-limit retry with exponential backoff, and timeout handling.
+ *
+ * Auth: OAuth2 Bearer token via getAccessToken()
+ * Base URL: https://{host}/ccx/api/v1/{tenant}
+ */
+import { WorkdayError, USER_AGENT, REQUEST_TIMEOUT_MS } from './types.js';
+import { getAccessToken, getApiBaseUrl, isConfigured, clearTokenCache } from './auth.js';
+/**
+ * Make an authenticated JSON request to the Workday REST API.
+ */
+export async function workdayFetch(resourcePath, options = {}, retryCount = 0) {
+    if (!isConfigured()) {
+        throw new WorkdayError('Workday not configured. Call configure_workday_credentials first.', 'NOT_CONFIGURED', 'Configure Workday with your OAuth credentials first.');
+    }
+    const accessToken = await getAccessToken();
+    const url = `${getApiBaseUrl()}${resourcePath}`;
+    const headers = {
+        Authorization: `Bearer ${accessToken}`,
+        Accept: 'application/json',
+        'User-Agent': USER_AGENT,
+        ...options.headers,
+    };
+    console.error(`[Workday API] ${options.method || 'GET'} ${url}`);
+    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 WorkdayError('Request to Workday API timed out', 'TIMEOUT', 'The request took too long. Try again or check if the Workday API is available.');
+        }
+        throw error;
+    }
+    if (!response.ok) {
+        // Handle 429 with exponential backoff (max 3 retries)
+        if (response.status === 429 && retryCount < 3) {
+            const retryAfter = response.headers.get('Retry-After');
+            const waitMs = retryAfter
+                ? parseInt(retryAfter, 10) * 1000
+                : Math.min(1000 * Math.pow(2, retryCount), 8000);
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+            return workdayFetch(resourcePath, options, retryCount + 1);
+        }
+        let errorText;
+        try {
+            const errorBody = await response.json();
+            const firstError = errorBody?.errors?.[0];
+            errorText = firstError?.message || firstError?.error || errorBody?.error || JSON.stringify(errorBody);
+        }
+        catch {
+            errorText = await response.text().catch(() => 'Unknown error');
+        }
+        if (response.status === 401) {
+            clearTokenCache();
+            throw new WorkdayError(`Authentication failed (${response.status}): ${errorText}`, 'AUTH_FAILED', 'Re-configure with configure_workday_credentials. Check client ID, secret, and tenant.');
+        }
+        if (response.status === 403) {
+            throw new WorkdayError(`Insufficient permissions (${response.status}): ${errorText}`, 'FORBIDDEN', 'Check ISU security group and domain permissions in Workday.');
+        }
+        if (response.status === 404) {
+            throw new WorkdayError(`Resource not found (${response.status}): ${errorText}`, 'NOT_FOUND', 'Verify the ID is correct.');
+        }
+        if (response.status === 429) {
+            throw new WorkdayError('Rate limited. Maximum retries exhausted.', 'RATE_LIMITED', 'Please wait before retrying.');
+        }
+        if (response.status >= 500) {
+            throw new WorkdayError(`Workday server error (${response.status}): ${errorText}`, 'SERVER_ERROR', 'Workday server error. Try again later.');
+        }
+        throw new WorkdayError(`Workday API error (${response.status}): ${errorText}`, `HTTP_${response.status}`, 'Check the request parameters and try again.');
+    }
+    return await response.json();
+}
+//# sourceMappingURL=client.js.map

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * Workday MCP Server
+ *
+ * Provides Workday HCM integration via Model Context Protocol.
+ * Read-only v1: workers (employees + contingent workers) and organizations.
+ *
+ * Uses the Workday REST API v1 directly via fetch().
+ * OAuth 2.0 token management with dual grant type support
+ * (client_credentials + refresh_token).
+ *
+ * Environment variables:
+ * - WORKDAY_HOST: Workday API domain (e.g., wd5-impl-services1.workday.com)
+ * - WORKDAY_TENANT: Customer's Workday tenant name
+ * - WORKDAY_CLIENT_ID: OAuth client ID
+ * - WORKDAY_CLIENT_SECRET: OAuth client secret
+ * - WORKDAY_REFRESH_TOKEN: Optional refresh token (enables refresh_token grant)
+ * - MCP_HOST_BRIDGE_STATE: Path to bridge state file for app communication
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+/**
+ * Workday MCP Server
+ *
+ * Provides Workday HCM integration via Model Context Protocol.
+ * Read-only v1: workers (employees + contingent workers) and organizations.
+ *
+ * Uses the Workday REST API v1 directly via fetch().
+ * OAuth 2.0 token management with dual grant type support
+ * (client_credentials + refresh_token).
+ *
+ * Environment variables:
+ * - WORKDAY_HOST: Workday API domain (e.g., wd5-impl-services1.workday.com)
+ * - WORKDAY_TENANT: Customer's Workday tenant name
+ * - WORKDAY_CLIENT_ID: OAuth client ID
+ * - WORKDAY_CLIENT_SECRET: OAuth client secret
+ * - WORKDAY_REFRESH_TOKEN: Optional refresh token (enables refresh_token grant)
+ * - MCP_HOST_BRIDGE_STATE: Path to bridge state file for app communication
+ * - MINDSTONE_REBEL_BRIDGE_STATE: Legacy bridge state path
+ */
+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('Workday 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,13 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { registerConfigureTools, registerWorkerTools, registerOrganizationTools, } from './tools/index.js';
+export function createServer() {
+    const server = new McpServer({
+        name: 'workday-mcp-server',
+        version: '0.1.0',
+    });
+    registerConfigureTools(server);
+    registerWorkerTools(server);
+    registerOrganizationTools(server);
+    return server;
+}
+//# sourceMappingURL=server.js.map

package/dist/tools/configure.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Workday credential configuration tool.
+ *
+ * Validates host (SSRF prevention), attempts token exchange + API probe,
+ * persists via bridge, and updates runtime credentials.
+ */
+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,164 @@
+/**
+ * Workday credential configuration tool.
+ *
+ * Validates host (SSRF prevention), attempts token exchange + API probe,
+ * persists via bridge, and updates runtime credentials.
+ */
+import { z } from 'zod';
+import { WorkdayError, USER_AGENT, REQUEST_TIMEOUT_MS } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+import { validateHost, setHost, setTenant, setClientId, setClientSecret, setRefreshToken, clearTokenCache, } from '../auth.js';
+import { bridgeRequest } from '../bridge.js';
+export function registerConfigureTools(server) {
+    server.registerTool('configure_workday_credentials', {
+        description: `Configure Workday API credentials. Call this when the user provides their Workday OAuth credentials.
+
+SETUP PREREQUISITES:
+1. A Workday Integration System User (ISU) with appropriate security group access
+2. An API Client registered in Workday (Tenant Setup > API Clients)
+3. The Client ID and Client Secret from the API Client registration
+4. Optionally, a pre-generated Refresh Token (from OAuth token exchange)
+
+PARAMETERS:
+- host: Workday API domain (e.g., "wd5-impl-services1.workday.com")
+- tenant: Your Workday tenant name (e.g., "acme_corp")
+- client_id: OAuth Client ID from API Client registration
+- client_secret: OAuth Client Secret
+- refresh_token: (Optional) Pre-generated refresh token. If omitted, uses client_credentials grant.
+
+COMMON MISTAKES:
+- Host should be just the domain (e.g., "wd5-impl-services1.workday.com"), not a full URL
+- Tenant name is case-sensitive
+- The ISU must have permissions for the REST API resources you want to access`,
+        inputSchema: z.object({
+            host: z.string().describe('Workday API domain (e.g., "wd5-impl-services1.workday.com")'),
+            tenant: z.string().describe('Workday tenant name (e.g., "acme_corp")'),
+            client_id: z.string().describe('OAuth Client ID from Workday API Client registration'),
+            client_secret: z.string().describe('OAuth Client Secret'),
+            refresh_token: z.string().optional().describe('Optional refresh token. If omitted, client_credentials grant is used.'),
+        }),
+        annotations: { destructiveHint: false },
+    }, withErrorHandling(async (args) => {
+        const rawHost = args.host.trim();
+        const tenant = args.tenant.trim();
+        const cid = args.client_id.trim();
+        const csecret = args.client_secret.trim();
+        const rtoken = args.refresh_token?.trim() || undefined;
+        if (!rawHost || !tenant || !cid || !csecret) {
+            return JSON.stringify({ ok: false, error: 'host, tenant, client_id, and client_secret are all required.' });
+        }
+        // Normalize and validate host (SSRF prevention)
+        const hostValidation = validateHost(rawHost);
+        if (!hostValidation.valid) {
+            return JSON.stringify({ ok: false, error: hostValidation.error });
+        }
+        const host = hostValidation.host;
+        // Validate credentials by attempting token exchange + API probe
+        const authHeader = 'Basic ' + Buffer.from(`${cid}:${csecret}`).toString('base64');
+        const bodyParams = rtoken
+            ? { grant_type: 'refresh_token', refresh_token: rtoken }
+            : { grant_type: 'client_credentials' };
+        const body = new URLSearchParams(bodyParams);
+        const tokenUrl = `https://${host}/ccx/oauth2/${tenant}/token`;
+        let tokenResponse;
+        try {
+            tokenResponse = await fetch(tokenUrl, {
+                method: 'POST',
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                headers: {
+                    Authorization: authHeader,
+                    'Content-Type': 'application/x-www-form-urlencoded',
+                    Accept: 'application/json',
+                    'User-Agent': USER_AGENT,
+                },
+                body: body.toString(),
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                return JSON.stringify({
+                    ok: false,
+                    error: 'Token exchange request timed out.',
+                    resolution: 'Verify the host domain is correct and accessible from your network.',
+                });
+            }
+            return JSON.stringify({
+                ok: false,
+                error: `Could not reach Workday: ${error instanceof Error ? error.message : String(error)}`,
+                resolution: 'Verify the host domain is correct and accessible from your network.',
+            });
+        }
+        if (!tokenResponse.ok) {
+            const errorBody = await tokenResponse.json().catch(() => ({}));
+            const detail = errorBody?.error_description || errorBody?.error || `HTTP ${tokenResponse.status}`;
+            return JSON.stringify({
+                ok: false,
+                error: `Token exchange failed: ${detail}`,
+                resolution: tokenResponse.status === 401
+                    ? 'Check your Client ID and Client Secret. Ensure the API Client is registered correctly in Workday.'
+                    : tokenResponse.status === 400
+                        ? 'Check your tenant name and host domain. If using a refresh token, it may be expired or invalid.'
+                        : `Unexpected error (${tokenResponse.status}). Verify host, tenant, and credentials.`,
+            });
+        }
+        const tokenData = await tokenResponse.json();
+        // API probe
+        const testUrl = `https://${host}/ccx/api/v1/${tenant}/workers?limit=1`;
+        let testResponse;
+        try {
+            testResponse = await fetch(testUrl, {
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+                headers: {
+                    Authorization: `Bearer ${tokenData.access_token}`,
+                    Accept: 'application/json',
+                    'User-Agent': USER_AGENT,
+                },
+            });
+        }
+        catch (error) {
+            if (error instanceof Error && error.name === 'TimeoutError') {
+                return JSON.stringify({
+                    ok: false,
+                    error: 'API probe timed out after successful token exchange.',
+                    resolution: 'Check network connectivity to Workday.',
+                });
+            }
+            return JSON.stringify({
+                ok: false,
+                error: `API probe failed: ${error instanceof Error ? error.message : String(error)}`,
+                resolution: 'Verify the host domain and network connectivity.',
+            });
+        }
+        if (!testResponse.ok) {
+            const status = testResponse.status;
+            return JSON.stringify({
+                ok: false,
+                error: `Token exchange succeeded but API probe failed (${status}).`,
+                resolution: status === 403
+                    ? 'The ISU lacks permissions for the Workers REST API. Add the Integration System Security Group to the "Worker Data" domain in Workday.'
+                    : status === 404
+                        ? 'Workers endpoint not found. Verify the tenant name and that REST API is enabled.'
+                        : `Unexpected API error (${status}). Check ISU permissions and REST API configuration.`,
+            });
+        }
+        // Persist via bridge
+        const result = await bridgeRequest('/bundled/workday/configure', {
+            host, tenant, clientId: cid, clientSecret: csecret, refreshToken: rtoken,
+        });
+        if (!result.success) {
+            throw new WorkdayError(result.error || 'Failed to configure Workday via bridge.', 'BRIDGE_ERROR', 'Check that the host application is running and bridge is available.');
+        }
+        // Update runtime credentials
+        setHost(host);
+        setTenant(tenant);
+        setClientId(cid);
+        setClientSecret(csecret);
+        setRefreshToken(rtoken ?? '');
+        clearTokenCache();
+        const message = result.warning
+            ? `Workday configured successfully. Note: ${result.warning}`
+            : 'Workday configured successfully! Try list_workday_workers to browse your team.';
+        return JSON.stringify({ ok: true, message });
+    }));
+}
+//# sourceMappingURL=configure.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerWorkerTools } from './workers.js';
+export { registerOrganizationTools } from './organizations.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.js

@@ -0,0 +1,4 @@
+export { registerConfigureTools } from './configure.js';
+export { registerWorkerTools } from './workers.js';
+export { registerOrganizationTools } from './organizations.js';
+//# sourceMappingURL=index.js.map

package/dist/tools/organizations.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Workday organization tools — list organizations.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerOrganizationTools(server: McpServer): void;
+//# sourceMappingURL=organizations.d.ts.map

package/dist/tools/organizations.js

@@ -0,0 +1,52 @@
+/**
+ * Workday organization tools — list organizations.
+ */
+import { z } from 'zod';
+import { ORG_LIST_FIELDS, pickFields, paginationHint } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+import { workdayFetch } from '../client.js';
+export function registerOrganizationTools(server) {
+    server.registerTool('list_workday_organizations', {
+        description: `List organizations (departments, supervisory orgs, cost centers, etc.) in Workday.
+
+Returns: ID, name/descriptor, type, active status.
+
+Example: {}
+Example: { "limit": 25, "offset": 50 }
+
+Pagination: Returns up to 'limit' results (default 50, max 100). Use 'offset' for next page.
+
+RELATED TOOLS:
+- list_workday_workers: Browse workers in the organization
+- get_workday_worker: See which organization a worker belongs to`,
+        inputSchema: z.object({
+            limit: z.number().optional().describe('Max results per page (default 50, max 100)'),
+            offset: z.number().optional().describe('Number of results to skip (for pagination, default 0)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured()) {
+            return JSON.stringify({
+                ok: false,
+                error: 'Workday not configured',
+                resolution: 'Configure Workday with your OAuth credentials first.',
+                next_step: {
+                    action: 'Ask the user for their Workday credentials, then call configure_workday_credentials',
+                    tool_to_call: 'configure_workday_credentials',
+                },
+            });
+        }
+        const limit = Math.min(Math.max(Number(args.limit) || 50, 1), 100);
+        const offset = Math.max(Number(args.offset) || 0, 0);
+        const params = new URLSearchParams();
+        params.set('limit', String(limit));
+        params.set('offset', String(offset));
+        const result = await workdayFetch(`/organizations?${params.toString()}`);
+        const organizations = (result.data || []).map((o) => pickFields(o, ORG_LIST_FIELDS));
+        const total = result.total || organizations.length;
+        const hint = paginationHint(total, offset, organizations.length);
+        return JSON.stringify({ ok: true, organizations, count: organizations.length, total, pagination: hint });
+    }));
+}
+//# sourceMappingURL=organizations.js.map

package/dist/tools/workers.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Workday worker tools — list and get worker profiles.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerWorkerTools(server: McpServer): void;
+//# sourceMappingURL=workers.d.ts.map

package/dist/tools/workers.js

@@ -0,0 +1,95 @@
+/**
+ * Workday worker tools — list and get worker profiles.
+ */
+import { z } from 'zod';
+import { WORKER_LIST_FIELDS, WORKER_DETAIL_FIELDS, NESTED_OBJECT_FIELDS, pickFields, paginationHint, } from '../types.js';
+import { withErrorHandling } from '../utils.js';
+import { isConfigured } from '../auth.js';
+import { workdayFetch } from '../client.js';
+function notConfiguredResponse() {
+    return JSON.stringify({
+        ok: false,
+        error: 'Workday not configured',
+        resolution: 'Configure Workday with your OAuth credentials first.',
+        next_step: {
+            action: 'Ask the user for their Workday credentials, then call configure_workday_credentials',
+            tool_to_call: 'configure_workday_credentials',
+        },
+    });
+}
+export function registerWorkerTools(server) {
+    server.registerTool('list_workday_workers', {
+        description: `List or search workers (employees and contingent workers) in Workday.
+
+Returns compact worker summaries: ID, name, email, title, manager status.
+
+Example: {}
+Example: { "search": "Jane Smith" }
+Example: { "limit": 20, "offset": 100 }
+
+Pagination: Returns up to 'limit' results (default 50, max 100). Use 'offset' for next page.
+
+RELATED TOOLS:
+- get_workday_worker: Pass a worker's id to get their full profile
+- list_workday_organizations: Browse organizational structure
+
+COMMON MISTAKES:
+- search is a free-text filter (name, email, etc.) — not a Workday query language
+- Maximum limit is 100 per request; use offset for pagination`,
+        inputSchema: z.object({
+            search: z.string().optional().describe('Free-text search filter (name, email, etc.)'),
+            limit: z.number().optional().describe('Max results per page (default 50, max 100)'),
+            offset: z.number().optional().describe('Number of results to skip (for pagination, default 0)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return notConfiguredResponse();
+        const limit = Math.min(Math.max(Number(args.limit) || 50, 1), 100);
+        const offset = Math.max(Number(args.offset) || 0, 0);
+        const params = new URLSearchParams();
+        params.set('limit', String(limit));
+        params.set('offset', String(offset));
+        if (args.search)
+            params.set('search', args.search);
+        const result = await workdayFetch(`/workers?${params.toString()}`);
+        const workers = (result.data || []).map((w) => pickFields(w, WORKER_LIST_FIELDS));
+        const total = result.total || workers.length;
+        const hint = paginationHint(total, offset, workers.length);
+        return JSON.stringify({ ok: true, workers, count: workers.length, total, pagination: hint });
+    }));
+    server.registerTool('get_workday_worker', {
+        description: `Get a worker's full profile by ID from Workday.
+
+Returns detailed profile: name, email, title, manager status, location,
+supervisory organization, years of service.
+
+Example: { "worker_id": "3aa5550b7fe348b98d7b5741afc65534" }
+
+WORKFLOW - To find a worker:
+1. Call list_workday_workers to search by name or email
+2. Use the worker's id from the results here
+
+RELATED TOOLS:
+- list_workday_workers: Search/browse workers to find IDs
+- list_workday_organizations: See org structure`,
+        inputSchema: z.object({
+            worker_id: z.string().describe('Worker ID (from list_workday_workers)'),
+        }),
+        annotations: { readOnlyHint: true },
+    }, withErrorHandling(async (args) => {
+        if (!isConfigured())
+            return notConfiguredResponse();
+        const worker = await workdayFetch(`/workers/${encodeURIComponent(args.worker_id)}`);
+        const filtered = pickFields(worker, WORKER_DETAIL_FIELDS);
+        // Deep-pick nested objects to prevent PII leakage from sub-fields
+        if (worker.location && typeof worker.location === 'object') {
+            filtered.location = pickFields(worker.location, NESTED_OBJECT_FIELDS);
+        }
+        if (worker.supervisoryOrganization && typeof worker.supervisoryOrganization === 'object') {
+            filtered.supervisoryOrganization = pickFields(worker.supervisoryOrganization, NESTED_OBJECT_FIELDS);
+        }
+        return JSON.stringify({ ok: true, worker: filtered });
+    }));
+}
+//# sourceMappingURL=workers.js.map

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+export declare const REQUEST_TIMEOUT_MS = 30000;
+export declare const USER_AGENT = "MindstoneRebel/1.0 (Workday-MCP)";
+export interface BridgeState {
+    port: number;
+    token: string;
+}
+export declare class WorkdayError extends Error {
+    readonly code: string;
+    readonly resolution: string;
+    constructor(message: string, code: string, resolution: string);
+}
+export declare const WORKER_LIST_FIELDS: readonly ["id", "descriptor", "primaryWorkEmail", "businessTitle", "isManager"];
+export declare const WORKER_DETAIL_FIELDS: readonly ["id", "descriptor", "primaryWorkEmail", "businessTitle", "isManager", "yearsOfService", "href"];
+export declare const NESTED_OBJECT_FIELDS: readonly ["id", "descriptor"];
+export declare const ORG_LIST_FIELDS: readonly ["id", "descriptor", "type", "isActive", "href"];
+export declare function pickFields<T extends readonly string[]>(obj: Record<string, unknown>, fields: T): Record<string, unknown>;
+export declare function paginationHint(total: number, offset: number, count: number): string;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,35 @@
+export const REQUEST_TIMEOUT_MS = 30_000;
+export const USER_AGENT = 'MindstoneRebel/1.0 (Workday-MCP)';
+export class WorkdayError extends Error {
+    code;
+    resolution;
+    constructor(message, code, resolution) {
+        super(message);
+        this.code = code;
+        this.resolution = resolution;
+        this.name = 'WorkdayError';
+    }
+}
+// ── Allowlisted response fields ──
+export const WORKER_LIST_FIELDS = ['id', 'descriptor', 'primaryWorkEmail', 'businessTitle', 'isManager'];
+export const WORKER_DETAIL_FIELDS = ['id', 'descriptor', 'primaryWorkEmail', 'businessTitle', 'isManager', 'yearsOfService', 'href'];
+export const NESTED_OBJECT_FIELDS = ['id', 'descriptor'];
+export const ORG_LIST_FIELDS = ['id', 'descriptor', 'type', 'isActive', 'href'];
+// ── Field allowlisting ──
+export function pickFields(obj, fields) {
+    const result = {};
+    for (const field of fields) {
+        if (field in obj) {
+            result[field] = obj[field];
+        }
+    }
+    return result;
+}
+// ── Pagination helper ──
+export function paginationHint(total, offset, count) {
+    if (count >= total)
+        return `Showing all ${total} results.`;
+    const remaining = total - offset - count;
+    return `Showing ${count} of ${total} total (offset=${offset}). ${remaining > 0 ? `Use offset=${offset + count} to see more.` : ''}`;
+}
+//# 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 WorkdayError: 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 { WorkdayError } from './types.js';
+/**
+ * Wraps a tool handler with standard error handling.
+ *
+ * - On success: returns the string result as a text content block.
+ * - On WorkdayError: 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 WorkdayError) {
+                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-workday",
+  "version": "0.1.0",
+  "description": "Workday HCM MCP server for Model Context Protocol hosts — workers, profiles, organizations",
+  "license": "FSL-1.1-MIT",
+  "type": "module",
+  "bin": {
+    "mcp-server-workday": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nspr-io/mcp-servers.git",
+    "directory": "connectors/workday"
+  },
+  "homepage": "https://github.com/nspr-io/mcp-servers/tree/main/connectors/workday",
+  "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"
+  }
+}