agent-orchestrator-mcp-server 0.1.1 → 0.1.2

package/README.md

@@ -56,12 +56,13 @@ Control which tools are available via the `ENABLED_TOOLGROUPS` environment varia
 
 ### Environment Variables
 
-| Variable                      | Required | Description                       | Default     |
-| ----------------------------- | -------- | --------------------------------- | ----------- |
-| `AGENT_ORCHESTRATOR_BASE_URL` | Yes      | Base URL for the orchestrator API | -           |
-| `AGENT_ORCHESTRATOR_API_KEY`  | Yes      | API key for authentication        | -           |
-| `ENABLED_TOOLGROUPS`          | No       | Comma-separated tool groups       | All enabled |
-| `SKIP_HEALTH_CHECKS`          | No       | Skip API validation at startup    | `false`     |
+| Variable                      | Required | Description                            | Default     |
+| ----------------------------- | -------- | -------------------------------------- | ----------- |
+| `AGENT_ORCHESTRATOR_BASE_URL` | Yes      | Base URL for the orchestrator API      | -           |
+| `AGENT_ORCHESTRATOR_API_KEY`  | Yes      | API key for authentication             | -           |
+| `ENABLED_TOOLGROUPS`          | No       | Comma-separated tool groups            | All enabled |
+| `SKIP_HEALTH_CHECKS`          | No       | Skip API connectivity check at startup | `false`     |
+| `HEALTH_CHECK_TIMEOUT`        | No       | Health check timeout in milliseconds   | `10000`     |
 
 ### Claude Desktop
 

package/build/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { createMCPServer } from '../shared/index.js';
-import { logServerStart, logError, logWarning } from '../shared/logging.js';
+import { createMCPServer, checkApiHealth, getErrorHint, parseHealthCheckTimeout, } from '../shared/index.js';
+import { logServerStart, logError, logWarning, logDebug } from '../shared/logging.js';
 // =============================================================================
 // ENVIRONMENT VALIDATION
 // =============================================================================
@@ -28,9 +28,14 @@ function validateEnvironment() {
         },
         {
             name: 'SKIP_HEALTH_CHECKS',
-            description: 'Skip API validation at startup',
+            description: 'Skip API connectivity check at startup (set to "true" to skip)',
             defaultValue: 'false',
         },
+        {
+            name: 'HEALTH_CHECK_TIMEOUT',
+            description: 'Health check timeout in milliseconds',
+            defaultValue: '10000',
+        },
     ];
     const missing = required.filter(({ name }) => !process.env[name]);
     if (missing.length > 0) {
@@ -71,8 +76,28 @@ async function performHealthChecks() {
         logWarning('healthcheck', 'Health checks skipped (SKIP_HEALTH_CHECKS=true)');
         return;
     }
-    // For agent-orchestrator, we could add a health check by calling the sessions endpoint
-    // For now, we skip complex validation since the API might not always be available
+    logDebug('healthcheck', 'Performing API connectivity health check...');
+    // Parse health check timeout using shared utility
+    const healthCheckTimeout = parseHealthCheckTimeout(process.env.HEALTH_CHECK_TIMEOUT, (msg) => logWarning('healthcheck', msg));
+    const baseUrl = process.env.AGENT_ORCHESTRATOR_BASE_URL;
+    const apiKey = process.env.AGENT_ORCHESTRATOR_API_KEY;
+    try {
+        await checkApiHealth(baseUrl, apiKey, healthCheckTimeout);
+        logDebug('healthcheck', `Health check passed - connected to ${baseUrl}`);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        // Provide helpful error messages based on common failure scenarios
+        const hint = getErrorHint(errorMessage, healthCheckTimeout);
+        logError('healthcheck', `API connectivity health check failed: ${errorMessage}${hint}`);
+        console.error('\n----------------------------------------');
+        console.error('API connectivity health check failed!');
+        console.error(`Error: ${errorMessage}${hint}`);
+        console.error('\nTo skip health checks, set:');
+        console.error('  SKIP_HEALTH_CHECKS=true');
+        console.error('----------------------------------------\n');
+        process.exit(1);
+    }
 }
 // =============================================================================
 // MAIN ENTRY POINT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Local implementation of agent-orchestrator MCP server",
   "main": "build/index.js",
   "type": "module",

