# olgasafonova/gleif-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/olgasafonova/gleif-mcp-server
- Repository: https://github.com/olgasafonova/gleif-mcp-server

## Overview

##### What this project is (type + purpose)
This is a **Go-based MCP (Model Context Protocol) “tool server”** packaged as a **single binary** (`main.go`) that exposes **~29 MCP tools** (LEI lookup, validation, search, relationships, issuers, etc.) to MCP-compatible clients (Claude Desktop, Cursor, VS Code extensions, Windsurf, etc.).
At runtime it acts as a **local broker** between an MCP client and the **public GLEIF REST API** (`https://api.gleif.org/api/v1`) and adds **cross-cutting concerns**: caching (LRU+TTL), rate limiting, retries/backoff, structured errors, and response shaping into JSON.

##### How the repo is structured (what to reflect
From the tree + README “Architecture” section:

##### Runtime / product code
- `main.go` — **entry point**, MCP server setup, wiring tools → handlers → client.
- `tools/`
- `definitions.go` — **tool metadata** (names, params, schema/spec).
- `handlers.go` — **tool implementations** (each tool → calls internal client methods).
- `internal/gleif/`
- `client.go` — **GLEIF API client** + caching + rate limiting + retries.
- `cache.go` — **LRU cache with TTL** (two logical caches per README: entities + searches).
- `types.go` — **response DTOs / structs** for parsing & returning.
- `errors.go` — **structured error types** (`not_found`, `invalid_format`, `rate_limited`, etc.).

- `Dockerfile` — container packaging (even if typical use is local binary).
- `.github/workflows/*` — CI, release, docker publishing pipeline.
- `Makefile`, `scripts/build-mcpb.sh` — build automation.

##### System Context (C4 L1) — “who talks to whom”
**Goal:** show the real-world runtime boundary: AI client ↔ local MCP server ↔ external GLEIF.

Nodes:
##### GLEIF Public API (external)

- MCP Client → MCP Server: **MCP over stdio** (tool invocation: `name`, `arguments`)
- MCP Server → MCP Client: **MCP response** (JSON result or structured error)
- MCP Server → GLEIF API: **HTTPS REST** (GETs to `/api/v1/...`)
- GLEIF API → MCP Server: **JSON API responses / HTTP errors**

- **Rate limiting** (50 req/min configured; external limit 60)
- **Retries** (3 attempts, exponential backoff)
- **Caching** (15 min TTL; capacities: 1000 entity, 500 searches)
- **No API key**

##### Container / Runtime view (C4 L2) — “what runs where”
Even though it’s a single binary, you still want to separate “containers” conceptually:

- **MCP Server Process (Go binary)**
- MCP transport adapter (stdio)
- Tool registry (definitions)
- Tool handlers (business logic)
- GLEIF client (HTTP)
- Cache (in-memory)
- Rate limiter + retry policy
- **External system**: GLEIF API

Optionally add:
- **Developer/CI pipeline** container (GitHub Actions) producing releases and Docker images
- **Docker container** runtime option (from `Dockerfile`), even if typical usage is direct binary

##### Entry / Wiring
- `main.go`
- Responsibilities: instantiate MCP server, register tools, create `gleif.Client`, attach handlers.

##### Tool Surface
- `tools/definitions.go`: tool schemas + parameter specs
- `tools/handlers.go`: handlers per tool (lei_lookup, validate_lei, batch, search, relationships, issuers, exceptions…)

##### Domain/Integration Layer
- `internal/gleif/client.go`: request builder, endpoints, pagination handling, mapping to types
- `internal/gleif/types.go`: DTOs / models
- `internal/gleif/errors.go`: canonical error mapping for MCP responses

##### Cross-cutting
- `internal/gleif/cache.go`: LRU+TTL caches (separate caches for entity vs search results)
- Rate limiter (in client) + retry/backoff (in client)

##### External
- GLEIF REST API

- `main.go` → `tools` (register)
- `tools/handlers.go` → `internal/gleif/client.go` (invoke)
- `client.go` → `cache.go` (get/set)
- `client.go` → GLEIF API (HTTP)
- `client.go` → `errors.go` (translate HTTP/network errors → structured error codes)

