Repository navigation
fix(agent): mount a dropped MCP server once its program is back - #35837
Conversation
A server whose command was not found at a rebuild was left out of kirocrew.json and recorded in mcp-dropped-servers.json, but nothing re-ran the rebuild when the program came back: only a gateway start or a config change does, so its tools stayed missing from every session until a restart. The pre-spawn self-heal for the default agent now also rebuilds an existing spec when a recorded command resolves on the rebuild resolver's search path. The rebuild mounts the server and clears the record, so the check goes quiet again. Docs name the retry. Closes #34969
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks. The retry runs inside the existing pre-spawn self-heal and reuses the gateway-start rebuild. It searches a subset of the path the resolver searches, so once a server is mounted the record clears and the check stops. Notes
[DESIGN-REVIEWED] 360461a Description read[DESCRIPTION-READ] 14a55876667884dd39725468d8ec3599f5f82aaa6f9a8a8f9e9102d58b3f3b67 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The new step goes to the cause: the drop record had no reader that retried the rebuild. It reuses the existing rebuild and search path, and it runs only while a drop is on record. What this change shipsInventory (4 items) — 4 justifiedIntent: a user who installs a missing MCP server's program gets that server's tools in their next chat without restarting the gateway. This is a FIX (#34969).
[FIRST-PRINCIPLES-REVIEWED] 360461a Description read[DESCRIPTION-READ] a241d2405bf21527c8f8ede0f98d2aaf9bcaacbc5de6beddead17ea7d0197144 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
Code change approver recommendation: ApproveWhy: the decider estimates a 10% chance that this change introduces a defect, within the 12% limit for approving on its own, and every check passes. Adds a retry to the pre-spawn self-heal in ensure_agent_materialized. When a server recorded in mcp-dropped-servers.json as command-not-found now resolves, it runs rebuild_agent_config once. The check expands the recorded command the same way the resolver does, and searches mcp_search_path(""), which is always a subset of what the resolver searches for any server (the server's own env.PATH entries come first, then the shared ones). So a found program always gets mounted, and the rewritten record stops the check from firing again; it cannot loop. The recorded command is the winning entry's command, the first one the resolver tries. All async callers already run this function off the event loop. The new test fails without the change and passes on Windows CI. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
buluoray
left a comment
There was a problem hiding this comment.
Approve on 360461a. Before this change, an MCP server that a rebuild dropped because its program was missing stayed out of every new chat until a gateway restart. Now the pre-spawn self-heal reads the drop record, and when a recorded program is found on the search path the rebuild uses, it runs the normal rebuild once before the session starts. The rebuild then mounts the server and clears the record. The gate is a subset of the rebuild's own resolver: same argument expansion, same search path minus the server's own PATH entry. So a program that the gate finds is also found by the rebuild, and the retry fires once. While the program is still missing, the cost is one small file read and one path lookup per recorded server, with no rebuild. The retry runs the same rebuild as a gateway start, so it applies the same disabled flags, spec gate, governance and approval ceiling. It adds no approval and does not touch a user's own MCP files. A server that the person removed or turned off is not mounted by this path, because the rebuild decides what to mount from the current sources, exactly as at a restart. The new test fails both when the retry is taken out and when the missing-program check is taken out. All checks pass and every review lane on this head passed or was correctly skipped. Decisive lines: src/kiro_crew/agent_parts/spec_rebuild.py:1187-1206, src/kiro_crew/agent_parts/spec_rebuild.py:877-883, src/kiro_crew/agent_materialization/mcp_sources.py:1014-1016, src/kiro_crew/agent_materialization/mcp_sources.py:710-717, test/test_agent_spec_safety.py:71-97
Problem / Motivation
Goal: An MCP server that was left out of the default agent because its program was missing comes back in the next chat once the program is installed, without a gateway restart.
When the gateway rebuilt
~/.kiro/agents/kirocrew.jsonwhile a server's program was briefly missing (for examplenpxduring a Homebrew relink of node), the rebuild loggedDropping MCP server '<name>': command not foundand wrote the spec without that server. Once the program was back, new chats still had none of the server's tools untilkirocrew restart.Why it matters
Agents told to use those tools stop or fall back to unmanaged work, and the only fix users find is restarting the gateway, which interrupts every running chat.
Not a goal
@<server>totools/allowedToolsinkirocrew.json(the second trigger): the file is rebuilt from the MCP sources on every start by design, and Customize → Connections → MCP Servers is the supported path. Not changed here.env.PATH, or under a Node version installed after the gateway started (those directories are listed once per process): the server is still retried at the next gateway start or config change, and the docs say so.What changed (motivation → approach → change)
A server dropped because its program was not found now comes back at the next chat on the default agent, once the program is installed. Before, the rebuild recorded the drop in
mcp-dropped-servers.jsonand nothing read that record again: only a gateway start or a config change re-runs the rebuild, so the server stayed out of every session until a restart.The self-heal that already runs before every default-agent session,
ensure_agent_materializedinagent_parts/spec_rebuild.py, now also checks that record whenkirocrew.jsonexists. If a recorded command is found on the search path the rebuild resolver uses, it runsrebuild_agent_config()once before the spawn and logs which servers came back. That rebuild mounts the server and clears its record, so the next session start finds nothing to do. With no record, the usual case, the self-heal returns as before.src/kiro_crew/docs/agents.md,src/kiro_crew/docs/troubleshooting.md,docs/architecture/mcp.mdand the module docstring ofsrc/kiro_crew/mcp_dropped_servers.pysay a dropped server is retried at the next session start, and when a restart is still needed.Backwards compatibility
Compatible: an existing spec is rebuilt only when a recorded program now resolves, and that rebuild is the same one a gateway start runs; nothing main accepts is refused, renamed or removed.
Removes nothing: the diff only adds a rebuild trigger.
Tests
test/test_agent_spec_safety.py::test_ensure_agent_materialized_rebuilds_once_a_dropped_program_is_found: with a drop recorded and the program absent fromPATH, a default-agent session start does not rebuild; once the program is onPATH, it rebuilds once. That the rebuild then mounts the server and clears the record is already locked in bytest/test_mcp_dropped_servers.py::test_a_command_not_found_drop_is_recorded_and_shown_until_it_resolves.The new test passes 20 times at
-n0, 10 times at-n 4 --dist loadgroupbesidetest/test_agent_spec_safety.pyandtest/test_mcp_dropped_servers.py, and the two files pass in a shuffled order (seed 14007, 43 tests).Proof: PROVEN test/test_agent_spec_safety.py::test_ensure_agent_materialized_rebuilds_once_a_dropped_program_is_found (head 360461a)
Manual verification
N/A — unit coverage sufficient: the change is one new branch in the pre-spawn self-heal, driven by the new test, and the rebuild it calls is the existing one the dropped-servers tests run end to end.
Related Issues
Closes #34969
Sibling sweep
Swept: git grep -nE "load_dropped|record_rebuild_drops" -- src/
Sibling: src/kiro_crew/agent_parts/spec_rebuild.py:1189 -- changed here
Sibling: src/kiro_crew/dashboard/handlers/mcp_probe.py:254 -- not affected -- it only reads the record to put a note on the server's row
Sibling: src/kiro_crew/agent_materialization/kiro_hooks.py:123 -- not affected -- a skipped hook is an absolute path the user wrote, never recorded, and not an MCP server
Pattern harvest
Not generalizable: the only drop that is recorded and then never re-read is the default-agent rebuild's command-not-found drop, and this is its one retry seam.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)