# Architecture — mermaid-mcp
This document explains the architecture of **mermaid-mcp**: how responsibilities are split, how requests flow through the system, and how the design supports safe access, predictable behavior, and easy extensibility.
<!-- Table of contents for quick navigation -->
## Table of contents
- [Goals](#goals)
- [Architecture at a glance](#architecture-at-a-glance)
- [Directory map (where things live)](#directory-map-where-things-live)
- [Request flow](#request-flow)
- [The FileSource contract (the core idea)](#the-filesource-contract-the-core-idea)
- [Source Factory (how backends are selected)](#source-factory-how-backends-are-selected)
- [Component responsibilities](#component-responsibilities)
- [Path and filtering semantics (stable behavior)](#path-and-filtering-semantics-stable-behavior)
- [Cross-cutting policies (why they exist)](#cross-cutting-policies-why-they-exist)
- [Interaction diagram (high-level)](#interaction-diagram-high-level)
- [Prompts & Resources](#prompts--resources)
- [Error boundaries (who raises what)](#error-boundaries-who-raises-what)
- [Security boundaries and predictable behavior](#security-boundaries-and-predictable-behavior)
- [Extending the system: adding a new source](#extending-the-system-adding-a-new-source)
- [Design tradeoffs](#design-tradeoffs)
---
## Goals
- **Backend-agnostic tools**: tools should not depend on whether files come from a local folder or a remote repository.
- **Contract-driven design**: one clear contract defines what a “source” is and how it behaves.
- **Predictable runtime behavior**: bounded reads, safe output paths, and stable performance under concurrency.
- **Extensibility**: adding new sources should not require changing tools.
---
## Architecture at a glance
The server exposes three MCP tools:
- `list_files` — discover files in a source
- `read_file` — read file contents with a configured limit
- `render_mermaid` — render Mermaid → PNG via Kroki and save output
The system is organized into four layers:
1. **Tools** — MCP surface and orchestration
2. **Sources** — backends that implement the Source contract
3. **Clients** — thin wrappers around external services (GitHub/Kroki)
4. **Core** — shared contracts and cross-cutting primitives
---
## Directory map (where things live)
```text
src/
server/ # MCP server entrypoint and registration
tools/ # MCP tools (list_files / read_file / render_mermaid)
sources/ # Source implementations + source factory
clients/ # External service wrappers (GitHub / Kroki)
core/ # Shared contracts, errors, models, policies, and path semantics (paths.py)
prompts/ # Server-registered prompts used to generate Mermaid (src/prompts/)
resources/ # Packaged static resources (Mermaid styles, templates) (src/resources/)
```
---
## Request flow
A typical end-to-end pipeline:
1. The client/agent calls `list_files`.
2. The tool selects a backend source (Local / GitHub) via the factory.
3. The tool calls `source.list_files(...)`.
4. The client/agent selects a small set of files and calls `read_file`.
5. The tool calls `source.read_file(...)`.
6. The client/agent generates Mermaid from real content.
7. The client/agent calls `render_mermaid` to produce PNG output.
---
## The FileSource contract (the core idea)
The `FileSource` contract is the interface that all backends must implement. Tools interact with sources only through this contract, which keeps tools backend-agnostic and makes new backends pluggable without changing tools.
### Contract surface
The `FileSource` instance is created by the factory with any backend configuration baked in (e.g., `project_root` for local, `repo_url`/`ref` for GitHub). The tool layer does not perform backend-specific logic beyond selecting/instantiating the source.
Pseudo-signature (conceptual):
```python
class FileSource:
async def list_files(
self,
*,
root: str = ".",
glob: str = "**/*",
recursive: bool = True,
) -> list[str]:
...
async def read_file(
self,
*,
path: str,
max_chars: int,
) -> str:
...
```
### Contract guarantees
All `FileSource` implementations must guarantee:
- Normalized paths in results: `list_files(...)` returns paths in a stable, normalized form (recommended: forward slashes `/`, no leading `./`, no trailing slashes).
- Relative-to-source semantics: `root` and `path` are interpreted relative to the source’s base (local project root or remote repo root).
- Bounded reads: `read_file(...)` respects `max_chars` and never returns unbounded content.
- Consistent failure modes:
- missing file/path → `NotFoundError` (project-level error)
- invalid inputs (bad URL / illegal path) → `ValidationError`
- upstream issues (network, throttling after retries, API errors) → `ExternalServiceError`
This contract makes new sources pluggable without changing tools.
---
## Source Factory (how backends are selected)
The factory keeps tools simple and consistent.
### Selection inputs (tool parameters)
At the MCP boundary the tool typically receives:
- `source`: "local" or "github"
For local: `root`, `glob`, `recursive`, etc.
For github: `repo_url` (required), `ref` (optional; the source/client may apply sensible defaults).
### Factory behavior (conceptual)
- If `source == "local"`: create a `LocalSource(project_root=PROJECT_ROOT, ...)`.
- If `source == "github"`: validate `repo_url` and create a `GitHubSource(repo_url=..., ref=..., client=GitHubClient(...), ...)`.
Key rule: backend-specific setup belongs in the factory and source constructors, not in tools.
---
## Component responsibilities
1) Tools (orchestration layer)
What belongs here:
- Input validation at the MCP boundary (required params, type/shape checks).
- Selecting the correct source via the factory.
- Returning results in MCP-friendly formats.
- For `render_mermaid`: output filename sanitization and writing within the allowed output directory.
What does NOT belong here:
- Filesystem containment checks.
- Remote API specifics (headers, pagination, ref quirks).
- Cross-cutting policies (caching, pacing, rate-limit handling).
2) Sources (backend implementations)
Sources implement the `FileSource` contract and own backend-specific concerns.
Local source:
- Enforces the `PROJECT_ROOT` boundary (no reads outside).
- Normalizes paths and performs containment checks.
- Applies `MAX_FILE_CHARS` to keep reads bounded.
Remote repository source (GitHub today; others later):
- Translates Source operations into remote API calls.
- Handles ref resolution behavior (including default-branch fallback when appropriate).
- Delegates network concerns to a dedicated client wrapper.
3) Clients (external service wrappers)
Clients are deliberately thin. They should:
- Encapsulate HTTP details (headers, timeouts, response parsing).
- Translate service errors into project-level errors.
- Remain reusable by sources without leaking service-specific quirks.
Kroki client:
- Sends Mermaid text and receives PNG bytes.
- Returns bytes and lets the tool decide output behavior (save path, filename, overwrite policy).
Remote repo client:
- Supports listing and reading with consistent normalization and failure modes.
- Keeps higher layers clean from API mechanics.
4) Core (shared primitives and policies)
Core hosts reusable building blocks used across the project:
- `errors` — project-specific exception types
- `models` — shared data structures
- `paths` — shared path normalization + glob semantics incl. `**`
- policy primitives (caching / pacing / rate limiting) used by networked components
Core is where "how we behave" lives, preventing behavioral drift across modules.
---
## Path and filtering semantics (stable behavior)
To keep behavior predictable across sources:
- `root` is a directory-like prefix to scope listing (default `.`).
- `glob` is applied to the candidate file set (default `**/*`).
- `recursive` controls directory traversal depth for backends that support it.
Recommended rule: tools apply the same parameter meanings for both local and remote. If a backend cannot support a parameter precisely, it should approximate reasonably but keep the same output invariants (normalized paths, stable ordering if applicable).
Implementation note: shared path normalization and `glob`/`**` matching are centralized in `core/paths.py` to prevent behavioral drift.
---
## Cross-cutting policies (why they exist)
These policies are runtime safety and stability mechanisms, not service-specific features:
- Bounded reads: prevents runaway memory/time on large files (`MAX_FILE_CHARS`).
- Concurrency cap: prevents too many simultaneous network calls and reduces contention.
- Pacing: avoids burst traffic when many tasks run concurrently.
- Rate-limit handling: respects explicit server throttling signals for predictable retries.
- TTL caching: avoids repeating identical remote reads within short windows.
Outcome: stable tool latency and fewer avoidable failures under load.
---
## Interaction diagram (high-level)
```mermaid
flowchart LR
A[Client / Agent] -->|list_files| T1[Tool: list_files]
A -->|read_file| T2[Tool: read_file]
A -->|render_mermaid| T3[Tool: render_mermaid]
T1 --> F[Source Factory]
T2 --> F
F --> L[Local Source]
F --> R[Remote Repo Source]
L --> FS[(Filesystem)]
R --> RC[Remote Repo Client]
RC --> API[(Remote API)]
T3 --> KC[Kroki Client]
KC --> K[(Kroki)]
T3 --> OUT[(PNG bytes + saved file)]
```
---
## Prompts & Resources
This project includes two supporting concepts that are important for agent-driven workflows and consistent Mermaid generation: server-registered prompts and packaged resources.
Prompts
- The server exposes canonical prompts that agents/clients can use when generating Mermaid diagrams. The canonical prompt enforces the pipeline (list_files → read_file → render_mermaid), style rules, and requirements such as embedding a style resource unchanged.
- Location: `src/prompts/` (the main prompt is `src/prompts/mermaid_prompt.py`, registered under the name `generate_mermaid_canonical`).
- Usage: MCP clients that support server-side prompts can select `generate_mermaid_canonical` so agents receive a stable, curated instruction set. If a client cannot use server-side prompts, copy the prompt text from `src/prompts/mermaid_prompt.py` and keep local copies in sync with repository changes.
- Rationale: keeping a canonical prompt on the server ensures consistency across agents and reduces errors from ad-hoc prompt variants.
Resources
- The project bundles static resources used by prompts and Mermaid diagrams (for example, color/style templates).
- Location: `src/resources/` (e.g., `mermaid_style_blue_flowchart.mmd` and `mermaid_styles.py`).
- Access: prompts expect resources to be available via the resource URI scheme used by the prompt (for example `mermaid://styles/blue-flowchart`). Tools or prompts that require a resource should read it from `src/resources/` and embed it into generated Mermaid text unchanged.
- Rationale: shipping canonical styles and other small assets with the server ensures diagrams are visually consistent and that agents do not rely on external resources at render time.
Operational notes
- When updating prompts or resources, update tests and documentation to avoid breaking agents that rely on the canonical prompt or style names.
- Prompts can reference resource names; if a resource filename or name changes, update both the prompt and any code that resolves resource URIs.
---
## Error boundaries (who raises what)
Tools:
- Validate presence/shape of required parameters and raise `ValidationError` early for malformed tool calls.
Sources:
- Enforce source boundaries (e.g., local containment) and translate "not found" into `NotFoundError`.
- Propagate project-level errors upward (not raw HTTP/filesystem exceptions).
Clients:
- Translate HTTP/network failures into `ExternalServiceError`.
- Handle retryable scenarios internally (rate limit / transient errors) within a bounded retry policy.
Guiding principle: callers should never need to interpret raw HTTP status codes or OS errors.
---
## Security boundaries and predictable behavior
- Local reads are restricted to `PROJECT_ROOT` (path traversal is rejected).
- Output writes are restricted to `DIAGRAM_OUT_DIR` within `PROJECT_ROOT`.
- Reads are bounded by `MAX_FILE_CHARS` to prevent oversized payloads.
- Output filenames derived from `title` are sanitized to be filesystem-safe.
- Network behavior is stabilized via pacing, concurrency caps, and rate-limit handling.
---
## Extending the system: adding a new source
To add a new backend (e.g., GitLab / Bitbucket / ZIP / URL):
1. Implement the Source contract in a new source module.
2. Register it in the factory (selection by `source=...`).
3. Add tests for list/read behavior and boundary conditions.
4. Update docs (README + this architecture doc if needed).
Key point: tools should remain unchanged.
---
## Design tradeoffs
- Contract-first over tool-specific logic: enables clean extensibility.
- Thin clients: keeps service specifics out of tools and sources.
- In-memory TTL caching: fast, simple, and sufficient for a stdio server (not persistent across runs).
- Limited retries: keeps tool calls responsive and avoids retry storms.
