# kakkky/mcp-sdk-go architecture

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

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

## Overview

##### Project Type & Purpose
- This is an SDK (library/tool) implemented in Go for the Model Context Protocol (MCP).
- It provides two main facets:
- A client library (`client/`)
- A server library (`mcp-server/` plus wrapper `McpServer`)
- Underlying both is a shared “protocol engine” (`shared/`) and a transport abstraction (stdio).
- Example programs (in `examples/`) show how to wire the client and server into stand-alone processes.

##### Main Components
A. Shared Core (shared/)
- schema: JSON-RPC schema definitions (requests, notifications, errors, capabilities, etc.)
- protocol: Core JSON-RPC engine (enforce capabilities, handlers)
- transport: Abstraction over I/O (stdio read/write buffers, interfaces)
- utilities: Helpers (e.g. URI template processor)
B. Client Library (client/)
- `client.Client`: high-level client API (ListTools, CallTool, ListResources, Ping, etc.)
- Under the hood uses `shared/protocol` + `shared/transport` via a stdio client transport
- Mock packages for unit tests
C. Server Library (mcp-server/)
- `Server`: low-level JSON-RPC engine (SetRequestHandler, SendNotification, Ping, etc.)
- `McpServer`: façade over Server adding Tool/Resource/Prompt registration APIs
- ResourceTemplate support (URI templating)
- Capability validators, request handler wiring
- Uses same `shared/protocol` + `shared/transport` via a stdio server transport
D. Examples
- `examples/client`: shows spawning a server process and using the client API
- `examples/server`: shows wiring up a McpServer with Tools/Resources/Prompts

##### Interactions & Data Flow
[ Client Process ]      <–STDIO/JSON-RPC–>      [ Server Process ]
- Inside Client Process:
- client.NewClient → shared.Protocol → transport.NewStdioClientTransport → os.Stdin/os.Stdout
- On connect: initialization handshake (capabilities) → operation phase → client.SendXXX() calls → JSON-RPC requests
- Inside Server Process:
- mcpserver.NewMcpServer → Server (shared.Protocol) → transport.NewStdioServerTransport → os.Stdin/os.Stdout
- On connect: handles init requests, then dispatches to registered Tool/Resource/Prompt handlers → sends JSON-RPC responses/notifications

