feat: read-only results-inspector MCP server (shared core + lens layer)

[Jammy2211]

Overview

Add a read-only "results-inspector" MCP server to the AI assistants so chat harnesses without code execution (Claude Desktop first; claude.ai web / ChatGPT via remote MCP later) can inspect PyAutoFit/PyAutoLens fit results: list and filter searches in an output directory, get model composition and posterior summaries, and fetch/combine result images, with figures returned inline via the MCP Image type. Fit composition and execution stay script-first through the existing skills — this deliberately closes the inspection gap only.

Plan

• Phase 1 (autofit_assistant, PR 1): FastMCP stdio server at autoassistant/mcp/ with ~8 read-only aggregator tools, each a thin wrapper over existing public PyAutoFit API (Aggregator, SearchOutput, AggregateImages, AggregateFITS). New skills/af_inspect_results_mcp.md (tool table, Claude Desktop config, .mcp.json, tiers 2/3 documented-not-built), skills/README.md registration, audit-sweep wiring, fixture-based unit tests.
• Phase 2 (autolens_assistant, PR 2): mirror the core server file (headed as mirrored; de-dup path = future graduation to an autofit[mcp] extra) + thin lens_tools.py layer and matching al_inspect_results_mcp.md.
• No recompute in v1: images are served/combined from existing outputs, never regenerated from datasets — every tool stays glue-only and fast.
• PyAutoFit contingent-only: a wrapper needing a missing public method promotes that method upstream first (none expected — the rhayes777/PyAutoMCP prototype ran on existing API).
• Acceptance: unit tests against a small fixture output directory + a documented Claude Desktop walkthrough — list fits ranked by log evidence, show a model.result summary, display a fit subplot inline in chat.

Detailed implementation plan

Work Classification

Workspace (assistant repos; no library changes expected)

Affected Repositories

• autofit_assistant (primary)
• autolens_assistant (lens layer)
• PyAutoFit (contingent-only — missing public methods promote upstream)

Branch Survey

Repository	Current Branch	Dirty?
./autofit_assistant	main	clean
./autolens_assistant	main	clean
./PyAutoFit	main	clean (residual feature/ep-projection-weights branch, unrelated)

Suggested branch: feature/results-inspector-mcp
Worktree root: ~/Code/PyAutoLabs-wt/results-inspector-mcp/ (created by /start_workspace)

Implementation Steps — Phase 1 (autofit_assistant)

