@anastops/mcp-server 1.1.2 → 2.0.0

package/dist/handlers/v3/routing-integration-example.d.ts

@@ -0,0 +1,258 @@
+/**
+ * Integration Example: Using Routing Middleware with v3.0 Tools
+ *
+ * This file demonstrates how to integrate the operation routing middleware
+ * with existing v3.0 consolidated tools (session, task, agent management).
+ *
+ * @module handlers/v3/routing-integration-example
+ */
+import type { HandlerContext } from '../types.js';
+import { type OperationRouter } from './routing-middleware.js';
+/**
+ * Create and configure the global v3 tools router
+ *
+ * This function sets up the router with all v3.0 consolidated tools.
+ * Call this once during MCP server initialization.
+ *
+ * @returns Configured OperationRouter instance
+ *
+ * @example
+ * ```typescript
+ * // In server initialization
+ * import { setupV3Router } from './routing-integration-example.js';
+ *
+ * const router = setupV3Router();
+ *
+ * // Later, in tool call handler
+ * const result = await router.routeToolCall(toolName, params, context);
+ * ```
+ */
+export declare function setupV3Router(): OperationRouter;
+/**
+ * Main MCP tool call handler using the router
+ *
+ * This function should be called from your MCP server's tool call handler.
+ * It validates and routes all v3.0 tool calls.
+ *
+ * @param toolName - Name of the tool being called
+ * @param params - Tool parameters from MCP request
+ * @param context - Handler context with shared state
+ * @returns Promise resolving to tool result
+ *
+ * @example
+ * ```typescript
+ * // In your MCP server's CallToolRequestSchema handler
+ * server.setRequestHandler(CallToolRequestSchema, async (request) => {
+ *   const { name, arguments: params } = request.params;
+ *
+ *   try {
+ *     const result = await handleV3ToolCall(name, params, context);
+ *
+ *     return {
+ *       content: [
+ *         {
+ *           type: 'text',
+ *           text: JSON.stringify(result, null, 2)
+ *         }
+ *       ]
+ *     };
+ *   } catch (error) {
+ *     return {
+ *       content: [
+ *         {
+ *           type: 'text',
+ *           text: `Error: ${error.message}`
+ *         }
+ *       ],
+ *       isError: true
+ *     };
+ *   }
+ * });
+ * ```
+ */
+export declare function handleV3ToolCall(toolName: string, params: Record<string, unknown>, context: HandlerContext): Promise<unknown>;
+/**
+ * Validate v3 tool call parameters without executing
+ *
+ * Useful for:
+ * - Pre-validation before expensive operations
+ * - Providing helpful error messages to users
+ * - UI form validation
+ *
+ * @param toolName - Name of the tool
+ * @param params - Tool parameters to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const validation = validateV3ToolCall('session_manage', params);
+ *
+ * if (!validation.valid) {
+ *   console.error('Validation failed:', validation.error);
+ *   if (validation.missingFields) {
+ *     console.error('Missing fields:', validation.missingFields);
+ *   }
+ *   return;
+ * }
+ *
+ * // Proceed with execution
+ * const result = await handleV3ToolCall(toolName, params, context);
+ * ```
+ */
+export declare function validateV3ToolCall(toolName: string, params: Record<string, unknown>): {
+    valid: boolean;
+    error?: string;
+    operation?: string;
+    missingFields?: string[];
+};
+/**
+ * Get required fields for a v3 tool operation
+ *
+ * @param toolName - Name of the tool
+ * @param operation - Operation name
+ * @returns Array of required field names, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const fields = getV3ToolRequiredFields('session_manage', 'create');
+ * // Returns: ['objective']
+ *
+ * // Use in UI to show required field indicators
+ * fields?.forEach(field => {
+ *   markFieldAsRequired(field);
+ * });
+ * ```
+ */
+export declare function getV3ToolRequiredFields(toolName: string, operation: string): string[] | null;
+/**
+ * List all available v3 tools
+ *
+ * @returns Array of tool names
+ *
+ * @example
+ * ```typescript
+ * const tools = listV3Tools();
+ * // Returns: ['session_manage', 'session_query', 'task_manage', ...]
+ *
+ * // Use in CLI help or UI
+ * console.log('Available tools:', tools.join(', '));
+ * ```
+ */
+export declare function listV3Tools(): string[];
+/**
+ * Initialize the global router
+ * Call this during server startup for better performance
+ *
+ * @example
+ * ```typescript
+ * // In server initialization
+ * import { initializeV3Router } from './routing-integration-example.js';
+ *
+ * async function startServer() {
+ *   initializeV3Router();
+ *   // ... rest of server setup
+ * }
+ * ```
+ */
+export declare function initializeV3Router(): void;
+/**
+ * Example 1: Basic tool call
+ *
+ * ```typescript
+ * async function createSession(context: HandlerContext) {
+ *   const session = await handleV3ToolCall(
+ *     'session_manage',
+ *     {
+ *       operation: 'create',
+ *       objective: 'Build authentication system',
+ *       concurrency: 3,
+ *       auto_execute: true,
+ *     },
+ *     context
+ *   );
+ *   console.log('Session created:', session);
+ * }
+ * ```
+ *
+ * Example 2: Validation before execution
+ *
+ * ```typescript
+ * async function validateBeforeExecution(context: HandlerContext) {
+ *   const params = {
+ *     operation: 'create',
+ *     objective: 'Build feature X',
+ *   };
+ *
+ *   // Validate first
+ *   const validation = validateV3ToolCall('session_manage', params);
+ *
+ *   if (!validation.valid) {
+ *     console.error('Invalid parameters:', validation.error);
+ *     return;
+ *   }
+ *
+ *   // Execute only if valid
+ *   const result = await handleV3ToolCall('session_manage', params, context);
+ *   console.log('Result:', result);
+ * }
+ * ```
+ *
+ * Example 3: Error handling
+ *
+ * ```typescript
+ * async function handleErrors(context: HandlerContext) {
+ *   try {
+ *     const result = await handleV3ToolCall(
+ *       'session_manage',
+ *       {
+ *         operation: 'fork',
+ *         session_id: 'invalid-id',
+ *       },
+ *       context
+ *     );
+ *     console.log('Forked:', result);
+ *   } catch (error) {
+ *     if (error instanceof Error) {
+ *       // Parse error for user-friendly message
+ *       if (error.message.includes('Session not found')) {
+ *         console.error('The session you tried to fork does not exist');
+ *       } else if (error.message.includes('Missing required fields')) {
+ *         console.error('Please provide all required fields');
+ *       } else {
+ *         console.error('Operation failed:', error.message);
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Example 4: Dynamic UI generation
+ *
+ * ```typescript
+ * function generateUI() {
+ *   const operation = 'create';
+ *   const requiredFields = getV3ToolRequiredFields('session_manage', operation);
+ *
+ *   if (requiredFields) {
+ *     console.log('Required fields for session_manage.create:');
+ *     requiredFields.forEach((field) => {
+ *       console.log(`- ${field} *`);
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * Example 5: Help command
+ *
+ * ```typescript
+ * function showHelp() {
+ *   const tools = listV3Tools();
+ *
+ *   console.log('Available v3.0 MCP tools:');
+ *   tools.forEach((tool) => {
+ *     console.log(`- ${tool}`);
+ *   });
+ * }
+ * ```
+ */
+//# sourceMappingURL=routing-integration-example.d.ts.map

