Oxenstierna

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## IMPORTANT - Never write any code that you don't also test! CHECK IT! - Prefer change file instead of creating a new one - Always read the whole file don't just read the head - Always give multiple reommendations of possible. - If think that a comments is important, insert in the docstring not in the code. Instead also if it very important in a specfic line, be very specfik with naming conventions of variables or functions instead. ## Commands ### Development - **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` - **Run with SSE transport (dev mode)**: `cd src/ra_mcp && python server.py --http` - **Install dependencies**: `uv sync && uv pip install -e .` - **Running Code**: `uv run <>` - **Cleaning Code**: `uvx ruff format .` , `uvx ruff check --fix` ### Claude Desktop Integration To connect Claude Desktop to a running SSE server, add the following configuration: **macOS/Linux**: `~/.config/claude/claude_desktop_config.json` **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` (typically `C:\Users\[YourUsername]\AppData\Roaming\Claude\claude_desktop_config.json`) ### Claude Code Integration To connect the MCP server to Claude Code: 1. Start the server with SSE transport: `cd src/ra_mcp && python server.py --http` 2. Add the server to Claude Code: `claude mcp add --transport sse ra-mcp http://localhost:8000/sse` 3. Verify connection: `claude mcp list` The server tools will be available with the `mcp__ra-mcp__` prefix. ### Claude Code as MCP Server **Start Claude Code as MCP server:** ```bash claude mcp serve ``` **Configure Claude Desktop to use Claude Code as MCP server:** Add to `claude_desktop_config.json`: ```json { "mcpServers": { "claude-code": { "command": "claude", "args": ["mcp", "serve"], "env": {} } } } ``` ### Building and Publishing with Dagger The project uses Dagger for containerized builds and publishing. **Build locally:** ```bash dagger call build ``` **Build and publish to Docker registry:** ```bash 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 - `test`: Runs the test suite using the built container - `publish`: Builds and publishes container image to registry with authentication - `build-local`: Build with custom environment variables and settings **Prerequisites for publishing:** - Set `DOCKER_USERNAME` environment variable with Docker registry username - Set `DOCKER_PASSWORD` environment variable with Docker registry password - Ensure Docker registry access for the specified credentials ## Architecture ### MCP Server Structure The project implements a FastMCP-based Model Context Protocol server that provides access to Swedish National Archives (Riksarkivet) data through multiple mounted sub-servers: - **Main Server** (`src/ra_mcp/server.py`): The entry point for the Riksarkivet MCP server - **RA Tools** (`tools.py`): Core functionality for searching transcribed documents, browsing documents, and getting document structure - **RA Core** (`ra_core.py`): Core API client for Riksarkivet services - **Cache** (`cache.py`): Caching functionality for API responses ### Core Components Located in `src/ra_mcp/`: - **RA Core** (`ra_core.py`): Main API client for accessing Riksarkivet's transcribed documents - **Tools** (`tools.py`): MCP tool definitions for search_transcribed and browse_document - **Formatters** (`formatters.py`): Text formatting utilities for search results and document content - **Cache** (`cache.py`): Response caching to improve performance ### Typical Workflow 1. Use search_transcribed() to find documents containing keywords 2. Review search results to identify relevant reference codes and page numbers 3. Use browse_document() to view full transcriptions of specific pages ### HTR Gradio Integration The `htr_gradio/` directory contains: - Gradio-based HTR flow client (`gradio_htrflow.py`) - MCP client implementations (`client.py`, `client_new.py`) - Visualization tools (`visualizer.py`) - Simple MCP server example (`simple_mcp_server.py`) ## API Endpoints - SEARCH_API_BASE_URL = "https://data.riksarkivet.se/api/records" - COLLECTION_API_BASE_URL = "https://lbiiif.riksarkivet.se/collection/arkiv" - IIIF_BASE_URL = "https://lbiiif.riksarkivet.se" - OAI_BASE_URL = "https://oai-pmh.riksarkivet.se/OAI" When using our endpoints opt to use httx or urllib instead of requests, since there is a bug (timeout) when using requests agaisnt RA's APIs ## Key Features - Search records with transcribed text across Riksarkivet collections - Access IIIF manifests and images with custom parameters - Download individual or batch images from collections - Build custom IIIF Image URLs with size and quality parameters - Integration with HTRflow for handwritten text recognition ## MCP Specification Reference For detailed information about the Model Context Protocol specification, implementation details, or when clarification is needed about MCP-specific features, refer to the official MCP specification documentation: - **MCP Specification**: https://modelcontextprotocol.io/specification/2025-06-18