# thinkinaixyz/go-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/thinkinaixyz/go-mcp
- Repository: https://github.com/thinkinaixyz/go-mcp

## Overview

##### Project Type and Purpose
- Type: An open‑source Go SDK/library implementing the Model Context Protocol (MCP).
- Purpose: Provide a modular, high‑performance, strongly‑typed API for bidirectional communication between AI applications and external systems over multiple transports.

##### File Structure
- Top‑level “client” and “server” packages → User Layer APIs.
- “protocol” package → Core MCP types, encoding/decoding, tool definitions.
- “transport” package → Transport interface and concrete implementations (SSE, HTTP POST, Stdio).
- “pkg” → Shared utilities (logging, JSON helper, sync primitives).
- “examples” and “docs” → Usage samples and design documentation.

##### README Insights
- Confirms a three‑layer architecture: Transport, Protocol, User.
- Shows supported transports (HTTP SSE/POST, Stdio).
- Mentions extensibility via a unified transport interface.

##### Main Components
a. **External Systems / Consumer Applications**
- AI applications or any Go program that uses Go‑MCP as client or server.
b. **User Layer**
- `client` package: MCP Client API
- `server` package: MCP Server API + Session Manager
c. **Protocol Layer**
- `protocol` package: message types (Initialize, CallTool, Progress, etc.), JSON‑RPC handling, validation
d. **Transport Layer**
- `transport` package: `Transport` interface
- Implementations: SSE client/server, HTTP POST, Stdio client/server, mock transports for testing
e. **Utilities**
- `pkg` package: common helpers (logging, errors, atomic booleans, maps)
f. **Examples & Integration Points**
- `examples/*` showing standalone servers, Gin integration, filesystem client, etc.

##### Relationships and Data Flow
- Consumer App → (calls) → User Layer (Client API)
→ (invokes) → Protocol Layer (marshal/unmarshal JSONRPC)
→ (sends/receives) → Transport Layer → External Endpoint (HTTP SSE or stdio)
- On Server side: External Endpoint → Transport Layer → Protocol Layer → Server API → Business Logic → reverse path for responses.

##### Architectural Patterns and Principles
- **Layered Architecture**: Strict separation of concerns.
- **Interface Abstraction**: Transport interface decouples protocol from concrete network/IO.
- **Dependency Inversion**: Higher layers define interfaces; lower layers implement them.
- **Modularity & Extensibility**: New transport protocols can be added without touching protocol or user layer.

##### Technologies and Frameworks
- Go modules + standard library (net/http, encoding/json, concurrency primitives)
- JSON‑RPC pattern for protocol messages
- HTTP Server‑Sent Events (SSE) and HTTP POST for web transports
- Standard I/O streams for local IPC
- Gin (example integration)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External
    External["External Systems / Consumer Applications"]:::external
    click External "https://github.com/thinkinaixyz/go-mcp/tree/main/examples/"

    %% User Layer
    subgraph "User Layer"
        ClientAPI["Client API\n(client/)"]:::user
        ServerAPI["Server API & Session Manager\n(server/)"]:::user
    end
    click ClientAPI "https://github.com/thinkinaixyz/go-mcp/tree/main/client/"
    click ServerAPI "https://github.com/thinkinaixyz/go-mcp/tree/main/server/"

    %% Protocol Layer
    Protocol["MCP Protocol Handler\n(protocol/)"]:::protocol
    click Protocol "https://github.com/thinkinaixyz/go-mcp/tree/main/protocol/"

    %% Transport Layer
    subgraph "Transport Layer"
        TransportInterface["Transport Interface\n(transport/transport.go)"]:::transport
        SSEClient["SSE Client\n(sse_client.go)"]:::transport
        SSEServer["SSE Server\n(sse_server.go)"]:::transport
        StdioClient["Stdio Client\n(stdio_client.go)"]:::transport
        StdioServer["Stdio Server\n(stdio_server.go)"]:::transport
        MockClient["Mock Client\n(mock_client.go)"]:::transport
        MockServer["Mock Server\n(mock_server.go)"]:::transport
    end
    click TransportInterface "https://github.com/thinkinaixyz/go-mcp/blob/main/transport/transport.go"
    click SSEClient "https://github.com/thinkinaixyz/go-mcp/blob/main/transport/sse_client.go"
    click SSEServer "https://github.com/thinkinaixyz/go-mcp/blob/main/transport/sse_server.go"
    click StdioClient "https://github.com/thinkinaixyz/go-mcp/blob/main/transport/stdio_client.go"
    click StdioServer "https://github.com/thinkinaixyz/go-mcp/blob/main/transport/stdio_server.go"
    click MockClient "https://github.com/thinkinaixyz/go-mcp/blob/main/transport/mock_client.go"
    click MockServer "https://github.com/thinkinaixyz/go-mcp/blob/main/transport/mock_server.go"

    %% Utilities
    Utilities["Utilities\n(pkg/)"]:::util
    click Utilities "https://github.com/thinkinaixyz/go-mcp/tree/main/pkg/"

    %% Boundary
    Boundary["Network / StdIO Boundary"]:::boundary

    %% Relationships
    External -->|"uses"| ClientAPI
    External -->|"uses"| ServerAPI

    ClientAPI -->|"client.SendRequest()"| Protocol
    ServerAPI -->|"server.Receive()"| Protocol

    Protocol -->|"uses interface"| TransportInterface
    Protocol -->|"respond via"| TransportInterface

    TransportInterface -->|"implemented by"| SSEClient
    TransportInterface -->|"implemented by"| SSEServer
    TransportInterface -->|"implemented by"| StdioClient
    TransportInterface -->|"implemented by"| StdioServer
    TransportInterface -->|"implemented by"| MockClient
    TransportInterface -->|"implemented by"| MockServer

    SSEClient -->|"Write()/Listen()"| Boundary
    Boundary -->|"HTTP SSE"| SSEServer

    StdioClient -->|"Write()/Read()"| Boundary
    Boundary -->|"StdIO"| StdioServer

    MockClient -.->|"for testing"| MockServer

    Utilities -.-> ClientAPI
    Utilities -.-> ServerAPI
    Utilities -.-> Protocol
    Utilities -.-> TransportInterface

    %% Styles
    classDef external fill:#eceff1,stroke:#90a4ae,color:#37474f,stroke-width:1px;
    classDef user fill:#bbdefb,stroke:#42a5f5,color:#0d47a1,stroke-width:1px;
    classDef protocol fill:#c8e6c9,stroke:#66bb6a,color:#1b5e20,stroke-width:1px;
    classDef transport fill:#ffe0b2,stroke:#ffb74d,color:#e65100,stroke-width:1px;
    classDef util fill:#e1bee7,stroke:#ab47bc,color:#4a148c,stroke-width:1px;
    classDef boundary fill:#f5f5f5,stroke:#bdbdbd,color:#424242,stroke-width:1px;
```