package/shared/health-check.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Health check utilities for Agent Orchestrator MCP server.
+ * These are exported separately for testing.
+ */
+export declare const DEFAULT_HEALTH_CHECK_TIMEOUT = 10000;
+export declare const MAX_HEALTH_CHECK_TIMEOUT = 300000;
+/**
+ * Get a helpful hint based on the error message to guide users in troubleshooting.
+ */
+export declare function getErrorHint(errorMessage: string, timeout: number): string;
+/**
+ * Parse and validate health check timeout from environment variable.
+ * Returns validated timeout value or default.
+ */
+export declare function parseHealthCheckTimeout(envValue: string | undefined, warnFn?: (message: string) => void): number;
+/**
+ * Perform a health check against the Agent Orchestrator API.
+ * Makes a lightweight request to verify connectivity and authentication.
+ */
+export declare function checkApiHealth(baseUrl: string, apiKey: string, timeoutMs?: number): Promise<void>;
+//# sourceMappingURL=health-check.d.ts.map

package/shared/health-check.js

@@ -0,0 +1,115 @@
+/**
+ * Health check utilities for Agent Orchestrator MCP server.
+ * These are exported separately for testing.
+ */
+export const DEFAULT_HEALTH_CHECK_TIMEOUT = 10000;
+export const MAX_HEALTH_CHECK_TIMEOUT = 300000; // 5 minutes max
+/**
+ * Get a helpful hint based on the error message to guide users in troubleshooting.
+ */
+export function getErrorHint(errorMessage, timeout) {
+    // Check for authentication errors first (most common initial setup issue)
+    if (errorMessage.includes('401') ||
+        errorMessage.includes('403') ||
+        errorMessage.toLowerCase().includes('unauthorized') ||
+        errorMessage.toLowerCase().includes('forbidden')) {
+        return '\nHint: Authentication failed. Check that AGENT_ORCHESTRATOR_API_KEY is correct.';
+    }
+    // Check for timeout errors
+    if (errorMessage.toLowerCase().includes('timeout')) {
+        return `\nHint: Connection timed out after ${timeout}ms. Check that the API server is running and reachable.`;
+    }
+    // Check for connection refused (specific error codes)
+    if (errorMessage.includes('ECONNREFUSED')) {
+        return '\nHint: Connection refused. Check that the API server is running and AGENT_ORCHESTRATOR_BASE_URL is correct.';
+    }
+    // Check for DNS resolution errors
+    if (errorMessage.includes('ENOTFOUND') || errorMessage.includes('getaddrinfo')) {
+        return '\nHint: Could not resolve hostname. Check that AGENT_ORCHESTRATOR_BASE_URL is correct.';
+    }
+    // Check for other connection errors (more specific patterns)
+    if (errorMessage.includes('ECONNRESET') ||
+        errorMessage.includes('EHOSTUNREACH') ||
+        errorMessage.includes('ENETUNREACH')) {
+        return '\nHint: Network error. Check that the API server is reachable and there are no firewall issues.';
+    }
+    // Check for invalid URL errors
+    if (errorMessage.includes('Invalid URL') || errorMessage.includes('ERR_INVALID_URL')) {
+        return '\nHint: Invalid URL. Check that AGENT_ORCHESTRATOR_BASE_URL is a valid URL (e.g., http://localhost:3000).';
+    }
+    return '';
+}
+/**
+ * Parse and validate health check timeout from environment variable.
+ * Returns validated timeout value or default.
+ */
+export function parseHealthCheckTimeout(envValue, warnFn) {
+    if (!envValue) {
+        return DEFAULT_HEALTH_CHECK_TIMEOUT;
+    }
+    const parsed = parseInt(envValue, 10);
+    if (!isNaN(parsed) && parsed > 0 && parsed <= MAX_HEALTH_CHECK_TIMEOUT) {
+        return parsed;
+    }
+    if (warnFn) {
+        warnFn(`Invalid HEALTH_CHECK_TIMEOUT: ${envValue}. Must be between 1 and ${MAX_HEALTH_CHECK_TIMEOUT}. Using default: ${DEFAULT_HEALTH_CHECK_TIMEOUT}ms`);
+    }
+    return DEFAULT_HEALTH_CHECK_TIMEOUT;
+}
+/**
+ * Perform a health check against the Agent Orchestrator API.
+ * Makes a lightweight request to verify connectivity and authentication.
+ */
+export async function checkApiHealth(baseUrl, apiKey, timeoutMs = DEFAULT_HEALTH_CHECK_TIMEOUT) {
+    // Validate inputs
+    if (!baseUrl || baseUrl.trim().length === 0) {
+        throw new Error('Base URL cannot be empty');
+    }
+    if (!apiKey || apiKey.trim().length === 0) {
+        throw new Error('API key cannot be empty');
+    }
+    // Remove trailing slash if present
+    const normalizedBaseUrl = baseUrl.trim().replace(/\/$/, '');
+    // Use the sessions endpoint with minimal data to verify connectivity
+    let url;
+    try {
+        url = new URL(`${normalizedBaseUrl}/api/v1/sessions`);
+    }
+    catch {
+        throw new Error('Invalid URL: Check that AGENT_ORCHESTRATOR_BASE_URL is a valid URL (e.g., http://localhost:3000)');
+    }
+    url.searchParams.set('per_page', '1');
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const response = await fetch(url.toString(), {
+            method: 'GET',
+            headers: {
+                'X-API-Key': apiKey.trim(),
+                'Content-Type': 'application/json',
+            },
+            signal: controller.signal,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            let errorMessage;
+            try {
+                const errorJson = JSON.parse(errorText);
+                errorMessage = errorJson.message || errorJson.error || errorText;
+            }
+            catch {
+                errorMessage = errorText || `HTTP ${response.status}`;
+            }
+            throw new Error(`API Error (${response.status}): ${errorMessage}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`Request timeout after ${timeoutMs}ms`);
+        }
+        throw error;
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}

package/shared/index.d.ts

@@ -2,6 +2,7 @@ export { registerResources } from './resources.js';
 export { registerTools, createRegisterTools, type ToolGroup, parseEnabledToolGroups, } from './tools.js';
 export { createMCPServer, type ClientFactory, type IAgentOrchestratorClient } from './server.js';
 export { AgentOrchestratorClient, type IAgentOrchestratorClient as AgentOrchestratorClientInterface, } from './orchestrator-client/orchestrator-client.js';
+export { checkApiHealth, getErrorHint, parseHealthCheckTimeout, DEFAULT_HEALTH_CHECK_TIMEOUT, MAX_HEALTH_CHECK_TIMEOUT, } from './health-check.js';
 export type { Session, Log, SubagentTranscript, SessionStatus, LogLevel, SubagentStatus, Pagination, SessionsResponse, SearchSessionsResponse, SessionResponse, SessionActionResponse, LogsResponse, LogResponse, SubagentTranscriptsResponse, SubagentTranscriptResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, } from './types.js';
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';
 //# sourceMappingURL=index.d.ts.map

package/shared/index.js

@@ -4,5 +4,7 @@ export { registerTools, createRegisterTools, parseEnabledToolGroups, } from './t
 export { createMCPServer } from './server.js';
 // Client exports
 export { AgentOrchestratorClient, } from './orchestrator-client/orchestrator-client.js';
+// Health check exports
+export { checkApiHealth, getErrorHint, parseHealthCheckTimeout, DEFAULT_HEALTH_CHECK_TIMEOUT, MAX_HEALTH_CHECK_TIMEOUT, } from './health-check.js';
 // Logging exports (re-exported for convenience)
 export { logServerStart, logError, logWarning, logDebug } from './logging.js';

package/shared/tools/search-sessions.d.ts

@@ -11,20 +11,20 @@ export declare const SearchSessionsSchema: z.ZodObject<{
     page: z.ZodOptional<z.ZodNumber>;
     per_page: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
+    per_page?: number | undefined;
     status?: "waiting" | "running" | "needs_input" | "failed" | "archived" | undefined;
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    per_page?: number | undefined;
     search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;
 }, {
+    per_page?: number | undefined;
     status?: "waiting" | "running" | "needs_input" | "failed" | "archived" | undefined;
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    per_page?: number | undefined;
     search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;