mcpXL30

WORK IN PROGRESS

mcpXL30 is an MCP (Model Context Protocol) server that exposes a curated subset of the pyxl30 control library to LLM agents (i.e. AI contorl of the XL30 ESEM).

Note that this project was partially generated with LLM support.

Features

• Async MCP tools for common Philips XL30 operations (identify, read/set high tension, change scan modes, trigger pump/vent cycles, capture TIFF images).

• Live MCP resources that describe the connected instrument and active config.

• Safety envelope that limits accelerating voltage and sensitive operations.

• Fine grained settings that control allowed operations for the LLM agent.

• Optional remote HTTP/UDS transport with the authentication workflow explained in my blog post.

Installation

pip install mcpXL30
# or
pip install "mcpXL30[remote]"  # adds FastAPI/uvicorn/argon2 for remote mode

Configuration

The server loads JSON configuration from ~/.config/mcpxl30/config.json by default (override via --config). A minimal example:

{
  "instrument": {
    "port": "/dev/ttyUSB0",
    "log_level": "INFO",
    "retry_count": 3,
    "reconnect_count": 3
  },
  "image_capture": {
    "remote_directory": "C:\\\\TEMP",
    "filename_prefix": "MCPIMG_"
  },
  "safety": {
    "max_high_tension_kv": 15.0,
    "allow_venting": false,
    "allow_pumping": true,
    "allow_scan_mode_changes": true,
    "allow_stage_motion": false,
    "allow_detector_switching": true,
    "allow_beam_shift": true,
    "allow_scan_rotation_changes": true,
    "allow_image_filter_changes": true,
    "allow_specimen_current_mode_changes": false,
    "allow_beam_blank_control": true,
    "allow_oplock_control": false
  },
  "logging": {
    "level": "INFO",
    "logfile": null
  },
  "remote_server": {
    "uds": "/var/run/mcpxl30.sock",
    "api_key_kdf": {
      "algorithm": "argon2id",
      "salt": "<base64>",
      "time_cost": 3,
      "memory_cost": 65536,
      "parallelism": 1,
      "hash_len": 32,
      "hash": "<base64>"
    }
  }
}

Use mcpxl30-genkey --config /path/to/config.json (or mcpxl30 --genkey) to generate a new API key and populate the Argon2 hash inside the remote_server block. The plain token prints once to stdout.

The safety block gates riskier capabilities. Keep allow_stage_motion and allow_oplock_control disabled unless you trust the calling agent. Imaging and detector-related fields default to safe-but-capable settings, but you can toggle them per deployment.

Running the server

stdio transport (default)

mcpxl30 --config ~/.config/mcpxl30/config.json

The process utilizes the stdio transport.

Remote FastAPI/uvicorn transport

pip install "mcpXL30[remote]"
mcpxl30 --transport remotehttp --config ~/.config/mcpxl30/config.json

• The FastAPI app exposes /mcp (MCP streaming API) and /status (unauthenticated health check).

• Authentication expects the API key in Authorization: Bearer, X-API-Key, or the ?api_key= query parameter.

• Binding uses a Unix domain socket (remote_server.uds) unless you specify a TCP port, in which case host (default 0.0.0.0) applies.

MCP functionality

Tools

Instrument Basics

Beam & Detector Controls

Scan Timing & Geometry

Imaging Utilities

Stage & Alignment

Image Filtering & Specimen Current

Beam Safety & Locks

Every setter uses blocking pyxl30 calls inside asyncio.to_thread, preserving the FastMCP event loop responsiveness. Review the safety settings to enable only the tools you trust agents with.

All setters perform blocking pyxl30 calls inside asyncio.to_thread so the MCP event loop stays responsive.

Resources

• mcpxl30://instrument/capabilities – supported scan modes, image filter names, and the configured safety envelope.

• mcpxl30://instrument/config – sanitized live configuration (excludes API secrets).

Examples

An examples/example_config.json file is included to bootstrap deployments. The repository mirrors mcpMQTT's project layout so existing FastMCP infrastructure (supervisors, packaging, docs) can be reused with minimal changes.