rcsb-mcp AGENTS.md

AGENTS.md — working on the rcsb-mcp repo

Guidance for AI coding agents (and humans) modifying this repository. This is an MCP server that lets an LLM interrogate Protein Data Bank structures across three RCSB APIs: Search (REST), Data (GraphQL), and Sequence Coordinates (GraphQL).

The runtime assistant persona and output format are not here — they live in src/rcsb_mcp/prompts/pdb_assistant.md, served over MCP as the pdb_assistant prompt (see "Two layers" below). Keep that split.

Layout

src/rcsb_mcp/
  server.py                  MCP server: @mcp.tool() tools, the @mcp.prompt() persona, HTTP calls, schema introspection
  queries.py                 PURE request-body builders (no network) + the DATA_OBJECTS registry
  search_attributes.py       SEARCH_ATTRIBUTES catalog (structure search schema)
  chemical_search_attributes.py  CHEMICAL_SEARCH_ATTRIBUTES catalog — auto-generated (see scripts/)
  prompts/pdb_assistant.md   Assistant persona + HTML-report format; served as the `pdb_assistant` MCP prompt (package data)
tests/
  test_queries.py            Network-free unit tests for the query builders
  test_server.py             Network-free tests for non-builder server logic (schema flatten), via a synthetic schema

Architecture & conventions

• Pure builders vs. I/O. queries.py builds request bodies and contains no network code, so it stays unit-testable. server.py does the HTTP and exposes the tools. Keep new query-construction logic in queries.py.
• The DATA_OBJECTS registry (queries.py) drives every Data API rcsb_get_* tool: one entry per GraphQL root field (root field, id arg, batch/single, default field selection). Adding a Data API object is ideally a one-line registry entry.
• Compact defaults + fields= overrides. Each rcsb_get_*/rcsb_seqcoord_* tool returns a curated compact field selection but accepts a fields= override; rcsb_describe_data_object (browse a level, drill in with into=, or keyword-search the schema with query= + max_depth=) and rcsb_describe_seqcoord_object introspect the live schema for field discovery. There is no raw-GraphQL passthrough tool any more: everything goes through a typed tool's fields=. Don't try to make defaults exhaustive — and don't invent fields= paths; discover them against the live schema first.
• Server instructions = tool-usage guidance only (routing, chaining, return types). Do not put application/presentation policy there — it's always-on for every client. That belongs in the project prompt.