Skip to content

MCP Registry Reload

When and how to refresh the MCP gateway skill registry. Pick by what changed: DATA (declarations / workflows / param schemas) → reload_skill_data, no restart; CODE (Op bodies, new Op modules, gateway functions) → Ctrl+R restart; transient tool-probe failure → recheck_disabled_skill.

When to use

When the user invokes /wb-dev-mcp-reload, or after editing a skill declaration / workflow / parameter schema and needing it live without a server restart

Slash command: /wb-dev-mcp-reload

  • reload_skill_data

Directions

Pick the refresh path by what changed — data, code, or a transient probe.

reload_skill_data — data changes (no restart)

Use when you edited or added a skill declaration (including its parameter schema) or a workflow unit, and want it live without a restart.

`mcp__work-buddy__wb_run("reload_skill_data")`

It resets the knowledge-store cache, clears _REGISTRY, and rebuilds in place — without purging sys.modules. Because no module is re-imported, Skill / WorkflowDefinition class identity stays stable and the long-lived FastMCP gateway reads the rebuilt registry directly. Cost: ~6–8s (it re-probes every tool as part of the rebuild); blocks /health for the duration.

Goes live with no restart: - A new or edited skill declaration whose Op is already registered. - A changed parameter schema on an existing skill. - A new or edited workflow unit. - Re-enabling a skill whose tool just came back (the rebuild re-probes + re-runs the requirements filter).

Verify a specific skill is now in the active registry: 

`mcp__work-buddy__wb_run("agent_docs", {"query": "<skill_name>", "depth": "summary"})`
(agent_docs is the right discovery tool here — wb_search is skill-only and may miss prose units.)

Restart (Ctrl+R) — code changes

reload_skill_data refreshes data, not code. Re-importing Python is what a process restart does safely, so a restart is required when you change: - an Op's Python body (the callable a declaration points at), - a brand-new Op module, - wb_run / wb_search or any gateway function frozen by FastMCP at boot.

In Claude Code Desktop that's Ctrl+R. (For sidecar-hosted code, a sidecar reset re-reads code at startup.) See dev/live-testing-directions for the two-process model — which restart picks up what.

recheck_disabled_skill(name) — transient probe failure

Use when a skill is in the disabled registry because its tool probe transient-failed (e.g. obsidian unreachable for 200ms during startup) but the underlying tool is now healthy, and you want to recover ONE skill without rebuilding.

from work_buddy.recovery import recheck_disabled_skill
recovered = recheck_disabled_skill("task_create")
# True  — skill is now in the active registry
# False — tool still probing as down; skill stays disabled

Cost: one tool probe (or zero within the 30s cool-down). Mutates _REGISTRY in place — no purge, no rebuild. There is no MCP wrapper; the gateway dispatch path and the sidecar retry sweep call it automatically, so agents rarely call it directly.

Decision tree

What changed?
  - Declaration / workflow / parameter schema ... reload_skill_data (no restart)
  - Op code / new Op module / gateway function .. Ctrl+R restart (re-imports Python)
  - Skill stuck disabled (transient probe) . recheck_disabled_skill(name) — usually automatic
  - Knowledge unit edited (prose only) ......... agent_docs_rebuild
  - Just want to verify discovery .............. agent_docs(query=...) — no reload needed

Retired: mcp_registry_reload

The heavy mcp_registry_reload was retired from the agent surface. It purged work_buddy.* from sys.modules to pick up code — but in the long-lived FastMCP gateway that silently did nothing: wb_run / wb_search are frozen against the boot module generation, so the rebuilt registry never reached dispatch, while the purge corrupted class identity (returning {"status": "ok"} while changing nothing). The underlying function invalidate_registry() still exists, dormant. For data changes use reload_skill_data; for code changes restart. Full background: architecture/skill-registry and .data/designs/mcp-registry-reload.