# smallnest/mcp-prompt-server-go architecture

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

- Interactive diagram: https://gitdiagram.com/smallnest/mcp-prompt-server-go
- Repository: https://github.com/smallnest/mcp-prompt-server-go

## Overview

##### Project Type and Purpose
- This is a **backend service** (an open-source MCP “tool” server) written in Go.
- It loads prompt templates (YAML/JSON), registers them as MCP tools via the `mark3labs/mcp-go` library, and exposes them over stdio or TCP for clients (Raycast, Cursor, Windsurf, etc.).

##### Main Components
a. **CLI / Entry Point** (`cmd/main.go`)
– Runs on server start, initializes configuration, kicks off prompt loader and server.
b. **Server Layer** (`internal/server/server.go`)
– Hosts the MCP tool service. Listens on stdio or network sockets, dispatches incoming requests.
c. **Prompt Loader & Model** (`internal/prompt/loader.go` & `model.go`)
– Scans `prompts/` directory, parses YAML/JSON into in-memory `Prompt` structures.
– Supports hot-reload commands (`reload_prompts`).
d. **Utility Module** (`internal/util/files.go`)
– File system helpers for scanning directories, watching file changes.
e. **Prompt Templates** (`prompts/*.yaml`)
– Source of truth for all prompt definitions (names, descriptions, arguments, message bodies).
f. **External Library** (`mark3labs/mcp-go`)
– Under the hood, provides MCP tooling interfaces, registration APIs, request/response handling.
g. **External Clients** (Raycast, Cursor, Windsurf, Cherrystudio, etc.)
– Issue MCP calls (via stdio or TCP) to the running server executable.

##### Relationships & Data Flow
1. **Startup**
– `main.go` calls `loader.LoadAll(prompts/)` → builds in-memory prompt registry.
– Registers each prompt as an MCP tool via `mcp-go` APIs.
– Starts the MCP service in `server.go`, listening on stdio or port.
2. **Runtime**
– Client sends MCP request (tool name + arguments) → Server receives request →
– Look up corresponding prompt model → Fill template placeholders → Forward to LLM or embedded engine → Receive response → Stream back to client.
3. **Hot-Reload**
– On `reload_prompts` command or file-watch event → Loader rescans `prompts/` → Unregister old tools → Register new/updated ones.

##### Architectural Patterns & Principles
- **Separation of Concerns**: CLI, server dispatch, prompt loading, and file utilities are in distinct packages.
- **Plugin-Style Registration**: Prompts auto-register as independent tools.
- **Hot-Reload**: Dynamic reconfiguration without restart.
- **Modular Design**: New prompt files add functionality without touching Go code.

##### Technologies & Frameworks
- Go modules (`go.mod`, `go.sum`)
- `mark3labs/mcp-go` for tool registration & request handling
- YAML/JSON parsing (Go stdlib or third-party lib)
- File I/O and (optional) fsnotify for hot-reload
- Standard I/O or TCP transport for MCP protocol

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Internal Modules
    subgraph "Internal Modules"
        direction TB
        CLI["CLI / Entrypoint\n(cmd/main.go)"]:::internal
        Loader["Prompt Loader\n(internal/prompt/loader.go)"]:::internal
        Model["Prompt Model\n(internal/prompt/model.go)"]:::internal
        FSUtils["File System Utilities\n(internal/util/files.go)"]:::internal
        Server["MCP Server\n(internal/server/server.go)"]:::internal
    end

    %% Prompt Templates
    subgraph "Prompt Templates"
        direction TB
        PromptsDir["Templates Directory\n(prompts/)"]:::prompt
        ExampleYAML["gen_html_web_page.yaml"]:::prompt
        MoreDir["Additional Templates\n(prompts/more/)"]:::prompt
    end

    %% External Library
    Lib["mcp-go Library"]:::lib

    %% External Clients
    subgraph "External Clients"
        direction TB
        Raycast["Raycast"]:::client
        Cursor["Cursor"]:::client
        Windsurf["Windsurf"]:::client
        Cherrystudio["Cherrystudio"]:::client
    end

    %% External Systems
    LLM["LLM/Engine"]:::external

    %% Startup Flow
    CLI -->|"LoadAll(prompts/)"| Loader
    Loader -->|"parse templates"| Model
    Loader -->|"scan/watch files"| FSUtils
    Loader -->|"RegisterTool()"| Lib
    CLI -->|"StartService()"| Server
    Server -->|"use MCP API"| Lib

    %% Runtime Flow
    Raycast -->|"Invoke tool"| Server
    Cursor -->|"Invoke tool"| Server
    Windsurf -->|"Invoke tool"| Server
    Cherrystudio -->|"Invoke tool"| Server
    Server -->|"Lookup Prompt"| Model
    Model -->|"Fill & Call"| LLM
    LLM -->|"Response"| Server
    Server -->|"Stream Response"| Raycast
    Server -->|"Stream Response"| Cursor
    Server -->|"Stream Response"| Windsurf
    Server -->|"Stream Response"| Cherrystudio

    %% Hot-Reload Flow
    PromptsDir -.->|"file change"| FSUtils
    ExampleYAML -.-> FSUtils
    MoreDir -.-> FSUtils
    FSUtils -->|"reload_prompts"| Loader
    Loader -->|"Unregister/Register"| Lib

    %% File Ingestion
    PromptsDir --> Model
    PromptsDir --> Loader

    %% Configuration & Build
    GoMod["go.mod"]:::config
    Executable["bin/mcp-prompt-server"]:::config
    GoMod --> CLI
    CLI --> Executable

    %% Click Events
    click CLI "https://github.com/smallnest/mcp-prompt-server-go/blob/master/cmd/main.go"
    click Loader "https://github.com/smallnest/mcp-prompt-server-go/blob/master/internal/prompt/loader.go"
    click Model "https://github.com/smallnest/mcp-prompt-server-go/blob/master/internal/prompt/model.go"
    click FSUtils "https://github.com/smallnest/mcp-prompt-server-go/blob/master/internal/util/files.go"
    click Server "https://github.com/smallnest/mcp-prompt-server-go/blob/master/internal/server/server.go"
    click PromptsDir "https://github.com/smallnest/mcp-prompt-server-go/tree/master/prompts/"
    click ExampleYAML "https://github.com/smallnest/mcp-prompt-server-go/blob/master/prompts/gen_html_web_page.yaml"
    click MoreDir "https://github.com/smallnest/mcp-prompt-server-go/tree/master/prompts/more/"
    click GoMod "https://github.com/smallnest/mcp-prompt-server-go/blob/master/go.mod"
    click Executable "https://github.com/smallnest/mcp-prompt-server-go/tree/master/bin/mcp-prompt-server"

    %% Styles
    classDef internal fill:#e0ffe0,stroke:#2d662d,stroke-width:1px
    classDef prompt fill:#fff5b1,stroke:#806600,stroke-width:1px
    classDef lib fill:#b1d4ff,stroke:#004d99,stroke-width:1px
    classDef client fill:#ffd1a9,stroke:#994c00,stroke-width:1px
    classDef external fill:#f2f2f2,stroke:#666666,stroke-width:1px,stroke-dasharray: 5 5
    classDef config fill:#e8e8e8,stroke:#333333,stroke-width:1px,stroke-dasharray: 2 2
```
