GitHub Repository Structure Inspector MCP

A Cloudflare Worker implementation designed to probe and structure the contents of arbitrary GitHub repositories. This utility is optimized for consumption by Smithery and companion MCP modules.

Core Capabilities

🔍 Enumerates file paths and directory hierarchies for any accessible GitHub repo (requires valid token for private repos).
🌳 Generates a formal, nested map detailing the project's organization.
📄 Renders the raw textual content of specified files.
⚡ Implements data caching for up to 24 hours to minimize repeated API calls.
🎭 Offers output in both human-readable HTML and machine-parsable JSON.
🔐 Security is maintained by requiring users to furnish their own authentication credentials (GitHub Tokens).

Endpoint Interaction

Browser Access

Navigate to the deployed worker URL through any standard web browser.

API Invocation

Execute a GET operation against the /scan path, supplying necessary query parameters:

/scan?repo_uri=GITHUB_REPO_URL&auth_key=YOUR_PAT&output_type=json

Parameters explained: - repo_uri: The full URL pointing to the target GitHub repository (e.g., https://github.com/org/project). - auth_key: Your personal GitHub access token, which must possess the necessary scopes (repo or public_repo). - output_type: (Optional) Specifies the response modality; use json for structured data exchange.

Example Invocation:

/scan?repo_uri=https://github.com/user/repo&auth_key=ghp_abcdef12345&output_type=json

Data Payload Structure (JSON Output)

The resulting JSON object encapsulates the inspection findings:

{ "status": true, "payload": { "repoName": "project-name", "repoOwner": "entity-name", "treeRepresentation": { "leafFiles": ["fileA.txt", "config.yml"], "subDirectories": { "src": { "leafFiles": ["main.js"], "subDirectories": {} } } }, "contentMap": { "fileA.txt": "Content of A", "src/main.js": "console.log('hello');" }, "captureTime": 1679000000000 }, "isCached": false, "requestTime": 1679000000000 }

Deployment Strategies

Cloudflare Worker Environment

Obtain the source code repository.
Install required node modules via npm install.
Utilize the deployment script: npm run deploy.

Containerized Deployment (Docker)

Instructions for deploying via standard container runtimes:

bash docker build -t github-inspector-service . docker run -p 8787:8787 github-inspector-service

Smithery Integration Notes

This component is purpose-built for seamless integration within the Smithery ecosystem. Upon deployment via the Smithery framework, end-users are responsible for supplying their authentication credentials (GitHub PATs) when invoking the service.

Authentication Requirements (GitHub PAT)

Access requires a Personal Access Token with the following minimum permissions: - repo: For access to private repositories. - public_repo: For access to publicly accessible repositories.

Token generation link: https://github.com/settings/tokens