Ra MCP

🚀 ra-mcp (WIP)

A MCP server and command - line tools for searching and browsing transcribed historical documents from the Swedish National Archives (Riksarkivet).

✨ Features

• Full - text search: Conduct full - text searches across millions of transcribed historical documents.
• Complete page transcriptions: Obtain complete page transcriptions with accurate text extraction from historical manuscripts.
• Reference - based document browsing: Browse documents using official archive reference codes.
• Contextual search highlighting: Quickly identify relevant content through contextual search highlighting.
• High - resolution image access: Access original document scans in high - resolution via IIIF.

🚀 Quick Start

📦 Installation

# Search for anything 
uv run ra search "Stockholm"

💻 Usage Examples

Basic Usage

1. Search for Keywords

Find documents containing specific words or phrases:

# Basic search
uv run ra search "Stockholm"

# Search with full page transcriptions
uv run ra search "trolldom" --context --max - pages 5

# Search with surrounding pages for context
uv run ra search "trolldom" --context --context - padding 1 --max - pages 3

# Search without document grouping
uv run ra search "vasa" --context --no - grouping --max - pages 3

Options:

• --max N: Maximum search results (default: 50).
• --max - display N: Maximum results to display (default: 20).
• --context: Show full page transcriptions.
• --max - pages N: Maximum pages to load context for (default: 10).
• --context - padding N: Include N pages before/after each hit for context (default: 0).
• --no - grouping: Show pages individually instead of grouped by document.

2. Browse Specific Documents

When you find interesting documents, browse them directly:

# View single page
uv run ra browse "SE/RA/123" --page 5

# View page range
uv run ra browse "SE/RA/123" --pages "1 - 10"

# View specific pages with search highlighting
uv run ra browse "SE/RA/123" --page "5,7,9" --search - term "Stockholm"

Options:

• --page or --pages: Page numbers (e.g., "5", "1 - 10", "5,7,9").
• --search - term: Highlight this term in the text.
• --max - display N: Maximum pages to display (default: 20).

3. Search with Full Context

The --context flag shows complete page transcriptions instead of just snippets:

# Search with full page transcriptions
uv run ra search "Stockholm" --context --max - pages 5

# Include surrounding pages for additional context
uv run ra search "trolldom" --context --context - padding 2

# Show pages individually instead of grouped by document
uv run ra search "vasa" --context --no - grouping

Advanced Usage

🔍 Search Results

When you run a search, results are presented with:

• Document grouping: Related pages grouped together for context.
• Institution & dates: Archive location and document dates.
• Page numbers: Specific pages containing your search terms.
• Highlighted snippets: Preview text with keywords emphasized.
• Browse commands: Ready - to - run commands for deeper exploration.

Example output:

Document: SE/RA/12345 - Stockholms stads tänkeböcker (1520 - 1550)
Institution: Stockholms stadsarkiv | Date: 1545
├─ Page 42: "...angående **Stockholm** rådstuga och dess underhåll..."
├─ Page 98: "...borgmästaren i **Stockholm** beslutade att..."
└─ Page 156: "...handlare från **Stockholm** begärde tillstånd..."

Browse commands:
  uv run ra browse "SE/RA/12345" --page 42 --search - term "Stockholm"
  uv run ra browse "SE/RA/12345" --pages "42,98,156" --search - term "Stockholm"

📄 Full Page Display

With the --context flag, you get complete page transcriptions featuring:

• Full text transcriptions: Complete page content from ALTO XML.
• Keyword highlighting: Your search terms highlighted in yellow.
• Rich metadata: Document titles, dates, and archive hierarchy.
• Direct access links: Quick links to images, XML, and interactive viewer.
• Context indicators: Clear marking of surrounding pages when using --context - padding.

Example output:

═══ SE/RA/12345 - Page 42 ═══
Title: Stockholms stads tänkeböcker
Date: 1545 - 03 - 15 | Institution: Stockholms stadsarkiv

Anno domini 1545 den 15 martii blef föredraget angående 🟡Stockholm🟡
rådstuga och dess underhåll. Borgmästaren förklarade att byggnaden
behöfde reparationer och att medel måste anskaffas för detta ändamål.
Flera borgare från 🟡Stockholm🟡 stad deltog i diskussionen om hur
kostnaderna skulle fördelas...

Links:
📄 ALTO XML: https://sok.riksarkivet.se/dokument/alto/SE_RA_12345_042.xml
🖼️  Image: https://lbiiif.riksarkivet.se/arkiv/SE_RA_12345_042.jpg
🔍 Bildvisning: https://sok.riksarkivet.se/bildvisning/SE_RA_12345#042

🔗 Available Resources

Each result provides direct access to:

Examples

Basic Workflow

1. Search for a keyword:

   uv run ra search "Stockholm"
   

2. Get full context for interesting hits:

   uv run ra search "Stockholm" --context --max - pages 3
   

