ra-mcp (WIP)

MCPs for Riksarkivet

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

Features

• Full-text search across millions of transcribed historical documents
• Complete page transcriptions with accurate text extraction from historical manuscripts
• Reference-based document browsing using official archive reference codes
• Contextual search highlighting to identify relevant content quickly
• High-resolution image access to original document scans via IIIF

Getting Started

Quick Setup

# Search for anything - uv will auto-install dependencies
uv run tools/ra.py search "Stockholm"

How to Use

1. Search for Keywords

Find documents containing specific words or phrases:

# Basic search
uv run tools/ra.py search "Stockholm"

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

# Search without document grouping
uv run tools/ra.py 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)
• --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 tools/ra.py browse "SE/RA/123" --page 5

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

# View specific pages with search highlighting
uv run tools/ra.py 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. Get Full Context

See complete pages with surrounding context for better understanding:

# Find pages with keyword and show full transcriptions
uv run tools/ra.py show-pages "Stockholm" --max-pages 5

# Include surrounding pages for context
uv run tools/ra.py show-pages "trolldom" --context-padding 2

# Show pages individually
uv run tools/ra.py show-pages "vasa" --no-grouping

Options:

• --max-pages N - Maximum pages to display (default: 10)
• --context-padding N - Include N pages before/after each hit (default: 1)
• --no-grouping - Show pages individually instead of grouped by document

Output Features

Search Results

• Grouped by document for better context
• Institution and date information
• Page numbers with search hits
• Snippet previews with keyword highlighting
• Browse command examples for further exploration

Full Page Display

• Complete transcriptions from ALTO XML
• Keyword highlighting in yellow
• Document metadata (title, date, hierarchy)
• Direct links to images, ALTO XML, and Bildvisning
• Context pages marked clearly

Links Provided

• ALTO XML - Full transcription data
• IIIF Images - High-resolution document images
• Bildvisning - Interactive viewer with search highlighting
• Collections & Manifests - IIIF metadata

Examples

Basic Workflow

1. Search for a keyword:

   uv run tools/ra.py search "Stockholm"
   

2. Get full context for interesting hits:

   uv run tools/ra.py search "Stockholm" --context --max-pages 3
   

3. Browse specific documents:

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

Advanced Usage

# Comprehensive search with context
uv run tools/ra.py show-pages "handelsbalansen" --context-padding 2 --max-pages 8

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

# Large search with selective display
uv run tools/ra.py search "järnväg" --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)
• 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 - Metadata harvesting for archive records and references (Documentation)

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 tools/ra.py --help
uv run tools/ra.py search --help
uv run tools/ra.py browse --help
uv run tools/ra.py show-pages --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.

---

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

---