atlasopenmagic-mcp: Instructions file for Claude Code

atlasopenmagic-mcp — Contributor Guide

Architecture

LLM <--MCP/stdio--> atlasopenmagic-mcp serve <--HTTPS--> ATLAS Open Data API
                          |                                (atlasopenmagic-api.app.cern.ch)
                          |
                          +-- atlasopenmagic (Python library, pip dependency)

The MCP server is a thin async wrapper around atlasopenmagic. Tools call library functions via _run_sync() (which uses asyncio.to_thread()) to keep the MCP event loop responsive.

Project Layout

src/atlasopenmagic_mcp/
├── __init__.py           # Package version
├── cli.py                # argparse CLI: `atlasopenmagic-mcp serve`
├── server.py             # FastMCP setup, lifespan, _run_sync helper
├── nomenclature.py       # Reference docs (embedded in instructions + resources)
├── resources.py          # MCP resource registration
└── tools/
    ├── __init__.py
    ├── _helpers.py       # run_sync (asyncio.to_thread wrapper)
    ├── discovery.py      # Releases, datasets, skims, keywords, fields
    ├── metadata.py       # get_metadata, get_all_info, match_metadata
    ├── urls.py           # get_urls (file URL retrieval)
    └── weights.py        # MC weight metadata

Key Conventions

Tool Registration Pattern

Every tool module exports register(mcp: FastMCP) -> None. Inside it, define tools with @mcp.tool():

def register(mcp: FastMCP) -> None:
    @mcp.tool()
    async def my_tool(arg: str, *, ctx: Context[Any, Any]) -> str:
        atom = ctx.request_context.lifespan_context["atom"]
        result = await run_sync(atom.some_function, arg)
        return json.dumps(result, default=str)

Error Handling

Tools return error strings, never raise:

try:
    ...
except Exception as exc:  # noqa: BLE001
    return f"Error: {exc}"

Async / Threading

atlasopenmagic uses blocking requests calls. Always wrap with:

from atlasopenmagic_mcp.tools._helpers import run_sync
result = await run_sync(atom.some_function, arg1, arg2)