githubViewRepoStructure
Read-onlyIdempotent
Explore GitHub repository directory structures to understand layout, locate files, and analyze configurations by navigating through folders with controlled depth parameters.
Instructions
Display directory structure
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| queries | Yes | Research queries for githubViewRepoStructure (1-3 queries per call for optimal resource management). Review schema before use for optimal results |
Implementation Reference
- Registration of the githubViewRepoStructure tool, including inline handler that delegates to exploreMultipleRepositoryStructures
export function registerViewGitHubRepoStructureTool( server: McpServer, callback?: ToolInvocationCallback ) { return server.registerTool( TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE, { description: DESCRIPTIONS[TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE], inputSchema: GitHubViewRepoStructureBulkQuerySchema, annotations: { title: 'GitHub Repository Structure Explorer', readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true, }, }, withSecurityValidation( TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE, async ( args: { queries: GitHubViewRepoStructureQuery[]; }, authInfo, sessionId ): Promise<CallToolResult> => { const queries = args.queries || []; await invokeCallbackSafely( callback, TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE, queries ); return exploreMultipleRepositoryStructures( queries, authInfo, sessionId ); } ) ); } - Core handler logic: processes bulk queries, calls GitHub API via viewGitHubRepositoryStructureAPI, filters structure, handles errors and pagination, formats results
async function exploreMultipleRepositoryStructures( queries: GitHubViewRepoStructureQuery[], authInfo?: AuthInfo, sessionId?: string ): Promise<CallToolResult> { return executeBulkOperation( queries, async (query: GitHubViewRepoStructureQuery, _index: number) => { try { const apiRequest = buildStructureApiRequest(query); const apiResult = await viewGitHubRepositoryStructureAPI( apiRequest, authInfo, sessionId ); const apiError = handleApiError(apiResult, query); if (apiError) { return createEmptyStructureResult(query, apiError); } if (!('structure' in apiResult) || !apiResult.structure) { return createEmptyStructureResult( query, handleCatchError( new Error('Invalid API response structure'), query )! ); } const filteredStructure = filterStructure(apiResult.structure); const hasContent = Object.keys(filteredStructure).length > 0; // Build result data with pagination info const resultData: Record<string, unknown> = { owner: apiRequest.owner, repo: apiRequest.repo, branch: apiResult.branch ?? apiRequest.branch, path: apiRequest.path || '/', structure: filteredStructure, summary: apiResult.summary, }; // Include pagination info if present if (apiResult.pagination) { resultData.pagination = apiResult.pagination; } // Extract API-generated hints (pagination hints, etc.) const apiHints = apiResult.hints || []; // Count entries for context-aware hints const entryCount = Object.values(filteredStructure).reduce( (sum, entry) => sum + entry.files.length + entry.folders.length, 0 ); // Use unified pattern: context for dynamic hints, extraHints for API pagination hints return createSuccessResult( query, resultData, hasContent, TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE, { hintContext: { entryCount }, extraHints: apiHints, } ); } catch (error) { const catchError = handleCatchError( error, query, 'Failed to explore repository structure' ); return createEmptyStructureResult(query, catchError); } }, { toolName: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE, keysPriority: [ 'owner', 'repo', 'branch', 'path', 'structure', 'error', ] satisfies Array<keyof RepoStructureResult>, } ); } - Zod schema for GitHubViewRepoStructureQuery input validation
export const GitHubViewRepoStructureQuerySchema = BaseQuerySchema.extend({ owner: z .string() .min(1) .max(200) .describe(GITHUB_VIEW_REPO_STRUCTURE.scope.owner), repo: z .string() .min(1) .max(150) .describe(GITHUB_VIEW_REPO_STRUCTURE.scope.repo), branch: z .string() .min(1) .max(255) .describe(GITHUB_VIEW_REPO_STRUCTURE.scope.branch), path: z .string() .default('') .optional() .describe(GITHUB_VIEW_REPO_STRUCTURE.scope.path), depth: z .number() .min(1) .max(2) .default(1) .optional() .describe(GITHUB_VIEW_REPO_STRUCTURE.range.depth), entriesPerPage: z .number() .min(1) .max(GITHUB_STRUCTURE_DEFAULTS.MAX_ENTRIES_PER_PAGE) .default(GITHUB_STRUCTURE_DEFAULTS.ENTRIES_PER_PAGE) .optional() .describe(GITHUB_VIEW_REPO_STRUCTURE.pagination.entriesPerPage), entryPageNumber: z .number() .min(1) .default(1) .optional() .describe(GITHUB_VIEW_REPO_STRUCTURE.pagination.entryPageNumber), }); - packages/octocode-mcp/src/tools/toolConfig.ts:54-61 (registration)Tool configuration entry that registers the tool via registerTools in toolsManager.ts
export const GITHUB_VIEW_REPO_STRUCTURE: ToolConfig = { name: TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE, description: getDescription(TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE), isDefault: true, isLocal: false, type: 'content', fn: registerViewGitHubRepoStructureTool, }; - Bulk query schema for handling multiple repo structure queries in a single tool call
export const GitHubViewRepoStructureBulkQuerySchema = createBulkQuerySchema( TOOL_NAMES.GITHUB_VIEW_REPO_STRUCTURE, GitHubViewRepoStructureQuerySchema );