@task-shepherd/agent 1.0.5 → 1.0.7

package/shared/dist/schema/mcp-mappings.js

@@ -0,0 +1,563 @@
+/**
+ * MCP Tool Mappings Configuration
+ *
+ * This file serves as the centralized mapping between MCP tools and GraphQL operations,
+ * ensuring consistency across all TasqHub components. It defines which GraphQL
+ * operations each MCP tool corresponds to and validates the interfaces.
+ */
+/**
+ * Centralized MCP tool mappings organized by functional categories
+ */
+export const MCP_TOOL_MAPPINGS = [
+    {
+        name: 'Project Management',
+        description: 'Tools for managing projects, stories, and tasks',
+        tools: [
+            {
+                toolName: 'list_projects',
+                description: 'List all projects with optional filtering',
+                graphqlOperation: 'projects',
+                operationType: 'query',
+                requiredPermissions: ['VIEW'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        limit: { type: 'number', default: 20, maximum: 100 },
+                        offset: { type: 'number', default: 0 },
+                        search: {
+                            type: 'object',
+                            properties: {
+                                query: { type: 'string' },
+                                stage: { type: 'string', enum: ['REQUIREMENTS', 'DESIGN', 'IMPLEMENTATION', 'COMPLETE', 'ARCHIVED'] },
+                                isArchived: { type: 'boolean' },
+                                isPublic: { type: 'boolean' }
+                            }
+                        }
+                    }
+                }
+            },
+            {
+                toolName: 'get_project',
+                description: 'Get a specific project by ID',
+                graphqlOperation: 'project',
+                operationType: 'query',
+                requiredPermissions: ['VIEW'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'create_project',
+                description: 'Create a new project',
+                graphqlOperation: 'createProject',
+                operationType: 'mutation',
+                requiredPermissions: ['PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        name: { type: 'string' },
+                        description: { type: 'string' },
+                        stage: { type: 'string', enum: ['REQUIREMENTS', 'DESIGN', 'IMPLEMENTATION', 'COMPLETE', 'ARCHIVED'] },
+                        isPublic: { type: 'boolean' },
+                        startDate: { type: 'string', format: 'date-time' },
+                        targetCompletionDate: { type: 'string', format: 'date-time' },
+                        repositoryUrl: { type: 'string', format: 'uri' },
+                        documentationUrl: { type: 'string', format: 'uri' }
+                    },
+                    required: ['name']
+                }
+            },
+            {
+                toolName: 'update_project',
+                description: 'Update an existing project',
+                graphqlOperation: 'updateProject',
+                operationType: 'mutation',
+                requiredPermissions: ['PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        name: { type: 'string' },
+                        description: { type: 'string' },
+                        stage: { type: 'string', enum: ['REQUIREMENTS', 'DESIGN', 'IMPLEMENTATION', 'COMPLETE', 'ARCHIVED'] },
+                        isPublic: { type: 'boolean' },
+                        startDate: { type: 'string', format: 'date-time' },
+                        targetCompletionDate: { type: 'string', format: 'date-time' },
+                        repositoryUrl: { type: 'string', format: 'uri' },
+                        documentationUrl: { type: 'string', format: 'uri' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'delete_project',
+                description: 'Delete a project',
+                graphqlOperation: 'deleteProject',
+                operationType: 'mutation',
+                requiredPermissions: ['PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            }
+        ]
+    },
+    {
+        name: 'Story Management',
+        description: 'Tools for managing user stories and their lifecycle',
+        tools: [
+            {
+                toolName: 'list_stories',
+                description: 'List stories with filtering and pagination',
+                graphqlOperation: 'stories',
+                operationType: 'query',
+                requiredPermissions: ['VIEW'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        limit: { type: 'number', default: 20, maximum: 100 },
+                        offset: { type: 'number', default: 0 },
+                        projectId: { type: 'string' },
+                        search: {
+                            type: 'object',
+                            properties: {
+                                query: { type: 'string' },
+                                state: { type: 'string', enum: ['pending', 'implementation', 'review', 'complete', 'blocked'] },
+                                assignedTo: { type: 'string' },
+                                priority: { type: 'string', enum: ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'] },
+                                tags: { type: 'array', items: { type: 'string' } }
+                            }
+                        }
+                    }
+                }
+            },
+            {
+                toolName: 'get_story',
+                description: 'Get a specific story by ID',
+                graphqlOperation: 'story',
+                operationType: 'query',
+                requiredPermissions: ['VIEW'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'create_story',
+                description: 'Create a new story',
+                graphqlOperation: 'createStory',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        description: { type: 'string' },
+                        projectId: { type: 'string' },
+                        priority: { type: 'string', enum: ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'] },
+                        estimate: { type: 'number', minimum: 1 },
+                        tags: { type: 'array', items: { type: 'string' } },
+                        acceptanceCriteria: { type: 'array', items: { type: 'string' } },
+                        storyLink: { type: 'string', format: 'uri' },
+                        assignedTo: { type: 'string' },
+                        orderIndex: { type: 'number' }
+                    },
+                    required: ['title', 'projectId']
+                }
+            },
+            {
+                toolName: 'update_story',
+                description: 'Update an existing story',
+                graphqlOperation: 'updateStory',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        title: { type: 'string' },
+                        description: { type: 'string' },
+                        priority: { type: 'string', enum: ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'] },
+                        estimate: { type: 'number', minimum: 1 },
+                        tags: { type: 'array', items: { type: 'string' } },
+                        acceptanceCriteria: { type: 'array', items: { type: 'string' } },
+                        storyLink: { type: 'string', format: 'uri' },
+                        assignedTo: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'claim_story',
+                description: 'Claim a story for work',
+                graphqlOperation: 'claimStory',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'unclaim_story',
+                description: 'Unclaim a previously claimed story',
+                graphqlOperation: 'releaseStory',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'complete_story',
+                description: 'Mark a story as complete',
+                graphqlOperation: 'completeStory',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        implementationSummary: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'review_story',
+                description: 'Review a completed story',
+                graphqlOperation: 'reviewStory',
+                operationType: 'mutation',
+                requiredPermissions: ['PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        approved: { type: 'boolean' },
+                        reviewNotes: { type: 'string' }
+                    },
+                    required: ['id', 'approved']
+                }
+            }
+        ]
+    },
+    {
+        name: 'Task Management',
+        description: 'Tools for managing tasks within stories',
+        tools: [
+            {
+                toolName: 'list_tasks',
+                description: 'List tasks with filtering and pagination',
+                graphqlOperation: 'tasks',
+                operationType: 'query',
+                requiredPermissions: ['VIEW'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        limit: { type: 'number', default: 20, maximum: 100 },
+                        offset: { type: 'number', default: 0 },
+                        storyId: { type: 'string' },
+                        search: {
+                            type: 'object',
+                            properties: {
+                                query: { type: 'string' },
+                                status: { type: 'string', enum: ['pending', 'implementation', 'complete', 'blocked'] },
+                                type: { type: 'string', enum: ['PLANNED', 'FOLLOWUP', 'ASK'] },
+                                assignedTo: { type: 'string' },
+                                areas: { type: 'array', items: { type: 'string' } }
+                            }
+                        }
+                    }
+                }
+            },
+            {
+                toolName: 'get_task',
+                description: 'Get a specific task by ID',
+                graphqlOperation: 'task',
+                operationType: 'query',
+                requiredPermissions: ['VIEW'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'create_task',
+                description: 'Create a new task',
+                graphqlOperation: 'createTask',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        description: { type: 'string' },
+                        storyId: { type: 'string' },
+                        areas: { type: 'array', items: { type: 'string' }, minItems: 1 },
+                        type: { type: 'string', enum: ['PLANNED', 'FOLLOWUP', 'ASK'] },
+                        priority: { type: 'string', enum: ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'] },
+                        estimate: { type: 'number', minimum: 1 },
+                        assignedTo: { type: 'string' }
+                    },
+                    required: ['title', 'storyId', 'areas']
+                }
+            },
+            {
+                toolName: 'update_task',
+                description: 'Update an existing task',
+                graphqlOperation: 'updateTask',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        title: { type: 'string' },
+                        description: { type: 'string' },
+                        type: { type: 'string', enum: ['PLANNED', 'FOLLOWUP', 'ASK'] },
+                        priority: { type: 'string', enum: ['LOW', 'MEDIUM', 'HIGH', 'CRITICAL'] },
+                        estimate: { type: 'number', minimum: 1 },
+                        assignedTo: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'claim_task',
+                description: 'Claim a task for work',
+                graphqlOperation: 'claimTask',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'unclaim_task',
+                description: 'Unclaim a previously claimed task',
+                graphqlOperation: 'unclaimTask',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            },
+            {
+                toolName: 'complete_task',
+                description: 'Mark a task as complete with implementation details',
+                graphqlOperation: 'completeTask',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        id: { type: 'string' },
+                        implementationSummary: { type: 'string' }
+                    },
+                    required: ['id']
+                }
+            }
+        ]
+    },
+    {
+        name: 'User Management',
+        description: 'Tools for user authentication and management',
+        tools: [
+            {
+                toolName: 'register_worker',
+                description: 'Register a new worker (human or AI) with the system',
+                graphqlOperation: 'register',
+                operationType: 'mutation',
+                requiredPermissions: [],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        email: { type: 'string', format: 'email' },
+                        password: { type: 'string', minLength: 8 },
+                        firstName: { type: 'string' },
+                        lastName: { type: 'string' },
+                        role: { type: 'string', enum: ['VIEW', 'WORKER', 'PRODUCT', 'ADMIN'] }
+                    },
+                    required: ['email', 'password']
+                }
+            },
+            {
+                toolName: 'list_workers',
+                description: 'List all registered workers',
+                graphqlOperation: 'users',
+                operationType: 'query',
+                requiredPermissions: ['ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        activeOnly: { type: 'boolean', default: true },
+                        type: { type: 'string', enum: ['HUMAN', 'AI'] },
+                        capability: { type: 'string' }
+                    }
+                }
+            }
+        ]
+    },
+    {
+        name: 'Dependencies',
+        description: 'Tools for managing story and task dependencies',
+        tools: [
+            {
+                toolName: 'create_story_dependency',
+                description: 'Create a dependency between two stories',
+                graphqlOperation: 'createStoryDependency',
+                operationType: 'mutation',
+                requiredPermissions: ['WORKER', 'PRODUCT', 'ADMIN'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        storyId: { type: 'string' },
+                        dependsOnStoryId: { type: 'string' }
+                    },
+                    required: ['storyId', 'dependsOnStoryId']
+                }
+            },
+            {
+                toolName: 'get_dependency_graph',
+                description: 'Get the complete dependency graph for a project',
+                graphqlOperation: 'project',
+                operationType: 'query',
+                requiredPermissions: ['VIEW'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        projectId: { type: 'string' }
+                    },
+                    required: ['projectId']
+                }
+            }
+        ]
+    },
+    {
+        name: 'Work Management',
+        description: 'Tools for finding and allocating available work',
+        tools: [
+            {
+                toolName: 'get_available_stories',
+                description: 'Find stories available for claiming',
+                graphqlOperation: 'stories',
+                operationType: 'query',
+                requiredPermissions: ['VIEW'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        limit: { type: 'number', default: 20, maximum: 100 },
+                        offset: { type: 'number', default: 0 },
+                        areas: { type: 'array', items: { type: 'string' } },
+                        search: {
+                            type: 'object',
+                            properties: {
+                                state: { type: 'string', enum: ['pending'] },
+                                assignedTo: { type: 'null' }
+                            }
+                        }
+                    }
+                }
+            },
+            {
+                toolName: 'get_available_tasks',
+                description: 'Find tasks available for claiming',
+                graphqlOperation: 'tasks',
+                operationType: 'query',
+                requiredPermissions: ['VIEW'],
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        limit: { type: 'number', default: 20, maximum: 100 },
+                        offset: { type: 'number', default: 0 },
+                        areas: { type: 'array', items: { type: 'string' } },
+                        search: {
+                            type: 'object',
+                            properties: {
+                                status: { type: 'string', enum: ['pending'] },
+                                assignedTo: { type: 'null' }
+                            }
+                        }
+                    }
+                }
+            }
+        ]
+    }
+];
+/**
+ * Get MCP tool mapping by tool name
+ */
+export function getMCPToolMapping(toolName) {
+    for (const category of MCP_TOOL_MAPPINGS) {
+        const tool = category.tools.find(t => t.toolName === toolName);
+        if (tool)
+            return tool;
+    }
+    return undefined;
+}
+/**
+ * Get all MCP tool names
+ */
+export function getAllMCPToolNames() {
+    return MCP_TOOL_MAPPINGS.flatMap(category => category.tools.map(tool => tool.toolName));
+}
+/**
+ * Get tools by GraphQL operation
+ */
+export function getToolsByGraphQLOperation(operationName) {
+    return MCP_TOOL_MAPPINGS.flatMap(category => category.tools.filter(tool => tool.graphqlOperation === operationName));
+}
+/**
+ * Get tools by category
+ */
+export function getToolsByCategory(categoryName) {
+    const category = MCP_TOOL_MAPPINGS.find(c => c.name === categoryName);
+    return category ? category.tools : [];
+}
+/**
+ * Validate that a tool operation matches its GraphQL schema
+ */
+export function validateToolOperation(toolName, input) {
+    const mapping = getMCPToolMapping(toolName);
+    if (!mapping) {
+        return { valid: false, errors: [`Unknown tool: ${toolName}`] };
+    }
+    // Basic validation - in a real implementation, this would use a JSON schema validator
+    const errors = [];
+    if (mapping.inputSchema?.required) {
+        for (const requiredField of mapping.inputSchema.required) {
+            if (!(requiredField in input)) {
+                errors.push(`Missing required field: ${requiredField}`);
+            }
+        }
+    }
+    return { valid: errors.length === 0, errors };
+}

