arquivo-pt-mcp: Instructions file for Claude Code

CLAUDE.md

MCP server for Arquivo.pt, the Portuguese Web Archive. Exposes 6 tools: search, image_search, list_versions, get_snapshot, extract_text, get_screenshot.

Workflow

This Claude session is expected to run inside the project's DevContainer.

container: id: 5f6c44112660 name: pensive_moser image: mcr.microsoft.com/devcontainers/python:3.12

What do run inside the Docker Container:

• Python commands
• tests
• anything tightly couple with the code

What to run on bare metal (Macbook)

• git and gh (already authenticated)
• hf (hugging face) (already authenticated)
• related curl commands to troubleshoot issues with git or huggingFace

When in doubt, pause the process and confirm with the user. Never install any dependencies on the bare metal machine.

Commands

• Install dev deps: uv sync --extra dev (or pip install -e ".[dev]")
• Lint / format: ruff check src tests · ruff format src tests
• Tests: pytest -q · single file: pytest tests/test_search.py -q · single test: pytest tests/test_search.py::test_search_basic -q
• Coverage: pytest --cov=arquivo_pt_mcp
• Integration (live API, opt-in): RUN_INTEGRATION=1 pytest -m integration -v
• Run server (stdio): uv run arquivo-pt-mcp
• Run server (HTTP): arquivo-pt-mcp --transport http --host 127.0.0.1 --port 8000
• Build wheel: python -m build

pytest.ini_options sets asyncio_mode = "auto" — async tests don't need @pytest.mark.asyncio. The integration marker is registered; tests without RUN_INTEGRATION=1 skip via tests/integration_fixtures.py.

Architecture

Single-module core, thin wrappers

src/arquivo_pt_mcp/__init__.py is the whole server: tool implementations, MCP wiring (@server.list_tools, @server.call_tool), HTTP helpers, and the main() entry point all live there. The other source files are deliberately thin:

• server.py — re-exports main for python -m arquivo_pt_mcp.server-style use. Don't add logic here.
• cli.py — argparse + env-var fallbacks for transport/host/port/security flags. Pure parsing; no I/O.
• http_app.py — Starlette ASGI factory used only when --transport http. Lazy-imported from __init__._async_main_http to avoid pulling Starlette/uvicorn into stdio runs.
• models.py — Pydantic *Params models. Validation runs in call_tool before dispatch via the PARAM_MODELS map; tool handlers themselves accept loose kwargs.