ra-mcp

⚠️ Work in Progress (WIP)

This repository is the result of two hackathons and is currently under development. It's more of a proof of concept than a production-ready solution. The codebase, documentation, and build processes are being continuously refined.

Please note:

• Expect changes and breaking updates

• APIs and interfaces may change without notice

• Use in production environments at your own risk

• Contributions and feedback are welcome as we work toward stability

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

MCP

Adding ra-mcp with streamable http for ChatGPT or Claude:

url: https://riksarkivet-ra-mcp.hf.space/mcp

Claude Code

IDEs

CLI

Install cli

How to Use

1. Search for Keywords

Find documents containing specific words or phrases:

Search Options:

• --max N - Maximum search results (default: 50)

• --max-display N - Maximum results to display (default: 20)

• --max-hits-per-vol N - Maximum hits to return per volume (default: 3)

Search Types:

2. Browse Specific Documents

When you find interesting documents, browse them directly:

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)

Output Features

🔍 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:

🔗 Available Resources

Each result provides direct access to:

Examples

Basic Workflow

1. Search for a keyword:

   uv run ra search "Stockholm"

2. Browse specific documents:

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

Advanced Usage

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

MCP Server Development

Running the MCP Server

Testing with MCP Inspector

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

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.

Prerequisites

• Dagger CLI installed

• Docker registry credentials (for publishing)

Available Commands

Build locally:

Run tests:

Build and publish to Docker registry:

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

The MCP server provides access to transcribed historical documents from the Swedish National Archives (Riksarkivet) through three primary tools and two resources:

🔧 Available Tools

1. search_transcribed

Search for keywords in transcribed materials with pagination support.

2. browse_document

Browse specific pages of a document by reference code.

📚 Available Resources

• riksarkivet://contents/table_of_contents - Complete guide index (Innehållsförteckning)

• riksarkivet://guide/{filename} - Specific guide sections (e.g., '01_Domstolar.md', '02_Fangelse.md')

🔄 Typical Workflow

1. Search → search_transcribed("trolldom", offset=0) to find relevant documents

2. Paginate → Continue with offset=50, 100, 150... for comprehensive discovery

3. Browse → Use browse_document() to view specific pages with full transcriptions

💡 Search Strategy Tips

• Start with show_context=False to maximize hit coverage

• Use pagination (increasing offsets) to find all matches

• Enable show_context=True only when you need full page text for specific hits

• Browse specific pages for detailed examination with keyword highlighting