Architecture

ra-mcp is organized as a uv workspace with modular packages, each with a single responsibility.

Package Overview

Package	Layer	Purpose
ra-mcp-common	0	Shared HTTP client, telemetry helpers, formatting utilities
ra-mcp-search	1	Search domain: Pydantic models, API client, operations
ra-mcp-browse	1	Browse domain: models, ALTO/IIIF/OAI-PMH clients, operations
ra-mcp-search-mcp	2	MCP tools: `search_transcribed`, `search_metadata`
ra-mcp-browse-mcp	2	MCP tool: `browse_document`
ra-mcp-guide-mcp	2	MCP resources: archival research guides (50+ sections)
ra-mcp-htr-mcp	2	MCP tool: `htr_transcribe` (handwritten text recognition)
ra-mcp-viewer-mcp	2	MCP App: interactive document viewer with zoomable images
ra-mcp-search-cli	2	CLI command: `ra search`
ra-mcp-browse-cli	2	CLI command: `ra browse`
ra-mcp-tui	2	Interactive terminal browser: `ra tui`
ra-mcp (root)	3	Server composition + Typer CLI entry point
ra-mcp-tools (plugin)	—	Claude Code skills for research workflows

Dependency Graph

graph TD
  common["ra-mcp-common\nshared HTTP client, telemetry"]

  search["ra-mcp-search\nsearch domain"]
  browse["ra-mcp-browse\nbrowse domain"]

  search_mcp["ra-mcp-search-mcp\nMCP tools"]
  search_cli["ra-mcp-search-cli\nCLI command"]
  browse_mcp["ra-mcp-browse-mcp\nMCP tool"]
  browse_cli["ra-mcp-browse-cli\nCLI command"]
  guide["ra-mcp-guide-mcp\nMCP resources"]
  htr["ra-mcp-htr-mcp\nHTR tool"]
  viewer["ra-mcp-viewer-mcp\nMCP App"]
  tui["ra-mcp-tui\nTerminal UI"]

  root["ra-mcp (root)\ncomposes all packages"]

  common --> search & browse & guide
  search --> search_mcp & search_cli & tui
  browse --> browse_mcp & browse_cli & tui
  search_mcp & search_cli & browse_mcp & browse_cli & guide & htr & viewer & tui --> root

Layer Architecture

Layer 0 — Foundation

ra-mcp-common has no internal dependencies. It provides the HTTPClient (with retry, telemetry, and logging) used by all other packages.

Layer 1 — Domain

ra-mcp-search and ra-mcp-browse contain pure business logic: Pydantic models, API clients, and operations. No MCP or CLI dependency — they can be used as standalone Python libraries.

Layer 2 — Interface

Thin wrappers that expose domain logic through different interfaces:

MCP packages (*-mcp) register tools/resources with FastMCP
CLI packages (*-cli) register Typer commands with Rich output
TUI (ra-mcp-tui) provides an interactive Textual application
HTR (ra-mcp-htr-mcp) delegates to a remote Gradio Space
Viewer (ra-mcp-viewer-mcp) is an MCP App serving an interactive HTML viewer

Layer 3 — Composition

The root package composes all MCP sub-servers into a single server using FastMCP.add_provider(). Each module gets a namespace (e.g., search.transcribed, browse.document) except the viewer which registers at root level.

Module System

The root server has a registry of available modules:

Module	Default	Tools / Resources
`search`	Enabled	`search_transcribed`, `search_metadata`
`browse`	Enabled	`browse_document`
`guide`	Enabled	Historical research guides (MCP resources)
`htr`	Enabled	`htr_transcribe`
`viewer`	Enabled	`view_document`, `load_page`, `load_thumbnails`

Modules can be selectively enabled:

ra serve --modules search,browse     # Only search and browse
ra serve --list-modules              # Show available modules

Plugin System

The server discovers skills from plugins/*/skills/ directories at startup using FastMCP's SkillsDirectoryProvider. Skills are SKILL.md files with YAML frontmatter that get exposed as MCP resources.

Workspace Structure

ra-mcp/
├── src/ra_mcp_server/          # Root: Server composition, CLI, telemetry
├── packages/
│   ├── common/                 # Layer 0: HTTPClient, telemetry, formatting
│   ├── search/                 # Layer 1: Search domain
│   ├── browse/                 # Layer 1: Browse domain
│   ├── search-mcp/            # Layer 2: MCP tools for search
│   ├── browse-mcp/            # Layer 2: MCP tool for browse
│   ├── guide-mcp/             # Layer 2: MCP resources for guides
│   ├── htr-mcp/               # Layer 2: MCP tool for HTR
│   ├── viewer-mcp/            # Layer 2: MCP App for document viewing
│   ├── search-cli/            # Layer 2: CLI for search
│   ├── browse-cli/            # Layer 2: CLI for browse
│   └── tui/                   # Layer 2: Terminal UI
├── plugins/
│   └── ra-mcp-tools/          # Claude Code skills plugin
├── docs/                       # Documentation site (Zensical)
├── charts/ra-mcp/             # Helm chart
├── pyproject.toml             # Workspace root
└── uv.lock                    # Shared lockfile