package/dist/handlers/v3/routing-integration-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing-integration-example.d.ts","sourceRoot":"","sources":["../../../src/handlers/v3/routing-integration-example.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAGlD,OAAO,EAGL,KAAK,eAAe,EACrB,MAAM,yBAAyB,CAAC;AAYjC;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,IAAI,eAAe,CA4K/C;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,OAAO,CAAC,CAalB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC9B;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAWlF;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAG5F;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,WAAW,IAAI,MAAM,EAAE,CAGtC;AAYD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAIzC;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG"}

package/dist/handlers/v3/routing-integration-example.js

@@ -0,0 +1,454 @@
+/**
+ * Integration Example: Using Routing Middleware with v3.0 Tools
+ *
+ * This file demonstrates how to integrate the operation routing middleware
+ * with existing v3.0 consolidated tools (session, task, agent management).
+ *
+ * @module handlers/v3/routing-integration-example
+ */
+import { handleAgentManage, handleAgentQuery } from './agent-tools.js';
+import { createOperationRouter, createToolConfig, } from './routing-middleware.js';
+import { handleSessionManage, handleSessionQuery, handleSessionQueueConfig, } from './session-tools.js';
+import { handleTool as handleTaskTool } from './task-tools.js';
+// ============================================================================
+// Router Setup
+// ============================================================================
+/**
+ * Create and configure the global v3 tools router
+ *
+ * This function sets up the router with all v3.0 consolidated tools.
+ * Call this once during MCP server initialization.
+ *
+ * @returns Configured OperationRouter instance
+ *
+ * @example
+ * ```typescript
+ * // In server initialization
+ * import { setupV3Router } from './routing-integration-example.js';
+ *
+ * const router = setupV3Router();
+ *
+ * // Later, in tool call handler
+ * const result = await router.routeToolCall(toolName, params, context);
+ * ```
+ */
+export function setupV3Router() {
+    const router = createOperationRouter();
+    // -------------------------------------------------------------------------
+    // Session Management Tools
+    // -------------------------------------------------------------------------
+    /**
+     * session_manage: Create, fork, archive, delete sessions
+     */
+    router.registerTool(createToolConfig('session_manage', {
+        create: {
+            requiredFields: ['objective'],
+            handler: handleSessionManage,
+        },
+        fork: {
+            requiredFields: ['session_id'],
+            handler: handleSessionManage,
+        },
+        archive: {
+            requiredFields: ['session_id'],
+            handler: handleSessionManage,
+        },
+        delete: {
+            requiredFields: ['confirm'],
+            handler: handleSessionManage,
+        },
+    }));
+    /**
+     * session_query: Get status, list sessions, generate reports
+     */
+    router.registerTool(createToolConfig('session_query', {
+        status: {
+            requiredFields: ['session_id'],
+            handler: handleSessionQuery,
+        },
+        list: {
+            requiredFields: [],
+            handler: handleSessionQuery,
+        },
+        report: {
+            requiredFields: [],
+            handler: handleSessionQuery,
+        },
+    }));
+    /**
+     * session_queue_config: Configure queue settings, query queue status
+     */
+    router.registerTool(createToolConfig('session_queue_config', {
+        configure: {
+            requiredFields: ['session_id'],
+            handler: handleSessionQueueConfig,
+        },
+        status: {
+            requiredFields: ['session_id'],
+            handler: handleSessionQueueConfig,
+        },
+    }));
+    // -------------------------------------------------------------------------
+    // Task Management Tools
+    // -------------------------------------------------------------------------
+    /**
+     * task_manage: Create, complete, cancel tasks (single and batch)
+     */
+    router.registerTool(createToolConfig('task_manage', {
+        create: {
+            requiredFields: ['session_id'],
+            handler: async (args, context) => handleTaskTool('task_manage', args, context),
+        },
+        complete: {
+            requiredFields: ['task_id', 'content'],
+            handler: async (args, context) => handleTaskTool('task_manage', args, context),
+        },
+        cancel: {
+            requiredFields: ['task_id'],
+            handler: async (args, context) => handleTaskTool('task_manage', args, context),
+        },
+    }));
+    /**
+     * task_execute: Execute tasks (single or batch, with queue support)
+     */
+    router.registerTool(createToolConfig('task_execute', {
+        execute: {
+            requiredFields: [], // Either task_id or task_ids required, validated in handler
+            handler: async (args, context) => handleTaskTool('task_execute', args, context),
+        },
+    }));
+    /**
+     * task_query: Get task status, list tasks
+     */
+    router.registerTool(createToolConfig('task_query', {
+        status: {
+            requiredFields: ['task_id'],
+            handler: async (args, context) => handleTaskTool('task_query', args, context),
+        },
+        list: {
+            requiredFields: ['session_id'],
+            handler: async (args, context) => handleTaskTool('task_query', args, context),
+        },
+    }));
+    /**
+     * task_retry: Retry failed tasks
+     */
+    router.registerTool(createToolConfig('task_retry', {
+        retry: {
+            requiredFields: ['task_id'],
+            handler: async (args, context) => handleTaskTool('task_retry', args, context),
+        },
+    }));
+    // -------------------------------------------------------------------------
+    // Agent Management Tools
+    // -------------------------------------------------------------------------
+    /**
+     * agent_manage: Create, deploy, retire agents
+     */
+    router.registerTool(createToolConfig('agent_manage', {
+        create: {
+            requiredFields: ['session_id', 'role'],
+            handler: handleAgentManage,
+        },
+        deploy: {
+            requiredFields: ['agent_id', 'task_id'],
+            handler: handleAgentManage,
+        },
+        retire: {
+            requiredFields: ['agent_id'],
+            handler: handleAgentManage,
+        },
+    }));
+    /**
+     * agent_query: Get agent status, list agents
+     */
+    router.registerTool(createToolConfig('agent_query', {
+        status: {
+            requiredFields: ['agent_id'],
+            handler: handleAgentQuery,
+        },
+        list: {
+            requiredFields: ['session_id'],
+            handler: handleAgentQuery,
+        },
+    }));
+    return router;
+}
+// ============================================================================
+// MCP Server Integration
+// ============================================================================
+/**
+ * Main MCP tool call handler using the router
+ *
+ * This function should be called from your MCP server's tool call handler.
+ * It validates and routes all v3.0 tool calls.
+ *
+ * @param toolName - Name of the tool being called
+ * @param params - Tool parameters from MCP request
+ * @param context - Handler context with shared state
+ * @returns Promise resolving to tool result
+ *
+ * @example
+ * ```typescript
+ * // In your MCP server's CallToolRequestSchema handler
+ * server.setRequestHandler(CallToolRequestSchema, async (request) => {
+ *   const { name, arguments: params } = request.params;
+ *
+ *   try {
+ *     const result = await handleV3ToolCall(name, params, context);
+ *
+ *     return {
+ *       content: [
+ *         {
+ *           type: 'text',
+ *           text: JSON.stringify(result, null, 2)
+ *         }
+ *       ]
+ *     };
+ *   } catch (error) {
+ *     return {
+ *       content: [
+ *         {
+ *           type: 'text',
+ *           text: `Error: ${error.message}`
+ *         }
+ *       ],
+ *       isError: true
+ *     };
+ *   }
+ * });
+ * ```
+ */
+export async function handleV3ToolCall(toolName, params, context) {
+    // Get or create router instance
+    const router = globalV3Router ?? setupV3Router();
+    // Validate tool exists
+    if (!router.hasTool(toolName)) {
+        throw new Error(`Unknown tool: ${toolName}. Available tools: ${router.getToolNames().join(', ')}`);
+    }
+    // Route to appropriate handler
+    return router.routeToolCall(toolName, params, context);
+}
+/**
+ * Validate v3 tool call parameters without executing
+ *
+ * Useful for:
+ * - Pre-validation before expensive operations
+ * - Providing helpful error messages to users
+ * - UI form validation
+ *
+ * @param toolName - Name of the tool
+ * @param params - Tool parameters to validate
+ * @returns Validation result
+ *
+ * @example
+ * ```typescript
+ * const validation = validateV3ToolCall('session_manage', params);
+ *
+ * if (!validation.valid) {
+ *   console.error('Validation failed:', validation.error);
+ *   if (validation.missingFields) {
+ *     console.error('Missing fields:', validation.missingFields);
+ *   }
+ *   return;
+ * }
+ *
+ * // Proceed with execution
+ * const result = await handleV3ToolCall(toolName, params, context);
+ * ```
+ */
+export function validateV3ToolCall(toolName, params) {
+    const router = globalV3Router ?? setupV3Router();
+    if (!router.hasTool(toolName)) {
+        return {
+            valid: false,
+            error: `Unknown tool: ${toolName}`,
+        };
+    }
+    return router.validateOperation(toolName, params);
+}
+/**
+ * Get required fields for a v3 tool operation
+ *
+ * @param toolName - Name of the tool
+ * @param operation - Operation name
+ * @returns Array of required field names, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const fields = getV3ToolRequiredFields('session_manage', 'create');
+ * // Returns: ['objective']
+ *
+ * // Use in UI to show required field indicators
+ * fields?.forEach(field => {
+ *   markFieldAsRequired(field);
+ * });
+ * ```
+ */
+export function getV3ToolRequiredFields(toolName, operation) {
+    const router = globalV3Router ?? setupV3Router();
+    return router.getRequiredFields(toolName, operation);
+}
+/**
+ * List all available v3 tools
+ *
+ * @returns Array of tool names
+ *
+ * @example
+ * ```typescript
+ * const tools = listV3Tools();
+ * // Returns: ['session_manage', 'session_query', 'task_manage', ...]
+ *
+ * // Use in CLI help or UI
+ * console.log('Available tools:', tools.join(', '));
+ * ```
+ */
+export function listV3Tools() {
+    const router = globalV3Router ?? setupV3Router();
+    return router.getToolNames();
+}
+// ============================================================================
+// Global Router Instance (Singleton)
+// ============================================================================
+/**
+ * Global router instance
+ * Initialized lazily on first use
+ */
+let globalV3Router = null;
+/**
+ * Initialize the global router
+ * Call this during server startup for better performance
+ *
+ * @example
+ * ```typescript
+ * // In server initialization
+ * import { initializeV3Router } from './routing-integration-example.js';
+ *
+ * async function startServer() {
+ *   initializeV3Router();
+ *   // ... rest of server setup
+ * }
+ * ```
+ */
+export function initializeV3Router() {
+    if (globalV3Router === null) {
+        globalV3Router = setupV3Router();
+    }
+}
+// ============================================================================
+// Usage Examples (in comments for documentation)
+// ============================================================================
+/**
+ * Example 1: Basic tool call
+ *
+ * ```typescript
+ * async function createSession(context: HandlerContext) {
+ *   const session = await handleV3ToolCall(
+ *     'session_manage',
+ *     {
+ *       operation: 'create',
+ *       objective: 'Build authentication system',
+ *       concurrency: 3,
+ *       auto_execute: true,
+ *     },
+ *     context
+ *   );
+ *   console.log('Session created:', session);
+ * }
+ * ```
+ *
+ * Example 2: Validation before execution
+ *
+ * ```typescript
+ * async function validateBeforeExecution(context: HandlerContext) {
+ *   const params = {
+ *     operation: 'create',
+ *     objective: 'Build feature X',
+ *   };
+ *
+ *   // Validate first
+ *   const validation = validateV3ToolCall('session_manage', params);
+ *
+ *   if (!validation.valid) {
+ *     console.error('Invalid parameters:', validation.error);
+ *     return;
+ *   }
+ *
+ *   // Execute only if valid
+ *   const result = await handleV3ToolCall('session_manage', params, context);
+ *   console.log('Result:', result);
+ * }
+ * ```
+ *
+ * Example 3: Error handling
+ *
+ * ```typescript
+ * async function handleErrors(context: HandlerContext) {
+ *   try {
+ *     const result = await handleV3ToolCall(
+ *       'session_manage',
+ *       {
+ *         operation: 'fork',
+ *         session_id: 'invalid-id',
+ *       },
+ *       context
+ *     );
+ *     console.log('Forked:', result);
+ *   } catch (error) {
+ *     if (error instanceof Error) {
+ *       // Parse error for user-friendly message
+ *       if (error.message.includes('Session not found')) {
+ *         console.error('The session you tried to fork does not exist');
+ *       } else if (error.message.includes('Missing required fields')) {
+ *         console.error('Please provide all required fields');
+ *       } else {
+ *         console.error('Operation failed:', error.message);
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Example 4: Dynamic UI generation
+ *
+ * ```typescript
+ * function generateUI() {
+ *   const operation = 'create';
+ *   const requiredFields = getV3ToolRequiredFields('session_manage', operation);
+ *
+ *   if (requiredFields) {
+ *     console.log('Required fields for session_manage.create:');
+ *     requiredFields.forEach((field) => {
+ *       console.log(`- ${field} *`);
+ *     });
+ *   }
+ * }
+ * ```
+ *
+ * Example 5: Help command
+ *
+ * ```typescript
+ * function showHelp() {
+ *   const tools = listV3Tools();
+ *
+ *   console.log('Available v3.0 MCP tools:');
+ *   tools.forEach((tool) => {
+ *     console.log(`- ${tool}`);
+ *   });
+ * }
+ * ```
+ */
+// ============================================================================
+// Exports
+// ============================================================================
+// Note: All exports are declared inline with their function definitions above
+// This includes:
+// - setupV3Router
+// - handleV3ToolCall
+// - validateV3ToolCall
+// - getV3ToolRequiredFields
+// - listV3Tools
+// - initializeV3Router
+//
+// Usage examples are provided in comments above (see "Usage Examples" section)
+//# sourceMappingURL=routing-integration-example.js.map