agent-orchestrator-mcp-server 0.1.0

package/shared/orchestrator-client/orchestrator-client.integration-mock.js

@@ -0,0 +1,373 @@
+/**
+ * Integration mock for the Agent Orchestrator API client.
+ *
+ * Used in integration tests to simulate API responses without hitting real endpoints.
+ */
+/**
+ * Creates a mock Agent Orchestrator client for integration testing.
+ */
+export function createIntegrationMockOrchestratorClient(initialMockData) {
+    const mockData = {
+        sessions: initialMockData?.sessions || [
+            {
+                id: 1,
+                slug: 'test-session-1',
+                title: 'Test Session 1',
+                status: 'running',
+                agent_type: 'claude_code',
+                prompt: 'Test prompt',
+                git_root: 'https://github.com/example/repo.git',
+                branch: 'main',
+                subdirectory: null,
+                execution_provider: 'local_filesystem',
+                stop_condition: null,
+                mcp_servers: ['github-development'],
+                config: {},
+                metadata: { clone_path: 'repo-main-123' },
+                custom_metadata: {},
+                session_id: 'abc123',
+                job_id: 'job_456',
+                running_job_id: null,
+                archived_at: null,
+                created_at: '2025-01-15T14:30:00Z',
+                updated_at: '2025-01-15T14:35:00Z',
+            },
+        ],
+        logs: initialMockData?.logs || [
+            {
+                id: 1,
+                session_id: 1,
+                content: 'Agent started',
+                level: 'info',
+                created_at: '2025-01-15T14:30:00Z',
+                updated_at: '2025-01-15T14:30:00Z',
+            },
+        ],
+        subagentTranscripts: initialMockData?.subagentTranscripts || [
+            {
+                id: 1,
+                session_id: 1,
+                agent_id: 'agent-abc123',
+                tool_use_id: 'tool-xyz789',
+                filename: 'transcript_001.jsonl',
+                message_count: 15,
+                subagent_type: 'explore',
+                description: 'Exploring authentication codebase',
+                status: 'completed',
+                duration_ms: 45000,
+                total_tokens: 12500,
+                tool_use_count: 8,
+                formatted_duration: '45s',
+                formatted_tokens: '12.5k',
+                display_label: 'Exploring authentication codebase',
+                created_at: '2025-01-15T14:31:00Z',
+                updated_at: '2025-01-15T14:31:45Z',
+            },
+        ],
+    };
+    let sessionIdCounter = mockData.sessions?.length || 1;
+    let logIdCounter = mockData.logs?.length || 1;
+    let transcriptIdCounter = mockData.subagentTranscripts?.length || 1;
+    return {
+        mockData,
+        async listSessions(options) {
+            let sessions = [...(mockData.sessions || [])];
+            if (options?.status) {
+                sessions = sessions.filter((s) => s.status === options.status);
+            }
+            if (options?.agent_type) {
+                sessions = sessions.filter((s) => s.agent_type === options.agent_type);
+            }
+            if (!options?.show_archived) {
+                sessions = sessions.filter((s) => s.status !== 'archived');
+            }
+            const page = options?.page || 1;
+            const perPage = options?.per_page || 25;
+            const start = (page - 1) * perPage;
+            const paginatedSessions = sessions.slice(start, start + perPage);
+            return {
+                sessions: paginatedSessions,
+                pagination: {
+                    page,
+                    per_page: perPage,
+                    total_count: sessions.length,
+                    total_pages: Math.ceil(sessions.length / perPage),
+                },
+            };
+        },
+        async searchSessions(query, options) {
+            let sessions = [...(mockData.sessions || [])];
+            // Filter by query (simple contains match on title)
+            sessions = sessions.filter((s) => s.title.toLowerCase().includes(query.toLowerCase()));
+            if (options?.status) {
+                sessions = sessions.filter((s) => s.status === options.status);
+            }
+            if (!options?.show_archived) {
+                sessions = sessions.filter((s) => s.status !== 'archived');
+            }
+            const page = options?.page || 1;
+            const perPage = options?.per_page || 25;
+            const start = (page - 1) * perPage;
+            const paginatedSessions = sessions.slice(start, start + perPage);
+            return {
+                query,
+                search_contents: options?.search_contents || false,
+                sessions: paginatedSessions,
+                pagination: {
+                    page,
+                    per_page: perPage,
+                    total_count: sessions.length,
+                    total_pages: Math.ceil(sessions.length / perPage),
+                },
+            };
+        },
+        async getSession(id, includeTranscript) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            const result = { ...session };
+            if (includeTranscript) {
+                result.transcript = '{"type":"user",...}\n{"type":"assistant",...}';
+            }
+            return result;
+        },
+        async createSession(data) {
+            sessionIdCounter++;
+            const session = {
+                id: sessionIdCounter,
+                slug: data.slug || null,
+                title: data.title || 'New Session',
+                status: 'waiting',
+                agent_type: data.agent_type || 'claude_code',
+                prompt: data.prompt || null,
+                git_root: data.git_root || null,
+                branch: data.branch || 'main',
+                subdirectory: data.subdirectory || null,
+                execution_provider: data.execution_provider || 'local_filesystem',
+                stop_condition: data.stop_condition || null,
+                mcp_servers: data.mcp_servers || [],
+                config: data.config || {},
+                metadata: {},
+                custom_metadata: data.custom_metadata || {},
+                session_id: null,
+                job_id: data.prompt ? `job_${Date.now()}` : null,
+                running_job_id: null,
+                archived_at: null,
+                created_at: new Date().toISOString(),
+                updated_at: new Date().toISOString(),
+            };
+            mockData.sessions?.push(session);
+            return session;
+        },
+        async updateSession(id, data) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            if (data.title !== undefined)
+                session.title = data.title;
+            if (data.slug !== undefined)
+                session.slug = data.slug;
+            if (data.stop_condition !== undefined)
+                session.stop_condition = data.stop_condition;
+            if (data.custom_metadata !== undefined)
+                session.custom_metadata = data.custom_metadata;
+            session.updated_at = new Date().toISOString();
+            return session;
+        },
+        async deleteSession(id) {
+            const index = mockData.sessions?.findIndex((s) => s.id === Number(id) || s.slug === String(id));
+            if (index === undefined || index === -1) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            mockData.sessions?.splice(index, 1);
+        },
+        async archiveSession(id) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            session.status = 'archived';
+            session.archived_at = new Date().toISOString();
+            session.updated_at = new Date().toISOString();
+            return session;
+        },
+        async unarchiveSession(id) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            session.status = 'needs_input';
+            session.archived_at = null;
+            session.updated_at = new Date().toISOString();
+            return session;
+        },
+        async followUp(id, prompt) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            if (session.status !== 'needs_input') {
+                throw new Error(`API Error (422): Session is not in needs_input status`);
+            }
+            session.prompt = prompt;
+            session.status = 'running';
+            session.running_job_id = `job_${Date.now()}`;
+            session.updated_at = new Date().toISOString();
+            return { session, message: 'Follow-up prompt sent' };
+        },
+        async pauseSession(id) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            session.status = 'needs_input';
+            session.running_job_id = null;
+            session.updated_at = new Date().toISOString();
+            return { session, message: 'Session paused' };
+        },
+        async restartSession(id) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            session.status = 'running';
+            session.running_job_id = `job_${Date.now()}`;
+            session.updated_at = new Date().toISOString();
+            return { session, message: 'Session restarted' };
+        },
+        async listLogs(sessionId, options) {
+            let logs = (mockData.logs || []).filter((l) => l.session_id === Number(sessionId));
+            if (options?.level) {
+                logs = logs.filter((l) => l.level === options.level);
+            }
+            const page = options?.page || 1;
+            const perPage = options?.per_page || 25;
+            const start = (page - 1) * perPage;
+            const paginatedLogs = logs.slice(start, start + perPage);
+            return {
+                logs: paginatedLogs,
+                pagination: {
+                    page,
+                    per_page: perPage,
+                    total_count: logs.length,
+                    total_pages: Math.ceil(logs.length / perPage),
+                },
+            };
+        },
+        async getLog(sessionId, logId) {
+            const log = mockData.logs?.find((l) => l.session_id === Number(sessionId) && l.id === logId);
+            if (!log) {
+                throw new Error(`API Error (404): Log not found`);
+            }
+            return log;
+        },
+        async createLog(sessionId, data) {
+            logIdCounter++;
+            const log = {
+                id: logIdCounter,
+                session_id: Number(sessionId),
+                content: data.content,
+                level: data.level,
+                created_at: new Date().toISOString(),
+                updated_at: new Date().toISOString(),
+            };
+            mockData.logs?.push(log);
+            return log;
+        },
+        async updateLog(sessionId, logId, data) {
+            const log = mockData.logs?.find((l) => l.session_id === Number(sessionId) && l.id === logId);
+            if (!log) {
+                throw new Error(`API Error (404): Log not found`);
+            }
+            if (data.content !== undefined)
+                log.content = data.content;
+            if (data.level !== undefined)
+                log.level = data.level;
+            log.updated_at = new Date().toISOString();
+            return log;
+        },
+        async deleteLog(sessionId, logId) {
+            const index = mockData.logs?.findIndex((l) => l.session_id === Number(sessionId) && l.id === logId);
+            if (index === undefined || index === -1) {
+                throw new Error(`API Error (404): Log not found`);
+            }
+            mockData.logs?.splice(index, 1);
+        },
+        async listSubagentTranscripts(sessionId, options) {
+            let transcripts = (mockData.subagentTranscripts || []).filter((t) => t.session_id === Number(sessionId));
+            if (options?.status) {
+                transcripts = transcripts.filter((t) => t.status === options.status);
+            }
+            if (options?.subagent_type) {
+                transcripts = transcripts.filter((t) => t.subagent_type === options.subagent_type);
+            }
+            const page = options?.page || 1;
+            const perPage = options?.per_page || 25;
+            const start = (page - 1) * perPage;
+            const paginatedTranscripts = transcripts.slice(start, start + perPage);
+            return {
+                subagent_transcripts: paginatedTranscripts,
+                pagination: {
+                    page,
+                    per_page: perPage,
+                    total_count: transcripts.length,
+                    total_pages: Math.ceil(transcripts.length / perPage),
+                },
+            };
+        },
+        async getSubagentTranscript(sessionId, transcriptId, includeTranscript) {
+            const transcript = mockData.subagentTranscripts?.find((t) => t.session_id === Number(sessionId) && t.id === transcriptId);
+            if (!transcript) {
+                throw new Error(`API Error (404): Subagent transcript not found`);
+            }
+            const result = { ...transcript };
+            if (includeTranscript) {
+                result.transcript = '{"type":"user",...}\n{"type":"assistant",...}';
+            }
+            return result;
+        },
+        async createSubagentTranscript(sessionId, data) {
+            transcriptIdCounter++;
+            const transcript = {
+                id: transcriptIdCounter,
+                session_id: Number(sessionId),
+                agent_id: data.agent_id,
+                tool_use_id: data.tool_use_id || null,
+                transcript: data.transcript,
+                filename: data.filename || null,
+                message_count: data.message_count || null,
+                subagent_type: data.subagent_type || null,
+                description: data.description || null,
+                status: data.status || null,
+                duration_ms: data.duration_ms || null,
+                total_tokens: data.total_tokens || null,
+                tool_use_count: data.tool_use_count || null,
+                formatted_duration: null,
+                formatted_tokens: null,
+                display_label: data.description || null,
+                created_at: new Date().toISOString(),
+                updated_at: new Date().toISOString(),
+            };
+            mockData.subagentTranscripts?.push(transcript);
+            return transcript;
+        },
+        async updateSubagentTranscript(sessionId, transcriptId, data) {
+            const transcript = mockData.subagentTranscripts?.find((t) => t.session_id === Number(sessionId) && t.id === transcriptId);
+            if (!transcript) {
+                throw new Error(`API Error (404): Subagent transcript not found`);
+            }
+            Object.assign(transcript, data);
+            transcript.updated_at = new Date().toISOString();
+            return transcript;
+        },
+        async deleteSubagentTranscript(sessionId, transcriptId) {
+            const index = mockData.subagentTranscripts?.findIndex((t) => t.session_id === Number(sessionId) && t.id === transcriptId);
+            if (index === undefined || index === -1) {
+                throw new Error(`API Error (404): Subagent transcript not found`);
+            }
+            mockData.subagentTranscripts?.splice(index, 1);
+        },
+    };
+}