package/shared/dist/schema/validation.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Schema Validation System
+ *
+ * This module provides comprehensive validation for GraphQL schema consistency
+ * and MCP tool compatibility across all TasqHub components.
+ */
+import { GraphQLSchema } from 'graphql';
+export interface SchemaValidationResult {
+    valid: boolean;
+    errors: SchemaValidationError[];
+    warnings: SchemaValidationWarning[];
+}
+export interface SchemaValidationError {
+    type: 'MISSING_OPERATION' | 'TYPE_MISMATCH' | 'BREAKING_CHANGE' | 'INVALID_MAPPING';
+    message: string;
+    toolName?: string;
+    operationName?: string;
+    fieldPath?: string;
+    severity: 'error' | 'warning';
+}
+export interface SchemaValidationWarning {
+    type: 'DEPRECATED_FIELD' | 'UNUSED_OPERATION' | 'PERFORMANCE_CONCERN';
+    message: string;
+    suggestion?: string;
+}
+export interface SchemaCompatibilityCheck {
+    compatible: boolean;
+    breakingChanges: string[];
+    safeChanges: string[];
+    deprecations: string[];
+}
+/**
+ * Main schema validator class
+ */
+export declare class SchemaValidator {
+    private schema;
+    private introspection;
+    constructor(schema?: GraphQLSchema);
+    /**
+     * Set the GraphQL schema to validate against
+     */
+    setSchema(schema: GraphQLSchema): void;
+    /**
+     * Validate all MCP tool mappings against the current schema
+     */
+    validateMCPMappings(): SchemaValidationResult;
+    /**
+     * Validate a single MCP tool mapping
+     */
+    private validateSingleTool;
+    /**
+     * Find a GraphQL operation in the schema
+     */
+    private findGraphQLOperation;
+    /**
+     * Validate input schema compatibility
+     */
+    private validateInputSchema;
+    /**
+     * Get all GraphQL operations from the schema
+     */
+    private getAllGraphQLOperations;
+    /**
+     * Check compatibility between two schemas (for migration validation)
+     */
+    static compareSchemas(oldSchema: GraphQLSchema, newSchema: GraphQLSchema): SchemaCompatibilityCheck;
+    /**
+     * Helper to extract operations from introspection
+     */
+    private static getOperationsFromIntrospection;
+    /**
+     * Validate a specific MCP tool operation
+     */
+    validateToolOperation(toolName: string, input: any): {
+        valid: boolean;
+        errors: string[];
+    };
+}
+/**
+ * Utility function to create a schema validator from a GraphQL schema file
+ */
+export declare function createSchemaValidatorFromFile(schemaPath: string): Promise<SchemaValidator>;
+/**
+ * Utility function to validate schema consistency across components
+ */
+export declare function validateCrossComponentConsistency(schemas: {
+    backend: GraphQLSchema;
+    frontend?: any;
+    mcpServer?: any;
+    aiToolsService?: any;
+}): SchemaValidationResult;