Skip to content

MCP Server

mcp_server.py exposes every feature of the app to AI agents over the Model Context Protocol (stdio). It reuses the app's own pipeline — the same monkeypatches, analysis workers, Ray throttling, CIF cache and presets as the GUI — so results are identical to running the desktop app. The GUI does not need to be running.

Registering the server

claude mcp add autophase -- python /path/to/QuickPhaseAnalysis/mcp_server.py

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "autophase": {
      "command": "python",
      "args": ["/path/to/QuickPhaseAnalysis/mcp_server.py"]
    }
  }
}

Use the same Python interpreter that runs main.py — it needs dara, PySide6, ray and mcp installed (see Installation).

Tools

Pattern inspection

  • get_pattern_info / get_pattern_data — pattern properties and downsampled 2θ / intensity arrays, with optional fitted background.
  • compute_phase_reflections — theoretical Bragg positions for candidate CIFs (the GUI's Overlay Phase Reflections).

Analysis

Async jobs — only one runs at a time.

  • start_phase_search — full phase search: chemical system (COD) and/or local CIFs, pinned phases, batch patterns, quick/advanced refinement parameters, custom 2θ range, background subtraction, presets.
  • start_refinement — single refinement with an exact phase list (the GUI's Refine Phases).
  • get_job_status / cancel_job / list_jobs.

Results

  • list_solutions — ranked solutions with Rwp / Rp / Rexp / GoF / Durbin–Watson and phase weight fractions (+ ESD).
  • get_solution_details — lattice parameters, cell volume, space groups.
  • get_profile_data / get_peak_list / get_lst_content.
  • export_solution — plot-data .txt, raw .lst, interactive Plotly .html, and an Origin-style publication figure .png (same formats as the GUI export buttons).

Housekeeping

  • list_cif_cache / clear_cif_cache — the persistent per-chemical-system COD cache.
  • list_presets / save_preset / delete_preset — parameter presets, stored in the same QSettings location as the GUI so both share them.
  • get_server_status / list_instrument_profiles.

Typical agent workflow

  1. get_pattern_info("/data/sample.xy")
  2. start_phase_search(pattern_paths=["/data/sample.xy"], chemical_system="Fe-As-S") → job_id
  3. Poll get_job_status(job_id) until state == "completed" — searches take minutes; the first run of a chemical system also downloads CIFs from COD.
  4. list_solutions(job_id) → pick a rank.
  5. get_solution_details(job_id, rank=1), then export_solution(job_id, 1, "/out").
  6. Optionally tweak the phase list and start_refinement(...) with the phase_cif_paths returned by list_solutions.

Notes

  • Ray is initialized lazily on the first search job (same memory / CPU caps as main.py) and kept alive for the whole server session.
  • BGMN binaries are auto-downloaded to a temp dir on first use (via app/patches.py), so the very first refinement is slower.
  • stdout is shielded: the JSON-RPC stream keeps the real stdout while stray prints from dara / Ray / BGMN subprocesses are routed to stderr.