# mcspidey/mcpi architecture

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

- Interactive diagram: https://gitdiagram.com/mcspidey/mcpi
- Repository: https://github.com/mcspidey/mcpi

## Overview

##### Main Components
- MCPI Server: This is the core backend written in Rust (located in the “mcpi-server” folder). It includes:
- A plugin registry and plugin engine (with built-in plugins for “hello”, “social”, “store”, “weather”, “website”).
- Communication modules for handling WebSocket connections (MCPI protocol endpoints) and HTTP-based REST discovery.
- Routing components (message_handler.rs and transport layers in “mcpi-server/src/transport” for protocol data transmission).
- Static files (like admin.html) and configuration files stored in the “data” folder.
- MCPI Client: This is a command-line client (in “mcpi-client”) responsible for:
- DNS-based server discovery.
- Direct WebSocket connection to the server.
- Option to test individual plugins.
- mcpi-common Library: Shared code and interfaces (located in “mcpi-common”) that defines JSON plugins, plugin factories, and common protocols.
- Chrome Extension: Found in the “chrome-extension” folder. It acts as a front-end integration tool that:
- Detects MCPI-enabled sites via DNS TXT records.
- Provides a popup interface with quick actions and tool exploration.
- Supporting Data and Configuration:
- The “data” directory contains JSON configuration files and dataset files for different domains (client, hello, server, social, store, weather, website).
- Docker configuration under “docker” for containerizing the server.

##### Relationships and Interactions
- The MCPI Server exposes two types of endpoints:
- A WebSocket endpoint (e.g., at ws://localhost:3001/mcpi) for MCP protocol communications.
- A REST discovery endpoint (e.g., http://localhost:3001/mcpi/discover) for capability discovery.
- The Server uses a plugin-based, modular architecture where each plugin (e.g., hello, store, weather) implements the McpPlugin trait.
- The plugin registry is responsible for routing incoming requests (including standard operations like SEARCH, GET, and LIST) to the appropriate plugin.
- The MCPI Client uses DNS-based discovery (using TXT records) and HTTP lookup to find the server before establishing a WebSocket connection.
- The Chrome Extension integrates with the MCPI server by automatically detecting a supported website, then connecting and allowing the user to interact with the available tools.

##### Architectural Patterns and Design Principles
- Modular Plugin Architecture: Plugins are self-contained, enabling dynamic extension without altering core server logic.
- Separation of Concerns: Clearly separated components for client, server, and shared libraries.
- Protocol Abstraction: Implementation of the Model Context Protocol through dedicated transport modules (WebSocket and HTTP REST).
- Data-Driven Configuration: The system relies on external JSON configuration files and data files, making the system flexible.

##### Relevant Technologies
- Rust and Cargo for building the server, client, and shared libraries.
- WebSocket and HTTP for communications.
- DNS TXT-based discovery mechanism.
- Chrome extension APIs for browser integration.
- Docker for containerized deployment of server components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% MCPI Server Section
    subgraph "MCPI Server"
        S1["MCPI Server"]:::server
        subgraph "Internal Components"
            S2["Plugin Registry & Plugins"]:::plugin
            S31["Communication & Routing Modules"]:::server
            subgraph "Comm Modules"
                CM1["Message Handler"]:::server
                CM2["Transport Modules"]:::server
            end
            S4["Static Files & Configuration"]:::server
            subgraph "Config Details"
                SF1["admin.html"]:::server
                SF2["Data & Config Files"]:::server
            end
            S5["Docker Config"]:::docker
        end
        %% Connections within Server
        S31 -->|"routes to"| S2
        S4 -->|"supplies"| S1
        S5 -->|"deploys"| S1
    end

    %% MCPI Client and Chrome Extension Section
    subgraph "MCPI Client & Chrome Extension"
        C1["MCPI Client"]:::client
        subgraph "Client Components"
            C1a["DNS Discovery"]:::client
            C1b["Main Client"]:::client
        end
        C2["Chrome Extension"]:::extension
        subgraph "Extension Components"
            CE1["manifest.json"]:::extension
            CE2["background.js"]:::extension
            CE3["popup.html"]:::extension
        end
    end

    %% mcpi-common Library Section
    subgraph "mcpi-common Library"
        M1["mcpi-common Library"]:::common
        subgraph "Common Interfaces"
            M1a["Plugin Interfaces & Factories"]:::common
        end
    end

    %% Interactions between Sections
    C1 -->|"HTTPREST/DNSTXT"| S31
    C1 -->|"WebSocket"| S31
    C2 -->|"REST/WebSocket"| S31
    S2 -->|"invokes Plugin Ops"| CM1
    S2 -->|"manages"| S2
    M1 -->|"shared protocols"| S1

    %% Styles
    classDef server fill:#ADD8E6,stroke:#333,stroke-width:2px;
    classDef client fill:#FFEB99,stroke:#333,stroke-width:2px;
    classDef common fill:#F4A460,stroke:#333,stroke-width:2px;
    classDef extension fill:#DDA0DD,stroke:#333,stroke-width:2px;
    classDef plugin fill:#90EE90,stroke:#333,stroke-width:2px;
    classDef docker fill:#C0C0C0,stroke:#333,stroke-width:2px;

    %% Click Events for MCPI Server
    click S1 "https://github.com/mcspidey/mcpi/tree/main/mcpi-server"
    click S2 "https://github.com/mcspidey/mcpi/blob/main/mcpi-server/src/plugin_registry.rs"
    click S2 "https://github.com/mcspidey/mcpi/tree/main/mcpi-server/src/plugins"
    click CM1 "https://github.com/mcspidey/mcpi/blob/main/mcpi-server/src/message_handler.rs"
    click CM2 "https://github.com/mcspidey/mcpi/tree/main/mcpi-server/src/transport"
    click SF1 "https://github.com/mcspidey/mcpi/blob/main/mcpi-server/static/admin.html"
    click SF2 "https://github.com/mcspidey/mcpi/tree/main/data"
    click S5 "https://github.com/mcspidey/mcpi/tree/main/docker/server"

    %% Click Events for MCPI Client
    click C1 "https://github.com/mcspidey/mcpi/tree/main/mcpi-client"
    click C1a "https://github.com/mcspidey/mcpi/blob/main/mcpi-client/src/discovery.rs"
    click C1b "https://github.com/mcspidey/mcpi/blob/main/mcpi-client/main.rs"

    %% Click Events for mcpi-common Library
    click M1 "https://github.com/mcspidey/mcpi/tree/main/mcpi-common"
    click M1a "https://github.com/mcspidey/mcpi/blob/main/mcpi-common/lib.rs"

    %% Click Events for Chrome Extension
    click C2 "https://github.com/mcspidey/mcpi/tree/main/chrome-extension"
    click CE1 "https://github.com/mcspidey/mcpi/blob/main/chrome-extension/manifest.json"
    click CE2 "https://github.com/mcspidey/mcpi/blob/main/chrome-extension/background.js"
    click CE3 "https://github.com/mcspidey/mcpi/blob/main/chrome-extension/popup.html"
```
