AI Agent Template MCP Server

Instructions

Implementation Reference

• src/tools/index.ts:82-100 (handler)

  MCP tool handler in the switch statement that validates input parameters using Zod, calls the getPatternForTask helper function, and returns the generated pattern as text content.

  case 'get_pattern_for_task': {
    const params = z.object({
      taskType: z.enum(['component', 'hook', 'service', 'api', 'test', 'error-handling']),
      requirements: z.array(z.string()).optional(),
    }).parse(args);
    
    const pattern = await getPatternForTask(
      params.taskType,
      params.requirements
    );
    return {
      content: [
        {
          type: 'text',
          text: pattern,
        },
      ],
    };
  }

• src/tools/tool-definitions.ts:52-78 (schema)

  Tool definition object exported in toolDefinitions array, providing the name, description, and inputSchema for the get_pattern_for_task tool used in ListTools response.

  {
    name: 'get_pattern_for_task',
    description: 'Get the correct pattern to use for a specific task',
    inputSchema: {
      type: 'object',
      properties: {
        taskType: {
          type: 'string',
          enum: ['component', 'api', 'test', 'hook', 'service', 'utility'],
          description: 'Type of task to get pattern for',
        },
        context: {
          type: 'object',
          properties: {
            hasState: { type: 'boolean' },
            hasAsync: { type: 'boolean' },
            needsAuth: { type: 'boolean' },
            complexity: {
              type: 'string',
              enum: ['simple', 'medium', 'complex'],
            },
          },
        },
      },
      required: ['taskType'],
    },
  },

• src/tools/patterns/pattern-provider.ts:6-28 (helper)

  Main helper function implementing the pattern generation logic: loads base patterns by task type, enhances with project context from files, adjusts for requirements, and returns markdown template.

  export async function getPatternForTask(
    taskType: TaskType,
    requirements?: string[]
  ): Promise<string> {
    const projectPath = process.env.PROJECT_PATH || process.cwd();
    const contextPath = join(projectPath, 'CODEBASE-CONTEXT.md');
    const templatePath = join(projectPath, '..', 'PROJECT-TEMPLATE-v10.md');
    
    let basePattern = getBasePattern(taskType);
    
    // Enhance with project-specific patterns
    if (existsSync(contextPath)) {
      const contextContent = readFileSync(contextPath, 'utf-8');
      basePattern = enhanceWithProjectContext(basePattern, contextContent, taskType);
    }
    
    // Add requirements-specific adjustments
    if (requirements && requirements.length > 0) {
      basePattern = adjustForRequirements(basePattern, requirements, taskType);
    }
    
    return basePattern;
  }

