AI Agent Template MCP Server

Instructions

Implementation Reference

• src/tools/workspace/create-conversation-starters.ts:22-72 (handler)

  Main handler function that executes the tool logic: generates and writes conversation starters file based on codebase analysis, recent work, and configuration.

  export async function createConversationStarters(
    config: ConversationStarterConfig
  ): Promise<ConversationStarterResult> {
    const result: ConversationStarterResult = {
      success: false,
      filePath: '',
      message: '',
      tokenCount: 0,
      filesCreated: [],
    };
  
    try {
      // Check if analysis has been completed
      const analysisId = config.analysisId || global.latestAnalysisId;
      if (!analysisId || !global.codebaseAnalysis?.[analysisId]) {
        throw new Error('Codebase analysis must be completed first. Run analyze_codebase_deeply tool.');
      }
  
      const analysis: DeepAnalysisResult = global.codebaseAnalysis[analysisId];
      
      // Check for existing git history to find recent work
      const recentWork = await getRecentWork(config.projectPath);
      
      // Generate conversation starters based on analysis and config
      const starters = generateConversationStarters(analysis, config, recentWork);
      
      // Estimate token count
      result.tokenCount = Math.ceil(starters.length / 4);
      
      // Apply token limit if specified
      let finalContent = starters;
      if (config.tokenLimit && result.tokenCount > config.tokenLimit) {
        finalContent = trimToTokenLimit(starters, config.tokenLimit);
        result.tokenCount = config.tokenLimit;
      }
      
      // Write to file
      const filePath = join(config.projectPath, 'agent-context', 'conversation-starters.md');
      writeFileSync(filePath, finalContent);
      
      result.success = true;
      result.filePath = filePath;
      result.filesCreated = [filePath];
      result.message = `Created conversation-starters.md (${result.tokenCount} tokens) with project context and ${config.includeQuickTasks ? 'quick tasks' : 'overview only'}`;
    } catch (error) {
      result.success = false;
      result.message = `Failed to create conversation starters: ${error}`;
    }
  
    return result;
  }

