CodeCompass MCP

Instructions

Implementation Reference

• src/index.ts:863-964 (handler)

  Main execution handler for 'explain_code' tool. Fetches repo info and files, generates AI explanation using OpenAI service based on type (overview, detailed, architecture, etc.).

  async function handleExplainCode(args: any) {
    try {
      const { url, file_paths, explanation_type = 'overview', options = {} } = args;
      
      // Get repository info and code content
      const repoInfo = await githubService.getRepositoryInfo(url);
      let filesToExplain: 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);
            filesToExplain[filePath] = content;
          } catch (error) {
            // Skip files that can't be fetched
          }
        }
      } else {
        // Use key files from repository
        filesToExplain = repoInfo.keyFiles;
      }
      
      if (Object.keys(filesToExplain).length === 0) {
        throw new Error('No files found to explain');
      }
      
      // Generate AI explanation based on type
      let aiExplanation: string;
      let aiExplanationResult: { content: string; modelUsed: string; warning?: string };
      
      switch (explanation_type) {
        case 'architecture':
          aiExplanation = await openaiService.explainArchitecture(url, repoInfo);
          // For architecture, create a mock result for consistency
          aiExplanationResult = {
            content: aiExplanation,
            modelUsed: options.ai_model || 'anthropic/claude-3.5-sonnet',
            warning: undefined
          };
          break;
        case 'overview':
        case 'detailed':
        case 'tutorial':
        case 'integration':
        default:
          // Create a prompt for the specific explanation type
          const codeContext = Object.entries(filesToExplain)
            .map(([path, content]) => `--- ${path} ---\n${content}`)
            .join('\n\n');
          
          const prompt = `Please provide a ${explanation_type} explanation of this ${repoInfo.language || 'code'} repository:
  
  Repository: ${repoInfo.name}
  Description: ${repoInfo.description || 'No description'}
  Language: ${repoInfo.language || 'Multiple'}
  
  Code:
  ${codeContext}
  
  Please focus on:
  ${options.focus_on_patterns ? '- Design patterns and architecture' : ''}
  ${options.include_examples ? '- Code examples and usage' : ''}
  ${options.include_diagrams ? '- Visual diagrams where helpful' : ''}
  
  Target audience: ${options.target_audience || 'intermediate'}`;
          
          aiExplanationResult = await openaiService.chatWithRepository(url, prompt, undefined, options.ai_model);
          aiExplanation = aiExplanationResult.content;
          break;
      }
      
      const result = {
        repository: {
          name: repoInfo.name,
          description: repoInfo.description,
          language: repoInfo.language,
          owner: repoInfo.owner,
        },
        explanation: {
          type: explanation_type,
          files_analyzed: Object.keys(filesToExplain),
          ai_model_used: aiExplanationResult.modelUsed,
          ai_model_requested: options.ai_model || 'auto',
          target_audience: options.target_audience || 'intermediate',
          content: aiExplanation,
          timestamp: new Date().toISOString(),
          model_warning: aiExplanationResult.warning,
        },
        metadata: {
          file_count: Object.keys(filesToExplain).length,
          total_lines: Object.values(filesToExplain).reduce((sum, content) => sum + content.split('\n').length, 0),
        },
      };
      
      const response = createResponse(result);
      return formatToolResponse(response);
    } catch (error) {
      const response = createResponse(null, error);
      return formatToolResponse(response);
    }
  }

• src/tools/consolidated.ts:402-457 (schema)

  Tool definition including name, description, and input schema for validation.

  {
    name: 'explain_code',
    description: '📚 AI-powered code explanation generating human-readable documentation, tutorials, and architectural insights. Transforms technical analysis into accessible explanations.',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'GitHub repository URL',
        },
        file_paths: {
          type: 'array',
          items: { type: 'string' },
          description: 'Specific files to explain (optional - explains key files if not specified)',
        },
        explanation_type: {
          type: 'string',
          enum: ['overview', 'detailed', 'architecture', 'tutorial', 'integration'],
          description: 'Type of explanation to generate',
          default: 'overview',
        },
        options: {
          type: 'object',
          properties: {
            ai_model: {
              type: 'string',
              description: 'AI model to use for explanation (OpenRouter models). Use "auto" for intelligent model selection',
              default: 'auto',
            },
            target_audience: {
              type: 'string',
              enum: ['beginner', 'intermediate', 'advanced'],
              description: 'Target audience for explanation',
              default: 'intermediate',
            },
            include_examples: {
              type: 'boolean',
              description: 'Include code examples in explanations',
              default: true,
            },
            include_diagrams: {
              type: 'boolean',
              description: 'Include ASCII diagrams where helpful',
              default: true,
            },
            focus_on_patterns: {
              type: 'boolean',
              description: 'Focus on design patterns and architecture',
              default: true,
            },
          },
        },
      },
      required: ['url'],
    },
  },

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

  Registers the consolidatedTools array (including 'explain_code') for the ListToolsRequestHandler.

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

• src/index.ts:277-279 (registration)

  Dispatch case in CallToolRequestHandler switch statement that routes 'explain_code' calls to the handler function.

  case 'explain_code':
    result = await handleExplainCode(args);
    break;