CodeCompass MCP

Instructions

Implementation Reference

• src/index.ts:428-514 (handler)

  The main handler function for the 'get_file_content' tool. Validates input file paths, fetches contents concurrently from GitHub using GitHubService, processes files in batch with metadata extraction and truncation, handles errors, and returns a structured response with file contents, summaries, and statistics.
  async function handleGetFileContent(args: any) { try { const { url, file_paths, options = {} } = args; // Validate file paths first const pathValidationErrors: string[] = []; for (const filePath of file_paths) { const validation = validateFilePath(filePath); if (!validation.valid) { pathValidationErrors.push(`${filePath}: ${validation.error}`); } } if (pathValidationErrors.length > 0) { throw new Error(`Invalid file paths detected:\n${pathValidationErrors.join('\n')}`); } // Fetch file contents from GitHub const fileContents: Array<{ path: string; content: string }> = []; const fetchErrors: Record<string, string> = {}; for (const filePath of file_paths) { try { const content = await githubService.getFileContent(url, filePath); fileContents.push({ path: filePath, content }); } catch (error: any) { fetchErrors[filePath] = error.message; } } // Process files using batch processing const batchOptions = { maxConcurrent: options.max_concurrent || config.limits.maxConcurrentRequests, continueOnError: options.continue_on_error !== false, validatePaths: false, // Already validated above includeMetadata: options.include_metadata !== false, maxFileSize: options.max_size || config.limits.maxFileSize, allowedExtensions: options.file_extensions, excludePatterns: options.exclude_patterns, }; const batchResult = await batchProcessFiles(fileContents, batchOptions); // Combine results with fetch errors const results: Record<string, any> = {}; // Add successful and failed processing results batchResult.results.forEach(result => { if (result.success) { results[result.filePath] = { content: result.content, metadata: result.metadata, size: result.metadata?.size || 0, truncated: result.metadata?.size ? result.metadata.size > (options.max_size || config.limits.maxFileSize) : false, }; } else { results[result.filePath] = { error: result.error?.message || 'Processing failed', details: result.error?.details, }; } }); // Add fetch errors Object.entries(fetchErrors).forEach(([filePath, error]) => { results[filePath] = { error: `Failed to fetch: ${error}`, }; }); // Add processing statistics const statistics = getFileStatistics(batchResult.results.filter(r => r.success)); const response = createResponse({ files: results, summary: { ...batchResult.summary, fetchErrors: Object.keys(fetchErrors).length, statistics, }, }); return formatToolResponse(response); } catch (error) { const response = createResponse(null, error, { tool: 'get_file_content', url: args.url }); return formatToolResponse(response); }
• src/tools/consolidated.ts:148-213 (registration)

  Tool registration definition including name, detailed description, and complete input schema for validation. This object is exported as part of consolidatedTools and served via ListToolsRequestSchema handler.
  { name: 'get_file_content', description: '📁 Retrieve content of specific files with smart truncation and batch processing capabilities.\n\n⚠️ FEATURES:\n• Batch processing with concurrent file retrieval\n• Automatic file validation and security checks\n• Rich metadata extraction (file type, language, size, line count)\n• Configurable processing limits and error handling\n• Support for multiple file formats with type detection', inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'GitHub repository URL', }, file_paths: { type: 'array', items: { type: 'string' }, description: 'Paths to files to retrieve (supports batch processing)', }, options: { type: 'object', properties: { max_size: { type: 'number', description: 'Maximum file size in bytes', default: 100000, }, include_metadata: { type: 'boolean', description: 'Include file metadata (size, modified date, etc.)', default: false, }, truncate_large_files: { type: 'boolean', description: 'Truncate files larger than max_size', default: true, }, max_concurrent: { type: 'number', description: 'Maximum concurrent file processing', default: 5, minimum: 1, maximum: 20, }, continue_on_error: { type: 'boolean', description: 'Continue processing other files if one fails', default: true, }, file_extensions: { type: 'array', items: { type: 'string' }, description: 'Only process files with these extensions (e.g., [".js", ".ts"])', }, exclude_patterns: { type: 'array', items: { type: 'string' }, description: 'Exclude files matching these regex patterns', }, format: { type: 'string', enum: ['raw', 'parsed', 'summary'], description: 'Format for file content', default: 'raw', }, }, }, }, required: ['url', 'file_paths'], },
• src/tools/consolidated.ts:151-212 (schema)

  Detailed input schema defining parameters for the tool: repository URL, array of file paths, and extensive options for processing limits, metadata, truncation, concurrency, filtering, and output format.
  inputSchema: { type: 'object', properties: { url: { type: 'string', description: 'GitHub repository URL', }, file_paths: { type: 'array', items: { type: 'string' }, description: 'Paths to files to retrieve (supports batch processing)', }, options: { type: 'object', properties: { max_size: { type: 'number', description: 'Maximum file size in bytes', default: 100000, }, include_metadata: { type: 'boolean', description: 'Include file metadata (size, modified date, etc.)', default: false, }, truncate_large_files: { type: 'boolean', description: 'Truncate files larger than max_size', default: true, }, max_concurrent: { type: 'number', description: 'Maximum concurrent file processing', default: 5, minimum: 1, maximum: 20, }, continue_on_error: { type: 'boolean', description: 'Continue processing other files if one fails', default: true, }, file_extensions: { type: 'array', items: { type: 'string' }, description: 'Only process files with these extensions (e.g., [".js", ".ts"])', }, exclude_patterns: { type: 'array', items: { type: 'string' }, description: 'Exclude files matching these regex patterns', }, format: { type: 'string', enum: ['raw', 'parsed', 'summary'], description: 'Format for file content', default: 'raw', }, }, }, }, required: ['url', 'file_paths'],
• src/services/github.ts:221-256 (helper)

  Core helper method in GitHubService that retrieves individual file content from GitHub repository using Octokit REST API. Includes caching, retry logic with rate limit handling, base64 decoding, and comprehensive error handling for 404s and rate limits.
  async getFileContent(url: string, filePath: string): Promise<string> { const { owner, repo } = this.parseGitHubUrl(url); const cacheKey = this.getCacheKey('getFileContent', { owner, repo, filePath }); // Check cache first const cached = this.getCachedResult<string>(cacheKey); if (cached) { return cached; } try { const { data } = await this.withRetry(() => this.octokit.rest.repos.getContent({ owner, repo, path: filePath, }) ); if ('content' in data) { const content = Buffer.from(data.content, 'base64').toString('utf-8'); this.setCachedResult(cacheKey, content); return content; } throw new Error('File content not available'); } catch (error: any) { if (error.status === 404) { throw new Error(`File not found: ${filePath}`); } if (error.status === 403 && error.message.includes('rate limit')) { throw new Error(`GitHub API rate limit exceeded. Please provide a GitHub token for higher limits. Error: ${error.message}`); } throw new Error(`Failed to fetch file content: ${error.message}`); } }