CodeCompass MCP

Instructions

Implementation Reference

• src/tools/consolidated.ts:11-44 (schema)

  Tool schema definition including input validation schema for get_repository_info.

  {
    name: 'get_repository_info',
    description: '📊 Get basic repository metadata, statistics, and key information. Atomic tool focused purely on repository-level data without file content analysis.',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'GitHub repository URL (e.g., https://github.com/owner/repo)',
        },
        options: {
          type: 'object',
          properties: {
            include_stats: {
              type: 'boolean',
              description: 'Include repository statistics (stars, forks, etc.)',
              default: true,
            },
            include_languages: {
              type: 'boolean',
              description: 'Include language breakdown',
              default: true,
            },
            include_topics: {
              type: 'boolean',
              description: 'Include repository topics and tags',
              default: true,
            },
          },
        },
      },
      required: ['url'],
    },
  },

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

  Registration of all tools including get_repository_info via consolidatedTools export.

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

• src/index.ts:254-256 (registration)

  Dispatch registration in CallToolRequestSchema handler switch statement.

  case 'get_repository_info':
    result = await handleGetRepositoryInfo(args);
    break;

• src/index.ts:312-348 (handler)

  Primary MCP tool handler: extracts parameters, calls GitHubService.getRepositoryInfo, conditionally includes stats/languages, formats and returns standardized ToolResponse.

  async function handleGetRepositoryInfo(args: any) {
    const { url, options = {} } = args;
    
    try {
      const info = await githubService.getRepositoryInfo(url);
      
      const response = {
        repository: {
          name: info.name,
          description: info.description,
          owner: info.owner,
          language: info.language,
          defaultBranch: info.defaultBranch,
          createdAt: info.createdAt,
          updatedAt: info.updatedAt,
          license: info.license,
          ...(options.include_stats && {
            stats: {
              stars: info.stars,
              fileCount: info.fileCount,
              lineCount: info.lineCount,
            }
          }),
          ...(options.include_languages && {
            languages: info.languages
          }),
          ...(options.include_topics && {
            topics: []  // Add topics to GitHubRepoInfo interface if needed
          })
        }
      };
      
      return formatToolResponse(createResponse(response, null, { tool: 'get_repository_info', url }));
    } catch (error) {
      return formatToolResponse(createResponse(null, error, { tool: 'get_repository_info', url }));
    }
  }

• src/services/github.ts:89-191 (helper)

  Core helper method in GitHubService: fetches repo metadata via Octokit, handles caching/retry/rate limits, builds file tree, fetches key files, computes stats and returns GitHubRepoInfo.

  async getRepositoryInfo(url: string): Promise<GitHubRepoInfo> {
    const { owner, repo } = this.parseGitHubUrl(url);
    const cacheKey = this.getCacheKey('getRepositoryInfo', { owner, repo });
    
    // Check cache first
    const cached = this.getCachedResult<GitHubRepoInfo>(cacheKey);
    if (cached) {
      return cached;
    }
  
    try {
      // Get repository info with retry logic
      const { data: repoData } = await this.withRetry(() => 
        this.octokit.rest.repos.get({ owner, repo })
      );
  
      // Get languages with retry logic
      const { data: languages } = await this.withRetry(() => 
        this.octokit.rest.repos.listLanguages({ owner, repo })
      );
  
      // Get file tree with retry logic and fallback for rate limits
      let fileTree: FileNode[] = [];
      let fileCount = 0;
      let keyFiles: Record<string, string> = {};
      
      try {
        const { data: treeData } = await this.withRetry(() => 
          this.octokit.rest.git.getTree({
            owner,
            repo,
            tree_sha: repoData.default_branch,
            recursive: 'true',
          })
        );
  
        fileTree = this.buildFileTree(treeData.tree);
        fileCount = treeData.tree.filter(item => item.type === 'blob').length;
        
        // Fetch key files for comprehensive analysis
        console.log(`Fetching key files for ${repoData.name}...`);
        keyFiles = await this.getKeyRepositoryFiles(url, fileTree);
        console.log(`Fetched ${Object.keys(keyFiles).length} key files`);
      } catch (treeError: any) {
        // If we hit rate limits on tree API, try to get basic structure
        console.warn('Failed to fetch full file tree, falling back to basic analysis');
        
        // Try to get at least README and package.json
        try {
          const basicFiles = ['README.md', 'README.txt', 'README', 'package.json'];
          for (const fileName of basicFiles) {
            try {
              const content = await this.getFileContent(url, fileName);
              keyFiles[fileName] = content;
            } catch (fileError) {
              // Skip files that don't exist
            }
          }
        } catch (fallbackError) {
          console.warn('Failed to fetch basic files, continuing with minimal info');
        }
      }
      
      // Calculate actual line count from fetched files
      const actualLineCount = Object.values(keyFiles).reduce((total, content) => {
        return total + content.split('\n').length;
      }, 0);
      
      // Estimate total line count based on fetched files ratio
      const estimatedLineCount = actualLineCount > 0 
        ? Math.floor((actualLineCount / Math.max(1, Object.keys(keyFiles).length)) * Math.max(fileCount, 10))
        : Math.floor(Math.max(fileCount, 10) * 50);
  
      const result: GitHubRepoInfo = {
        name: repoData.name,
        description: repoData.description,
        owner: repoData.owner.login,
        stars: repoData.stargazers_count,
        language: repoData.language,
        languages,
        fileCount,
        lineCount: estimatedLineCount,
        fileTree,
        keyFiles,
        license: repoData.license?.name,
        defaultBranch: repoData.default_branch,
        createdAt: repoData.created_at,
        updatedAt: repoData.updated_at,
      };
  
      // Cache the result
      this.setCachedResult(cacheKey, result);
      return result;
    } catch (error: any) {
      if (error.status === 404) {
        throw new Error('Repository not found or not accessible');
      }
      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 repository: ${error.message}`);
    }
  }