# funwarioisii/mcp-rb architecture

> Architecture diagram of the GitHub repository funwarioisii/mcp-rb, 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/funwarioisii/mcp-rb
- Repository: https://github.com/funwarioisii/mcp-rb

## Overview

##### Main Components
- MCP DSL Interface: This is where the user writes definitions (as seen in the README examples) for resources, resource templates, and tools. These definitions are processed by the MCP application layer (found in lib/mcp/app and related files).
- Server Component: Implemented within lib/mcp/server, this handles incoming connections (with subcomponents like ClientConnection and StdioClientConnection) and manages the protocol (ping, resource requests, tool calls, etc.).
- Client Component: Although basic, there is a client implementation (see lib/mcp/client) that likely encapsulates outbound calls or testing interactions with the server.
- Core Logic and Delegation: Modules in lib/mcp such as mcp/delegator.rb and constants provide core routing and shared constants that glue the DSL interface to the runtime logic.
- Examples and Tests: The examples directory and test suite (under test/) indicate how external calls and scenarios can be exercised—an important bit when visualizing external interactions, such as integration with tools like the MCP Inspector.

##### Relationships and Interactions
- The “DSL Interface” (where definitions are declared) sets up resources and tool handlers that are registered in the MCP application runtime (lib/mcp/app).
- When the server (lib/mcp/server) starts, it uses these registered definitions to handle incoming requests.
- Depending on the connection mode (stdio or other client-based connections), the server uses specific client connection classes to handle requests/responses.
- The client component (lib/mcp/client) and external testing tools from the examples also interact through these standard protocols.
- The delegator (lib/mcp/delegator.rb) routes calls between these components, ensuring correct access to the defined behaviors.

##### Architectural Patterns and Design Principles
- DSL Pattern: The setup in the README shows a DSL-like style where “resource”, “resource_template”, and “tool” block definitions create modular endpoints.
- Separation of Concerns: Notice the separation between server-side connection handling (lib/mcp/server) versus application logic (lib/mcp/app) and the client’s role. This clear separation is beneficial in both organizing logic and making the gem extensible.
- Modular Organization: The directory structure (with separate directories for app, server, and client) supports modularity and testing (as evident by the dedicated test folder).

##### Detail and Clarity
- Don’t just list the components but also show the interaction order; this is important because it clarifies the flow of data from when the user writes a definition to when the server processes a client request.
- How the design adheres to standard design principles (modularity, separation of concerns, and extensibility through DSL) to give a quick insight to any new team members or reviewers.

– Clearly separate the layers (DSL interface, application core, server, client).
– Show how configuration flows into runtime behavior and call dispatch.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% MCP DSL Interface
    subgraph "MCP DSL Interface"
        DSL1("app.rb"):::dsl
        DSL2("resource.rb"):::dsl
        DSL3("resource_template.rb"):::dsl
        DSL4("tool.rb"):::dsl
    end

    %% Core Logic & Delegation
    subgraph "Core Logic & Delegation"
        CORE1("delegator.rb"):::core
        CORE2("constants.rb"):::core
    end

    %% MCP Server and Connection Handling
    subgraph "MCP Server"
        SERVER1("server.rb"):::server
        SERVER2("client_connection.rb"):::server
        SERVER3("stdio_client_connection.rb"):::server
    end

    %% MCP Client
    subgraph "MCP Client"
        CLIENT("client.rb"):::client
    end

    %% External Interactions
    subgraph "External Interactions"
        EX("Examples & Tools"):::external
        TEST("Testing Framework"):::external
    end

    %% Interactions
    DSL1 -->|"registers"| CORE1
    CORE1 -->|"routes"| SERVER1

    CLIENT -->|"sends_request"| SERVER1
    EX -->|"sends_request"| SERVER1
    TEST -->|"sends_request"| SERVER1

    SERVER1 -->|"returns_response"| CLIENT
    SERVER1 -->|"returns_response"| EX
    SERVER1 -->|"returns_response"| TEST

    %% Internal server handling
    SERVER1 -->|"handles"| SERVER2
    SERVER1 -->|"handles"| SERVER3

    %% Click Events for MCP DSL Interface
    click DSL1 "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/app.rb"
    click DSL2 "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/app/resource.rb"
    click DSL3 "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/app/resource_template.rb"
    click DSL4 "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/app/tool.rb"

    %% Click Events for Core Logic & Delegation
    click CORE1 "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/delegator.rb"
    click CORE2 "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/constants.rb"

    %% Click Events for MCP Server
    click SERVER1 "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/server.rb"
    click SERVER2 "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/server/client_connection.rb"
    click SERVER3 "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/server/stdio_client_connection.rb"

    %% Click Event for MCP Client
    click CLIENT "https://github.com/funwarioisii/mcp-rb/blob/master/lib/mcp/client.rb"

    %% Click Events for External Interactions
    click EX "https://github.com/funwarioisii/mcp-rb/tree/master/examples/"
    click TEST "https://github.com/funwarioisii/mcp-rb/tree/master/test/"

    %% Styles
    classDef dsl fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef core fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef server fill:#FFA500,stroke:#000,stroke-width:2px;
    classDef client fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef external fill:#FFB6C1,stroke:#000,stroke-width:2px;
```