1. autoassistant/mcp/__init__.py + autoassistant/mcp/server.py + autoassistant/mcp/__main__.py — FastMCP stdio server (python -m autoassistant.mcp), name pyauto-results-inspector.
2. Tools (all read-only; JSON or MCP Image returns; limit guards on directory scans):
   • list_searches(directory, sort_by="log_evidence", limit) — name, unique tag, path, model summary, log evidence (via Aggregator.from_directory).
   • get_model(directory) — model composition dict (SearchOutput.model).
   • get_result_summary(directory) — model.result text.
   • get_samples_summary(directory) — max-LH / median-PDF vectors + errors at sigma.
   • get_search_info(directory) — search name/config/info.
   • fetch_image(directory, name) — serve an existing files/*.png as MCP Image.
   • combine_images(directories, image_names) — AggregateImages subplot combination, returned as Image.
   • extract_fits(directories, hdus) — AggregateFITS extraction to a scratch path + summary.
3. skills/af_inspect_results_mcp.md — what the server is; tool table; Claude Desktop claude_desktop_config.json snippet; Claude Code .mcp.json snippet; tier 2 (claude.ai web / ChatGPT developer mode via ngrok/cloudflared tunnel) and tier 3 (hosted collaboration deployment) documented but not built; the glue-not-code rule (any logic beyond arg-parsing + calling an existing public API belongs in PyAutoFit).
4. Register in skills/README.md; add .claude/skills/ symlink; add .mcp.json at repo root for Claude Code sessions.
5. fastmcp dependency documented in af_setup_environment (assistant env only — never a library requirement).
6. Audit wiring: autoassistant/mcp/*.py PyAuto* symbols join the audit_skill_apis.py sweep.
7. Tests: autoassistant/tests/test_mcp_server.py — call tool functions directly against a tiny fixture output directory (numpy-only, no JAX, no network).

Implementation Steps — Phase 2 (autolens_assistant)

1. Mirror autoassistant/mcp/server.py core (file header marks it mirrored-from-autofit_assistant).
2. autoassistant/mcp/lens_tools.py — thin lens layer: fit-subplot fetch and lens-specific image combinations from existing outputs (no recompute; source-reconstruction recompute is an explicit follow-up).
3. skills/al_inspect_results_mcp.md + README registration + symlink + .mcp.json.
4. Mirrored fixture tests.

Key Files

• autofit_assistant/autoassistant/mcp/server.py — the server + core tool set
• autofit_assistant/skills/af_inspect_results_mcp.md — canonical documentation/skill
• autofit_assistant/autoassistant/audit_skill_apis.py — anti-drift sweep to extend
• autolens_assistant/autoassistant/mcp/lens_tools.py — lens viz layer
• Prior art: rhayes777/PyAutoMCP (aggregate.py/visualise.py are the parts to mature; optimisation.py/compute.py deliberately dropped)

Client-support matrix (verified 2026-07-17)

• Claude Desktop / Claude Code: local stdio MCP — tier 1, the acceptance target.
• claude.ai web/mobile + ChatGPT developer mode: remote-only MCP (no stdio) — tier 2, needs tunnel/hosting, documented only.
• Hosted next to collaboration outputs (Euclid-scale triage, e.g. by rhayes777/aggregator-agent-style classifiers): tier 3, future.

Original Prompt

Click to expand starting prompt

Add a read-only "results-inspector" MCP server to the AI assistants so chat harnesses
without code execution (Claude Desktop first; claude.ai web / ChatGPT via remote MCP later)
can inspect PyAutoFit/PyAutoLens fit results: list and filter searches in an output
directory, get model composition and posterior summaries (model.result, log evidence,
samples summaries), and fetch/combine result images and FITS, with figures returned
inline via the MCP Image type.

Scope and design constraints (agreed in research discussion 2026-07-17):

• READ-ONLY. No optimise/fit-running tools, no compute tools. Model composition and fit
  execution stay script-first through the existing skills; the trap of flattening the
  compositional API into JSON schemas (demonstrated by rhayes777/PyAutoMCP's optimise
  tool, which hardcodes pixel_scales/Imaging/LBFGS) is explicitly out of scope.
• Glue, not code: ~8-10 tools, each a thin wrapper over an existing public PyAutoFit
  aggregator API (Aggregator, SearchOutput, AggregateImages, AggregateFITS) or existing
  aplt subplot functions. Rule: any logic beyond argument-parsing + calling an existing
  public API belongs in PyAutoFit itself, not the server. If a tool needs new logic,
  add the method to PyAutoFit first.
• Shared core + thin lens layer: the aggregator tool core is autofit-level and shared by
  autofit_assistant and autolens_assistant; autolens_assistant adds a thin layer of
  lens-specific visualization tools (fit subplots, source reconstruction) reusing
  existing aplt functions. No duplicated code between the two assistants.
• Delivery inside the assistants (e.g. autoassistant/mcp/ + a .mcp.json registration),
  documented by a symmetric af_/al_ skill file in each assistant's skills/. Graduate the
  core into PyAutoFit proper only if it earns it.
• Anti-drift: the server's cited PyAuto* symbols are added to the existing
  audit_skill_apis sweep so the tool surface cannot drift silently against the stack.
• Acceptance test: a Claude Desktop session with the server configured (local stdio)
  can list fits in an output directory ranked by log evidence, show a model.result
  summary, and display a fit subplot inline in chat.
• Tiers 2/3 (claude.ai web / ChatGPT via ngrok-cloudflared tunnel; hosted
  collaboration/Euclid deployment next to shared outputs) are DOCUMENTED in the skill
  file but not built in this task.
• Prior art to review: rhayes777/PyAutoMCP (FastMCP prototype, Sept 2025 — aggregate.py
  and visualise.py are the good parts to mature; drop optimisation.py/compute.py) and
  rhayes777/aggregator-agent (pydantic-ai vision triage over fit subplots — a future
  consumer of this tool surface, not part of this task). Coordinate with Richard, who
  built both prototypes.

Repos: autofit_assistant (primary), autolens_assistant (lens layer), PyAutoFit (only if
a wrapper needs a missing public method).

[Jammy2211]

Shipped — 2026-07-17

PRs

• feat: read-only results-inspector MCP server (core aggregator tools) #13 (Phase 1 — core aggregator tools)
• feat: results-inspector MCP server — mirrored core + lens layer autolens_assistant#75 (Phase 2 — mirrored core + lens layer)

Summary

The read-only results-inspector MCP stdio server is built in both assistants: 7 core tools over PyAutoFit output directories (list/summaries/inline images) plus 3 lens tools (al.agg enum-driven subplot/FITS extraction), documented by symmetric af_/al_ skills with Claude Desktop config, wired into the audit_skill_apis anti-drift sweep, and covered by fixture tests that run a real tiny fit (63 + 62 suite passes; end-to-end stdio smokes green).

Session Notes

• SubplotFit → SubplotFitImage rename and af.Aggregator (database) vs autofit.aggregator.Aggregator (directory) both confirmed the drift risk the audit wiring exists for.
• stdout is the JSON-RPC channel: autofit's progress prints AND its logging config's stdout handlers both had to be rerouted to stderr — one stray line corrupts the protocol.
• MCP clients spawn servers with a minimal environment: PYTHONPATH (editable installs) must be declared in the client config's env block — documented in both skills.
• SearchOutput.image() reads image/, not files/ as its docstring claims (upstream docs nit).
• Deliberately no pending-release label — assistants are outside the release chain.
• Heart was RED on an unrelated PyAutoLens dirty file (JOSS draft); ship proceeded with explicit human acknowledgement.
• Follow-ups (not this task): Claude Desktop acceptance walkthrough by the user; tier 2/3 (tunnel/hosted) if demand appears; graduation of the mirrored core to an autofit[mcp] extra.

[Jammy2211]

Both PRs merged (autofit_assistant#13, autolens_assistant#75). Remaining acceptance — the Claude Desktop walkthrough — is tracked in the skill docs (af_/al_inspect_results_mcp); closing as shipped.