package/shared/orchestrator-client/orchestrator-client.js

@@ -0,0 +1,166 @@
+/**
+ * Agent Orchestrator API Client
+ *
+ * A client for interacting with the Agent Orchestrator REST API.
+ */
+/** Default timeout for API requests in milliseconds */
+const DEFAULT_TIMEOUT_MS = 30000;
+/**
+ * Implementation of the Agent Orchestrator API client.
+ */
+export class AgentOrchestratorClient {
+    baseUrl;
+    apiKey;
+    timeoutMs;
+    constructor(baseUrl, apiKey, timeoutMs = DEFAULT_TIMEOUT_MS) {
+        // 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
+        this.baseUrl = baseUrl.trim().replace(/\/$/, '');
+        this.apiKey = apiKey.trim();
+        this.timeoutMs = timeoutMs;
+    }
+    async request(method, path, body, query) {
+        const url = new URL(`${this.baseUrl}/api/v1${path}`);
+        if (query) {
+            Object.entries(query).forEach(([key, value]) => {
+                if (value !== undefined) {
+                    url.searchParams.set(key, String(value));
+                }
+            });
+        }
+        const headers = {
+            'X-API-Key': this.apiKey,
+            'Content-Type': 'application/json',
+        };
+        // Set up timeout with AbortController
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeoutMs);
+        const options = {
+            method,
+            headers,
+            signal: controller.signal,
+        };
+        if (body && (method === 'POST' || method === 'PATCH' || method === 'PUT')) {
+            options.body = JSON.stringify(body);
+        }
+        let response;
+        try {
+            response = await fetch(url.toString(), options);
+        }
+        catch (error) {
+            clearTimeout(timeoutId);
+            if (error instanceof Error && error.name === 'AbortError') {
+                throw new Error(`Request timeout after ${this.timeoutMs}ms`);
+            }
+            throw error;
+        }
+        finally {
+            clearTimeout(timeoutId);
+        }
+        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;
+            }
+            throw new Error(`API Error (${response.status}): ${errorMessage}`);
+        }
+        // Handle 204 No Content
+        if (response.status === 204) {
+            return undefined;
+        }
+        return response.json();
+    }
+    // Sessions
+    async listSessions(options) {
+        return this.request('GET', '/sessions', undefined, options);
+    }
+    async searchSessions(query, options) {
+        return this.request('GET', '/sessions/search', undefined, {
+            q: query,
+            ...options,
+        });
+    }
+    async getSession(id, includeTranscript) {
+        const response = await this.request('GET', `/sessions/${id}`, undefined, {
+            include_transcript: includeTranscript,
+        });
+        return response.session;
+    }
+    async createSession(data) {
+        const response = await this.request('POST', '/sessions', data);
+        return response.session;
+    }
+    async updateSession(id, data) {
+        const response = await this.request('PATCH', `/sessions/${id}`, data);
+        return response.session;
+    }
+    async deleteSession(id) {
+        await this.request('DELETE', `/sessions/${id}`);
+    }
+    async archiveSession(id) {
+        const response = await this.request('POST', `/sessions/${id}/archive`);
+        return response.session;
+    }
+    async unarchiveSession(id) {
+        const response = await this.request('POST', `/sessions/${id}/unarchive`);
+        return response.session;
+    }
+    async followUp(id, prompt) {
+        return this.request('POST', `/sessions/${id}/follow_up`, { prompt });
+    }
+    async pauseSession(id) {
+        return this.request('POST', `/sessions/${id}/pause`);
+    }
+    async restartSession(id) {
+        return this.request('POST', `/sessions/${id}/restart`);
+    }
+    // Logs
+    async listLogs(sessionId, options) {
+        return this.request('GET', `/sessions/${sessionId}/logs`, undefined, options);
+    }
+    async getLog(sessionId, logId) {
+        const response = await this.request('GET', `/sessions/${sessionId}/logs/${logId}`);
+        return response.log;
+    }
+    async createLog(sessionId, data) {
+        const response = await this.request('POST', `/sessions/${sessionId}/logs`, data);
+        return response.log;
+    }
+    async updateLog(sessionId, logId, data) {
+        const response = await this.request('PATCH', `/sessions/${sessionId}/logs/${logId}`, data);
+        return response.log;
+    }
+    async deleteLog(sessionId, logId) {
+        await this.request('DELETE', `/sessions/${sessionId}/logs/${logId}`);
+    }
+    // Subagent Transcripts
+    async listSubagentTranscripts(sessionId, options) {
+        return this.request('GET', `/sessions/${sessionId}/subagent_transcripts`, undefined, options);
+    }
+    async getSubagentTranscript(sessionId, transcriptId, includeTranscript) {
+        const response = await this.request('GET', `/sessions/${sessionId}/subagent_transcripts/${transcriptId}`, undefined, { include_transcript: includeTranscript });
+        return response.subagent_transcript;
+    }
+    async createSubagentTranscript(sessionId, data) {
+        const response = await this.request('POST', `/sessions/${sessionId}/subagent_transcripts`, data);
+        return response.subagent_transcript;
+    }
+    async updateSubagentTranscript(sessionId, transcriptId, data) {
+        const response = await this.request('PATCH', `/sessions/${sessionId}/subagent_transcripts/${transcriptId}`, data);
+        return response.subagent_transcript;
+    }
+    async deleteSubagentTranscript(sessionId, transcriptId) {
+        await this.request('DELETE', `/sessions/${sessionId}/subagent_transcripts/${transcriptId}`);
+    }
+}

