[HengyuLi-Ozaki-lab]

Summary

Exposes set_param_str as an fp_mcp MCP tool. This is pure wiring — every layer below the MCP server already supports it:

layer	status
fp/fp_api.f90:165	fp_api_set_param_str … BIND(C, NAME="fp_set_param_str") — already an exported symbol
fp/fp_param_registry.f90:73-79, :295	fp_param_set_str (the wrapper that counts a successful set, #253) and its CASE ("KNAMEQ")
python/fplib/fplib.py:163	Fplib.set_param_str()
python/mcp-servers/fp_mcp/server.py	← the only gap

No Fortran changes: a libfpapi.so built from develop already exports the symbol (fplib refuses a library whose fp_state_t layout is older than develop's version 2):

$ nm -gU fp/libfpapi.so | grep set_param_str
000000000036ac68 T _fp_set_param_str

Why

fp_param_registry.f90's own comment states the intent (written before fp_prep returned the load error; today a missing file stops at fp_mesh with FP_ERR_CALC_FAILED, see Verification):

Required because the FP namelist /FP/ inherits KNAMEQ from plcomm (the equilibrium-data file name used by the MODELG=3 eq_load path on fp_iter01). Without this entry point the Layer 1 fixture cannot point at a real EQDSK; the default KNAMEQ='eqdata' (from pl_init) is missing in cwd, so eq_load fails silently and downstream BESEKNX trips with NCALC=-2.

Until now that entry point was unreachable from an MCP client, so fp_mcp could take the MODELG=3 equilibrium-load path only with pl_init's default KNAMEQ='eqdata' in its working directory: a client could not name the file. eq_mcp and tr_mcp both already expose set_param_str; this brings fp_mcp to parity.

Changes

• str added to the SupportedValue union, so set_params({"KNAMEQ": ...}) routes to the string setter instead of dying in float()
• KNAMEQ registered in PARAMETER_REGISTRY as type: "str"
• handle_set_param_str() handler, error-mapped through the existing _wrap_fplib_error (FplibError → rebuild hint, registry rc=1 → invalid parameter)
• tool registration + --print-tools (9 → 10 tools), instructions string, docstrings
• README.md: tool table, --print-tools output, and two corrections — §8.3 described MODELG=3 as "analytic" when it is the file-loading path, and §8.4 said string parameters were unsupported

Added on 2026-10-21, after develop (ea9806ac, with #232, #233, #240) was merged in:

• the scalars description in the state schema: zero again "after a set_param or set_param_str"; the get_state docstring names scalars (feat(fp): expose global plasma scalars (Ip, stored energy, powers, volume) in fp_state_t #233's first LOW)
• the text the merge left behind: eq_mcp's save tool is in develop, no longer "once Reconcile bpsi/develop base into develop (bpsi↔fork merge baseline, CI-green) #226 lands"; the Sphinx FP MCP pages (en, ja) list ten tools with a set_param_str row instead of saying it is not exposed; README §2 names the eight exported symbols
• tot_mcp lists fp:KNAMEQ as run_pipeline only: it reads fp_mcp's registry, but tot's set_param passes string values on for eq: and tr: only (tot/tot_param_registry.f90; set_param("fp:KNAMEQ", ...) is refused with rc=1), while run_pipeline sets it through fplib
• two points of the feat(fp): expose global plasma scalars (Ip, stored energy, powers, volume) in fp_state_t #233 approval: the raw-ctypes mono tests run the wrappers' layout check (version and size) before passing a struct, and the refused-set test runs one more step and checks that TIMEFP doubles (no re-preparation)
• a CHANGELOG.md Added entry

Verification

Against a stock build (gfortran 15.2.0, macOS arm64):

• set_param_str("KNAMEQ", "eq.bin") accepted; set_param_str("KNAMFP", ...) correctly rejected with rc=1 (the registry has exactly one CASE)
• Positive path: an equilibrium written by eq_mcp's save tool is loaded by FP — # OLD FILE (eq.bin) IS ASSIGNED FOR INPUT., and eqgetb writes the file's geometry back into FP (DEVICE, RR, RA, BB = 3.60E+00 1.20E+00 4.50E+00, matching the perturbed EQ run rather than FP's own defaults). Mesh metrics move accordingly (rsrhon 0.805→1.0264, bpm 0.3506→0.1829, ql 2.2961→7.0134), and global integrals scale with the volume ratio (stored energy 5.369→10.341 MJ = 1.93× vs TVOL 28.42→53.12 = 1.87×)
• Negative control: pointing KNAMEQ at a missing file gives this chain (the registry comment predicted BESEKNX tripping with NCALC=-2; the load error now stops fp_prep first) — XX FROPEN (EQ): FILE NOT FOUND → eq_load: eqload: ierr=7 → XX FPMESH:EQLOAD:IERR=7 → XX fp_prep: fp_mesh failed
• Stability: 5/5 fresh subprocesses, 7.07–7.30 s, bit-identical states
• Tests, before the merge of develop: 45 passed, 55 subtests. Two existing tests pinned the old contract (test_rejects_string_value, test_print_tools_lists_nine) and were rewritten to pin the new one; added coverage for the registry entry, the handler, and the error mapping for a simulated missing-symbol error

Note for reviewers

#232 (the stdout guard) is merged; fp_mcp's fd isolation is develop's python/_fd_isolation.py, kept as it is by the merge.

One finding worth recording, though it needs no change here: FP's six get_state profile arrays are local per-unit-volume moments, so with MODELD=0 and no wave/current-drive model they are bit-identical across different equilibria. The equilibrium enters only through the volume element and mesh metrics, which fp_state_t did not expose. The geometry-dependent globals the code already computes (rtotalIP, stored energy, total collision/absorption power, TVOL) were written to unit 6 but not returned in the state. #233 now returns seven of them as scalars, and a successful set_param_str zeroes them until the next run, as a numeric set does.

🤖 Generated with Claude Code

[HengyuLi-Ozaki-lab]

This has been green since 2026-08-06 and has had no review yet. Could one of you look at it when you have time? It is
small and self-contained (3 files, +163/-22) and the FP work we are doing downstream builds on it. It does not depend
on #226, and a trial merge of #226, #231, #232, #233 and #240 together is clean.

[k-yoshimi]

Reviewed at 62600919 (based on current develop tip 4a5d977d). Approving.

Verified locally (macOS, stock fp/libfpapi.so, pytest 9.1.1 --forked):

• python/mcp-servers/fp_mcp: 45 passed (42 unit + 3 integration), also with the strict-subTest override from #243 active.
• Claims cross-checked against develop: Fplib.set_param_str exists with the rebuild-hint FplibError; fp_param_set_str has exactly one CASE ("KNAMEQ"); nm shows 6 exported fp_* symbols including fp_set_param_str; _apply_bulk_params keeps the bool-reject first and the new str branch sits before the numeric one; the handler mirrors tr_mcp.handle_set_param_str.
• Live probe: set_param_str("KNAMEQ", "eq.bin") accepted, set_param_str("KNAMFP", ...) → FplibInvalidParamError rc=1, as the PR says.

One non-blocking note: fplib._encode_name(value, _MAX_C_STRING_VALUE_BYTES) caps the value at 80 bytes and raises FplibInvalidParamError beyond that; a one-line mention in the set_param_str tool docstring ("paths longer than 80 bytes are rejected") would save an LLM client a confusing round trip. Fine as a follow-up.

[k-yoshimi]

Independent Codex review (second reviewer, read-only) found no HIGH items. Code wiring stands as approved; three documentation points need a small fix before merge, all verified against develop:

1. eq_mcp has no save tool on develop. README.md §8.4 and the set_param_str tool docstring show eq.save(path="eq.bin") / "an equilibrium written by eq_mcp's save tool". That tool exists only on the Reconcile bpsi/develop base into develop (bpsi↔fork merge baseline, CI-green) #226 branch. Please phrase it as "a TASK/EQ-format equilibrium file (e.g. one written by EQSAVE / the eq program, or by eq_mcp's save tool once Reconcile bpsi/develop base into develop (bpsi↔fork merge baseline, CI-green) #226 lands)".
2. The "missing KNAMEQ → NaN via BESEKNX" description is stale. On develop, fp_mesh propagates the eq_load failure (fp/fpprep.f90:66-68) and fp_api_run returns FP_ERR_CALC_FAILED (fp/fp_api.f90:213-218), i.e. FplibCalcFailedError / "calculation failed" to the client, which is what your own negative control showed. The registry comment you quote predates that; please describe the current behaviour in README §8.4 and in handle_set_param_str's docstring.
3. §8.3 wording: fp_iter01.in does not set MODELG (the fixture runs with the pl_init default MODELG=2), so "MODELG=3 が既定的な選択" is misleading; the file-loading note you added is right, but say that MODELG=3 is the choice when an equilibrium file is to be loaded, not the iter01 default.

Non-blocking (follow-up material): the decorated set_params / run_and_get_state still type params as Dict[str, Any], so the MCP JSON schema does not advertise the str/number/list/dict union; set_params({"RR": "6.5"}) reaches fp_set_param_str and reports rc=1 without saying RR is numeric (a PARAMETER_REGISTRY["type"] pre-check would do); KNAMEQ is CHARACTER(LEN=80) in plcomm while the wrapper accepts up to 128 bytes, so an 81–128-byte path is silently truncated (pre-existing in fplib, now reachable from MCP) — worth a doc line or an 80-byte cap.

Once 1–3 are pushed I will re-approve and we merge.

[HengyuLi-Ozaki-lab]

Pushed 9cd01e66 with the three documentation points. Each was checked against a build of this branch (macOS arm64, gfortran 15):

1. No eq_mcp save on develop. README 8.4 and the set_param_str docstrings now say the file is "a TASK/EQ-format equilibrium file (e.g. one written by EQSAVE / the eq program, or by eq_mcp's save tool once Reconcile bpsi/develop base into develop (bpsi↔fork merge baseline, CI-green) #226 lands)".
2. A missing KNAMEQ. README 8.4 and handle_set_param_str describe what happens now: fp_mesh returns eq_load's error, fp_run returns FP_ERR_CALC_FAILED, fplib raises FplibCalcFailedError and the handler turns it into a "calculation failed" ToolError (measured for a missing file and for a directory: fp_run(1): rc=3). The text says the BESEKNX comment in fp_param_registry.f90 describes the behaviour before that propagation; I left the Fortran comment alone to keep this pull request to Python and documentation.
3. 8.3. MODELG=3 is the choice when an equilibrium file is to be loaded; fp_iter01.in sets no MODELG and runs with pl_init's MODELG=2.

The statement of point 3 stood in two more places, corrected in the same commit:

• The example of section 6.2 ("iter01-like parameters") set MODELG=3 with no KNAMEQ: as written it fails with "calculation failed". It now leaves MODELG out and runs (run_and_get_state returns 40 RTT values).
• PARAMETER_REGISTRY["MODELG"], the description describe_parameters serves, said "3 = typical for iter01 fixture". It now says "pl_init default 2; 3 = load the TASK/EQ file named by KNAMEQ". This is the one change outside the README and docstrings, a description string.

Two things found while checking point 2, both older than this branch and documented here rather than fixed:

• A file that opens but is not a TASK/EQ file can end the process. With MODELG=3 and KNAMEQ naming an empty file or a text file, the run does not return an error: At line 143 of file eqfile.f90 ... Fortran runtime error: End of file, exit status 2. EQRTSK reads the leading records without IOSTAT (eq/eqfile.f90:143 onwards). Through fp_mcp the server is gone. It is a library-reachable abort of the Fortran STOP in library-reachable code paths — enumeration + migration #142 kind, now one tool call away for an MCP client, so the tool docstring and README 8.4 warn about it. I can open an issue for it, or a small pull request that gives those reads an IOSTAT, whichever you prefer.
• The path length, from your non-blocking notes: the wrapper accepts up to 128 bytes and KNAMEQ is CHARACTER(LEN=80), so a path of 81 to 128 bytes is cut to its first 80 characters without an error (measured: a 100-byte name loads the file whose name is its first 80 characters), and more than 128 bytes is refused. The docstring and 8.4 say so. Capping the wrapper at 80 is a code change I would rather make as a follow-up.

python/ on this branch: 727 passed, 35 skipped, 1 xpassed with CI's flags. develop has moved to a0b58408 (#242, #243) since your review: this branch merges into it without a conflict, and on develop with #231, #232, #233 and #240 merged together python/ gives 831 passed, 35 skipped, 1 xfailed (#243's strict subTest active). The workflow run needs your approval.

[k-yoshimi]

#233 and #240 are merged (develop ea9806ac). This branch is now 46+ commits behind and touches the same fp_mcp/server.py block that #233 rewrote, so please rebase (or merge develop) and re-run CI; per the note on #233, the scalars schema text should say "after a set_param or set_param_str" again once this tool exists, and the module comment near line 100 can state that fp_mcp now exposes the string setter. We will re-review the delta after the push.

[HengyuLi-Ozaki-lab]

develop (ea9806ac) is merged in, with no conflict (557344c8; its message lists what came in that the branch's text had to follow). Five commits follow:

• 811a12d6: the scalars description in the state schema reads "after a set_param or set_param_str". A successful fp_set_param_str moves the registry's counter like a numeric set (fp/fp_param_registry.f90:78), and python/fplib/tests/test_state_scalars_window.py checks it for KNAMEQ. The other descriptions of that window already name fp_set_param_str since feat(fp): expose global plasma scalars (Ip, stored energy, powers, volume) in fp_state_t #233: fplib's README and state.py, docs/fp-library/architecture.md, fp_api.h, the Sphinx state pages and CHANGELOG.
• aeeab628: the text the merge left behind.
  • eq_mcp's save tool is in develop (feat(eq): eq_save, Eq.save() and the save tool of eq_mcp, with errors reported #256), so "once Reconcile bpsi/develop base into develop (bpsi↔fork merge baseline, CI-green) #226 lands" goes, in three places.
  • The Sphinx FP MCP pages (en, ja) said nine tools and that the string setter is not reachable through MCP; they now list ten, with a set_param_str row.
  • README §2 names the eight exported symbols.
  • The get_state docstring names scalars: your first LOW on feat(fp): expose global plasma scalars (Ip, stored energy, powers, volume) in fp_state_t #233.
  • The comment above SupportedValue says this server exposes the string setter as the set_param_str tool, as you suggested.
• 84ec1c1b: tot_mcp marks fp:KNAMEQ as run_pipeline only.
  • tot_mcp builds describe_parameters from the sibling servers' registries, so this PR's KNAMEQ showed up under fp:.
  • tot's set_param passes string values on for eq: and tr: only (tot/tot_param_registry.f90); set_param("fp:KNAMEQ", ...) is refused with rc=1. run_pipeline does set it, through fplib (TotPipeline.set_param).
  • So the fp: entry stays: its description keeps what the parameter is and says to give it in run_pipeline's params, since set_param, set_params and run_and_get_state refuse it. A ti:, wr: or wrx: string entry would be left out (there is none). Three tests; two of them fail without the change.
  • Passing fp: strings through tot's set_param would be a Fortran change, for later if wanted.
• c91544fa: your LOW 3 and the optional item on feat(fp): expose global plasma scalars (Ip, stored energy, powers, volume) in fp_state_t #233.
  • The raw-ctypes mono tests run the wrappers' layout check (_abi_check.check_state_layout: version and size) before passing a struct (fp and ti cases).
  • The refused-set test runs one more step and checks that TIMEFP doubles, so the run continues without re-preparation.
  • All three layout cases fail on a mutated copy with the version one higher or the struct 8 bytes larger, and the TIMEFP check fails with a successful set in place of the refused one.
• 08d60044: a CHANGELOG.md Added entry.

Your LOW 2 on #233 (README §8.4) was this PR's §8.4 rewrite already. Of #273, this PR settles the fp_mcp items server.py:100-102, README :64 and §8.4. The two-step build command in that README, and the fplib README and architecture.md items, stay with #273. I have updated the description for the merge: the line numbers, the rebuild sentence (a library whose fp_state_t layout is older than develop's version 2 is refused), the 2026-10-21 changes, and the notes on #232 and the globals.

Locally on the head (macOS, gfortran 15, a clean build of the merged tree; the later commits change no Fortran; CI's flags --forked --timeout=120 --timeout-method=signal): 1042 passed, 39 skipped. The skips are the 19 Linux-only equivalence tests, 16 that need the mono image or libtotapi.so set by path, 3 ti_mcp cases without their fixture, and /dev/full. The four files of CI's mono step, run with the mono image: 20 passed. The head merges without conflict into develop and with #267, #269 and #270.

[k-yoshimi]

Review of the delta after the merge of develop (557344c8..08d60044), through the full cycle (Codex + in-house correctness and test-oracle lenses + docs/workflow review), with the tests run under the CI flags.

Verdict: approve. The merge commit's tree is identical to a clean merge of develop ea9806ac into 9cd01e66, and the five commits after it change no Fortran, so develop's libfpapi.so, libtotapi.so, libtrapi.so and mono image are the right binaries for this head; I used them. Locally: fp_mcp + tot_mcp + fplib's scalars-window test, 133 passed / 5 skipped (the skips want libtotapi.so in the tree); with develop's libtotapi.so and libtrapi.so placed in the worktree and MONO_LIB_PATH on the mono image, test_set_after_run.py and tot_mcp's integration tests 14 passed, no skip. CI on 08d60044 is green.

What the reviewers verified: tot/tot_param_registry.f90:124-134 forwards strings for tr and eq only, and totlib/pipeline.py:504-511 routes a string to the module's own set_param_str, which eqlib/fplib/trlib have, so the fp:KNAMEQ description _as_tot_sees_it writes is true on both halves. The string entries today are eq: KNAMEQ/KNAMWR/KNAMWM and tr:/fp: KNAMEQ, none in ti/wr/wrx, so the "left out" branch is exercised only by the synthetic test. PARAMETER_REGISTRIES consumers (_flat_count, describe_parameters, the shape tests) see the same counts, order and, for eq/tr, the same dict objects. _check_layout calls check_state_layout with its real signature, both *_state_abi_version/*_state_size pairs are in the mono image (whole obj/pic wildcards, no export list), and the MONO_LIB_PATH skip is in setUp. The TIMEFP assertion discriminates: fp_run re-preps only when the generation moved (fp/fp_api.f90:236-244), the registry bumps only on ierr==0, and fp_prep zeroes TIMEFP, so a spurious re-prep would give DELT, not 2*DELT. Counts: 10 @mcp.tool() in fp_mcp/server.py, 8 BIND(C) names in fp/fp_api.f90.

LOW (no re-review needed if you take them, a push is enough).

• tot_mcp/server.py:225: .split(". ")[0] cuts a first sentence at "e.g. " or "i.e. ". The one entry it is applied to has none, so today's output is right, but the test asserts only a prefix; pinning the exact part before ". Through tot_mcp:" would catch a future reword of fp_mcp's description.
• _PIPELINE_STRING_NAMESPACES lists eq and tr, which return at line 216-217 and never reach that branch; only fp is live.
• docs/sphinx/modules/fp/en/mcp.md sends the English reader to section 8.4 of a README written in Japanese.
• _check_layout hard-codes lib_name="libtotapi_mono.so" while the path comes from MONO_LIB_PATH.
• tot_mcp's set_param/set_params/run_pipeline docstrings could point an fp:KNAMEQ caller at run_pipeline's params, and the "no eq_mcp yet" comment at :122-125/:140-141 is stale.

Pre-existing, not on this PR. The docs review found that the tot Sphinx pages (parameters.md, parameter-setting.md, en and ja) show tot.set_param_str("fp:KNAMEQ", …) and "wr:KNAMEQ", which tot_param_set_str refuses with rc=1, that tot_mcp/__init__.py and the tot Sphinx pages say 9 tools where server.py registers 10 (run_pipeline has no row), and that _wrap_totlib_error's "names must be namespaced" hint misleads when a correctly namespaced fp: string is refused. All of that is on develop unchanged and is now #274. The fplib README and the fp/fp_api.f90 header still naming five symbols belongs to #273.

Merge on the maintainers' instruction; after #267 in the queue, since both touch the mono tests.

[HengyuLi-Ozaki-lab]

The LOWs are in bfa64d9e; no Fortran changes.

• First sentence. _as_tot_sees_it takes the first sentence by splitting at a period followed by a capital, so an "e.g." or "i.e." before a lowercase word no longer cuts it. The test pins the exact first sentence of fp:KNAMEQ, and the synthetic case has an "e.g." (it fails with the old split(". ")).
• Namespaces. _PIPELINE_STRING_NAMESPACES is now _PIPELINE_ONLY_STRING_NAMESPACES = ("fp",).
• tot_mcp text. The set_param, set_params and run_pipeline docstrings point a fp:KNAMEQ caller at run_pipeline's params. The two "no eq_mcp yet" comments now say that the inline eq: registry was written before eq_mcp existed.
• Sphinx. The English FP MCP page says what set_param_str is for, instead of pointing at the Japanese README.
• _check_layout. It names the image it loaded (the basename of MONO_LIB_PATH) in its rebuild hint.

Locally: tot_mcp and fp_mcp 128 passed. The mono step's four files, run with the mono image: 20 passed. The head merges without conflict into develop and with #226, #267, #269 and #270. #274 is next, as a separate PR.

[k-yoshimi]

bfa64d9e checked (Codex pass on the code hunks + the tests run here). Diff against 08d60044: tot_mcp/server.py (regex first-sentence split, _PIPELINE_ONLY_STRING_NAMESPACES, docstrings, the two stale comments), its tests, _check_layout's lib_name, the English Sphinx page. No Fortran.

What was checked: the regex \.\s+(?=[A-Z]) gives exactly the first sentence of the real fp:KNAMEQ description (the test now pins it), keeps "e.g. a" whole, preserves a description with no period, and the template restores the period rstrip removes; fp: is the only namespace reaching that branch, so no other description is transformed. ctypes.CDLL._name is the path given to CDLL on 3.11 and 3.13 and os is imported in the test module. Nothing else references the removed _PIPELINE_STRING_NAMESPACES. Codex: no must_fix / should_fix; one optional (more regex edge cases in the synthetic test, e.g. "e.g. ASCII"), not needed for any entry that exists.

Locally at this head, with develop's libfpapi.so / libtotapi.so / libtrapi.so and MONO_LIB_PATH on the mono image: fp_mcp + tot_mcp + fplib scalars window + test_set_after_run.py, 144 passed, no skip. CI 3/3. Merges clean against develop, #267, #269, #270 and #226.

Verdict: approve (renewed on this head). Merge on the maintainers' instruction; #274 as its own PR is fine.