agent-orchestrator-mcp-server 0.2.4 → 0.3.0

package/shared/tools/action-trigger.d.ts

@@ -0,0 +1,114 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const ActionTriggerSchema: z.ZodObject<{
+    action: z.ZodEnum<["create", "update", "delete", "toggle"]>;
+    id: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+    trigger_type: z.ZodOptional<z.ZodEnum<["slack", "schedule"]>>;
+    agent_root_name: z.ZodOptional<z.ZodString>;
+    prompt_template: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<["enabled", "disabled"]>>;
+    stop_condition: z.ZodOptional<z.ZodString>;
+    reuse_session: z.ZodOptional<z.ZodBoolean>;
+    mcp_servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    configuration: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    action: "create" | "update" | "delete" | "toggle";
+    status?: "enabled" | "disabled" | undefined;
+    mcp_servers?: string[] | undefined;
+    trigger_type?: "slack" | "schedule" | undefined;
+    name?: string | undefined;
+    id?: number | undefined;
+    stop_condition?: string | undefined;
+    agent_root_name?: string | undefined;
+    prompt_template?: string | undefined;
+    reuse_session?: boolean | undefined;
+    configuration?: Record<string, unknown> | undefined;
+}, {
+    action: "create" | "update" | "delete" | "toggle";
+    status?: "enabled" | "disabled" | undefined;
+    mcp_servers?: string[] | undefined;
+    trigger_type?: "slack" | "schedule" | undefined;
+    name?: string | undefined;
+    id?: number | undefined;
+    stop_condition?: string | undefined;
+    agent_root_name?: string | undefined;
+    prompt_template?: string | undefined;
+    reuse_session?: boolean | undefined;
+    configuration?: Record<string, unknown> | undefined;
+}>;
+export declare function actionTriggerTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            action: {
+                type: string;
+                enum: readonly ["create", "update", "delete", "toggle"];
+                description: string;
+            };
+            id: {
+                type: string;
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            trigger_type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            agent_root_name: {
+                type: string;
+                description: string;
+            };
+            prompt_template: {
+                type: string;
+                description: string;
+            };
+            status: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            stop_condition: {
+                type: string;
+                description: string;
+            };
+            reuse_session: {
+                type: string;
+                description: string;
+            };
+            mcp_servers: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
+            configuration: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+};
+//# sourceMappingURL=action-trigger.d.ts.map

package/shared/tools/action-trigger.js