package/shared/resources.d.ts

@@ -0,0 +1,3 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+export declare function registerResources(server: Server): void;
+//# sourceMappingURL=resources.d.ts.map

package/shared/resources.js

@@ -0,0 +1,67 @@
+import { ListResourcesRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+// =============================================================================
+// RESOURCES IMPLEMENTATION
+// =============================================================================
+// Resources expose data that can be read by MCP clients.
+// For agent-orchestrator, we expose a configuration resource for debugging.
+// =============================================================================
+export function registerResources(server) {
+    // List available resources
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+        return {
+            resources: [
+                {
+                    uri: 'agent-orchestrator://config',
+                    name: 'Server Configuration',
+                    description: 'Current server configuration and status. Useful for debugging and verifying setup.',
+                    mimeType: 'application/json',
+                },
+            ],
+        };
+    });
+    // Read resource contents
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+        const { uri } = request.params;
+        // =========================================================================
+        // CONFIG RESOURCE - Server Status and Configuration
+        // =========================================================================
+        if (uri === 'agent-orchestrator://config') {
+            const config = {
+                server: {
+                    name: 'agent-orchestrator-mcp-server',
+                    version: '0.1.0',
+                    transport: 'stdio',
+                },
+                environment: {
+                    AGENT_ORCHESTRATOR_BASE_URL: process.env.AGENT_ORCHESTRATOR_BASE_URL
+                        ? '***configured***'
+                        : 'not set',
+                    AGENT_ORCHESTRATOR_API_KEY: process.env.AGENT_ORCHESTRATOR_API_KEY
+                        ? '***configured***'
+                        : 'not set',
+                    ENABLED_TOOLGROUPS: process.env.ENABLED_TOOLGROUPS || 'all (default)',
+                    SKIP_HEALTH_CHECKS: process.env.SKIP_HEALTH_CHECKS || 'false',
+                },
+                capabilities: {
+                    tools: true,
+                    resources: true,
+                },
+                toolGroups: {
+                    readonly: 'Read-only operations (list, get, search)',
+                    write: 'Write operations (create, update, follow_up, pause, restart, archive, unarchive)',
+                    admin: 'Administrative operations (delete)',
+                },
+            };
+            return {
+                contents: [
+                    {
+                        uri: 'agent-orchestrator://config',
+                        mimeType: 'application/json',
+                        text: JSON.stringify(config, null, 2),
+                    },
+                ],
+            };
+        }
+        throw new Error(`Resource not found: ${uri}`);
+    });
+}

