# inquirelab/mcp-bridge-api architecture

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

- Interactive diagram: https://gitdiagram.com/inquirelab/mcp-bridge-api
- Repository: https://github.com/inquirelab/mcp-bridge-api

## Overview

##### Project type and purpose
- This is a two‑piece system:
- A Node.js “MCP Bridge” service (mcp-bridge.js) that exposes a unified REST API to multiple Model Context Protocol (MCP) servers.
- A Python “MCP‑Gemini Agent” client (llm_test.py) that uses Google’s Gemini LLM to drive and orchestrate calls to the Bridge.
- Its purpose is to make any MCP‑compatible tool available via HTTP and to provide an intelligent Python client that can perform multi-step reasoning and risk‑level confirmations.

##### File structure
- Top‑level files:
- mcp-bridge.js – the Express-based HTTP server
- mcp_config.json – configuration of backend MCP servers (commands, args, risk levels)
- package.json – declares dependencies for the Bridge
- llm_test.py – the Python CLI/agent entry point
- README.md – full overview and architecture
- No separate “src” directories; Bridge and Agent live side by side at root.
- Configuration drive: JSON file for the Bridge, CLI args for the Agent.

##### README for additional insights
- The “Architecture” section shows three categories of clients (Mobile, Browser, Other) calling the REST API, which forwards to multiple MCP servers via STDIO or SSE.
- Risk levels (low/medium/high) introduce confirmation or Docker isolation workflows.
- The Python agent connects to the Bridge over HTTP, discovers tools, and handles confirmations automatically.

##### Components
a. External Clients
– Mobile App
– Browser App
– Other Clients (e.g., scripts, microservices)
b. REST API Layer (Express server in mcp-bridge.js)
c. MCP Bridge Core
– HTTP endpoints (/servers, /tools, /confirmations, /health, etc.)
– Configuration loader (mcp_config.json)
– Risk‑level engine (confirmation workflow / Docker spawns)
d. Underlying MCP Servers
– STDIO‑based servers (filesystem, slack, etc.)
– SSE‑based servers (if any)
– Docker container processes for high‑risk servers
e. MCP‑Gemini Agent (llm_test.py)
– Gemini API integration (google‑generativeai)
– HTTP client to Bridge
– Multi‑step reasoning / confirmation prompts

##### Relationships and data flow
- The Bridge core invokes subprocesses or Docker containers for each configured MCP server via STDIO or SSE.
- For medium‑risk calls, show two‑step flow: initial “request → confirmation required” response, then “confirmation call → execution.”
- Python Agent as a specialized client: it calls the same REST API, handles confirmations, parses JSON, and submits follow‑up requests.

##### Architectural patterns and design principles
- Separation of concerns: HTTP/API layer vs. server‑management logic vs. risk workflow.
- Plug‑in architecture: any number of MCP servers configured via JSON.
- Risk‑based execution pipeline: low/medium/high mapped to direct exec, confirmation, Docker isolation.
- Client‑agnostic design: any consumer (mobile, web, CLI) can integrate through REST.

##### Technologies and frameworks to annotate
- Node.js (Express, CORS, Morgan, UUID) in the Bridge
- Python (requests, google-generativeai, rich) in the Agent
- STDIO and SSE transports to MCP servers
- Docker for risk level 3 isolation
- JSON for configuration (mcp_config.json)
- HTTP/REST for all external interactions

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    subgraph "External Clients"
        direction TB
        Mobile["Mobile App"]:::client
        Browser["Browser App"]:::client
        Other["Other Clients"]:::client
    end

    %% Bridge Service
    subgraph "MCP Bridge Service"
        direction TB
        API["REST API Layer (Express)"]:::bridge
        subgraph "Core Modules"
            direction TB
            Config["Configuration Loader"]:::config
            Risk["Risk-Level Engine"]:::bridge
        end
    end

    %% Docs & Config
    subgraph "Docs & Config"
        direction TB
        Package["package.json"]:::docs
        ConfigFile["mcp_config.json"]:::docs
        Readme["README.md"]:::docs
        License["LICENSE"]:::docs
    end

    %% MCP Servers
    subgraph "MCP Servers"
        direction TB
        Stdio["STDIO-based Servers"]:::server
        SSE["SSE-based Servers"]:::server
        Docker["Docker Containers (High-Risk)"]:::docker
    end

    %% Python Agent
    subgraph "Python MCP-Gemini Agent"
        direction TB
        Agent["llm_test.py (Gemini API)"]:::agent
    end

    %% Connections
    Mobile -->|"HTTP/JSON"| API
    Browser -->|"HTTP/JSON"| API
    Other -->|"HTTP/JSON"| API
    Agent -->|"HTTP/JSON & Confirmations"| API

    API -->|"load config"| Config
    API -->|"risk evaluation"| Risk
    Config -->|"spawn process"| Stdio
    Config -->|"spawn process"| SSE
    Risk -->|"high risk → Docker"| Docker

    %% Click Events
    click API "https://github.com/inquirelab/mcp-bridge-api/blob/main/mcp-bridge.js"
    click ConfigFile "https://github.com/inquirelab/mcp-bridge-api/blob/main/mcp_config.json"
    click Risk "https://github.com/inquirelab/mcp-bridge-api/blob/main/mcp-bridge.js"
    click Agent "https://github.com/inquirelab/mcp-bridge-api/blob/main/llm_test.py"
    click Package "https://github.com/inquirelab/mcp-bridge-api/blob/main/package.json"
    click Readme "https://github.com/inquirelab/mcp-bridge-api/blob/main/README.md"
    click License "https://github.com/inquirelab/mcp-bridge-api/tree/main/LICENSE"

    %% Styles
    classDef client fill:#e0ffe0,stroke:#0a0,stroke-width:1px
    classDef bridge fill:#e0f0ff,stroke:#08f,stroke-width:1px
    classDef config fill:#f0f8ff,stroke:#08f,stroke-width:1px
    classDef server fill:#ffe8cc,stroke:#f80,stroke-width:1px
    classDef docker fill:#dddddd,stroke:#888,stroke-width:1px
    classDef agent fill:#f8e0ff,stroke:#a0f,stroke-width:1px
    classDef docs fill:#fff0b3,stroke:#cc0,stroke-width:1px
```
