feat(mcp): enhance MCP backend restoration and migration handling

- Introduced functions to restore user and workspace MCP configurations from backend definitions, ensuring that existing configurations are merged and unnecessary keys are removed.
- Updated hook uninstall processes to restore MCP configurations alongside removing hooks, improving the overall management of agent settings.
- Added checks for migratable MCP backends to prevent unnecessary operations when no valid backends are found.
- Enhanced test coverage for MCP restoration and migration scenarios, ensuring robust handling of configurations across different agents.

This update aims to streamline the MCP management process and improve the reliability of agent configurations.

Author: qdrddr

scripts/pre-commit-hooks/prek-hook-groups.yaml

@@ -4,6 +4,9 @@
 # Integration tests (src/tests/integration) are manual-only:
 #   uv run pytest -m integration --run-integration
 # prek-loop.sh unsets CYT_RUN_INTEGRATION_TESTS; do not add integration pytest hooks here.
+# MCP restore/uninstall unit tests use autouse isolation in src/tests/conftest.py
+# (_isolate_agent_hook_paths + _isolate_cyt_mcp_user_config) so pre-commit never
+# touches ~/.cursor/mcp.json, ~/.config/cyt/mcp/, or workspace .agents/cyt/config/mcp/.
 #
 # Hooks may appear in more than one group. The `suggestion` hook is omitted
 # intentionally (informational only).

src/cyt/hook/setup_wizard.py

@@ -2226,7 +2226,12 @@ def _apply_prevent_hallucinations_config(
     agents: list[HookAgentName],
 ) -> dict[str, Any]:
     from cyt.config import save_user_config, sync_config_in_place
-    from cyt.tools.cyt_mcp_setup import setup_cyt_mcp_for_agent, write_mcp_aggregator_yaml
+    from cyt.hook.install_scope import CytInstallScope
+    from cyt.tools.cyt_mcp_setup import (
+        has_migratable_mcp_backends,
+        setup_cyt_mcp_for_agent,
+        write_mcp_aggregator_yaml,
+    )
 
     inject_map: dict[str, str] = {
         "cursor": "hook",
@@ -2251,6 +2256,7 @@ def _apply_prevent_hallucinations_config(
     sync_config_in_place(config, config_path)
 
     invocation = detect_hook_cli_invocation()
+    scope = CytInstallScope.from_cwd()
     if invocation.is_dev and invocation.repo_root is not None:
         print(
             f"\nInstalling development cyt-mcp via uv run --directory {invocation.repo_root}",
@@ -2261,6 +2267,12 @@ def _apply_prevent_hallucinations_config(
         if inject_map.get(agent) != "hook":
             write_mcp_aggregator_yaml(agent, transport="stdio", verify_only=True)
             continue
+        if not invocation.is_dev and not has_migratable_mcp_backends(agent, scope):
+            print(
+                f"No MCP backend servers found; skipping cyt-mcp injection for {agent}.",
+                file=sys.stderr,
+            )
+            continue
         migrate_backends = _prompt_prevent_hallucinations_mcp_migration(agent)
         setup_cyt_mcp_for_agent(
             agent,
@@ -2603,9 +2615,9 @@ def run_hook_uninstall_workspace(
     agents: list[HookAgentName] | None = None,
     workspace_root: Path | None = None,
 ) -> None:
-    """Remove workspace-scoped cyt-mcp artifacts from the current or given project."""
+    """Restore workspace-scoped agent MCP configs from cyt backend defs."""
     from cyt.hook.install_scope import CytInstallScope
-    from cyt.tools.cyt_mcp_setup import remove_workspace_cyt_mcp_for_agent
+    from cyt.tools.cyt_mcp_setup import restore_workspace_cyt_mcp_for_agent
 
     selected_agents = _resolve_hook_setup_agents(agents)
     scope = CytInstallScope(
@@ -2618,7 +2630,7 @@ def run_hook_uninstall_workspace(
     print("CYT workspace MCP uninstall\n")
     any_changed = False
     for agent in selected_agents:
-        if remove_workspace_cyt_mcp_for_agent(agent, scope):
+        if restore_workspace_cyt_mcp_for_agent(agent, scope):
             any_changed = True
 
     if any_changed:
@@ -2628,8 +2640,15 @@ def run_hook_uninstall_workspace(
 
 
 def run_hook_uninstall(*, agents: list[HookAgentName] | None = None) -> None:
-    """Remove CYT agent hooks from Claude, Codex, and/or Cursor config files."""
+    """Remove CYT agent hooks and restore migrated MCP configs."""
+    from cyt.hook.install_scope import CytInstallScope
+    from cyt.tools.cyt_mcp_setup import (
+        restore_user_cyt_mcp_for_agent,
+        restore_workspace_cyt_mcp_for_agent,
+    )
+
     selected_agents = _resolve_hook_setup_agents(agents)
+    scope = CytInstallScope.from_cwd()
 
     if len(selected_agents) == 1:
         print(f"CYT hook uninstall ({selected_agents[0]})\n")
@@ -2642,23 +2661,31 @@ def run_hook_uninstall(*, agents: list[HookAgentName] | None = None) -> None:
         path = _agent_hook_path(agent)
         if not path.is_file():
             print(f"{label}: skipped ({path} not found)")
-            continue
-        preserve_empty_hooks_object = agent == "cursor"
-        if uninstall_hooks_from_file(
-            path,
-            preserve_empty_hooks_object=preserve_empty_hooks_object,
-        ):
-            print(f"{label}: removed CYT hook from {path}")
-            any_changed = True
         else:
-            print(f"{label}: no CYT hook in {path}")
+            preserve_empty_hooks_object = agent == "cursor"
+            if uninstall_hooks_from_file(
+                path,
+                preserve_empty_hooks_object=preserve_empty_hooks_object,
+            ):
+                print(f"{label}: removed CYT hook from {path}")
+                any_changed = True
+            else:
+                print(f"{label}: no CYT hook in {path}")
+
+        if restore_user_cyt_mcp_for_agent(agent, scope):
+            print(f"{label}: restored user MCP config")
+            any_changed = True
+
+        if scope.has_workspace and restore_workspace_cyt_mcp_for_agent(agent, scope):
+            print(f"{label}: restored workspace MCP config")
+            any_changed = True
 
     if "cursor" in selected_agents:
         removed = remove_windows_hook_wrappers()
         if removed:
             print(f"Cursor: removed {len(removed)} Windows hook wrapper(s)")
 
     if any_changed:
-        print("\nRestart your agent so hook changes take effect.")
+        print("\nRestart your agent so hook and MCP changes take effect.")
     else:
-        print("\nNo hook files were modified.")
+        print("\nNo hook or MCP files were modified.")

src/cyt/proxy/cli_impl.py

@@ -391,12 +391,12 @@ def _add_hook_handler_args(parser: argparse.ArgumentParser) -> None:
     hook_uninstall_parent.add_argument(
         "--uninstall",
         action="store_true",
-        help="Remove CYT hooks from agent config file(s)",
+        help="Remove CYT hooks and restore migrated MCP configs (user and workspace)",
     )
     hook_uninstall_parent.add_argument(
         "--uninstall-workspace",
         action="store_true",
-        help="Remove workspace-scoped cyt-mcp from the current project only",
+        help="Restore workspace-scoped agent MCP configs from cyt backend defs only",
     )
 
     hook_parser = subparsers.add_parser(