• src/tools/patterns/pattern-provider.ts:30-726 (helper)

  Helper function providing hardcoded base markdown patterns for each taskType (component, hook, service, api, test, error-handling) with code examples and checklists.

  function getBasePattern(taskType: TaskType): string {
    const patterns: Record<TaskType, string> = {
      component: `# React Component Pattern
  
  ## Required Structure
  \`\`\`typescript
  import React from 'react';
  import type { ComponentNameProps } from '../types';
  
  interface ComponentNameProps {
    // Define all props with TypeScript types
    required: string;
    optional?: boolean;
    children?: React.ReactNode;
  }
  
  const ComponentName: React.FC<ComponentNameProps> = ({ 
    required,
    optional = false,
    children 
  }) => {
    // 1. Hooks (if needed)
    const [state, setState] = useState<Type>(initialValue);
    
    // 2. Data fetching (if needed)
    const { data, isLoading, error } = useQuery(...);
    
    // 3. Event handlers
    const handleEvent = useCallback(() => {
      // Handle with proper error handling
    }, [dependencies]);
    
    // 4. Effects (if needed)
    useEffect(() => {
      // Effect logic
      return () => {
        // Cleanup
      };
    }, [dependencies]);
    
    // 5. Early returns for states
    if (isLoading) return <LoadingSpinner />;
    if (error) return <ErrorMessage error={error} />;
    if (!data) return <EmptyState />;
    
    // 6. Main render
    return (
      <div className="component-wrapper">
        {/* Component content */}
      </div>
    );
  };
  
  export default ComponentName;
  \`\`\`
  
  ## Checklist
  - [ ] TypeScript interfaces for all props
  - [ ] Loading, error, and empty states handled
  - [ ] Event handlers wrapped in useCallback if passed as props
  - [ ] No inline styles (use className)
  - [ ] Accessibility attributes included
  - [ ] Memoization applied where needed
  `,
  
      hook: `# React Hook Pattern
  
  ## Required Structure
  \`\`\`typescript
  import { useState, useEffect, useCallback, useMemo } from 'react';
  import type { HookReturnType } from '../types';
  
  interface UseHookNameOptions {
    // Hook configuration options
    initialValue?: Type;
    onSuccess?: (data: Type) => void;
    onError?: (error: Error) => void;
  }
  
  interface UseHookNameReturn {
    data: Type | null;
    isLoading: boolean;
    error: Error | null;
    refetch: () => Promise<void>;
  }
  
  export function useHookName(
    param: string,
    options: UseHookNameOptions = {}
  ): UseHookNameReturn {
    // 1. State management
    const [data, setData] = useState<Type | null>(null);
    const [isLoading, setIsLoading] = useState(false);
    const [error, setError] = useState<Error | null>(null);
    
    // 2. Callbacks
    const fetchData = useCallback(async () => {
      try {
        setIsLoading(true);
        setError(null);
        
        const result = await apiCall(param);
        setData(result);
        options.onSuccess?.(result);
      } catch (err) {
        const error = err instanceof Error ? err : new Error('Unknown error');
        setError(error);
        options.onError?.(error);
      } finally {
        setIsLoading(false);
      }
    }, [param, options.onSuccess, options.onError]);
    
    // 3. Effects
    useEffect(() => {
      fetchData();
    }, [fetchData]);
    
    // 4. Memoized values
    const memoizedValue = useMemo(() => {
      // Expensive computations
      return computeValue(data);
    }, [data]);
    
    // 5. Return consistent interface
    return {
      data,
      isLoading,
      error,
      refetch: fetchData,
    };
  }
  \`\`\`
  
  ## Rules
  - [ ] Must start with "use"
  - [ ] Cannot be called conditionally
  - [ ] Must return consistent interface
  - [ ] Handle all edge cases
  - [ ] Clean up effects properly
  `,
  
      service: `# Service Layer Pattern
  
  ## Required Structure
  \`\`\`typescript
  import type { ApiResponse, ServiceError } from '../types';
  
  class ServiceName {
    private baseUrl: string;
    
    constructor(baseUrl: string = process.env.API_URL || '') {
      this.baseUrl = baseUrl;
    }
    
    // GET method example
    async getItems(params?: QueryParams): Promise<ApiResponse<Item[]>> {
      try {
        const queryString = this.buildQueryString(params);
        const response = await fetch(\`\${this.baseUrl}/items\${queryString}\`);
        
        if (!response.ok) {
          throw new ServiceError(\`Failed to fetch items: \${response.statusText}\`, response.status);
        }
        
        const data = await response.json();
        return { data, error: null };
      } catch (error) {
        console.error('ServiceName.getItems error:', error);
        return { 
          data: null, 
          error: this.formatError(error) 
        };
      }
    }
    
    // POST method example
    async createItem(item: CreateItemDto): Promise<ApiResponse<Item>> {
      try {
        const response = await fetch(\`\${this.baseUrl}/items\`, {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
            ...this.getAuthHeaders(),
          },
          body: JSON.stringify(item),
        });
        
        if (!response.ok) {
          const errorData = await response.json();
          throw new ServiceError(errorData.message || 'Failed to create item', response.status);
        }
        
        const data = await response.json();
        return { data, error: null };
      } catch (error) {
        console.error('ServiceName.createItem error:', error);
        return { 
          data: null, 
          error: this.formatError(error) 
        };
      }
    }
    
    // Helper methods
    private buildQueryString(params?: Record<string, any>): string {
      if (!params) return '';
      const filtered = Object.entries(params)
        .filter(([_, value]) => value !== undefined && value !== null)
        .map(([key, value]) => \`\${key}=\${encodeURIComponent(String(value))}\`);
      return filtered.length > 0 ? \`?\${filtered.join('&')}\` : '';
    }
    
    private getAuthHeaders(): Record<string, string> {
      const token = this.getAuthToken();
      return token ? { Authorization: \`Bearer \${token}\` } : {};
    }
    
    private formatError(error: unknown): ServiceError {
      if (error instanceof ServiceError) return error;
      if (error instanceof Error) return new ServiceError(error.message);
      return new ServiceError('An unknown error occurred');
    }
  }
  
  export default new ServiceName();
  \`\`\`
  
  ## Requirements
  - [ ] Consistent error handling
  - [ ] Type-safe responses
  - [ ] Proper HTTP methods
  - [ ] Authentication handling
  - [ ] Request/response logging
  - [ ] Input validation
  `,
  
      api: `# API Endpoint Pattern
  
  ## RESTful API Structure
  \`\`\`typescript
  import type { Request, Response, NextFunction } from 'express';
  import { z } from 'zod';
  
  // Validation schemas
  const createItemSchema = z.object({
    name: z.string().min(1).max(100),
    description: z.string().optional(),
    price: z.number().positive(),
  });
  
  const querySchema = z.object({
    page: z.coerce.number().positive().default(1),
    limit: z.coerce.number().positive().max(100).default(20),
    sort: z.enum(['name', 'price', 'created']).default('created'),
  });
  
  // Controller class
  export class ItemController {
    // GET /items
    async getItems(req: Request, res: Response, next: NextFunction) {
      try {
        // Validate query params
        const query = querySchema.parse(req.query);
        
        // Business logic
        const { items, total } = await itemService.findAll(query);
        
        // Standard response format
        res.json({
          data: items,
          meta: {
            page: query.page,
            limit: query.limit,
            total,
            totalPages: Math.ceil(total / query.limit),
          },
        });
      } catch (error) {
        next(error);
      }
    }
    
    // POST /items
    async createItem(req: Request, res: Response, next: NextFunction) {
      try {
        // Validate body
        const data = createItemSchema.parse(req.body);
        
        // Check permissions
        if (!req.user?.canCreateItems) {
          throw new ForbiddenError('Insufficient permissions');
        }
        
        // Business logic
        const item = await itemService.create(data, req.user.id);
        
        // Created response
        res.status(201).json({
          data: item,
          message: 'Item created successfully',
        });
      } catch (error) {
        if (error instanceof z.ZodError) {
          return res.status(400).json({
            error: {
              code: 'VALIDATION_ERROR',
              message: 'Invalid request data',
              details: error.errors,
            },
          });
        }
        next(error);
      }
    }
    
    // Error handler middleware
    handleError(err: Error, req: Request, res: Response, next: NextFunction) {
      console.error('API Error:', err);
      
      if (err instanceof ValidationError) {
        return res.status(400).json({
          error: {
            code: 'VALIDATION_ERROR',
            message: err.message,
            details: err.details,
          },
        });
      }
      
      if (err instanceof NotFoundError) {
        return res.status(404).json({
          error: {
            code: 'NOT_FOUND',
            message: err.message,
          },
        });
      }
      
      // Generic error
      res.status(500).json({
        error: {
          code: 'INTERNAL_ERROR',
          message: 'An unexpected error occurred',
        },
      });
    }
  }
  \`\`\`
  
  ## API Checklist
  - [ ] Input validation with Zod
  - [ ] Consistent error responses
  - [ ] Proper HTTP status codes
  - [ ] Authentication/authorization
  - [ ] Rate limiting
  - [ ] Request logging
  - [ ] CORS configuration
  `,
  
      test: `# Test Pattern
  
  ## Unit Test Structure
  \`\`\`typescript
  import { render, screen, fireEvent, waitFor } from '@testing-library/react';
  import userEvent from '@testing-library/user-event';
  import { ComponentName } from './ComponentName';
  
  // Mock dependencies
  jest.mock('../hooks/useData', () => ({
    useData: jest.fn(),
  }));
  
  describe('ComponentName', () => {
    // Setup
    const defaultProps = {
      id: '123',
      name: 'Test Item',
      onClick: jest.fn(),
    };
    
    beforeEach(() => {
      jest.clearAllMocks();
    });
    
    // Rendering tests
    describe('Rendering', () => {
      it('should render with required props', () => {
        render(<ComponentName {...defaultProps} />);
        
        expect(screen.getByText('Test Item')).toBeInTheDocument();
        expect(screen.getByRole('button')).toBeEnabled();
      });
      
      it('should render loading state', () => {
        (useData as jest.Mock).mockReturnValue({
          isLoading: true,
          data: null,
          error: null,
        });
        
        render(<ComponentName {...defaultProps} />);
        
        expect(screen.getByTestId('loading-spinner')).toBeInTheDocument();
        expect(screen.queryByText('Test Item')).not.toBeInTheDocument();
      });
      
      it('should render error state', () => {
        const error = new Error('Failed to load');
        (useData as jest.Mock).mockReturnValue({
          isLoading: false,
          data: null,
          error,
        });
        
        render(<ComponentName {...defaultProps} />);
        
        expect(screen.getByText(/Failed to load/)).toBeInTheDocument();
      });
    });
    
    // Interaction tests
    describe('Interactions', () => {
      it('should call onClick when button is clicked', async () => {
        const user = userEvent.setup();
        render(<ComponentName {...defaultProps} />);
        
        await user.click(screen.getByRole('button'));
        
        expect(defaultProps.onClick).toHaveBeenCalledTimes(1);
        expect(defaultProps.onClick).toHaveBeenCalledWith('123');
      });
      
      it('should update state on input change', async () => {
        const user = userEvent.setup();
        render(<ComponentName {...defaultProps} />);
        
        const input = screen.getByLabelText('Name');
        await user.clear(input);
        await user.type(input, 'New Name');
        
        expect(input).toHaveValue('New Name');
      });
    });
    
    // Edge cases
    describe('Edge Cases', () => {
      it('should handle empty data gracefully', () => {
        render(<ComponentName {...defaultProps} items={[]} />);
        
        expect(screen.getByText('No items found')).toBeInTheDocument();
      });
      
      it('should handle missing optional props', () => {
        const { onClick, ...requiredOnly } = defaultProps;
        
        expect(() => render(<ComponentName {...requiredOnly} />)).not.toThrow();
      });
    });
    
    // Accessibility
    describe('Accessibility', () => {
      it('should have proper ARIA labels', () => {
        render(<ComponentName {...defaultProps} />);
        
        expect(screen.getByRole('button')).toHaveAttribute('aria-label');
        expect(screen.getByRole('region')).toHaveAttribute('aria-labelledby');
      });
      
      it('should be keyboard navigable', async () => {
        const user = userEvent.setup();
        render(<ComponentName {...defaultProps} />);
        
        await user.tab();
        expect(screen.getByRole('button')).toHaveFocus();
      });
    });
  });
  \`\`\`
  
  ## Test Requirements
  - [ ] Test all props combinations
  - [ ] Test all states (loading, error, empty, success)
  - [ ] Test user interactions
  - [ ] Test edge cases
  - [ ] Test accessibility
  - [ ] Mock external dependencies
  - [ ] Use meaningful test descriptions
  `,
  
      'error-handling': `# Error Handling Pattern
  
  ## Comprehensive Error Handling
  \`\`\`typescript
  // 1. Custom Error Classes
  export class AppError extends Error {
    constructor(
      message: string,
      public code: string,
      public statusCode: number = 500,
      public isOperational: boolean = true
    ) {
      super(message);
      Object.setPrototypeOf(this, AppError.prototype);
      Error.captureStackTrace(this, this.constructor);
    }
  }
  
  export class ValidationError extends AppError {
    constructor(message: string, public details?: any) {
      super(message, 'VALIDATION_ERROR', 400);
    }
  }
  
  export class NotFoundError extends AppError {
    constructor(resource: string) {
      super(\`\${resource} not found\`, 'NOT_FOUND', 404);
    }
  }
  
  export class AuthenticationError extends AppError {
    constructor(message = 'Authentication failed') {
      super(message, 'AUTH_ERROR', 401);
    }
  }
  
  // 2. Error Boundary Component
  import React, { Component, ErrorInfo, ReactNode } from 'react';
  
  interface Props {
    children: ReactNode;
    fallback?: ReactNode;
    onError?: (error: Error, errorInfo: ErrorInfo) => void;
  }
  
  interface State {
    hasError: boolean;
    error: Error | null;
  }
  
  export class ErrorBoundary extends Component<Props, State> {
    state: State = {
      hasError: false,
      error: null,
    };
    
    static getDerivedStateFromError(error: Error): State {
      return { hasError: true, error };
    }
    
    componentDidCatch(error: Error, errorInfo: ErrorInfo) {
      console.error('Error caught by boundary:', error, errorInfo);
      this.props.onError?.(error, errorInfo);
      
      // Log to error tracking service
      if (process.env.NODE_ENV === 'production') {
        errorTracker.logError(error, {
          componentStack: errorInfo.componentStack,
          props: this.props,
        });
      }
    }
    
    render() {
      if (this.state.hasError) {
        return this.props.fallback || (
          <div className="error-boundary-fallback">
            <h2>Something went wrong</h2>
            <details style={{ whiteSpace: 'pre-wrap' }}>
              {this.state.error?.toString()}
            </details>
          </div>
        );
      }
      
      return this.props.children;
    }
  }
  
  // 3. Async Error Handler
  export async function withErrorHandling<T>(
    operation: () => Promise<T>,
    context: string
  ): Promise<{ data: T | null; error: Error | null }> {
    try {
      const data = await operation();
      return { data, error: null };
    } catch (error) {
      console.error(\`Error in \${context}:\`, error);
      
      // Transform known errors
      if (error instanceof AppError) {
        return { data: null, error };
      }
      
      // Handle fetch errors
      if (error instanceof TypeError && error.message.includes('fetch')) {
        return {
          data: null,
          error: new AppError('Network error', 'NETWORK_ERROR', 0),
        };
      }
      
      // Generic error
      return {
        data: null,
        error: new AppError(
          error instanceof Error ? error.message : 'Unknown error',
          'UNKNOWN_ERROR'
        ),
      };
    }
  }
  
  // 4. React Hook with Error Handling
  export function useErrorHandler() {
    const [error, setError] = useState<Error | null>(null);
    
    const resetError = useCallback(() => setError(null), []);
    
    const handleError = useCallback((error: Error) => {
      console.error('Error handled:', error);
      setError(error);
      
      // Show user notification
      if (error instanceof AppError && error.isOperational) {
        showNotification({
          type: 'error',
          message: error.message,
        });
      } else {
        showNotification({
          type: 'error',
          message: 'An unexpected error occurred',
        });
      }
    }, []);
    
    return { error, resetError, handleError };
  }
  
  // 5. API Error Response Handler
  export function handleApiError(error: unknown): Response {
    console.error('API Error:', error);
    
    if (error instanceof ValidationError) {
      return new Response(
        JSON.stringify({
          error: {
            code: error.code,
            message: error.message,
            details: error.details,
          },
        }),
        { status: error.statusCode, headers: { 'Content-Type': 'application/json' } }
      );
    }
    
    if (error instanceof AppError) {
      return new Response(
        JSON.stringify({
          error: {
            code: error.code,
            message: error.message,
          },
        }),
        { status: error.statusCode, headers: { 'Content-Type': 'application/json' } }
      );
    }
    
    // Unknown error
    return new Response(
      JSON.stringify({
        error: {
          code: 'INTERNAL_ERROR',
          message: 'An unexpected error occurred',
        },
      }),
      { status: 500, headers: { 'Content-Type': 'application/json' } }
    );
  }
  \`\`\`
  
  ## Error Handling Checklist
  - [ ] Custom error classes for different scenarios
  - [ ] Error boundaries for React components
  - [ ] Async operation error handling
  - [ ] User-friendly error messages
  - [ ] Error logging and tracking
  - [ ] Network error handling
  - [ ] Form validation errors
  - [ ] API error responses
  `
    };
  
    return patterns[taskType];
  }