# patruff/ollama-mcp-bridge architecture

> Architecture diagram of the GitHub repository patruff/ollama-mcp-bridge, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-04). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/patruff/ollama-mcp-bridge
- Repository: https://github.com/patruff/ollama-mcp-bridge

## Overview

##### Main Components
- Bridge (Core): This is the central controller that handles tool registration, command routing, and communication between the LLM and various MCP servers.
- LLM Client: A component that manages interactions with Ollama (as seen in files like llm-client.ts) including sending prompts and receiving structured tool-call outputs.
- MCP Client (including specialized clients): Responsible for managing the connections with various MCP servers, handling JSON-RPC communications. Look at components such as mcp-client.ts and mcp-registry.ts.
- Tool Router/Registry: This component detects which tool to call based on user input and routes the operation to the correct MCP (tool-registry.ts and possibly the constant definitions in types).
- Logger and Configuration Management: Files like logger.ts and config.ts indicate configurable options and detailed logging, which are crucial for debugging and monitoring.
- Test Components: To ensure reliability and proper routing among components, a suite of tests exists in both the “src/tests” and “tests” directories.

##### Relationships and Interactions
- The LLM Client (for sending and receiving messages).
- The MCP Client/Registry (which further connects to individual MCP servers for filesystem, search, GitHub, memory, image generation, etc.).
- The Tool Router that parses the user prompt, identifies the required tool, and forwards it to the corresponding MCP server.
- The LLM Client interacts bidirectionally with the Bridge: it receives prompts from the user, then sends structured commands to the Bridge for further handling.
- Configuration management (bridge_config.json), which influences how the Bridge initializes connections to each MCP.

##### Architectural Patterns & Technologies
- The system follows a modular architecture with clearly separated concerns:
- Command Routing (Tool Router and MCP Clients),
- Communication Handling (LLM interaction and JSON-RPC protocol),
- Configuration and Logging.
- The code structure suggests a “plug-and-play” design for MCP servers (dynamic tool registration) – an important design principle to highlight.
- Multiple directories (src vs. tests) suggest strong unit and integration testing practices.
- Use of TypeScript for type safety, which is critical in a system relying on structured message passing and multiple client interactions.

##### Additional Details
- Optionally, highlight the startup sequence, which begins by reading the configuration, initializing the Bridge, setting up LLM and MCP clients, and then waiting for user, command, and tool calls.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Interaction
    user["User Input"]:::user
    subgraph "User Interaction"
        llmClient["LLM Client"]:::client
        ollamaManager["Ollama Manager"]:::client
    end
    user -->|"sends prompt"| llmClient

    %% Core Bridge Components
    subgraph "Core Bridge Components"
        Bridge["Bridge"]:::core
        Entry["Entry Point"]:::core
        toolRegistry["Tool Router / Registry"]:::core
        mcpClient["MCP Client"]:::core
        mcpRegistry["MCP Registry"]:::core
        logger["Logger"]:::config
        configManager["Config Manager"]:::config
        bridgeConfig["bridge_config.json"]:::config
    end

    %% External MCP Servers
    mcpServers["MCP Servers"]:::external

    %% Test Suites
    subgraph "Test Suites"
        testsSrc["Tests (src)"]:::test
        testsDir["Tests (other)"]:::test
    end

    %% Primary Flow Connections
    llmClient -->|"sends command"| Bridge
    Bridge -->|"initializes"| Entry
    Bridge -->|"routes command"| toolRegistry
    toolRegistry -->|"invokes tool"| mcpClient
    mcpClient -->|"registers via"| mcpRegistry
    mcpClient -->|"calls"| mcpServers
    mcpServers -->|"returns response"| mcpClient
    Bridge -->|"sends response"| llmClient

    %% Support Connections
    Bridge -->|"logs to"| logger
    Bridge -->|"loads config from"| configManager
    configManager -->|"reads"| bridgeConfig

    %% Test Connections
    testsSrc --- Bridge
    testsSrc --- llmClient
    testsDir --- mcpClient

    %% Click Events for Mapped Components
    click Bridge "https://github.com/patruff/ollama-mcp-bridge/blob/main/src/bridge.ts"
    click Entry "https://github.com/patruff/ollama-mcp-bridge/blob/main/src/main.ts"
    click llmClient "https://github.com/patruff/ollama-mcp-bridge/blob/main/src/llm-client.ts"
    click ollamaManager "https://github.com/patruff/ollama-mcp-bridge/blob/main/src/ollama-manager.ts"
    click mcpClient "https://github.com/patruff/ollama-mcp-bridge/blob/main/src/mcp-client.ts"
    click mcpRegistry "https://github.com/patruff/ollama-mcp-bridge/blob/main/src/mcp-registry.ts"
    click toolRegistry "https://github.com/patruff/ollama-mcp-bridge/blob/main/src/tool-registry.ts"
    click logger "https://github.com/patruff/ollama-mcp-bridge/blob/main/src/logger.ts"
    click configManager "https://github.com/patruff/ollama-mcp-bridge/blob/main/src/config.ts"
    click bridgeConfig "https://github.com/patruff/ollama-mcp-bridge/blob/main/bridge_config.json"
    click testsSrc "https://github.com/patruff/ollama-mcp-bridge/tree/main/src/tests"
    click testsDir "https://github.com/patruff/ollama-mcp-bridge/tree/main/tests"

    %% Styles
    classDef user fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef client fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef core fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef config fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef test fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;
    classDef external fill:#e2e3e5,stroke:#6c757d,stroke-width:2px;
```