package/shared/server.d.ts

@@ -0,0 +1,31 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { type IAgentOrchestratorClient } from './orchestrator-client/orchestrator-client.js';
+export type { IAgentOrchestratorClient } from './orchestrator-client/orchestrator-client.js';
+export type ClientFactory = () => IAgentOrchestratorClient;
+export declare function createMCPServer(): {
+    server: Server<{
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+                progressToken?: string | number | undefined;
+            } | undefined;
+        } | undefined;
+    }, {
+        method: string;
+        params?: {
+            [x: string]: unknown;
+            _meta?: {
+                [x: string]: unknown;
+            } | undefined;
+        } | undefined;
+    }, {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    }>;
+    registerHandlers: (server: Server, clientFactory?: ClientFactory) => Promise<void>;
+};
+//# sourceMappingURL=server.d.ts.map

package/shared/server.js

@@ -0,0 +1,34 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { registerResources } from './resources.js';
+import { createRegisterTools } from './tools.js';
+import { AgentOrchestratorClient, } from './orchestrator-client/orchestrator-client.js';
+export function createMCPServer() {
+    const server = new Server({
+        name: 'agent-orchestrator-mcp-server',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+        },
+    });
+    const registerHandlers = async (server, clientFactory) => {
+        // Use provided factory or create default client
+        const factory = clientFactory ||
+            (() => {
+                const baseUrl = process.env.AGENT_ORCHESTRATOR_BASE_URL;
+                const apiKey = process.env.AGENT_ORCHESTRATOR_API_KEY;
+                if (!baseUrl) {
+                    throw new Error('AGENT_ORCHESTRATOR_BASE_URL environment variable must be configured');
+                }
+                if (!apiKey) {
+                    throw new Error('AGENT_ORCHESTRATOR_API_KEY environment variable must be configured');
+                }
+                return new AgentOrchestratorClient(baseUrl, apiKey);
+            });
+        registerResources(server);
+        const registerTools = createRegisterTools(factory);
+        registerTools(server);
+    };
+    return { server, registerHandlers };
+}