Oxenstierna

# 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 ```bash # 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: ```bash # 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: ```bash # 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: ```bash # 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:** ```bash uv run tools/ra.py search "Stockholm" ``` 2. **Get full context for interesting hits:** ```bash uv run tools/ra.py search "Stockholm" --context --max-pages 3 ``` 3. **Browse specific documents:** ```bash uv run tools/ra.py browse "SE/RA/123456" --page "10-15" --search-term "Stockholm" ``` ### Advanced Usage ```bash # 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](https://data.riksarkivet.se/api/records)** - Primary endpoint for full-text search across transcribed materials ([Documentation](https://github.com/Riksarkivet/dataplattform/wiki/Search-API)) - **[IIIF Collections](https://lbiiif.riksarkivet.se/collection/arkiv)** - Access to digitized document collections via IIIF standard ([Documentation](https://github.com/Riksarkivet/dataplattform/wiki/IIIF)) - **[ALTO XML](https://sok.riksarkivet.se/dokument/alto)** - Structured text transcriptions with precise positioning data - **[IIIF Images](https://lbiiif.riksarkivet.se)** - High-resolution document images with zoom and cropping capabilities - **[Bildvisning](https://sok.riksarkivet.se/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](https://github.com/Riksarkivet/dataplattform/wiki) provides comprehensive documentation for building additional MCP integrations. #### Experimental Features - **[Förvaltningshistorik](https://forvaltningshistorik.riksarkivet.se/Index.htm)** - 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 ```bash 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 ```bash # 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](https://github.com/modelcontextprotocol/inspector) to test and debug the MCP server: ```bash # 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 ``` ___