# idosal/git-mcp architecture

> Architecture diagram of the GitHub repository idosal/git-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/idosal/git-mcp
- Repository: https://github.com/idosal/git-mcp

## Overview

GitMCP is a hosted MCP documentation service with a repository-specific or generic-server workflow: an AI assistant requests documentation or code tools, GitMCP resolves the repository and dispatches tools, and retrieval returns source material. Its web app also offers embedded chat and server configuration. The graph preserves documented search and specialized repository capabilities; several route and handler implementations were not sampled, so those links are marked unverified rather than inferred as direct calls.

Main entry points: [`src/api/tools/commonTools.ts`](https://github.com/idosal/git-mcp/blob/main/src/api/tools/commonTools.ts) (Documentation Tools), [`src/index.ts`](https://github.com/idosal/git-mcp/blob/main/src/index.ts) (MCP Request Server), [`src/api/tools/repoHandlers/handlers.ts`](https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/handlers.ts) (Handler Dispatch), [`src/api/tools/repoHandlers/ThreejsRepoHandler.ts`](https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/ThreejsRepoHandler.ts) (Three.js Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_serving["MCP Serving"]
  node_mcp["MCP Request Server<br/>[index.ts]"]
  node_tool_registry["Tool Registry<br/>[index.ts]"]
  node_handler_dispatch["Handler Dispatch<br/>[handlers.ts]"]
  node_handler_contract["Handler Contract<br/>[RepoHandler.ts]"]
  node_default_handler["Repository Tools"]
  node_generic_handler["Generic Tools"]
  node_react_router_handler["React Router Tools"]
  node_three_handler["Three.js Tools"]
end

subgraph group_retrieval["Repository Retrieval"]
  node_common_tools["Documentation Tools<br/>[commonTools.ts]"]
  node_github_fetch["GitHub Fetch<br/>[github.ts]"]
  node_github_client["GitHub API Client<br/>[githubClient.ts]"]
  node_robots["Robots Checks<br/>[robotsTxt.ts]"]
  node_vector_search["Vector Search<br/>[vectorStore.ts]"]
  node_three_utils["Three.js Docs<br/>[utils.ts]"]
end

subgraph group_web["Web Experience"]
  node_landing["Landing Page<br/>[_index.tsx]"]
  node_content["Repository Content UI<br/>[content.tsx]"]
  node_chat_route["Chat Endpoint<br/>[api.chat.ts]"]
  node_chat_ui["Embedded Chat UI<br/>[chat.tsx]"]
  node_mcp_manager["Server Manager"]
  node_chat_providers["AI Providers"]
end

subgraph group_support["Shared Services"]
  node_repo_resolution["Repository Resolution<br/>[repoData.ts]"]
  node_cache[("Retrieval Cache<br/>[cache.ts]")]
  node_local_state[("Browser State")]
  node_badge["Project Badge<br/>[badge.ts]"]
end

node_assistant(("AI Assistant"))
node_github["GitHub"]
node_web_user(("Web User"))

node_assistant -->|"requests tools"| node_mcp
node_mcp -->|"registers tools"| node_tool_registry
node_mcp -->|"resolves repository"| node_repo_resolution
node_tool_registry -.->|"selects handlers"| node_handler_dispatch
node_handler_dispatch -.->|"dispatches to"| node_default_handler
node_handler_dispatch -.->|"dispatches to"| node_generic_handler
node_handler_dispatch -.->|"dispatches to"| node_react_router_handler
node_handler_dispatch -.->|"dispatches to"| node_three_handler
node_default_handler -->|"calls tools"| node_common_tools
node_generic_handler -->|"calls tools"| node_common_tools
node_react_router_handler -->|"calls tools"| node_common_tools
node_three_handler -->|"searches docs"| node_common_tools
node_three_handler -->|"fetches references"| node_three_utils
node_common_tools -->|"fetches files"| node_github_fetch
node_common_tools -->|"searches code"| node_github_client
node_common_tools -->|"checks access"| node_robots
node_common_tools -->|"reads and writes"| node_cache
node_github_fetch -->|"uses client"| node_github_client
node_github_client -.->|"requests content"| node_github
node_github_fetch -.->|"fetches repository"| node_github
node_common_tools -.->|"searches vectors"| node_vector_search
node_mcp -->|"returns results"| node_assistant
node_web_user -->|"opens site"| node_landing
node_landing -.->|"shows repository docs"| node_content
node_web_user -->|"starts chat"| node_chat_ui
node_chat_ui -.->|"sends messages"| node_chat_route
node_chat_ui -.->|"selects provider"| node_chat_providers
node_mcp_manager -.->|"persists settings"| node_local_state
node_web_user -->|"configures servers"| node_mcp_manager
node_mcp -->|"serves badge"| node_badge

click node_mcp "https://github.com/idosal/git-mcp/blob/main/src/index.ts"
click node_tool_registry "https://github.com/idosal/git-mcp/blob/main/src/api/tools/index.ts"
click node_handler_dispatch "https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/handlers.ts"
click node_handler_contract "https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/RepoHandler.ts"
click node_default_handler "https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/DefaultRepoHandler.ts"
click node_generic_handler "https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/GenericRepoHandler.ts"
click node_react_router_handler "https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts"
click node_three_handler "https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/ThreejsRepoHandler.ts"
click node_common_tools "https://github.com/idosal/git-mcp/blob/main/src/api/tools/commonTools.ts"
click node_repo_resolution "https://github.com/idosal/git-mcp/blob/main/src/shared/repoData.ts"
click node_github_fetch "https://github.com/idosal/git-mcp/blob/main/src/api/utils/github.ts"
click node_github_client "https://github.com/idosal/git-mcp/blob/main/src/api/utils/githubClient.ts"
click node_robots "https://github.com/idosal/git-mcp/blob/main/src/api/utils/robotsTxt.ts"
click node_cache "https://github.com/idosal/git-mcp/blob/main/src/api/utils/cache.ts"
click node_vector_search "https://github.com/idosal/git-mcp/blob/main/src/api/utils/vectorStore.ts"
click node_three_utils "https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/threejs/utils.ts"
click node_landing "https://github.com/idosal/git-mcp/blob/main/app/routes/_index.tsx"
click node_content "https://github.com/idosal/git-mcp/blob/main/app/components/content.tsx"
click node_chat_route "https://github.com/idosal/git-mcp/blob/main/app/routes/api.chat.ts"
click node_chat_ui "https://github.com/idosal/git-mcp/blob/main/app/chat/components/chat.tsx"
click node_mcp_manager "https://github.com/idosal/git-mcp/blob/main/app/chat/components/mcp-server-manager.tsx"
click node_chat_providers "https://github.com/idosal/git-mcp/blob/main/app/chat/ai/providers.shared.ts"
click node_local_state "https://github.com/idosal/git-mcp/blob/main/app/chat/lib/hooks/use-local-storage.ts"
click node_badge "https://github.com/idosal/git-mcp/blob/main/src/api/utils/badge.ts"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_mcp,node_tool_registry,node_handler_dispatch,node_handler_contract,node_default_handler,node_generic_handler,node_react_router_handler,node_three_handler,node_web_user toneBlue
class node_common_tools,node_github_fetch,node_github_client,node_robots,node_vector_search,node_three_utils toneAmber
class node_landing,node_content,node_chat_route,node_chat_ui,node_mcp_manager,node_chat_providers toneMint
class node_repo_resolution,node_cache,node_local_state,node_badge toneRose
class node_assistant,node_github toneIndigo
```

## Components

### MCP Serving

- [MCP Request Server](https://github.com/idosal/git-mcp/blob/main/src/index.ts): `src/index.ts`
- [Tool Registry](https://github.com/idosal/git-mcp/blob/main/src/api/tools/index.ts): `src/api/tools/index.ts`
- [Handler Dispatch](https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/handlers.ts): `src/api/tools/repoHandlers/handlers.ts`
- [Handler Contract](https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/RepoHandler.ts): `src/api/tools/repoHandlers/RepoHandler.ts`
- [Repository Tools](https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/DefaultRepoHandler.ts): `src/api/tools/repoHandlers/DefaultRepoHandler.ts`
- [Generic Tools](https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/GenericRepoHandler.ts): `src/api/tools/repoHandlers/GenericRepoHandler.ts`
- [React Router Tools](https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/ReactRouterRepoHandler.ts): `src/api/tools/repoHandlers/ReactRouterRepoHandler.ts`
- [Three.js Tools](https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/ThreejsRepoHandler.ts): `src/api/tools/repoHandlers/ThreejsRepoHandler.ts`

### Repository Retrieval

- [Documentation Tools](https://github.com/idosal/git-mcp/blob/main/src/api/tools/commonTools.ts): `src/api/tools/commonTools.ts`
- [GitHub Fetch](https://github.com/idosal/git-mcp/blob/main/src/api/utils/github.ts): `src/api/utils/github.ts`
- [GitHub API Client](https://github.com/idosal/git-mcp/blob/main/src/api/utils/githubClient.ts): `src/api/utils/githubClient.ts`
- [Robots Checks](https://github.com/idosal/git-mcp/blob/main/src/api/utils/robotsTxt.ts): `src/api/utils/robotsTxt.ts`
- [Vector Search](https://github.com/idosal/git-mcp/blob/main/src/api/utils/vectorStore.ts): `src/api/utils/vectorStore.ts`
- [Three.js Docs](https://github.com/idosal/git-mcp/blob/main/src/api/tools/repoHandlers/threejs/utils.ts): `src/api/tools/repoHandlers/threejs/utils.ts`

### Web Experience

- [Landing Page](https://github.com/idosal/git-mcp/blob/main/app/routes/_index.tsx): `app/routes/_index.tsx`
- [Repository Content UI](https://github.com/idosal/git-mcp/blob/main/app/components/content.tsx): `app/components/content.tsx`
- [Chat Endpoint](https://github.com/idosal/git-mcp/blob/main/app/routes/api.chat.ts): `app/routes/api.chat.ts`
- [Embedded Chat UI](https://github.com/idosal/git-mcp/blob/main/app/chat/components/chat.tsx): `app/chat/components/chat.tsx`
- [Server Manager](https://github.com/idosal/git-mcp/blob/main/app/chat/components/mcp-server-manager.tsx): `app/chat/components/mcp-server-manager.tsx`
- [AI Providers](https://github.com/idosal/git-mcp/blob/main/app/chat/ai/providers.shared.ts): `app/chat/ai/providers.shared.ts`

### Shared Services

- [Repository Resolution](https://github.com/idosal/git-mcp/blob/main/src/shared/repoData.ts): `src/shared/repoData.ts`
- [Retrieval Cache](https://github.com/idosal/git-mcp/blob/main/src/api/utils/cache.ts): `src/api/utils/cache.ts`
- [Browser State](https://github.com/idosal/git-mcp/blob/main/app/chat/lib/hooks/use-local-storage.ts): `app/chat/lib/hooks/use-local-storage.ts`
- [Project Badge](https://github.com/idosal/git-mcp/blob/main/src/api/utils/badge.ts): `src/api/utils/badge.ts`

### Other components

- **AI Assistant**
- **GitHub**
- **Web User**

## Connections

- AI Assistant → MCP Request Server: requests tools
- MCP Request Server → Tool Registry: registers tools (evidence: `src/index.ts`)
- MCP Request Server → Repository Resolution: resolves repository (evidence: `src/index.ts`)
- Tool Registry → Handler Dispatch: selects handlers (evidence: `src/api/tools/index.ts`)
- Handler Dispatch → Repository Tools: dispatches to
- Handler Dispatch → Generic Tools: dispatches to
- Handler Dispatch → React Router Tools: dispatches to
- Handler Dispatch → Three.js Tools: dispatches to
- Repository Tools → Documentation Tools: calls tools (evidence: `src/api/tools/repoHandlers/DefaultRepoHandler.ts`)
- Generic Tools → Documentation Tools: calls tools (evidence: `src/api/tools/repoHandlers/GenericRepoHandler.ts`)
- React Router Tools → Documentation Tools: calls tools (evidence: `src/api/tools/repoHandlers/ReactRouterRepoHandler.ts`)
- Three.js Tools → Documentation Tools: searches docs (evidence: `src/api/tools/repoHandlers/ThreejsRepoHandler.ts`)
- Three.js Tools → Three.js Docs: fetches references (evidence: `src/api/tools/repoHandlers/ThreejsRepoHandler.ts`)
- Documentation Tools → GitHub Fetch: fetches files (evidence: `src/api/tools/commonTools.ts`)
- Documentation Tools → GitHub API Client: searches code (evidence: `src/api/tools/commonTools.ts`)
- Documentation Tools → Robots Checks: checks access (evidence: `src/api/tools/commonTools.ts`)
- Documentation Tools → Retrieval Cache: reads and writes (evidence: `src/api/tools/commonTools.ts`)
- GitHub Fetch → GitHub API Client: uses client (evidence: `src/api/utils/github.ts`)
- GitHub API Client → GitHub: requests content
- GitHub Fetch → GitHub: fetches repository
- Documentation Tools → Vector Search: searches vectors
- MCP Request Server → AI Assistant: returns results
- Web User → Landing Page: opens site
- Landing Page → Repository Content UI: shows repository docs
- Web User → Embedded Chat UI: starts chat
- Embedded Chat UI → Chat Endpoint: sends messages
- Embedded Chat UI → AI Providers: selects provider
- Server Manager → Browser State: persists settings
- Web User → Server Manager: configures servers
- MCP Request Server → Project Badge: serves badge (evidence: `src/index.ts`)