• src/tools/index.ts:232-251 (registration)

  Tool registration and execution handler in the main switch statement, including input validation schema and call to the handler function.

  case 'create_conversation_starters': {
    const params = z.object({
      projectPath: z.string(),
      analysisId: z.string().optional(),
      includeQuickTasks: z.boolean().optional(),
      includeCurrentWork: z.boolean().optional(),
      tokenLimit: z.number().optional(),
      customTasks: z.array(z.string()).optional(),
    }).parse(args);
    
    const result = await createConversationStarters(params);
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/tools/tool-definitions.ts:239-273 (schema)

  Tool schema definition including name, description, and inputSchema for validation in the tool list.

  {
    name: 'create_conversation_starters',
    description: 'Create conversation starters to help AI understand project context quickly',
    inputSchema: {
      type: 'object',
      properties: {
        projectPath: {
          type: 'string',
          description: 'Path to the project directory',
        },
        analysisId: {
          type: 'string',
          description: 'Analysis ID from analyze_codebase_deeply',
        },
        includeQuickTasks: {
          type: 'boolean',
          description: 'Include common quick tasks section',
        },
        includeCurrentWork: {
          type: 'boolean',
          description: 'Include recent git commits',
        },
        tokenLimit: {
          type: 'number',
          description: 'Maximum tokens for the file',
        },
        customTasks: {
          type: 'array',
          items: { type: 'string' },
          description: 'Custom quick tasks to include',
        },
      },
      required: ['projectPath'],
    },
  },

• src/tools/index.ts:16-16 (registration)

  Import statement registering the handler function for use in the tool execution switch.

  import { createConversationStarters } from './workspace/create-conversation-starters.js';

• src/tools/workspace/create-conversation-starters.ts:74-223 (helper)

  Helper function that generates the actual conversation starters content from the analysis data.

  function generateConversationStarters(
    analysis: DeepAnalysisResult,
    config: ConversationStarterConfig,
    recentWork: string[]
  ): string {
    const { summary, patterns, structure, recommendations } = analysis;
    const projectName = analysis.projectPath.split('/').pop() || 'Project';
    
    let content = `# 🚀 AI Context Loading Instructions
  
  ## Quick Start (Copy & Paste)
  \`\`\`
  I'm working on ${projectName}, a ${summary.frameworks.join(' + ')} application. 
  Please load and review these context files in order:
  1. agent-context/CODEBASE-CONTEXT.md - patterns and conventions
  2. agent-context/PROJECT-TEMPLATE.md - architecture overview
  3. agent-context/.context7.yaml - API verification
  \`\`\`
  
  ## Project Overview
  - **Tech Stack**: ${summary.techStack.join(', ')}
  - **Total Files**: ${summary.totalFiles}
  - **Primary Language**: ${summary.primaryLanguage}
  - **Testing**: ${summary.testingFrameworks.join(', ') || 'Not configured'}
  
  ## Key Patterns to Follow
  - **Components**: ${patterns.components.style} with ${patterns.components.propsPattern}
  - **State**: ${patterns.stateManagement.join(', ') || 'Local state only'}
  - **Styling**: ${patterns.styling}
  - **Imports**: ${patterns.imports.style} style preferred
  
  ## Project Structure
  ${Object.entries(structure.directories)
    .filter(([_, info]: [string, any]) => info.fileCount > 5)
    .slice(0, 6)
    .map(([path, info]: [string, any]) => `- **${path}**: ${info.purpose}`)
    .join('\n')}
  `;
  
    // Add recent work section if requested and available
    if (config.includeCurrentWork && recentWork.length > 0) {
      content += `\n## Recent Work (Last 7 days)
  ${recentWork.slice(0, 5).map(commit => `- ${commit}`).join('\n')}
  `;
    }
  
    // Add quick tasks section if requested
    if (config.includeQuickTasks) {
      content += `\n## Common Quick Tasks
  ${generateQuickTasks(analysis, config.customTasks)}
  `;
    }
  
    // Add recommendations if any
    if (recommendations.length > 0) {
      content += `\n## Important Recommendations
  ${recommendations.slice(0, 3).map(rec => `- ${rec}`).join('\n')}
  `;
    }
  
    // Add token optimization tip
    content += `\n## Token Optimization
  - For simple tasks: Load only CODEBASE-CONTEXT.md
  - For new features: Load PROJECT-TEMPLATE.md + CODEBASE-CONTEXT.md
  - For debugging: Add .context7.yaml for import verification
  - For architecture: Load all three files
  
  ## Starting a Task
  After loading context, you can say:
  - "Create a new component called..."
  - "Add a feature that..."
  - "Fix the issue with..."
  - "Refactor the..."
  - "Add tests for..."
  `;
  
    // Add evidence files section
    if (analysis.evidenceFiles.length > 0) {
      content += `\n## Example Files to Reference
  ${analysis.evidenceFiles.slice(0, 5).map(ef => `- ${ef.path}: ${ef.purpose}`).join('\n')}
  `;
    }
  
    return content;
  }
  
  function generateQuickTasks(analysis: DeepAnalysisResult, customTasks?: string[]): string {
    const defaultTasks = [
      `Create a new ${analysis.patterns.components.style} component with TypeScript`,
      `Add a new API endpoint following existing patterns`,
      `Write tests for a component using ${analysis.summary.testingFrameworks[0] || 'Jest'}`,
      `Add error handling to an existing feature`,
      `Implement a new hook following the use* pattern`,
    ];
    
    const tasks = customTasks && customTasks.length > 0 ? customTasks : defaultTasks;
    
    return tasks.map((task, i) => `${i + 1}. ${task}`).join('\n');
  }
  
  async function getRecentWork(projectPath: string): Promise<string[]> {
    try {
      // Check if it's a git repository
      const gitPath = join(projectPath, '.git');
      if (!existsSync(gitPath)) {
        return [];
      }
      
      // Get recent commits (this is a simplified version)
      // In a real implementation, you'd use git commands or a git library
      const { execSync } = await import('child_process');
      const recentCommits = execSync(
        'git log --oneline --since="7 days ago" --max-count=10',
        { cwd: projectPath, encoding: 'utf-8' }
      ).trim().split('\n').filter(Boolean);
      
      return recentCommits;
    } catch (error) {
      // If git commands fail, return empty array
      return [];
    }
  }
  
  function trimToTokenLimit(content: string, tokenLimit: number): string {
    // Simple token estimation: 1 token ≈ 4 characters
    const charLimit = tokenLimit * 4;
    
    if (content.length <= charLimit) {
      return content;
    }
    
    // Trim content intelligently by sections
    const sections = content.split('\n## ');
    let trimmedContent = sections[0]; // Keep the header
    let currentLength = trimmedContent.length;
    
    // Add sections until we hit the limit
    for (let i = 1; i < sections.length; i++) {
      const section = '\n## ' + sections[i];
      if (currentLength + section.length > charLimit) {
        // Add a truncation notice
        trimmedContent += '\n\n*[Content trimmed to fit token limit]*';
        break;
      }
      trimmedContent += section;
      currentLength += section.length;
    }
    
    return trimmedContent;
  }