@@ -0,0 +1,177 @@
+import { z } from 'zod';
+const ACTION_ENUM = ['create', 'update', 'delete', 'toggle'];
+export const ActionTriggerSchema = z.object({
+    action: z.enum(ACTION_ENUM),
+    id: z.number().optional(),
+    name: z.string().optional(),
+    trigger_type: z.enum(['slack', 'schedule']).optional(),
+    agent_root_name: z.string().optional(),
+    prompt_template: z.string().optional(),
+    status: z.enum(['enabled', 'disabled']).optional(),
+    stop_condition: z.string().optional(),
+    reuse_session: z.boolean().optional(),
+    mcp_servers: z.array(z.string()).optional(),
+    configuration: z.record(z.unknown()).optional(),
+});
+const TOOL_DESCRIPTION = `Create, update, delete, or toggle automation triggers.
+
+**Actions:**
+- **create**: Create a new trigger (requires name, trigger_type, agent_root_name, prompt_template)
+- **update**: Update an existing trigger (requires "id")
+- **delete**: Delete a trigger (requires "id")
+- **toggle**: Enable/disable a trigger (requires "id")
+
+**Trigger types:**
+- **slack**: Triggered by Slack events (requires configuration with channel_id)
+- **schedule**: Triggered on a schedule (requires configuration with interval, unit, etc.)
+
+Use search_triggers first to see available triggers and Slack channels.`;
+export function actionTriggerTool(_server, clientFactory) {
+    return {
+        name: 'action_trigger',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ACTION_ENUM, description: 'Action to perform.' },
+                id: { type: 'number', description: 'Trigger ID. Required for update, delete, toggle.' },
+                name: { type: 'string', description: 'Trigger name. Required for create.' },
+                trigger_type: {
+                    type: 'string',
+                    enum: ['slack', 'schedule'],
+                    description: 'Trigger type. Required for create.',
+                },
+                agent_root_name: { type: 'string', description: 'Agent root name. Required for create.' },
+                prompt_template: { type: 'string', description: 'Prompt template. Required for create.' },
+                status: { type: 'string', enum: ['enabled', 'disabled'], description: 'Trigger status.' },
+                stop_condition: { type: 'string', description: 'Stop condition for triggered sessions.' },
+                reuse_session: { type: 'boolean', description: 'Whether to reuse existing sessions.' },
+                mcp_servers: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'MCP servers for triggered sessions.',
+                },
+                configuration: {
+                    type: 'object',
+                    description: 'Type-specific configuration (schedule, Slack channel, etc.).',
+                },
+            },
+            required: ['action'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = ActionTriggerSchema.parse(args);
+                const client = clientFactory();
+                const { action, id } = validated;
+                let result;
+                switch (action) {
+                    case 'create': {
+                        if (!validated.name ||
+                            !validated.trigger_type ||
+                            !validated.agent_root_name ||
+                            !validated.prompt_template) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "name", "trigger_type", "agent_root_name", and "prompt_template" are required for the "create" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const trigger = await client.createTrigger({
+                            name: validated.name,
+                            trigger_type: validated.trigger_type,
+                            agent_root_name: validated.agent_root_name,
+                            prompt_template: validated.prompt_template,
+                            status: validated.status,
+                            stop_condition: validated.stop_condition,
+                            reuse_session: validated.reuse_session,
+                            mcp_servers: validated.mcp_servers,
+                            configuration: validated.configuration,
+                        });
+                        result = [
+                            '## Trigger Created',
+                            '',
+                            `- **ID:** ${trigger.id}`,
+                            `- **Name:** ${trigger.name}`,
+                            `- **Type:** ${trigger.trigger_type}`,
+                            `- **Status:** ${trigger.status}`,
+                            `- **Agent Root:** ${trigger.agent_root_name}`,
+                        ].join('\n');
+                        break;
+                    }
+                    case 'update': {
+                        if (!id) {
+                            return {
+                                content: [
+                                    { type: 'text', text: 'Error: "id" is required for the "update" action.' },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const trigger = await client.updateTrigger(id, {
+                            name: validated.name,
+                            trigger_type: validated.trigger_type,
+                            agent_root_name: validated.agent_root_name,
+                            prompt_template: validated.prompt_template,
+                            status: validated.status,
+                            stop_condition: validated.stop_condition,
+                            reuse_session: validated.reuse_session,
+                            mcp_servers: validated.mcp_servers,
+                            configuration: validated.configuration,
+                        });
+                        result = `## Trigger Updated\n\n- **ID:** ${trigger.id}\n- **Name:** ${trigger.name}\n- **Status:** ${trigger.status}`;
+                        break;
+                    }
+                    case 'delete': {
+                        if (!id) {
+                            return {
+                                content: [
+                                    { type: 'text', text: 'Error: "id" is required for the "delete" action.' },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        await client.deleteTrigger(id);
+                        result = `## Trigger Deleted\n\nTrigger ${id} has been deleted.`;
+                        break;
+                    }
+                    case 'toggle': {
+                        if (!id) {
+                            return {
+                                content: [
+                                    { type: 'text', text: 'Error: "id" is required for the "toggle" action.' },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const trigger = await client.toggleTrigger(id);
+                        result = `## Trigger Toggled\n\n- **ID:** ${trigger.id}\n- **Name:** ${trigger.name}\n- **New Status:** ${trigger.status}`;
+                        break;
+                    }
+                    default: {
+                        const _exhaustiveCheck = action;
+                        return {
+                            content: [{ type: 'text', text: `Error: Unknown action "${_exhaustiveCheck}"` }],
+                            isError: true,
+                        };
+                    }
+                }
+                return { content: [{ type: 'text', text: result }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error managing trigger: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/get-notifications.d.ts

@@ -0,0 +1,70 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const GetNotificationsSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    badge_only: z.ZodOptional<z.ZodBoolean>;
+    status: z.ZodOptional<z.ZodEnum<["read", "unread"]>>;
+    page: z.ZodOptional<z.ZodNumber>;
+    per_page: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    per_page?: number | undefined;
+    status?: "read" | "unread" | undefined;
+    page?: number | undefined;
+    id?: number | undefined;
+    badge_only?: boolean | undefined;
+}, {
+    per_page?: number | undefined;
+    status?: "read" | "unread" | undefined;
+    page?: number | undefined;
+    id?: number | undefined;
+    badge_only?: boolean | undefined;
+}>;
+export declare function getNotificationsTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            badge_only: {
+                type: string;
+                description: string;
+            };
+            status: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            page: {
+                type: string;
+                minimum: number;
+                description: string;
+            };
+            per_page: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=get-notifications.d.ts.map

package/shared/tools/get-notifications.js

@@ -0,0 +1,113 @@
+import { z } from 'zod';
+export const GetNotificationsSchema = z.object({
+    id: z.number().optional(),
+    badge_only: z.boolean().optional(),
+    status: z.enum(['read', 'unread']).optional(),
+    page: z.number().min(1).optional(),
+    per_page: z.number().min(1).max(100).optional(),
+});
+const TOOL_DESCRIPTION = `Get notifications from the Agent Orchestrator.
+
+**Modes:**
+- **Badge only**: Set badge_only=true to get just the pending notification count
+- **Get by ID**: Provide an id to get a specific notification
+- **List**: List notifications with optional status filter and pagination
+
+**Use cases:**
+- Check how many unread notifications you have
+- Review notification details
+- Monitor session alerts`;
+export function getNotificationsTool(_server, clientFactory) {
+    return {
+        name: 'get_notifications',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: { type: 'number', description: 'Get a specific notification by ID.' },
+                badge_only: {
+                    type: 'boolean',
+                    description: 'If true, returns only the pending notification count. Default: false',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['read', 'unread'],
+                    description: 'Filter by status when listing.',
+                },
+                page: { type: 'number', minimum: 1, description: 'Page number. Default: 1' },
+                per_page: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 100,
+                    description: 'Results per page. Default: 25',
+                },
+            },
+            required: [],
+        },
+        handler: async (args) => {
+            try {
+                const validated = GetNotificationsSchema.parse(args);
+                const client = clientFactory();
+                if (validated.badge_only) {
+                    const badge = await client.getNotificationBadge();
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `## Notification Badge\n\n**Pending notifications:** ${badge.pending_count}`,
+                            },
+                        ],
+                    };
+                }
+                if (validated.id) {
+                    const notification = await client.getNotification(validated.id);
+                    const lines = [
+                        `## Notification #${notification.id}`,
+                        '',
+                        `- **Type:** ${notification.notification_type}`,
+                        `- **Read:** ${notification.read ? 'Yes' : 'No'}`,
+                        `- **Session ID:** ${notification.session_id}`,
+                    ];
+                    if (notification.session) {
+                        lines.push(`- **Session Title:** ${notification.session.title}`);
+                        lines.push(`- **Session Status:** ${notification.session.status}`);
+                    }
+                    lines.push(`- **Created:** ${notification.created_at}`);
+                    return { content: [{ type: 'text', text: lines.join('\n') }] };
+                }
+                // List notifications
+                const response = await client.listNotifications({
+                    status: validated.status,
+                    page: validated.page,
+                    per_page: validated.per_page,
+                });
+                if (response.notifications.length === 0) {
+                    return {
+                        content: [{ type: 'text', text: '## Notifications\n\nNo notifications found.' }],
+                    };
+                }
+                const lines = [
+                    `## Notifications (${response.pagination.total_count} total, page ${response.pagination.page} of ${response.pagination.total_pages})`,
+                    '',
+                ];
+                response.notifications.forEach((n) => {
+                    const readStatus = n.read ? 'read' : 'unread';
+                    const sessionInfo = n.session ? ` - ${n.session.title} (${n.session.status})` : '';
+                    lines.push(`- **#${n.id}** [${readStatus}] ${n.notification_type}${sessionInfo} (${n.created_at})`);
+                });
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error getting notifications: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/get-session.d.ts

@@ -4,6 +4,7 @@ import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrat
 export declare const GetSessionSchema: z.ZodObject<{
     id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
     include_transcript: z.ZodOptional<z.ZodBoolean>;
+    transcript_format: z.ZodOptional<z.ZodEnum<["text", "json"]>>;
     include_logs: z.ZodOptional<z.ZodBoolean>;
     logs_page: z.ZodOptional<z.ZodNumber>;
     logs_per_page: z.ZodOptional<z.ZodNumber>;
@@ -13,6 +14,7 @@ export declare const GetSessionSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     id: string | number;
     include_transcript?: boolean | undefined;
+    transcript_format?: "text" | "json" | undefined;
     include_logs?: boolean | undefined;
     logs_page?: number | undefined;
     logs_per_page?: number | undefined;
@@ -22,6 +24,7 @@ export declare const GetSessionSchema: z.ZodObject<{
 }, {
     id: string | number;
     include_transcript?: boolean | undefined;
+    transcript_format?: "text" | "json" | undefined;
     include_logs?: boolean | undefined;
     logs_page?: number | undefined;
     logs_per_page?: number | undefined;
@@ -45,6 +48,11 @@ export declare function getSessionTool(_server: Server, clientFactory: () => IAg
                 type: string;
                 description: "Include the full transcript of the session. Default: false. Set to true for complete conversation history.";
             };
+            transcript_format: {
+                type: string;
+                enum: string[];
+                description: "Format for transcript retrieval: \"text\" (human-readable) or \"json\" (structured). Only used when include_transcript is true. When specified, fetches transcript via dedicated endpoint instead of inline.";
+            };
             include_logs: {
                 type: string;
                 description: "Include logs for the session. Default: false. Use logs_page and logs_per_page for pagination.";

package/shared/tools/get-session.js

@@ -2,6 +2,7 @@ import { z } from 'zod';
 const PARAM_DESCRIPTIONS = {
     id: 'Session ID (numeric) or slug (string). Examples: "1", "fix-auth-bug-20250115"',
     include_transcript: 'Include the full transcript of the session. Default: false. Set to true for complete conversation history.',
+    transcript_format: 'Format for transcript retrieval: "text" (human-readable) or "json" (structured). Only used when include_transcript is true. When specified, fetches transcript via dedicated endpoint instead of inline.',
     include_logs: 'Include logs for the session. Default: false. Use logs_page and logs_per_page for pagination.',
     logs_page: 'Page number for logs pagination. Default: 1',
     logs_per_page: 'Number of logs per page (1-100). Default: 25',
@@ -12,6 +13,10 @@ const PARAM_DESCRIPTIONS = {
 export const GetSessionSchema = z.object({
     id: z.union([z.string(), z.number()]).describe(PARAM_DESCRIPTIONS.id),
     include_transcript: z.boolean().optional().describe(PARAM_DESCRIPTIONS.include_transcript),
+    transcript_format: z
+        .enum(['text', 'json'])
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.transcript_format),
     include_logs: z.boolean().optional().describe(PARAM_DESCRIPTIONS.include_logs),
     logs_page: z.number().min(1).optional().describe(PARAM_DESCRIPTIONS.logs_page),
     logs_per_page: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.logs_per_page),
@@ -190,6 +195,11 @@ export function getSessionTool(_server, clientFactory) {
                     type: 'boolean',
                     description: PARAM_DESCRIPTIONS.include_transcript,
                 },
+                transcript_format: {
+                    type: 'string',
+                    enum: ['text', 'json'],
+                    description: PARAM_DESCRIPTIONS.transcript_format,
+                },
                 include_logs: {
                     type: 'boolean',
                     description: PARAM_DESCRIPTIONS.include_logs,
@@ -227,9 +237,18 @@ export function getSessionTool(_server, clientFactory) {
             try {
                 const validatedArgs = GetSessionSchema.parse(args);
                 const client = clientFactory();
-                // Get session details
-                const session = await client.getSession(validatedArgs.id, validatedArgs.include_transcript);
+                // Get session details - if using transcript_format, fetch transcript separately
+                const useTranscriptEndpoint = validatedArgs.include_transcript && validatedArgs.transcript_format;
+                const session = await client.getSession(validatedArgs.id, validatedArgs.include_transcript && !useTranscriptEndpoint);
                 let output = formatSessionDetails(session, validatedArgs.include_transcript || false);
+                // If transcript_format specified, use dedicated transcript endpoint
+                if (useTranscriptEndpoint) {
+                    const transcriptResponse = await client.getTranscript(session.id, validatedArgs.transcript_format);
+                    output += '\n\n### Transcript';
+                    output += '\n```';
+                    output += `\n${transcriptResponse.transcript_text}`;
+                    output += '\n```';
+                }
                 // Get logs if requested
                 if (validatedArgs.include_logs) {
                     const logsResponse = await client.listLogs(session.id, {

package/shared/tools/get-system-health.d.ts

@@ -0,0 +1,38 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const GetSystemHealthSchema: z.ZodObject<{
+    include_cli_status: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    include_cli_status?: boolean | undefined;
+}, {
+    include_cli_status?: boolean | undefined;
+}>;
+export declare function getSystemHealthTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            include_cli_status: {
+                type: string;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=get-system-health.d.ts.map

package/shared/tools/get-system-health.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+export const GetSystemHealthSchema = z.object({
+    include_cli_status: z.boolean().optional(),
+});
+const TOOL_DESCRIPTION = `Get the system health report for the Agent Orchestrator.
+
+Returns system health information including session counts, job queue status, and system metrics.
+Optionally include CLI tool installation status.
+
+**Use cases:**
+- Monitor system health and performance
+- Check for stuck sessions or failed jobs
+- Verify CLI tools are properly installed`;
+export function getSystemHealthTool(_server, clientFactory) {
+    return {
+        name: 'get_system_health',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                include_cli_status: {
+                    type: 'boolean',
+                    description: 'Include CLI tool installation status. Default: false',
+                },
+            },
+            required: [],
+        },
+        handler: async (args) => {
+            try {
+                const validated = GetSystemHealthSchema.parse(args);
+                const client = clientFactory();
+                const health = await client.getHealth();
+                const lines = [
+                    '## System Health Report',
+                    '',
+                    `- **Timestamp:** ${health.timestamp}`,
+                    `- **Environment:** ${health.rails_env}`,
+                    `- **Ruby Version:** ${health.ruby_version}`,
+                    '',
+                    '### Health Details',
+                    '```json',
+                    JSON.stringify(health.health_report, null, 2),
+                    '```',
+                ];
+                if (validated.include_cli_status) {
+                    try {
+                        const cliStatus = await client.getCliStatus();
+                        lines.push('', '### CLI Status', `- **Unauthenticated CLIs:** ${cliStatus.unauthenticated_count}`, '', '```json', JSON.stringify(cliStatus.cli_status, null, 2), '```');
+                    }
+                    catch (error) {
+                        lines.push('', `*Could not fetch CLI status: ${error instanceof Error ? error.message : 'Unknown error'}*`);
+                    }
+                }
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error getting system health: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}