Phase 6 -- The MCP server (2026-10-01) ====================================== **Result:** ``seamm-flowchart mcp`` serves the flowchart tools to AI clients over stdio (``seamm/mcp_server.py``, optional ``seamm[mcp]``, mcp >= 2.2). Local only (Option 1 of the design); a web UI endpoint is left for later. Committed on ``dev`` (eda33ae), not pushed. ``mcp`` 2.2.0 installed in ``~/SEAMM_DEV/venv`` (only additions; pre-install freeze in ``~/SEAMM_DEV/venv-freeze-2026-10-01-before-mcp.txt``). Tools ----- ``list_steps``, ``describe_step``, ``show_flowchart``, ``flowchart_tree`` and ``validate_flowchart`` (read only); ``build_flowchart`` (will not replace a file unless ``overwrite``), ``set_parameters``, ``insert_step``, ``remove_step`` (marked destructive), ``move_step`` and ``convert_flowchart``. Thin wrappers over ``catalog``, ``spec`` and ``edit``. The files stay the source of truth: each tool reads the ``.flow`` it is given and writes the result back (or to ``output``) in 3.0, and the editing tools return the new step tree and any problems. Errors users can fix (unknown step, bad value, no-effect setting) come back as tool errors with the builder's message. The server's instructions carry the skill's workflow (look up, spec, build, validate, show). Design points ------------- - **stdout is the protocol.** mcp 2's stdio transport diverts fd 1 to stderr while serving, so the plug-ins are loaded after serving starts (a background warm-up in the lifespan), never before. The client connects in about 1.5 s; the first call waits for the warm-up (about 4 s). - **One lock** around every tool and the warm-up: SEAMM's objects are not thread safe, and the SDK runs synchronous tools in worker threads. Speed ----- Warm calls first took 4-6 s. Profiling found two costs in SEAMM itself, now fixed in core (874c90e): every new step re-parsed its plug-in's ``references.bib`` (cached by path and modification time) and every 3.0 read called ``importlib.metadata.packages_distributions()`` (cached per process). Warm calls now take 0.2-0.8 s (edit 0.8 s, tree 0.5 s, validate 0.2 s); the editor, the builder and job start-up gain too. MOPAC's step ``__init__`` still runs ``cpuinfo`` (a subprocess) for every MOPAC step created -- a plug-in fix for later. Checked ------- - 9 tests through a real MCP client in-process (``tests/test_mcp_server.py``, skipped without ``mcp`` or the plug-ins); the full suite: 227 passed. - End to end over real stdio, starting ``~/SEAMM_DEV/venv/bin/seamm-flowchart mcp``: all 11 tools, a loop flowchart built, a step inserted and edited, "PM9" refused with the closest choices. Incident: ~/.seamm.d/seammrc wiped ---------------------------------- The first stdio test wiped ``~/.seamm.d/seammrc`` down to ``[VERSION]`` (06:34), losing the dashboard credentials and Zenodo tokens. Cause: a latent race in ``SEAMMrc`` -- every new Flowchart creates one, its ``__init__`` re-ran on the singleton, emptying the shared parser before re-reading, and a second thread could find it empty, "upgrade" it and save it. The warm-up thread ran outside the lock while a tool call created flowcharts. Reproduced 3/3 with four threads (under a fake ``HOME``). **Fixed** in core (d6c9feb): one lock, read into a new parser, never save over a file that reads as empty, atomic saves keeping the mode; ``SEAMMrc(path)`` no longer raises ``TypeError``. 5/5 clean after the fix; 6 tests, all with their own ``HOME``. The warm-up now holds the server's lock too. The real file was **not** restored automatically (blocked as an overwrite): Paul to restore it from ``~/.seamm.d/seammrc~`` (2026-08-11, 16 sections), re-adding anything added since. Time Machine's disk could not be mounted and there are no local snapshots. Job tools (2026-10-01) ---------------------- Committed on ``dev`` (19d884b), not pushed. Seven tools talk to dashboards: ``list_dashboards``, ``dashboard_info`` (status, projects, queues with their SLURM limits), ``submit_job``, ``job_status``, ``list_jobs``, ``list_job_files`` and ``read_job_file``. - The dashboards are those in the installation's ``dashboards.ini`` (``seamm_util.installation_path``, so ``~/SEAMM``'s for SEAMM_DEV) and the credentials those in ``~/.seamm.d/seammrc``. Both are only read -- deliberately not through ``DashboardHandler``, which creates ``dashboards.ini`` if missing and adds empty sections to ``seammrc`` -- and credentials are never returned. - ``submit_job`` refuses a flowchart with problems; fills in the defaults of the Parameters step's variables (``Dashboard.submit`` indexes every one) and converts yes/no to booleans; checks that files exist (they are uploaded with the job) and the project exists; and needs one of the dashboard's queues when it lists any (a submission without a queue once went to ``molssi10``). Marked open-world and not read only; the instructions say to confirm the dashboard, project and queue first. - **Checked:** 6 tests with a stand-in client (the queue rule, defaults, refusals, both file-list formats, read-only credentials); 233 passed. Live on the dev web UI: job 3999, built and submitted through the tools with ``SMILES=CCO``, finished (PM7 ΔHf -53.29 kcal/mol); status, job list, files and ``job.out`` read back; all 18 tools over real stdio. Found along the way: - **seamm_dashboard_client ``Job.list_files`` found no files** (tested the list, not each entry) and failed with ``KeyError: 'parent'`` on seamm_webui's ``{"path", "size"}`` listing. Fixed in the client (e9e83de, local); the server reads both formats itself, so it does not depend on the fix. The client's test file needs ``responses``, which the SEAMM_DEV venv lacks. - **The queue configuration on this Mac is ignored.** The JobServer and web UI run without ``--name``/``--jobserver-name``, so they look for ``.ini``; the hostname is now ``PaulVT.local`` but the file is ``PaulsPersonal.local.ini`` (queues ``local`` and ``molssi10``, default ``molssi10``). So the web UI lists no queues and every job runs locally. For Paul. - ``list_dashboards(check=True)``: ``ChemAI_WebUI`` and ``MacMini`` report errors from here (not investigated). Next ---- Registering the server with Claude Code / Claude Desktop; the skill pointing at the server where available.