GitHub Repository Accessor Micro-Control Point (MCP)

This MCP backend furnishes clients such as Claude Desktop and Cursor with granular access to GitHub repository artifacts, encompassing file substance, directory hierarchy representations, and supplementary repository statistics.

Core Capabilities

• Repo Overviews: Acquire exhaustive data summaries pertaining to specified GitHub repositories.
• Structural Visualization: Present the complete file and folder layout of any repository, utilizing an aesthetic ASCII-based tree diagram.
• Source Code Retrieval: Fetch the textual content of discrete files within the repository structure.
• Metric Augmentation: Obtain vital statistics like stargazing counts, forking frequency, descriptive narratives, and recency of last modification.
• Local Mirroring: Execute full local clones of target repositories to facilitate rapid data analysis and comprehensive offline access.
• Performance Caching: Implement intelligent data memoization for repository assets to minimize redundant remote API interactions.
• Operation Feedback: Deliver incremental status updates concerning lengthy background tasks.
• Output Modality: Support data serialization in either plain text or standardized JSON structures.
• Input Prompting: Offer intelligent suggestions for repository maintainers and repository names during interaction.
• Operational Dashboard: A minimal HTTP endpoint for checking service health and configuration details.

Deployment Instructions

Via Node Package Manager (NPM)

# Install globally
npm install @trishchuk/github-explorer-mcp -g

# Initiate the server (Standard I/O mode for MCP consumers)
github-explorer-mcp

# Alternatively, launch in HTTP/Server-Sent Events mode
github-explorer-mcp-sse

Via Containerization (Docker)

# Construct the Docker image
docker build -t github-explorer-mcp .

# Execute the container, mapping port 3000
docker run -p 3000:3000 github-explorer-mcp

Integration with Consumer Applications

Claude Desktop Configuration Snippet

In your application settings file:

{
  "mcpServers": {
    "github-explorer": {
      "command": "npx",
      "args": ["-y", "@trishchuk/github-explorer-mcp"]
    }
  }
}

Cursor Configuration Snippet

Update your configuration JSON:

{
  "mcpServers": {
    "github-explorer": {
      "command": "npx",
      "args": ["-y", "@trishchuk/github-explorer-mcp"]
    }
  }
}

Service Function Catalog

The backend exposes the following transactional tools for MCP interactions:

get_repository_overview

Retrieves a high-level summary for a specified GitHub repository.

{
  owner: string;    // GitHub account or organization identifier
  repo: string;     // The repository's designated name
  branch?: string;  // Optonal reference to a specific branch or tag
  includeMetadata?: boolean; // Flag to incorporate supplementary metrics (stars, forks)
}

get_repository_file_tree

Fetches the hierarchical organization map of a GitHub repository.

{
  owner: string;    // GitHub account or organization identifier
  repo: string;     // The repository's designated name
  branch?: string;  // Optonal reference to a specific branch or tag
}

fetch_specific_file_contents

Downloads the textual data for designated files within a GitHub repository.

{
  owner: string;     // GitHub account or organization identifier
  repo: string;      // The repository's designated name
  filePaths: string[]; // An array listing the relative paths to the desired files
  branch?: string;   // Optonal reference to a specific branch or tag
  format?: 'text' | 'json'; // Desired output serialization format
}

search_repository_content (Planned)

Enables searching for patterns or strings inside repository source files.

{
  owner: string;     // GitHub account or organization identifier
  repo: string;      // The repository's designated name
  query: string;     // The text pattern to search for
  branch?: string;   // Optonal reference to a specific branch or tag
  maxResults?: number; // Limit on the number of matches returned
}

calculate_version_delta (Planned)

Computes the difference (patch) between two distinct points in the repository history.

{
  owner: string;     // GitHub account or organization identifier
  repo: string;      // The repository's designated name
  base: string;      // The foundational branch or commit identifier
  head: string;      // The comparative branch or commit identifier
}

Development Workflow

# Obtain the source repository
git clone https://github.com/x51xxx/github-explorer-mcp.git
cd github-explorer-mcp

# Install required software packages
npm install

# Prerequisite Check: This application mandates Node.js version 18 or newer
# If utilizing nvm (Node Version Manager), execute:
nvm use

# Compile the source code
npm run build

# Initiate the compiled server
npm start
# OR for SSE mode:
npm run start:sse

Troubleshooting Common Issues

Node.js Version Incompatibility

This software relies on contemporary Web APIs, such as ReadableStream, necessitating Node.js runtime version 18 or higher. Should you encounter errors resembling:

ReferenceError: ReadableStream is not defined

Resolution steps are:

1. Upgrade your installed Node.js runtime to version 18 or a later iteration.
2. If managing environments with nvm, ensure you activate the correct version by running nvm use in the project directory.
3. Verify that the execution scripts incorporate any required environment patches or polyfills.

Collaboration Guidelines

We welcome external contributions! Feel free to propose modifications via a Pull Request.

Licensing

This software is distributed under the MIT License.

WIKIPEDIA: XMLHttpRequest (XHR) is an API in the form of a JavaScript object whose methods transmit HTTP requests from a web browser to a web server. The methods allow a browser-based application to send requests to the server after page loading is complete, and receive information back. XMLHttpRequest is a component of Ajax programming. Prior to Ajax, hyperlinks and form submissions were the primary mechanisms for interacting with the server, often replacing the current page with another one. The concept behind XMLHttpRequest was conceived in 2000 by the developers of Microsoft Outlook. The concept was then implemented within the Internet Explorer 5 browser (1999). However, the original syntax did not use the XMLHttpRequest identifier. Instead, the developers used the identifiers ActiveXObject("Msxml2.XMLHTTP") and ActiveXObject("Microsoft.XMLHTTP"). As of Internet Explorer 7 (2006), all browsers support the XMLHttpRequest identifier. The XMLHttpRequest identifier is now the de facto standard in all the major browsers, including Mozilla's Gecko layout engine (2002), Safari 1.2 (2004) and Opera 8.0 (2005). The World Wide Web Consortium (W3C) published a Working Draft specification for the XMLHttpRequest object on April 5, 2006. On February 25, 2008, the W3C published the Working Draft Level 2 specification. Level 2 added methods to monitor event progress, allow cross-site requests, and handle byte streams. At the end of 2011, the Level 2 specification was absorbed into the original specification. At the end of 2012, the WHATWG took over development and maintains a living document using Web IDL. Generally, sending a request with XMLHttpRequest has several programming steps. Create an XMLHttpRequest object by calling a constructor: Call the "open" method to specify the request type, identify the relevant resource, and select synchronous or asynchronous operation: For an asynchronous request, set a listener that will be notified when the request's state changes: Initiate the request by calling the "send" method: Respond to state changes in the event listener. If the server sends response data, by default it is captured in the "responseText" property. When the object stops processing the response, it changes to state 4, the "done" state. Aside from these general steps, XMLHttpRequest has many options to control how the request is sent and how the response is processed. Custom header fields can be added to the request to indicate how the server should fulfill it, and data can be uploaded to the server by providing it in the "send" call. The response can be parsed from the JSON format into a readily usable JavaScript object, or processed gradually as it arrives rather than waiting for the entire text. The request can be aborted prematurely or set to fail if not completed in a specified amount of time. In the early development of the World Wide Web, it was found possible to brea