##### Handler
- validate input format (LEI length/check digits) → if fail return `invalid_format`
##### Client → Cache: lookup key
- **Cache hit** → return cached entity (fast path)
- **Cache miss**:
- Client → RateLimiter: acquire token
- Client → GLEIF API: HTTPS GET
- API → Client: response / 404 / 429 / timeout
- Client → Retry policy: maybe retry (timeouts, 429, network errors)
- Client → Cache: store success
##### Handler → MCP Client: JSON response

Do a second mini-sequence (or annotate branches) for:
- 429 rate limit → retry → eventual `rate_limited` error
- 404 → `not_found` error (non-retryable)

##### Relationships/interactions to highlight (the “truths” of the architecture)
These are the architectural “center points” worth emphasizing visually:

- **Tool registry is data-driven** (`tools/definitions.go`) while behavior lives in `tools/handlers.go`.
- The server is a **thin MCP façade**; most complexity is in the **GLEIF client** (caching, retries, rate limiting, error mapping).
- **External dependency is singular**: GLEIF API. That makes this a classic “adapter/proxy with resilience”.
- **Performance is primarily cache-driven** (repeat queries become instant).
- **No persistence**: cache is in-memory only (important to call out so nobody assumes DB).

- Developer/Release pipeline:
- GitHub Actions (`.github/workflows/release.yml`, `docker.yml`) → produces binaries + Docker image
- End-user runtime:
- MCP Client config file (Claude Desktop JSON / Cursor mcp.json / Continue config) → launches **local binary** as subprocess → stdio MCP

This helps readers understand “it’s not a hosted API; it’s a local tool server”.

##### A concrete “best final output” checklist
Deliver these 4 artifacts:

## Diagram (Mermaid)

