Riksarkivet MCP Server

Instructions

Implementation Reference

• src/ra_mcp/search_tools.py:347-394 (handler)

  Main handler function for the 'browse_document' tool. It creates BrowseOperations instance, fetches pages, formats results using BrowseDisplayService, and handles errors.
  async def browse_document( reference_code: str, pages: str, highlight_term: Optional[str] = None, max_pages: int = 20, ) -> str: """ Browse specific pages of a document by reference code. Returns: - Full transcribed text for each requested page - Optional keyword highlighting - Direct links to images and ALTO XML Examples: - browse_document("SE/RA/420422/01", "5") - View page 5 - browse_document("SE/RA/420422/01", "1-10") - View pages 1 through 10 - browse_document("SE/RA/420422/01", "5,7,9", highlight_term="Stockholm") - View specific pages with highlighting """ try: browse_operations = BrowseOperations(http_client=default_http_client) browse_display_service = BrowseDisplayService(formatter=PlainTextFormatter()) browse_result = _fetch_document_pages( browse_operations, reference_code=reference_code, pages=pages, highlight_term=highlight_term, max_pages=max_pages, ) if not browse_result.contexts: return _generate_no_pages_found_message(reference_code) result = browse_display_service.format_browse_results(browse_result, highlight_term) # MCPFormatter always returns string, but type hints include List for RichConsoleFormatter return result if isinstance(result, str) else str(result) except Exception as e: return format_error_message( f"Browse failed: {str(e)}", error_suggestions=[ "Check the reference code format", "Verify page numbers are valid", "Try with fewer pages", ], )
• src/ra_mcp/search_tools.py:307-346 (registration)

  Registration of the 'browse_document' tool using FastMCP @tool decorator, including name, description, and implicit schema from parameters.
  @search_mcp.tool( name="browse_document", description="""Browse specific pages of a document by reference code and view full transcriptions. This tool retrieves complete page transcriptions from historical documents in Swedish. Each result includes the full transcribed text as it appears in the original document, plus direct links to view the original page images in Riksarkivet's image viewer (bildvisaren). Prefer showing the whole transcription and link in responses of individual pages. Download some of the nearby pages too on selected pages if context seem to be missing from the trancript to get a better picture Original text: transcript Translation Modern translation in language of user Links Key features: - Returns full page transcriptions in (original language) - Provides links to bildvisaren (Riksarkivet's image viewer) for viewing original documents - Supports single pages, page ranges, or multiple specific pages - Direct links to ALTO XML for detailed text layout information Parameters: - reference_code: Document reference code from search results (e.g., "SE/RA/420422/01") - pages: Page specification - single ("5"), range ("1-10"), or comma-separated ("5,7,9") - highlight_term: Optional keyword to highlight in the transcription - max_pages: Maximum number of pages to retrieve (default: 20) Examples: - browse_document("SE/RA/420422/01", "5") - View full transcription of page 5 - browse_document("SE/RA/420422/01", "1-10") - View pages 1 through 10 - browse_document("SE/RA/420422/01", "5,7,9", highlight_term="Stockholm") - View specific pages with highlighting Note: Transcriptions are as they appear in the historical documents. Use this tool when you need complete page content rather than just search snippets. """, )
• src/ra_mcp/services/browse_operations.py:31-76 (helper)

  Core implementation of document browsing logic in BrowseOperations class. Extracts manifest ID, fetches page contexts, metadata, and returns BrowseResult.
  def browse_document( self, reference_code: str, pages: str, highlight_term: Optional[str] = None, max_pages: int = 20, ) -> BrowseResult: """Browse specific pages of a document. Retrieves full transcribed content for specified pages of a document, with optional term highlighting. Supports various page specifications including ranges (1-5), lists (1,3,5), and combinations. Args: reference_code: Document identifier (e.g., 'SE/RA/730128/730128.006'). pages: Page specification (e.g., '1-3,5,7-9' or 'all'). highlight_term: Optional term to highlight in the returned text. max_pages: Maximum number of pages to retrieve. Returns: BrowseResult containing page contexts, document metadata, and persistent identifiers. Returns empty contexts if document not found or no valid pages. """ manifset_id = self.oai_client.extract_manifset_id(reference_code) if not manifset_id: return BrowseResult( contexts=[], reference_code=reference_code, pages_requested=pages, ) page_contexts = self._fetch_page_contexts(manifset_id, pages, max_pages, reference_code, highlight_term) # Fetch document metadata by searching for the reference code document_metadata = self._fetch_document_metadata(reference_code) return BrowseResult( contexts=page_contexts, reference_code=reference_code, pages_requested=pages, manifest_id=manifset_id, document_metadata=document_metadata, )