CodeCompass MCP

Instructions

Implementation Reference

• src/index.ts:966-1034 (handler)

  Main execution handler for the suggest_improvements tool. Fetches repository data and files, then calls OpenAI service to generate refactoring suggestions.

  async function handleSuggestImprovements(args: any) {
    try {
      const { url, file_paths, refactoring_goals = ['modernize', 'maintainability'], target_framework, options = {} } = args;
      
      // Get repository info and code content
      const repoInfo = await githubService.getRepositoryInfo(url);
      let filesToRefactor: Record<string, string> = {};
      
      if (file_paths && file_paths.length > 0) {
        // Get specific files
        for (const filePath of file_paths) {
          try {
            const content = await githubService.getFileContent(url, filePath);
            filesToRefactor[filePath] = content;
          } catch (error) {
            // Skip files that can't be fetched
          }
        }
      } else {
        // Use key files from repository
        filesToRefactor = repoInfo.keyFiles;
      }
      
      if (Object.keys(filesToRefactor).length === 0) {
        throw new Error('No files found to analyze for refactoring');
      }
      
      // Generate AI refactoring suggestions
      const targetProject = {
        framework: target_framework || 'Not specified',
        language: repoInfo.language || 'javascript',
        constraints: [],
        timeline: 'Not specified',
      };
      
      const aiSuggestionsResult = await openaiService.suggestRefactoringPlan(url, targetProject, refactoring_goals, options.ai_model);
      
      const result = {
        repository: {
          name: repoInfo.name,
          description: repoInfo.description,
          language: repoInfo.language,
          owner: repoInfo.owner,
        },
        refactoring: {
          goals: refactoring_goals,
          target_framework: target_framework,
          files_analyzed: Object.keys(filesToRefactor),
          ai_model_used: aiSuggestionsResult.modelUsed,
          ai_model_requested: options.ai_model || 'auto',
          suggestions: aiSuggestionsResult.content,
          priority_level: options.priority_level || 'medium',
          timestamp: new Date().toISOString(),
          model_warning: aiSuggestionsResult.warning,
        },
        metadata: {
          file_count: Object.keys(filesToRefactor).length,
          total_lines: Object.values(filesToRefactor).reduce((sum, content) => sum + content.split('\n').length, 0),
          estimated_effort: options.estimate_effort ? 'Will be provided by AI' : null,
        },
      };
      
      const response = createResponse(result);
      return formatToolResponse(response);
    } catch (error) {
      const response = createResponse(null, error);
      return formatToolResponse(response);
    }
  }

• src/tools/consolidated.ts:459-516 (schema)

  Input schema and tool definition for suggest_improvements, including parameters for repository URL, files, goals, and options.

  {
    name: 'suggest_improvements',
    description: '💡 AI-powered improvement suggestions providing strategic refactoring recommendations, modernization plans, and architectural enhancements.',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'GitHub repository URL',
        },
        file_paths: {
          type: 'array',
          items: { type: 'string' },
          description: 'Specific files to analyze for improvements (optional - analyzes key files if not specified)',
        },
        improvement_goals: {
          type: 'array',
          items: {
            type: 'string',
            enum: ['modernize', 'performance', 'maintainability', 'security', 'readability', 'testability'],
          },
          description: 'Goals for improvement suggestions',
          default: ['modernize', 'maintainability'],
        },
        target_framework: {
          type: 'string',
          description: 'Target framework for improvement suggestions',
        },
        options: {
          type: 'object',
          properties: {
            ai_model: {
              type: 'string',
              description: 'AI model to use for suggestions (OpenRouter models). Use "auto" for intelligent model selection',
              default: 'auto',
            },
            include_code_examples: {
              type: 'boolean',
              description: 'Include before/after code examples',
              default: true,
            },
            priority_level: {
              type: 'string',
              enum: ['low', 'medium', 'high'],
              description: 'Minimum priority level for suggestions',
              default: 'medium',
            },
            estimate_effort: {
              type: 'boolean',
              description: 'Include effort estimates for improvement tasks',
              default: true,
            },
          },
        },
      },
      required: ['url'],
    },
  },

• src/index.ts:236-240 (registration)

  Tool registration via returning consolidatedTools (which includes suggest_improvements) in ListToolsRequestSchema handler.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    return {
      tools: consolidatedTools,
    };
  });

• src/index.ts:280-282 (registration)

  Dispatcher switch case that routes calls to the suggest_improvements handler.

  case 'suggest_improvements':
    result = await handleSuggestImprovements(args);
    break;