```mermaid
flowchart TD
  %% =========================
  %% A) System Context (C4 L1)
  %% =========================
  subgraph AContext["A) System Context (C4 L1)"]
    MCPClient["MCP Client\n(Claude Desktop / Cursor / VS Code / Windsurf / CLI)"]:::external

    subgraph GLEIFLocal["GLEIF MCP Server (Local Go Process)"]
      MCPServer["GLEIF MCP Server\n(single binary)"]:::runtime
      LocalCache[("In-memory Cache\nLRU + TTL (15 min)\nEntity: 1000, Search: 500")]:::crosscut
      Resilience["Resilience Policies\nRateLimit: 50 req/min\nRetries: 3 (exp backoff)\nNo API key"]:::crosscut
    end

    GLEIFAPI["GLEIF Public REST API\nhttps://api.gleif.org/api/v1"]:::external

    MCPClient -->|"MCP_over_stdio(tool:name+arguments)"| MCPServer
    MCPServer -->|"MCP_response(JSON_result_or_structured_error)"| MCPClient

    MCPServer -->|"HTTPS_GET(/api/v1/...)"| GLEIFAPI
    GLEIFAPI -->|"JSON_responses_or_HTTP_errors"| MCPServer

    MCPServer --- LocalCache
    MCPServer --- Resilience
  end

  %% ==================================
  %% B) Container / Runtime View (C4 L2)
  %% ==================================
  subgraph BContainer["B) Container / Runtime View (C4 L2)"]
    subgraph EndUserMachine["End User Machine"]
      MCPClient2["MCP Client"]:::external

      subgraph MCPProc["MCP Server Process (Go binary)"]
        Transport["MCP Transport Adapter\n(stdio)"]:::runtime
        Registry["Tool Registry\n(definitions)"]:::runtime
        Handlers["Tool Handlers\n(implementations)"]:::runtime
        GClient["GLEIF Client (HTTP)"]:::runtime
        Cache2[("In-memory LRU+TTL Cache\n(entity + search)")]:::crosscut
        RateLimiter["Rate Limiter\n(50 req/min)"]:::crosscutDashed
        Retry["Retry/Backoff\n(3 attempts, exp)"]:::crosscutDashed
        ErrorMap["Structured Errors\n(not_found, invalid_format,\nrate_limited, ...)"]:::runtime
      end
    end

    GLEIFAPI2["GLEIF Public REST API\n(External)"]:::external

    MCPClient2 -->|"MCP_over_stdio"| Transport
    Transport -->|"dispatch_tool_call"| Registry
    Registry -->|"route_to_handler"| Handlers
    Handlers -->|"invoke_client_methods"| GClient

    GClient -->|"cache_get/set"| Cache2
    GClient -->|"acquire"| RateLimiter
    GClient -->|"retry_on(429/timeout/network)"| Retry
    GClient -->|"map_errors_to_codes"| ErrorMap
    GClient -->|"HTTPS_JSON"| GLEIFAPI2
  end

  %% =================================
  %% C) Component View (C4 L3 / Code)
  %% =================================
  subgraph CComponent["C) Component View (C4 L3) - Code Mapped"]
    subgraph EntryWiring["Entry / Wiring"]
      Main["main.go\nEntry point\nMCP server setup + wiring"]:::runtime
    end

    subgraph ToolSurface["Tool Surface (tools/)"]
      ToolDefs["Tool Metadata\n(names, params, schemas)"]:::runtime
      ToolHandlers["Tool Implementations\n(handlers per tool)"]:::runtime
    end

    subgraph IntegrationLayer["Integration Layer (internal/gleif/)"]
      Client["GLEIF API Client\nHTTP + pagination + shaping"]:::runtime
      Types["DTOs / Models\n(parse + return structs)"]:::runtime
      Errors["Structured Error Mapping\n(not_found, invalid_format,\nrate_limited, ...)"]:::runtime
    end

    subgraph CrossCutting["Cross-cutting (in client/process)"]
      Cache["LRU + TTL Cache\n(entities + searches)"]:::crosscut
      RL["Rate Limiter\n50 req/min"]:::crosscutDashed
      RP["Retry Policy\n3 attempts (exp backoff)"]:::crosscutDashed
      NoDB["No Persistence\n(in-memory only)"]:::note
    end

    ExtAPI["GLEIF REST API\n/api/v1/..."]:::external

    Main -->|"register_tools"| ToolDefs
    Main -->|"attach_handlers"| ToolHandlers
    ToolDefs -->|"drives_exposed_tool_surface"| ToolHandlers

    ToolHandlers -->|"calls"| Client
    Client -->|"uses"| Types
    Client -->|"translates"| Errors

    Client -->|"get/set"| Cache
    Client -->|"acquire"| RL
    Client -->|"retry_on_429_timeout_network"| RP
    Client -->|"HTTPS_JSON"| ExtAPI

    Cache --- NoDB
  end

  %% ==========================================
  %% D) Optional: Build / Deployment (High value)
  %% ==========================================
  subgraph DDeploy["D) Build & Deployment (Optional)"]
    subgraph CIRelease["CI / Release"]
      GHA_CI["GitHub Actions\nCI Workflow"]:::ops
      GHA_Release["GitHub Actions\nRelease Workflow"]:::ops
      GHA_Docker["GitHub Actions\nDocker Publish Workflow"]:::ops
      Artifacts["Release Artifacts\nsingle binaries + Docker image"]:::ops
    end

    subgraph PackagingConfig["Packaging / Config"]
      Docker["Docker Runtime Option\n(container image)"]:::ops
      BuildMakefile["Build Automation\nMakefile"]:::ops
      BuildScript["Build Automation\nscripts/build-mcpb.sh"]:::ops
      MCPManifest["MCP Integration Metadata\nmanifest.json"]:::ops
      MCPServerCfg["MCP Integration Metadata\nserver.json"]:::ops
    end

    GHA_CI -->|"build_test"| Artifacts
    GHA_Release -->|"release"| Artifacts
    GHA_Docker -->|"docker_publish"| Artifacts

    BuildMakefile -->|"build_binary"| Artifacts
    BuildScript -->|"build_binary"| Artifacts
    Artifacts -->|"optional_container"| Docker

    MCPManifest -->|"client_launches_local_subprocess"| MCPServer
    MCPServerCfg -->|"client_launches_local_subprocess"| MCPServer
  end

  %% ======================
  %% Sequence Diagram (E)
  %% ======================
  subgraph ESequence["E) Sequence - lei_lookup Tool Call"]
    SEQ_NOTE["Representative flow: lei_lookup\nCache hit/miss + retries + structured errors"]:::note

    subgraph SeqParticipants["Participants"]
      SC["MCP Client"]:::external
      SS["MCP Server (stdio)"]:::runtime
      SH["lei_lookup Handler"]:::runtime
      SG["GLEIF Client"]:::runtime
      SCache[("LRU+TTL Cache")]:::crosscut
      SRL["Rate Limiter"]:::crosscutDashed
      SRetry["Retry Policy"]:::crosscutDashed
      SAPI["GLEIF API"]:::external
    end

    SC -->|"tool_call(name=lei_lookup,args={lei})"| SS
    SS -->|"dispatch"| SH
    SH -->|"validate_LEI_format"| SH
    SH -->|"GetEntity(lei)"| SG
    SG -->|"cache_lookup(key=lei)"| SCache

    SCache -->|"hit:entity_dto"| SG
    SG -->|"return_dto"| SH
    SH -->|"MCP_result(JSON)"| SC

    SG -->|"miss:acquire"| SRL
    SRL -->|"token"| SG
    SG -->|"HTTPS_GET(/lei-records/{lei})"| SAPI
    SAPI -->|"200_JSON / 404 / 429 / timeout"| SG
    SG -->|"retry_if(429/timeout/network)\nmax=3_backoff"| SRetry
    SRetry -->|"retry_or_give_up"| SG
    SG -->|"store_success"| SCache
    SG -->|"dto_or_structured_error\n(not_found/rate_limited/etc.)"| SH
    SH -->|"MCP_response(JSON_or_error_code)"| SC
  end

  %% ======================
  %% Click Events (Mapped)
  %% ======================
  click Main "https://github.com/olgasafonova/gleif-mcp-server/blob/main/main.go"
  click ToolDefs "https://github.com/olgasafonova/gleif-mcp-server/blob/main/tools/definitions.go"
  click ToolHandlers "https://github.com/olgasafonova/gleif-mcp-server/blob/main/tools/handlers.go"
  click Client "https://github.com/olgasafonova/gleif-mcp-server/blob/main/internal/gleif/client.go"
  click Cache "https://github.com/olgasafonova/gleif-mcp-server/blob/main/internal/gleif/cache.go"
  click Types "https://github.com/olgasafonova/gleif-mcp-server/blob/main/internal/gleif/types.go"
  click Errors "https://github.com/olgasafonova/gleif-mcp-server/blob/main/internal/gleif/errors.go"
  click Docker "https://github.com/olgasafonova/gleif-mcp-server/tree/main/Dockerfile"
  click GHA_CI "https://github.com/olgasafonova/gleif-mcp-server/blob/main/.github/workflows/ci.yml"
  click GHA_Release "https://github.com/olgasafonova/gleif-mcp-server/blob/main/.github/workflows/release.yml"
  click GHA_Docker "https://github.com/olgasafonova/gleif-mcp-server/blob/main/.github/workflows/docker.yml"
  click BuildMakefile "https://github.com/olgasafonova/gleif-mcp-server/tree/main/Makefile"
  click BuildScript "https://github.com/olgasafonova/gleif-mcp-server/blob/main/scripts/build-mcpb.sh"
  click MCPManifest "https://github.com/olgasafonova/gleif-mcp-server/blob/main/manifest.json"
  click MCPServerCfg "https://github.com/olgasafonova/gleif-mcp-server/blob/main/server.json"

  %% ======================
  %% Styles
  %% ======================
  classDef runtime fill:#1f77b4,stroke:#0b3d6e,color:#ffffff,stroke-width:1px
  classDef external fill:#f39c12,stroke:#8a4b08,color:#111111,stroke-width:1px
  classDef crosscut fill:#95a5a6,stroke:#4d5a60,color:#111111,stroke-width:1px
  classDef crosscutDashed fill:#bdc3c7,stroke:#4d5a60,color:#111111,stroke-width:2px,stroke-dasharray:6 4
  classDef ops fill:#2ecc71,stroke:#1f7a3a,color:#0b1a0f,stroke-width:1px
  classDef note fill:#fff2cc,stroke:#d6b656,color:#111111,stroke-width:1px
```
