CodeCompass MCP

Instructions

Implementation Reference

• src/tools/consolidated.ts:46-90 (schema)

  Defines the Tool object for 'get_file_tree' including name, description, and detailed inputSchema with url required and various filtering options.

  {
    name: 'get_file_tree',
    description: '🌳 Get complete directory structure and file listing with filtering options. Focused on file system structure without content analysis.',
    inputSchema: {
      type: 'object',
      properties: {
        url: {
          type: 'string',
          description: 'GitHub repository URL',
        },
        options: {
          type: 'object',
          properties: {
            max_depth: {
              type: 'number',
              description: 'Maximum directory depth to traverse',
              default: 10,
            },
            include_hidden: {
              type: 'boolean',
              description: 'Include hidden files and directories',
              default: false,
            },
            file_extensions: {
              type: 'array',
              items: { type: 'string' },
              description: 'Filter by file extensions (e.g., [".js", ".ts"])',
            },
            exclude_paths: {
              type: 'array',
              items: { type: 'string' },
              description: 'Paths to exclude from listing',
              default: ['node_modules', 'dist', 'build', '.git'],
            },
            include_file_info: {
              type: 'boolean',
              description: 'Include file metadata (size, modified date)',
              default: true,
            },
          },
        },
      },
      required: ['url'],
    },
  },

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

  Registers the consolidatedTools array (which includes get_file_tree schema) in response to MCP ListToolsRequestSchema.

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

• src/index.ts:260-262 (registration)

  Dispatches calls to 'get_file_tree' tool name to the handleGetFileTree handler function in the main CallToolRequestSchema switch statement.

  case 'search_repository':
    result = await handleSearchRepository(args);
    break;

• src/index.ts:350-371 (handler)

  Primary MCP tool handler that processes input arguments, calls GitHubService.getFileTree, formats response with metadata, and handles errors using standardized response format.

  async function handleGetFileTree(args: any) {
    const { url, options = {} } = args;
    
    try {
      const tree = await githubService.getFileTree(url);
      
      const response = {
        file_tree: tree,
        metadata: {
          max_depth: options.max_depth || 10,
          include_hidden: options.include_hidden || false,
          total_files: tree.length,
          filtered_extensions: options.file_extensions || null,
          excluded_paths: options.exclude_paths || ['node_modules', 'dist', 'build', '.git']
        }
      };
      
      return formatToolResponse(createResponse(response, null, { tool: 'get_file_tree', url }));
    } catch (error) {
      return formatToolResponse(createResponse(null, error, { tool: 'get_file_tree', url }));
    }
  }

• src/services/github.ts:193-219 (helper)

  GitHubService method that fetches the recursive git tree from GitHub API, parses repo details, builds structured FileNode tree using buildFileTree helper, and supports optional path filtering.

  async getFileTree(url: string, path?: string): Promise<FileNode[]> {
    const { owner, repo } = this.parseGitHubUrl(url);
  
    try {
      const { data: repoData } = await this.octokit.rest.repos.get({
        owner,
        repo,
      });
  
      const { data: treeData } = await this.octokit.rest.git.getTree({
        owner,
        repo,
        tree_sha: repoData.default_branch,
        recursive: 'true',
      });
  
      const fileTree = this.buildFileTree(treeData.tree);
      
      if (path) {
        return this.filterTreeByPath(fileTree, path);
      }
      
      return fileTree;
    } catch (error: any) {
      throw new Error(`Failed to fetch file tree: ${error.message}`);
    }
  }