git-mcp

Exposes GitHub repositories as standardized Model Context Protocol servers running on Cloudflare Workers, transforming repository data into AI-accessible tools without requiring local installation. The system uses URL pattern matching to route requests to repository-specific handlers (ThreejsRepoHandler, GenericHandler) that dynamically generate MCP-compatible tool schemas, enabling Claude, Copilot, Cursor, and other AI assistants to invoke repository operations through a unified protocol interface.

Implements a three-tier documentation fetching strategy that prioritizes llms.txt (AI-optimized format) → AI-specific documentation → README.md, automatically selecting the most appropriate documentation source for LLM consumption. The system uses GitHub API to detect file presence and content, applying intelligent fallback logic to ensure AI assistants always receive relevant, well-formatted documentation even when preferred formats are unavailable.

Implements a multi-stage documentation processing pipeline that detects file formats (markdown, plain text, HTML), normalizes content for LLM consumption, and extracts structured metadata (headings, code blocks, links). The pipeline handles various documentation sources (README.md, llms.txt, custom AI docs) and applies format-specific transformations to ensure consistent, LLM-optimized output regardless of source format.

Generates MCP-compliant tool schemas with full parameter validation, type definitions, and usage examples, ensuring AI assistants can invoke tools correctly with proper input validation. The system creates JSON schemas for each tool, specifying required/optional parameters, parameter types, constraints, and examples, enabling AI assistants to understand tool capabilities and invoke them with correct arguments.

Enables AI assistants to access repository content (files, code, documentation) via GitHub API without requiring local repository clones, reducing setup time and storage overhead. The system fetches file contents on-demand via GitHub API, caches frequently accessed files in KV, and streams large files to avoid memory exhaustion, allowing AI assistants to work with repositories of any size.

Integrates Cloudflare Vectorize to generate embeddings for repository documentation, enabling semantic search queries that find relevant content by meaning rather than keyword matching. The system processes documentation text into vector embeddings, stores them in Vectorize, and executes cosine-similarity searches to return contextually relevant documentation snippets when AI assistants query the repository.

Integrates FalkorDB graph database to index repository code structure, enabling queries that traverse code relationships (imports, function calls, class hierarchies) and analyze code patterns. The system builds a code graph from GitHub API responses, storing nodes (files, functions, classes) and edges (dependencies, calls), allowing AI assistants to understand code organization and answer structural questions without parsing source files directly.

Implements a handler registry pattern where specialized handlers (ThreejsRepoHandler, GenericHandler) generate repository-specific MCP tools tailored to each project's structure and conventions. The ToolIndex coordinator selects appropriate handlers based on repository metadata, generating custom tool schemas that expose repository-specific operations (e.g., Three.js example browsing, build system queries) alongside common tools (documentation search, code lookup).

Implements sophisticated URL pattern matching to route requests to appropriate repository handlers, supporting both path-based (gitmcp.io/{owner}/{repo}) and subdomain-based (owner.gitmcp.io/{repo}) repository selection. The routing system extracts repository metadata from URLs, validates against GitHub, and selects specialized handlers, enabling flexible repository addressing and dynamic repository selection through generic endpoints.

Integrates GitHub API for repository data fetching, documentation retrieval, and code analysis, with support for both public and private repositories via token-based authentication. The system manages GitHub API rate limits (60 req/hour unauthenticated, 5000/hour authenticated), implements request batching and caching to minimize API calls, and handles authentication via GITHUB_TOKEN environment variable for private repository access.

Uses Cloudflare Workers KV (key-value store) as a distributed cache for repository documentation, code snippets, and API responses, reducing GitHub API calls and improving response latency. The system implements cache invalidation strategies (TTL-based expiration, manual invalidation) and stores frequently accessed data (documentation, code graphs, tool schemas) in KV for sub-millisecond retrieval across global edge locations.

Implements MCP protocol compatibility with 8+ AI assistants (Claude, Copilot, Cursor, etc.), handling tool invocation requests in MCP JSON-RPC format and returning results in assistant-specific formats. The system abstracts away protocol differences between assistants, exposing a unified tool interface that each client can invoke according to its MCP implementation, enabling the same repository tools to work across heterogeneous AI platforms.

Provides a web UI (built with Remix/React) that converts GitHub repository URLs into MCP server endpoints, displays MCP configuration instructions for different AI assistants, and offers a chat interface for testing repository tools. The interface generates platform-specific setup guides (Claude, Copilot, Cursor) and allows users to preview tool availability before connecting to their AI assistant.