# metoro-io/mcp-golang architecture

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

- Interactive diagram: https://gitdiagram.com/metoro-io/mcp-golang
- Repository: https://github.com/metoro-io/mcp-golang

## Overview

##### Project Type and Purpose
- mcp-golang is an unofficial Go implementation of the Model Context Protocol (MCP). Its purpose is to allow developers to rapidly write both servers and clients that implement MCP using Go. The library’s modular design covers tool, prompt, and resource calls, and supports multiple transports (e.g., stdio, HTTP, Gin, SSE).
- The README emphasizes type safety, low boilerplate integration, and modularity. These highlights suggest that the design should separate concerns between protocol handling, transport mechanisms, and the server/client logic.

##### Analyzing the File Structure
- Top-Level Files: There are files like client.go, server.go, content_api.go, and various API definitions (e.g., tool_api.go, prompt_api.go, resource_api.go) which indicate that the core functionality is split between client functionality and server endpoints.
- Directories:
– examples: Provides practical use cases (server, client, and several transport examples) that illustrate how the system functions in different scenarios.
– internal: Contains subdirectories such as protocol, schema, datastructures, and testing utilities. These implement the internal mechanics of protocol processing, message encoding/decoding, schema generation, and testing patterns.
– transport: Contains implementations for different transports (e.g., stdio, HTTP, Gin, SSE). This clearly indicates that the design separates transport layer logic from core protocol and business logic.

##### Main Components
a. Core Components:
- Server/Client Core: Represented by files such as server.go, client.go, tool_api.go, prompt_api.go, and resource_api.go. These handle the high-level registration and invocation of tools, prompts, and resources.
- Protocol: The “internal/protocol” directory and associated tests handle encoding/decoding and other protocol-level concerns.
- Schema Generation: In internal/schema, which generates and manages the automatic generation of JSON schemas from Go structs.
- Utilities & Datastructures: In internal/datastructures and internal/testingutils, which support the core functionalities.
b. Transport Layer:
- Multiple implementations (stdio, HTTP, Gin, SSE) are provided in the “transport” directory. This layer abstracts the communication protocol between the server and the client.
c. External Interactions:
- Tools, Prompts, and Resources: These are the registered endpoints that the server will expose, and which the client can call.
- Custom Transports: The design allows for plugging in custom transports, making the architecture extensible.
- Integration with third-party tools such as Claude (as indicated by the dedicated instructions in the README).

##### Relationships and Interactions
- The server component accepts registrations for tools, prompts, and resources. It then uses the defined protocol to generate endpoints automatically.
- The transport layer acts as an abstraction between the server/client core and the underlying communication mechanism. Different transports provide either bidirectional (stdio, SSE) or stateless (HTTP, Gin) communications.
- Example directories show how clients can invoke server methods and use different transports to communicate.

##### Architectural Patterns and Design Principles
- Modularity: The library has a clear separation between the transport, protocol, and business logic layers.
- Layered Architecture: The design clearly distinguishes between lower-level utilities (protocol handling, schema generation), transport implementations, and high-level server/client APIs.
- Extensibility: Custom transports can be plugged in, suggesting an interface-based design that decouples communication details from core logic.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Server/Client Core Layer
    subgraph "Server/Client Core"
        S["Server"]:::core
        C["Client"]:::core
        TAPI["Tool API"]:::core
        PAPI["Prompt API"]:::core
        RAPI["Resource API"]:::core
        CAPI["Content API"]:::core
        %% Server registers all API endpoints
        S -->|"registers"| TAPI
        S -->|"registers"| PAPI
        S -->|"registers"| RAPI
        S -->|"registers"| CAPI
    end

    %% Protocol & Schema Layer
    subgraph "Protocol & Schema Layer"
        PH["Protocol Handler"]:::protocol
        SG["Schema Generator"]:::protocol
        PH -->|"autogen"| SG
    end

    %% Transport Layer
    subgraph "Transport Layer"
        GT["Generic Transport"]:::transport
        HT["HTTP Transport"]:::transport
        SET["SSE Transport"]:::transport
        ST["Stdio Transport"]:::transport
        GT --> HT
        GT --> SET
        GT --> ST
    end

    %% External Client
    subgraph "External"
        EC["External Client"]:::external
    end

    %% Utilities & Datastructures Layer
    subgraph "Utilities & Datastructures"
        DS["Datastructures"]:::utils
        TU["Testing Utilities"]:::utils
        TD["Tools Definitions"]:::utils
    end

    %% Connections between layers
    %% Core to Protocol
    S -->|"registers"| PH

    %% Protocol to Transport
    PH -->|"encodes"| GT

    %% External Client invokes through Transport
    EC -->|"send_request"| GT

    %% Utility relationships (dotted arrows)
    S -.->|"uses"| DS
    S -.->|"defines"| TD
    PH -.->|"utilizes"| TU

    %% Styling classes
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef protocol fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef transport fill:#FFD700,stroke:#000,stroke-width:1px;
    classDef utils fill:#FFB6C1,stroke:#000,stroke-width:1px;
    classDef external fill:#D3D3D3,stroke:#000,stroke-width:1px;

    %% Click Events for Server/Client Core
    click S "https://github.com/metoro-io/mcp-golang/blob/main/server.go"
    click C "https://github.com/metoro-io/mcp-golang/blob/main/client.go"
    click TAPI "https://github.com/metoro-io/mcp-golang/blob/main/tool_api.go"
    click PAPI "https://github.com/metoro-io/mcp-golang/blob/main/prompt_api.go"
    click RAPI "https://github.com/metoro-io/mcp-golang/blob/main/resource_api.go"
    click CAPI "https://github.com/metoro-io/mcp-golang/blob/main/content_api.go"

    %% Click Events for Protocol & Schema
    click PH "https://github.com/metoro-io/mcp-golang/tree/main/internal/protocol"
    click SG "https://github.com/metoro-io/mcp-golang/tree/main/internal/schema"

    %% Click Events for Utilities & Datastructures
    click DS "https://github.com/metoro-io/mcp-golang/tree/main/internal/datastructures"
    click TU "https://github.com/metoro-io/mcp-golang/tree/main/internal/testingutils"
    click TD "https://github.com/metoro-io/mcp-golang/tree/main/internal/tools"

    %% Click Events for Transport Layer
    click GT "https://github.com/metoro-io/mcp-golang/tree/main/transport"
    click HT "https://github.com/metoro-io/mcp-golang/tree/main/transport/http"
    click SET "https://github.com/metoro-io/mcp-golang/tree/main/transport/sse"
    click ST "https://github.com/metoro-io/mcp-golang/tree/main/transport/stdio"
```
