# headcrab/letter_mcp architecture

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

- Interactive diagram: https://gitdiagram.com/headcrab/letter_mcp
- Repository: https://github.com/headcrab/letter_mcp

## Overview

##### Project Type and Purpose
- This project is a server application for counting letters in words using an MCP-compliant protocol.
- Its main purpose is to process JSON RPC requests (via stdio or SSE) by counting specified letters (with case sensitivity), formatting the results, and returning a response.
- The README further clarifies features for counting, testing mode execution, and diverse transport support, indicating a focus on processing user input and delivering accurate results.

##### File Structure
- Top-level files include main.go, Dockerfile, docker-compose.yml, and a go.mod/go.sum, showing a Go-based project designed for containerized deployment.
- The “app” directory contains server.go, which houses the server’s startup and routing logic.
- The “letters” package includes counter.go and formatter.go, which encapsulate core business logic – letter counting and result formatting.
- The “mcp” directory contains tools.go for handling MCP protocol specifics (i.e., processing and validating JSON RPC requests).

##### User Flow
- Once the server receives the request, it:
- Validates and routes the request based on the MCP protocol guidelines (using mcp/tools.go).
- Delegates the letter counting task to the letters package (using letters/counter.go).
- Calls the formatter (letters/formatter.go) to format the output text response.
- Finally, the response is built (as a JSON RPC response) and sent back to the client.

##### Major Components
a. Client / MCP Client:
- Different transport methods (stdio and SSE) as separate entry paths if needed.

b. Main Service Entry:
- Main.go as the entry point that bootstraps the server.

c. Server Component (app/server.go):
- That this handles server configuration and initiates listening for incoming requests.

d. Business Logic – Letters Package:
- counter.go for carrying out the counting logic.
- formatter.go for formatting the results.

e. MCP Protocol Handling:
- “mcp” package (tools.go) which is responsible for processing protocol specifics (e.g., routing requests, verifying parameters).
- Interaction paths between the server and the MCP tools for command and control.

##### Architectural Patterns & Design Principles
- The project follows SOLID principles with a clear separation of concerns – server setup, business logic for letter counting, and protocol handling are all isolated in their own packages.
- Data flow from the client to server reception.
- Internal delegation to protocol tools and letter processing modules.
- Data flowing back to the client as a formatted JSON RPC response.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User flow nodes
    U["User/MCP Client (JSON RPC)"]:::client
    M["Main Service Entry (main.go)"]:::service
    S["Server Component (app/server.go)"]:::service
    P["MCP Protocol Handling (mcp/tools.go)"]:::mcp
    C["Letter Counter (letters/counter.go)"]:::business
    F["Result Formatter (letters/formatter.go)"]:::business

    %% Deployment subgraph for container configuration (hidden file names)
    subgraph "Container Deployment"
        DF["Container Config A"]:::deployment
        DC["Container Config B"]:::deployment
    end

    %% Flow connections
    U -->|"SendsJSONRPCRequest"| M
    M -->|"BootstrapsServer"| S
    S -->|"ValidatesRequest"| P
    P -->|"DelegatesCounting"| C
    C -->|"TriggersFormatting"| F
    F -->|"AssemblesResponse"| S
    S -->|"ReturnsJSONRPCResponse"| U

    %% Deployment connections
    DF ---|"DeploysVia"| M
    DC ---|"DeploysVia"| M

    %% Click Events for component mapping
    click M "https://github.com/headcrab/letter_mcp/blob/master/main.go"
    click S "https://github.com/headcrab/letter_mcp/blob/master/app/server.go"
    click P "https://github.com/headcrab/letter_mcp/blob/master/mcp/tools.go"
    click C "https://github.com/headcrab/letter_mcp/blob/master/letters/counter.go"
    click F "https://github.com/headcrab/letter_mcp/blob/master/letters/formatter.go"
    click DF "https://github.com/headcrab/letter_mcp/tree/master/Dockerfile"
    click DC "https://github.com/headcrab/letter_mcp/blob/master/docker-compose.yml"

    %% Styles
    classDef client fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef service fill:#66ccff,stroke:#333,stroke-width:2px;
    classDef mcp fill:#ff99cc,stroke:#333,stroke-width:2px;
    classDef business fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef deployment fill:#ffe6cc,stroke:#333,stroke-width:2px;
```
