Riksarkivet MCP Server

# Implementation Plan: Riksarkivet Historical Document Search and Access System **Branch**: `001-researchers-historians-and` | **Date**: 2025-09-23 | **Spec**: [spec.md](./spec.md) **Input**: Feature specification from `/specs/001-researchers-historians-and/spec.md` ## Execution Flow (/plan command scope) ```  1. Load feature spec from Input path � Feature spec loaded successfully from spec.md  2. Fill Technical Context (scan for NEEDS CLARIFICATION) � Detected Project Type: single (MCP server with CLI) � Set Structure Decision: Option 1 (single project structure)  3. Fill Constitution Check section based on constitution v2.1.0  4. Evaluate Constitution Check section below � No violations detected - tech stack aligns with MCP-First Architecture � Update Progress Tracking: Initial Constitution Check PASSED  5. Execute Phase 0 � research.md � No NEEDS CLARIFICATION remain - tech stack fully specified  6. Execute Phase 1 � contracts, data-model.md, quickstart.md, CLAUDE.md � Ready for Phase 1 execution  7. Re-evaluate Constitution Check section � Post-design constitution check will validate after Phase 1 � Update Progress Tracking: Post-Design Constitution Check pending  8. Plan Phase 2 � Describe task generation approach (DO NOT create tasks.md)  9. STOP - Ready for /tasks command ``` **IMPORTANT**: The /plan command STOPS at step 8. Phases 2-4 are executed by other commands: - Phase 2: /tasks command creates tasks.md - Phase 3-4: Implementation execution (manual or via tools) ## Summary Enhance the existing Riksarkivet MCP server to provide comprehensive historical document search and access capabilities for researchers, historians, and AI assistants. The system uses Python 3.12+ with FastMCP framework for MCP protocol implementation, maintaining separation between MCP tools and business logic services. Core functionality leverages existing Riksarkivet API integration with httpx for async operations, uses typer for CLI interface, and includes Docker containerization with Dagger CI/CD pipeline. ## Technical Context **Language/Version**: Python 3.12+ (specified, matches current implementation) **Primary Dependencies**: FastMCP framework, httpx for async HTTP, typer for CLI, pydantic for validation **Storage**: No persistent storage - relies on Riksarkivet API caching **Testing**: pytest for unit/integration tests, contract tests for MCP tools **Target Platform**: Cross-platform (Linux, macOS, Windows) with Docker containerization **Project Type**: single (MCP server with integrated CLI interface) **Performance Goals**: <2 second response for search queries, handle 100+ concurrent MCP calls **Constraints**: Riksarkivet API rate limits, response size optimization for LLM tokens **Scale/Scope**: Access to millions of documents via API, multiple AI assistant integrations ## Constitution Check *GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.* ###  MCP-First Architecture (Principle I) - **Status**: COMPLIANT - FastMCP framework ensures MCP specification standards - **Enhancement**: Refine tool descriptions for better AI assistant integration - **Transports**: stdio and HTTP/SSE already supported ###  API Client Modularity (Principle II) - **Status**: COMPLIANT - Business logic separated from MCP transport - **Enhancement**: httpx async client maintains clean separation from MCP layer ###  Documentation Standards (Principle III) - **Status**: NEEDS ENHANCEMENT - Tool descriptions need FastMCP best practices - **Action**: Update CLAUDE.md with enhanced capabilities documentation ###  Reproducible CI/CD (Principle IV) - **Status**: IMPLEMENTATION REQUIRED - Docker and Dagger specified - **Action**: Create Dockerfile and .dagger/ Go pipeline for containerized builds ###  Open Source Excellence (Principle V) - **Status**: COMPLIANT - Apache License 2.0, English documentation - **Action**: Create governance files (SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md) **Gate Status**:  PASS - Tech stack aligns with constitutional principles ## Project Structure ### Documentation (this feature) ``` specs/001-researchers-historians-and/  plan.md # This file (/plan command output)  research.md # Phase 0 output (/plan command)  data-model.md # Phase 1 output (/plan command)  quickstart.md # Phase 1 output (/plan command)  contracts/ # Phase 1 output (/plan command)   search_transcribed.yaml   browse_document.yaml   get_document_structure.yaml  tasks.md # Phase 2 output (/tasks command - NOT created by /plan) ``` ### Source Code (repository root) ``` # Option 1: Single project (CURRENT - matches existing structure) src/ra_mcp/  models.py # Pydantic data models  services/ # Business logic (httpx clients)   search_operations.py   display_service.py   riksarkivet_client.py  cli/ # Typer-based CLI interface   __init__.py   main.py   commands/  mcp_tools.py # FastMCP tool definitions  formatters.py # Response formatting  server.py # FastMCP server entry point  utils/ # Shared utilities tests/  contract/ # MCP tool contract tests  integration/ # End-to-end workflow tests  unit/ # Unit tests for services .dagger/ # Go-based CI/CD pipeline (NEW)  main.go  ci/  build.go  test.go  deploy.go # Infrastructure files (NEW)  Dockerfile # Multi-stage Python build  .env.example # Environment template  SECURITY.md # Vulnerability reporting  CONTRIBUTING.md # Contribution guidelines  CODE_OF_CONDUCT.md # Community standards ``` **Structure Decision**: Option 1 - Single project structure matches MCP server pattern and existing codebase ## Phase 0: Outline & Research All technical decisions are clearly specified in the input: ###  Framework Selection - **Decision**: FastMCP framework for MCP protocol implementation - **Rationale**: Provides MCP specification compliance with proven abstractions - **Alternatives considered**: Direct MCP implementation rejected for complexity ###  HTTP Client Strategy - **Decision**: httpx for async HTTP operations with Riksarkivet API - **Rationale**: Async support essential for concurrent MCP tool calls - **Alternatives considered**: requests library rejected due to sync-only limitations ###  CLI Framework Choice - **Decision**: typer over click for command-line interface - **Rationale**: Modern type hints, better integration with pydantic models - **Alternatives considered**: click rejected per explicit user preference ###  Package Management - **Decision**: uv for package management, linting, and formatting - **Rationale**: Fast, modern Python tooling with excellent dependency resolution - **Alternatives considered**: pip/poetry rejected for performance reasons ###  Containerization Strategy - **Decision**: Docker with Dagger CI/CD pipeline in Go - **Rationale**: Reproducible builds, matches constitutional requirements - **Alternatives considered**: Native packaging rejected for environment consistency **Output**: No research.md needed - all technical decisions provided in input ## Phase 1: Design & Contracts *Prerequisites: research.md complete (skipped - no unknowns)* ### 1. Data Model Enhancement (`data-model.md`): - SearchResult: Pydantic models for structured API responses - DocumentPage: Enhanced metadata for AI assistant consumption - BrowseOperation: Structured navigation and highlighting - DocumentStructure: IIIF manifest hierarchy representation ### 2. MCP Tool Contract Refinement (`/contracts/`): - OpenAPI schemas for each MCP tool (search_transcribed, browse_document, get_document_structure) - Parameter validation using pydantic models - Error response standardization - Response size optimization for token efficiency ### 3. Contract Test Generation: - pytest-based contract tests for each MCP tool - Schema validation for request/response formats - Error condition handling verification - Performance benchmarking tests ### 4. Integration Test Scenarios: - Researcher workflow: keyword search � document browsing � analysis - AI assistant integration patterns with various LLM providers - Concurrent access performance validation - API rate limit handling ### 5. CLAUDE.md Update (Agent-Specific File): - Enhanced MCP tool documentation with FastMCP best practices - Performance optimization guidelines for large document collections - Troubleshooting guide for common integration issues - Example usage patterns for different research scenarios **Output**: data-model.md, /contracts/*, failing tests, quickstart.md, updated CLAUDE.md ## Phase 2: Task Planning Approach *This section describes what the /tasks command will do - DO NOT execute during /plan* **Task Generation Strategy**: - Load `.specify/templates/tasks-template.md` as base structure - Generate tasks from Phase 1 design documents and constitutional requirements - Focus on enhancement rather than greenfield development - Include infrastructure tasks (Docker, Dagger, governance files) - Prioritize MCP tool improvements with contract-first approach **Ordering Strategy**: - **Infrastructure Setup** [P]: Dockerfile, .dagger/ pipeline, governance files creation - **Contract Definition** [P]: OpenAPI schemas and pydantic models - **Test-First Development**: Contract tests before implementation - **MCP Tool Enhancement**: Sequential improvement of existing tools - **Integration Validation**: End-to-end workflow testing - **Documentation**: CLAUDE.md updates and quickstart guide **Task Categories**: 1. **Governance & Infrastructure** [P]: Docker, Dagger pipeline, SECURITY.md, CONTRIBUTING.md 2. **Data Models** [P]: Pydantic model enhancements for better AI integration 3. **Contract Tests** [P]: pytest-based MCP tool validation 4. **Tool Enhancement**: Improve search_transcribed, browse_document, get_document_structure 5. **CLI Integration**: typer-based command interface improvements 6. **Performance**: Response optimization and concurrent access handling 7. **Documentation**: CLAUDE.md updates and usage examples **Estimated Output**: 18-22 numbered, ordered tasks focusing on systematic enhancement **IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan ## Phase 3+: Future Implementation *These phases are beyond the scope of the /plan command* **Phase 3**: Task execution (/tasks command creates tasks.md) **Phase 4**: Implementation (execute tasks.md following constitutional principles) **Phase 5**: Validation (run tests, execute quickstart.md, performance validation) ## Complexity Tracking *Fill ONLY if Constitution Check has violations that must be justified* No constitutional violations detected. The specified tech stack (Python 3.12+, FastMCP, httpx, typer, Docker, Dagger) aligns perfectly with constitutional principles while enhancing the existing implementation. ## Progress Tracking *This checklist is updated during execution flow* **Phase Status**: - [x] Phase 0: Research complete (/plan command) - tech stack fully specified - [ ] Phase 1: Design complete (/plan command) - ready to execute - [ ] Phase 2: Task planning complete (/plan command - describe approach only) - [ ] Phase 3: Tasks generated (/tasks command) - [ ] Phase 4: Implementation complete - [ ] Phase 5: Validation passed **Gate Status**: - [x] Initial Constitution Check: PASS - [ ] Post-Design Constitution Check: PENDING (after Phase 1) - [x] All NEEDS CLARIFICATION resolved - [x] Complexity deviations documented: NONE --- *Based on Constitution v2.1.0 - See `ra-mcp/.specify/memory/constitution.md`*