##### Architectural Patterns & Design Principles
- Layered architecture:
- Transport layer (stdio) at bottom
- Protocol layer (JSON-RPC handling, capability negotiation) in middle
- SDK façade (Client, McpServer) at top
- Facade pattern: `McpServer` wraps lower-level `Server` to simplify registration of Tools/Resources/Prompts
- Plugin/registration pattern: Users register callbacks for tools, resources, prompts at runtime
- Interface segregation: Transport is pluggable; additional transports (HTTP, SSE) can be added later

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Example Apps
    subgraph "Example Applications"
        direction LR
        EX_CLIENT["Example Client App"]:::external
        EX_SERVER_STDIO["Example Server App (stdio)"]:::external
        EX_SERVER_REQ["Example Server App (request-driven)"]:::external
    end

    %% Shared Core
    subgraph "Shared Core"
        direction TB
        SCHEMA["Schema"]:::shared
        PROTOCOL["Protocol"]:::shared
        TRANSPORT["Transport (stdio)"]:::shared
        UTIL["Utilities (URI Templates)"]:::shared
    end

    %% Client SDK
    subgraph "Client SDK"
        direction TB
        CLIENT["client.Client"]:::client
        CLIENT_VAL["Capability Validators"]:::client
        CLI_TRANSPORT["Stdio Transport"]:::client
        CLIENT_MOCK["Client Mocks"]:::client
    end

    %% Server SDK
    subgraph "Server SDK"
        direction TB
        SERVER_CORE["Server (JSON-RPC Engine)"]:::server
        SERVER_VAL["Capability Validators"]:::server
        SERVER_FACADE["McpServer Facade"]:::server
        SERVER_RESOURCE["ResourceTemplate Support"]:::server
        SERVER_SET["set_request_handlers"]:::server
        SERVER_HANDLE["handle_completion"]:::server
        SERVER_SEND["send_list_changed"]:::server
        SERVER_TRANSPORT["Stdio Transport"]:::server
        SERVER_MOCK["Server Mocks"]:::server
    end

    %% OS Stdio
    OS["OS Stdio (stdin/stdout)"]:::external

    %% Relationships
    EX_CLIENT -->|calls| CLIENT
    CLIENT -->|uses| PROTOCOL
    CLIENT -->|uses| CLI_TRANSPORT
    CLIENT -->|uses| CLIENT_VAL
    CLIENT -->|uses| CLIENT_MOCK

    EX_SERVER_STDIO -->|calls| SERVER_FACADE
    EX_SERVER_REQ -->|calls| SERVER_FACADE
    SERVER_FACADE -->|wraps| SERVER_CORE
    SERVER_CORE -->|uses| PROTOCOL
    SERVER_CORE -->|uses| SERVER_VAL
    SERVER_CORE -->|uses| SERVER_MOCK

    CLI_TRANSPORT -->|reads/writes| OS
    SERVER_TRANSPORT -->|reads/writes| OS
    PROTOCOL -->|calls| TRANSPORT
    TRANSPORT -->|abstracts IO| OS
    UTIL -->|helper for| SERVER_RESOURCE

    %% STDIO / JSON-RPC between processes
    EX_CLIENT <-->|"STDIO / JSON-RPC"| EX_SERVER_STDIO

    %% Click Events
    click SCHEMA "https://github.com/kakkky/mcp-sdk-go/tree/main/shared/schema/"
    click PROTOCOL "https://github.com/kakkky/mcp-sdk-go/tree/main/shared/protocol/"
    click PROTOCOL "https://github.com/kakkky/mcp-sdk-go/blob/main/shared/protocol_interface.go"
    click TRANSPORT "https://github.com/kakkky/mcp-sdk-go/blob/main/shared/transport/stdio_read_buffer.go"
    click UTIL "https://github.com/kakkky/mcp-sdk-go/blob/main/shared/utilities/uri-template/uri_template.go"
    click CLIENT "https://github.com/kakkky/mcp-sdk-go/blob/main/client/client.go"
    click CLIENT_VAL "https://github.com/kakkky/mcp-sdk-go/blob/main/client/capability_validators.go"
    click CLI_TRANSPORT "https://github.com/kakkky/mcp-sdk-go/blob/main/client/transport/stdio.go"
    click CLIENT_MOCK "https://github.com/kakkky/mcp-sdk-go/tree/main/client/mock/"
    click SERVER_CORE "https://github.com/kakkky/mcp-sdk-go/blob/main/mcp-server/server/server.go"
    click SERVER_VAL "https://github.com/kakkky/mcp-sdk-go/blob/main/mcp-server/server/capability_validators.go"
    click SERVER_FACADE "https://github.com/kakkky/mcp-sdk-go/blob/main/mcp-server/mcp_server.go"
    click SERVER_FACADE "https://github.com/kakkky/mcp-sdk-go/blob/main/mcp-server/registerd_capabilities.go"
    click SERVER_RESOURCE "https://github.com/kakkky/mcp-sdk-go/blob/main/mcp-server/resource_template.go"
    click SERVER_SET "https://github.com/kakkky/mcp-sdk-go/blob/main/mcp-server/set_request_handlers.go"
    click SERVER_HANDLE "https://github.com/kakkky/mcp-sdk-go/blob/main/mcp-server/handle_completion.go"
    click SERVER_SEND "https://github.com/kakkky/mcp-sdk-go/blob/main/mcp-server/send_list_changed.go"
    click SERVER_TRANSPORT "https://github.com/kakkky/mcp-sdk-go/blob/main/mcp-server/transport/stdio.go"
    click SERVER_MOCK "https://github.com/kakkky/mcp-sdk-go/tree/main/mcp-server/server/mock/"
    click EX_CLIENT "https://github.com/kakkky/mcp-sdk-go/blob/main/examples/client/cli-use/main.go"
    click EX_SERVER_STDIO "https://github.com/kakkky/mcp-sdk-go/blob/main/examples/server/with-stdio/main.go"
    click EX_SERVER_REQ "https://github.com/kakkky/mcp-sdk-go/blob/main/examples/server/request-from-server/main.go"

    %% Styles
    classDef shared fill:#D0E8FF,stroke:#0288D1,color:#000
    classDef client fill:#DFF8E1,stroke:#43A047,color:#000
    classDef server fill:#FFE6CC,stroke:#FB8C00,color:#000
    classDef external fill:#F5F5F5,stroke:#9E9E9E,color:#000
```
