How olgasafonova/gleif-mcp-server works
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: