APS 12-ID MCP Server

This repository provides a Python MCP server package for beamline 12-ID at the Advanced Photon Source. It is structured as an MCP frontend process that talks over ZMQ to a separate blocking instrument worker process. Facility control code should be added only in the worker.

The current tools are placeholders:

• acquire_image: forwards image acquisition parameters to the worker and returns the worker result.
• move_motor: forwards a requested motor move to the worker.
• dump_array and get_attribute_payload: EAA-compatible support methods for image buffers and logic-driven workflows.

Setup

uv sync

Copy and edit the example configuration before running against a real deployment:

cp configs/example.yaml configs/local.yaml

Configuration values are loaded from YAML first. Explicit CLI flags override YAML values for that process.

Launch Both Processes

uv run aps-12id \
  --config configs/example.yaml \
  --worker-endpoint tcp://127.0.0.1:5555 \
  --worker-startup-timeout-s 10 \
  --request-timeout-ms 30000 \
  --mcp-host 0.0.0.0 \
  --mcp-port 8050 \
  --mcp-path /mcp

With these values, the MCP endpoint is:

http://127.0.0.1:8050/mcp

Debug Launches

Worker only:

uv run aps-12id-worker \
  --config configs/example.yaml \
  --bind tcp://127.0.0.1:5555

MCP frontend only:

uv run aps-12id-mcp \
  --config configs/example.yaml \
  --worker tcp://127.0.0.1:5555 \
  --timeout-ms 30000 \
  --host 0.0.0.0 \
  --port 8050 \
  --path /mcp

MCP Client Configuration

{
  "mcpServers": {
    "aps_12id": {
      "url": "http://127.0.0.1:8050/mcp",
      "transport": "http"
    }
  }
}

Important Options

• worker.endpoint: ZMQ endpoint used between the MCP frontend and worker.
• worker.request_timeout_ms: frontend request timeout for worker calls.
• worker.startup_timeout_s: launcher health-check timeout before starting MCP.
• mcp.host, mcp.port, mcp.path: HTTP transport settings.
• artifacts.output_dir: directory for PNG and .npy artifacts. It must be readable by MCP clients that consume returned paths.
• safety.simulation_mode: flag for non-hardware operation while control code is incomplete.
• safety.allow_hardware_moves: must remain false until real motor control is implemented and reviewed.
• tools.acquire_image_defaults: default scan center, size, step, and exposure values.

The current worker deliberately does not implement real beamline control. Replace the placeholder handlers in src/control_suite_mcp_aps_12id/worker.py with synchronous, blocking calls to the APS 12-ID control stack.