3. Include surrounding pages for additional context:

   uv run ra search "Stockholm" --context --context - padding 1 --max - pages 3
   

4. Browse specific documents:

   uv run ra browse "SE/RA/123456" --page "10 - 15" --search - term "Stockholm"
   

Advanced Usage

# Comprehensive search with context and surrounding pages
uv run ra search "trolldom" --context --context - padding 2 --max - pages 8

# Targeted document browsing
uv run ra browse "SE/RA/760264" --pages "1,5,10 - 12" --search - term "trolldom"

# Large search with selective display
uv run ra search "trolldom" --max 100 --max - display 30

🔧 Technical Details

Riksarkivet APIs & Data Sources

This tool integrates with multiple Riksarkivet APIs to provide comprehensive access to historical documents:

Current Integrations

• Search API: Primary endpoint for full - text search across transcribed materials ([Documentation](https://github.com/Riksarkivet/dataplattform/wiki/Search - API)).
• IIIF Collections: Access to digitized document collections via IIIF standard (Documentation).
• ALTO XML: Structured text transcriptions with precise positioning data.
• IIIF Images: High - resolution document images with zoom and cropping capabilities.
• Bildvisning: Interactive document viewer with search highlighting.
• [OAI - PMH](https://oai - pmh.riksarkivet.se/OAI): Metadata harvesting for archive records and references ([Documentation](https://github.com/Riksarkivet/dataplattform/wiki/OAI - PMH)).

Additional Resources

The Riksarkivet Data Platform Wiki provides comprehensive documentation for building additional MCP integrations.

Experimental Features

• Förvaltningshistorik: Semantic search interface (under evaluation).
• AI - Riksarkivet HTRflow: Handwritten text recognition pipeline (PyPI package).

🛠️ Troubleshooting

Common Issues

1. No results found: Try broader search terms or check spelling.
2. Page not loading: Some pages may not have transcriptions available.
3. Network timeouts: Tool includes retry logic, but very slow connections may time out.

Getting Help

uv run ra --help
uv run ra search --help
uv run ra browse --help
uv run ra serve --help

🛠️ MCP Server Development

Running the MCP Server

# Install dependencies
uv sync && uv pip install -e .

# Run the main MCP server (stdio)
cd src/ra_mcp && python server.py

# Run with SSE/HTTP transport on port 8000
cd src/ra_mcp && python server.py --http

Testing with MCP Inspector

Use the MCP Inspector to test and debug the MCP server:

# Test the server interactively
npx @modelcontextprotocol/inspector uv run python src/ra_mcp/server.py

The MCP Inspector provides a web interface to test server tools, resources, and prompts during development.

Building and Publishing with Dagger

The project uses Dagger for containerized builds and publishing to Docker registries. Pre - built images are available on [Docker Hub](https://hub.docker.com/r/riksarkivet/ra - mcp).

Prerequisites

• Dagger CLI installed.
• Docker registry credentials (for publishing).

Available Commands

Build locally:

dagger call build

Run tests:

dagger call test

Build and publish to Docker registry:

# Set environment variables
export DOCKER_USERNAME="your - username"
export DOCKER_PASSWORD="your - password"

# Build and publish
dagger call publish \
  --docker - username=env:DOCKER_USERNAME \
  --docker - password=env:DOCKER_PASSWORD \
  --image - repository="riksarkivet/ra - mcp" \
  --tag="latest" \
  --source=.

Available Dagger Functions

• build: Creates a production - ready container image using the Dockerfile.
• test: Runs the test suite using pytest with coverage reporting.
• publish: Builds and publishes container image to registry with authentication.
• build - local: Build with custom environment variables and registry settings.

The Dagger configuration is located in .dagger/main.go and provides a complete CI/CD pipeline for the project.

Current MCP Server Implementation

This server provides access to the Swedish National Archives (Riksarkivet) through multiple APIs.
    SEARCH - BASED WORKFLOW (start here):
    - search_records: Search for content by keywords (e.g., "coffee", "medical records")
    - get_collection_info: Explore what's available in a collection
    - get_all_manifests_from_pid: Get all image batches from a collection
    - get_manifest_info: Get details about a specific image batch
    - get_manifest_image: Download specific images from a batch
    - get_all_images_from_pid: Download all images from a collection
    URL BUILDING TOOLS:
    - build_image_url: Build IIIF Image URLs with custom parameters
    - get_image_urls_from_manifest: Get all URLs from an image batch
    - get_image_urls_from_pid: Get all URLs from a collection
    TYPICAL WORKFLOW:
    1. search_records("your keywords") → find PIDs
    2. get_collection_info(pid) → see what's available
    3. get_manifest_info(manifest_id) → explore specific image batch
    4. get_manifest_image(manifest_id, image_index) → download specific image
    Example PID: LmOmKigRrH6xqG3GjpvwY3