mcp-config-dedupe 0.1.0__tar.gz

mcp_config_dedupe-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hao li
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_config_dedupe-0.1.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: mcp-config-dedupe
+Version: 0.1.0
+Summary: Detect duplicate, drifted, and dead MCP server configs across clients — and dedupe them in one command
+Author-email: hao li <haoli5933@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/mcp-config-dedupe
+Project-URL: Issues, https://github.com/hahahahahahahahah6/mcp-config-dedupe/issues
+Keywords: mcp,model-context-protocol,config,dedupe,claude,cursor,vscode,codex
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mcp-config-dedupe
+
+Detect duplicate, drifted, and dead MCP server configurations across your AI clients — then dedupe them in one command.
+
+If you run Claude Desktop, Cursor, VS Code, and Codex side by side, you have probably pasted the same `mcpServers` block into four different config files. Over time they rot: the same server gets configured twice, one copy gets different args than the other (**drift**), and old entries point at commands you uninstalled months ago (**dead links**). `mcp-dedupe` scans every client, shows you the mess, and cleans it up — with backups and a dry-run first.
+
+Stdlib-only. No dependencies, no network calls, no telemetry.
+
+## Install
+
+```bash
+pip install mcp-config-dedupe
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+```bash
+# Scan all supported clients (read-only) and print findings
+mcp-dedupe scan
+
+# Machine-readable report (exit code 1 when findings exist — CI friendly)
+mcp-dedupe scan --format json
+
+# Preview what dedupe would change (default; writes nothing)
+mcp-dedupe dedupe
+
+# Actually dedupe: backups are taken first, confirmation is explicit
+mcp-dedupe dedupe --apply --yes
+
+# Also resolve drifted duplicates, preferring Cursor's copy
+mcp-dedupe dedupe --apply --yes --include-drift --prefer cursor
+
+# Also remove servers whose command/cwd no longer exists
+mcp-dedupe dedupe --apply --yes --prune-dead
+```
+
+What it detects:
+
+| Finding | Meaning |
+|---|---|
+| `DUPLICATE` | Same server name with an identical config in 2+ clients — safe to dedupe automatically |
+| `DRIFT` | Same server name but different command/args/env across clients — reported, and only touched with `--include-drift` |
+| `DEAD-LINK` | `command` not on `PATH` / path doesn't exist, or `cwd` is gone — only removed with `--prune-dead` |
+| `REMOTE` | URL-based server; can't be verified offline, listed for visibility |
+| `UNREADABLE` | Config file exists but can't be parsed |
+
+Supported clients: **Claude Desktop**, **Cursor**, **VS Code** (`mcp.servers` settings), **Codex CLI** (`~/.codex/config.toml`).
+
+Safety model: `scan` and the default `dedupe` (dry-run) never write. `--apply` refuses to run without `--yes`, backs up every touched file to `~/.mcp-dedupe/backups/<timestamp>/` first, and only rewrites configs that parsed cleanly. Drifted duplicates are never auto-merged — you pick the winner with `--prefer`.
+
+## Differentiation
+
+- **vs `mcp-audit-tool` (config security auditing):** auditing tells you a config looks risky; `mcp-dedupe` takes action — it removes the duplicate and dead entries across clients in one command.
+- **vs editing JSON by hand:** one scan gives you a unified cross-client view with drift highlighted, instead of diffing four files in four different locations yourself.
+- **vs `mcp-config-sync` (merge-everything sync):** syncing unions every server into every client; dedupe does the opposite job — it collapses redundant copies down to one canonical entry and prunes what's dead.
+
+## Exit codes
+
+- `0` — success (scan clean / apply completed)
+- `1` — findings present (scan or dry-run)
+- `2` — usage error, or `--apply` without `--yes`
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v   # 14 smoke tests, stdlib only
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_config_dedupe-0.1.0/README.md

@@ -0,0 +1,73 @@
+# mcp-config-dedupe
+
+Detect duplicate, drifted, and dead MCP server configurations across your AI clients — then dedupe them in one command.
+
+If you run Claude Desktop, Cursor, VS Code, and Codex side by side, you have probably pasted the same `mcpServers` block into four different config files. Over time they rot: the same server gets configured twice, one copy gets different args than the other (**drift**), and old entries point at commands you uninstalled months ago (**dead links**). `mcp-dedupe` scans every client, shows you the mess, and cleans it up — with backups and a dry-run first.
+
+Stdlib-only. No dependencies, no network calls, no telemetry.
+
+## Install
+
+```bash
+pip install mcp-config-dedupe
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+```bash
+# Scan all supported clients (read-only) and print findings
+mcp-dedupe scan
+
+# Machine-readable report (exit code 1 when findings exist — CI friendly)
+mcp-dedupe scan --format json
+
+# Preview what dedupe would change (default; writes nothing)
+mcp-dedupe dedupe
+
+# Actually dedupe: backups are taken first, confirmation is explicit
+mcp-dedupe dedupe --apply --yes
+
+# Also resolve drifted duplicates, preferring Cursor's copy
+mcp-dedupe dedupe --apply --yes --include-drift --prefer cursor
+
+# Also remove servers whose command/cwd no longer exists
+mcp-dedupe dedupe --apply --yes --prune-dead
+```
+
+What it detects:
+
+| Finding | Meaning |
+|---|---|
+| `DUPLICATE` | Same server name with an identical config in 2+ clients — safe to dedupe automatically |
+| `DRIFT` | Same server name but different command/args/env across clients — reported, and only touched with `--include-drift` |
+| `DEAD-LINK` | `command` not on `PATH` / path doesn't exist, or `cwd` is gone — only removed with `--prune-dead` |
+| `REMOTE` | URL-based server; can't be verified offline, listed for visibility |
+| `UNREADABLE` | Config file exists but can't be parsed |
+
+Supported clients: **Claude Desktop**, **Cursor**, **VS Code** (`mcp.servers` settings), **Codex CLI** (`~/.codex/config.toml`).
+
+Safety model: `scan` and the default `dedupe` (dry-run) never write. `--apply` refuses to run without `--yes`, backs up every touched file to `~/.mcp-dedupe/backups/<timestamp>/` first, and only rewrites configs that parsed cleanly. Drifted duplicates are never auto-merged — you pick the winner with `--prefer`.
+
+## Differentiation
+
+- **vs `mcp-audit-tool` (config security auditing):** auditing tells you a config looks risky; `mcp-dedupe` takes action — it removes the duplicate and dead entries across clients in one command.
+- **vs editing JSON by hand:** one scan gives you a unified cross-client view with drift highlighted, instead of diffing four files in four different locations yourself.
+- **vs `mcp-config-sync` (merge-everything sync):** syncing unions every server into every client; dedupe does the opposite job — it collapses redundant copies down to one canonical entry and prunes what's dead.
+
+## Exit codes
+
+- `0` — success (scan clean / apply completed)
+- `1` — findings present (scan or dry-run)
+- `2` — usage error, or `--apply` without `--yes`
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v   # 14 smoke tests, stdlib only
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_config_dedupe-0.1.0/mcp_config_dedupe.egg-info/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.4
+Name: mcp-config-dedupe
+Version: 0.1.0
+Summary: Detect duplicate, drifted, and dead MCP server configs across clients — and dedupe them in one command
+Author-email: hao li <haoli5933@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/hahahahahahahahah6/mcp-config-dedupe
+Project-URL: Issues, https://github.com/hahahahahahahahah6/mcp-config-dedupe/issues
+Keywords: mcp,model-context-protocol,config,dedupe,claude,cursor,vscode,codex
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# mcp-config-dedupe
+
+Detect duplicate, drifted, and dead MCP server configurations across your AI clients — then dedupe them in one command.
+
+If you run Claude Desktop, Cursor, VS Code, and Codex side by side, you have probably pasted the same `mcpServers` block into four different config files. Over time they rot: the same server gets configured twice, one copy gets different args than the other (**drift**), and old entries point at commands you uninstalled months ago (**dead links**). `mcp-dedupe` scans every client, shows you the mess, and cleans it up — with backups and a dry-run first.
+
+Stdlib-only. No dependencies, no network calls, no telemetry.
+
+## Install
+
+```bash
+pip install mcp-config-dedupe
+```
+
+Requires Python 3.11+.
+
+## Usage
+
+```bash
+# Scan all supported clients (read-only) and print findings
+mcp-dedupe scan
+
+# Machine-readable report (exit code 1 when findings exist — CI friendly)
+mcp-dedupe scan --format json
+
+# Preview what dedupe would change (default; writes nothing)
+mcp-dedupe dedupe
+
+# Actually dedupe: backups are taken first, confirmation is explicit
+mcp-dedupe dedupe --apply --yes
+
+# Also resolve drifted duplicates, preferring Cursor's copy
+mcp-dedupe dedupe --apply --yes --include-drift --prefer cursor
+
+# Also remove servers whose command/cwd no longer exists
+mcp-dedupe dedupe --apply --yes --prune-dead
+```
+
+What it detects:
+
+| Finding | Meaning |
+|---|---|
+| `DUPLICATE` | Same server name with an identical config in 2+ clients — safe to dedupe automatically |
+| `DRIFT` | Same server name but different command/args/env across clients — reported, and only touched with `--include-drift` |
+| `DEAD-LINK` | `command` not on `PATH` / path doesn't exist, or `cwd` is gone — only removed with `--prune-dead` |
+| `REMOTE` | URL-based server; can't be verified offline, listed for visibility |
+| `UNREADABLE` | Config file exists but can't be parsed |
+
+Supported clients: **Claude Desktop**, **Cursor**, **VS Code** (`mcp.servers` settings), **Codex CLI** (`~/.codex/config.toml`).
+
+Safety model: `scan` and the default `dedupe` (dry-run) never write. `--apply` refuses to run without `--yes`, backs up every touched file to `~/.mcp-dedupe/backups/<timestamp>/` first, and only rewrites configs that parsed cleanly. Drifted duplicates are never auto-merged — you pick the winner with `--prefer`.
+
+## Differentiation
+
+- **vs `mcp-audit-tool` (config security auditing):** auditing tells you a config looks risky; `mcp-dedupe` takes action — it removes the duplicate and dead entries across clients in one command.
+- **vs editing JSON by hand:** one scan gives you a unified cross-client view with drift highlighted, instead of diffing four files in four different locations yourself.
+- **vs `mcp-config-sync` (merge-everything sync):** syncing unions every server into every client; dedupe does the opposite job — it collapses redundant copies down to one canonical entry and prunes what's dead.
+
+## Exit codes
+
+- `0` — success (scan clean / apply completed)
+- `1` — findings present (scan or dry-run)
+- `2` — usage error, or `--apply` without `--yes`
+
+## Development
+
+```bash
+python3 -m unittest discover -s tests -v   # 14 smoke tests, stdlib only
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

mcp_config_dedupe-0.1.0/mcp_config_dedupe.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+mcp_config_dedupe.egg-info/PKG-INFO
+mcp_config_dedupe.egg-info/SOURCES.txt
+mcp_config_dedupe.egg-info/dependency_links.txt
+mcp_config_dedupe.egg-info/entry_points.txt
+mcp_config_dedupe.egg-info/top_level.txt
+mcp_dedupe/__init__.py
+mcp_dedupe/__main__.py
+mcp_dedupe/cli.py
+mcp_dedupe/clients.py
+mcp_dedupe/findings.py
+mcp_dedupe/sync.py
+mcp_dedupe/toml_util.py
+tests/test_dedupe.py

mcp_config_dedupe-0.1.0/mcp_config_dedupe.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcp_config_dedupe-0.1.0/mcp_config_dedupe.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-dedupe = mcp_dedupe.cli:main

mcp_config_dedupe-0.1.0/mcp_config_dedupe.egg-info/top_level.txt

@@ -0,0 +1 @@
+mcp_dedupe

mcp_config_dedupe-0.1.0/mcp_dedupe/__init__.py

@@ -0,0 +1,4 @@
+"""mcp_dedupe: detect drift/duplicates/dead links across MCP client configs."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

mcp_config_dedupe-0.1.0/mcp_dedupe/__main__.py

@@ -0,0 +1,5 @@
+"""Entry point for `python -m mcp_dedupe`."""
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

mcp_config_dedupe-0.1.0/mcp_dedupe/cli.py

@@ -0,0 +1,139 @@
+"""CLI for mcp-dedupe: scan and dedupe MCP client configurations."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from . import __version__
+from .clients import BY_ID
+from .findings import actionable, scan_all
+from .sync import apply_plan, build_plan, describe_plan
+
+EXIT_OK = 0
+EXIT_FINDINGS = 1
+EXIT_ERROR = 2
+
+
+def _home_arg(args) -> Path:
+    return Path(args.home).expanduser() if args.home else Path.home()
+
+
+def cmd_scan(args) -> int:
+    result = scan_all(home=_home_arg(args))
+    if args.format == "json":
+        print(json.dumps(result.to_dict(), indent=2, ensure_ascii=False))
+    else:
+        present = [s for s in result.scans if s.path and s.path.is_file()]
+        print("MCP config scan")
+        print("=" * 60)
+        for s in result.scans:
+            status = (
+                f"{len(s.servers)} server(s)" if s.path and s.path.is_file()
+                else "no config file"
+            )
+            extra = f"  [ERROR: {s.error}]" if s.error else ""
+            print(f"- {s.client.id:15} {status}{extra}")
+        print("-" * 60)
+        if not result.findings:
+            print("Clean: no duplicates, drift, or dead links found.")
+        for f in result.findings:
+            who = f", ".join(f.clients) if f.clients else "-"
+            label = {"duplicate": "DUPLICATE", "drift": "DRIFT",
+                     "dead-link": "DEAD-LINK", "remote": "REMOTE",
+                     "unreadable": "UNREADABLE"}.get(f.kind, f.kind.upper())
+            print(f"[{label}] {f.server or '(config)'} ({who}): {f.detail}")
+    return EXIT_FINDINGS if actionable(result.findings) else EXIT_OK
+
+
+def cmd_dedupe(args) -> int:
+    if args.prefer and args.prefer not in BY_ID:
+        print(f"error: unknown client '{args.prefer}'. Known: {', '.join(sorted(BY_ID))}",
+              file=sys.stderr)
+        return EXIT_ERROR
+    home = _home_arg(args)
+    result = scan_all(home=home)
+    plan = build_plan(result, include_drift=args.include_drift,
+                      prune_dead=args.prune_dead, prefer=args.prefer)
+
+    dry = not args.apply
+    print("Dedupe plan (dry-run)" if dry else "Dedupe plan")
+    print("=" * 60)
+    for line in describe_plan(plan):
+        print(line)
+
+    if not plan.actions:
+        return EXIT_FINDINGS if actionable(result.findings) else EXIT_OK
+
+    if dry:
+        print("-" * 60)
+        print("Dry run: no files were changed. Re-run with --apply --yes to apply.")
+        return EXIT_FINDINGS
+
+    if not args.yes:
+        print("Refusing to apply: pass --yes to confirm you want these files rewritten.",
+              file=sys.stderr)
+        return EXIT_ERROR
+
+    backup_dir = Path(args.backup_dir).expanduser() if args.backup_dir else \
+        Path.home() / ".mcp-dedupe" / "backups"
+    removed = apply_plan(plan, result, backup_dir)
+    print("-" * 60)
+    print(f"Applied. Backups saved under {backup_dir}.")
+    for cid in sorted(removed):
+        print(f"  {cid}: removed {', '.join(sorted(removed[cid]))}")
+    return EXIT_OK
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="mcp-dedupe",
+        description="Detect duplicate / drifted / dead MCP server configs across "
+                    "Claude Desktop, Cursor, VS Code and Codex, and dedupe them.")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    p.add_argument("--home", default=None,
+                   help="Override the home directory configs are resolved from "
+                        "(useful for testing).")
+    sub = p.add_subparsers(dest="command", required=True)
+
+    s = sub.add_parser("scan", help="Scan client configs and report findings (read-only).")
+    s.add_argument("--format", choices=["text", "json"], default="text")
+    s.add_argument("--home", default=None,
+                   help="Override the home directory configs are resolved from.")
+    s.set_defaults(func=cmd_scan)
+
+    d = sub.add_parser("dedupe",
+                       help="Plan or apply dedupe of duplicated / dead servers.")
+    d.add_argument("--dry-run", action="store_true",
+                   help="Show the plan without changing files (default).")
+    d.add_argument("--apply", action="store_true",
+                   help="Rewrite config files. Requires --yes.")
+    d.add_argument("--yes", action="store_true",
+                   help="Explicit confirmation for --apply.")
+    d.add_argument("--prefer", default=None, metavar="CLIENT",
+                   help="When resolving duplicates/drift, keep this client's copy "
+                        f"({', '.join(sorted(BY_ID))}).")
+    d.add_argument("--include-drift", action="store_true",
+                   help="Also resolve drifted duplicates (same name, different config). "
+                        "Without this flag drift is reported but left untouched.")
+    d.add_argument("--prune-dead", action="store_true",
+                   help="Also remove servers whose command/cwd is a dead link.")
+    d.add_argument("--backup-dir", default=None,
+                   help="Where to store backups (default ~/.mcp-dedupe/backups).")
+    d.add_argument("--home", default=None,
+                   help="Override the home directory configs are resolved from.")
+    d.set_defaults(func=cmd_dedupe)
+    return p
+
+
+def main(argv=None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        return args.func(args)
+    except BrokenPipeError:
+        return EXIT_OK
+    except Exception as exc:  # never crash with a traceback on bad input
+        print(f"error: {exc}", file=sys.stderr)
+        return EXIT_ERROR

mcp_config_dedupe-0.1.0/mcp_dedupe/clients.py

@@ -0,0 +1,176 @@
+"""Client adapters: where each MCP client keeps its server configuration.
+
+Every adapter knows how to locate its config file(s) relative to a home
+directory, and how to extract / replace the ``{name: server-config}`` mapping.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional
+
+Servers = Dict[str, Dict[str, Any]]
+
+
+def _json_servers(doc: Any, *path: str) -> Servers:
+    """Walk a parsed JSON document to the servers mapping."""
+    node = doc
+    for key in path:
+        if not isinstance(node, dict) or key not in node:
+            return {}
+        node = node[key]
+    if not isinstance(node, dict):
+        return {}
+    return {k: v for k, v in node.items() if isinstance(v, dict)}
+
+
+def _read_json(text: str) -> Servers:
+    return _json_servers(json.loads(text), "mcpServers")
+
+
+def _write_json(servers: Servers, original_text: Optional[str]) -> str:
+    """Replace the mcpServers block, preserving sibling keys."""
+    try:
+        doc = json.loads(original_text) if original_text else {}
+    except (json.JSONDecodeError, TypeError):
+        doc = {}
+    if not isinstance(doc, dict):
+        doc = {}
+    doc["mcpServers"] = servers
+    return json.dumps(doc, indent=2, ensure_ascii=False) + "\n"
+
+
+def _read_vscode(text: str) -> Servers:
+    doc = json.loads(text)
+    # Official VS Code MCP layout: "mcp": {"servers": {...}}.
+    servers = _json_servers(doc, "mcp", "servers")
+    if servers:
+        return servers
+    # Legacy/alternate layout with a dotted key.
+    return _json_servers(doc, "mcp.servers")
+
+
+def _write_vscode(servers: Servers, original_text: Optional[str]) -> str:
+    try:
+        doc = json.loads(original_text) if original_text else {}
+    except (json.JSONDecodeError, TypeError):
+        doc = {}
+    if not isinstance(doc, dict):
+        doc = {}
+    if isinstance(doc.get("mcp"), dict):
+        doc["mcp"]["servers"] = servers
+    elif "mcp.servers" in doc:
+        doc["mcp.servers"] = servers
+    else:
+        doc.setdefault("mcp", {})["servers"] = servers
+    return json.dumps(doc, indent=2, ensure_ascii=False) + "\n"
+
+
+def _read_codex(text: str) -> Servers:
+    doc = tomllib.loads(text)
+    node = doc.get("mcp_servers", {})
+    if not isinstance(node, dict):
+        return {}
+    return {k: v for k, v in node.items() if isinstance(v, dict)}
+
+
+def _write_codex(servers: Servers, original_text: Optional[str]) -> str:
+    from . import toml_util
+
+    try:
+        doc = tomllib.loads(original_text) if original_text else {}
+    except tomllib.TOMLDecodeError:
+        doc = {}
+    if not isinstance(doc, dict):
+        doc = {}
+    doc["mcp_servers"] = servers
+    return toml_util.dumps(doc)
+
+
+class Client:
+    def __init__(
+        self,
+        client_id: str,
+        display: str,
+        relpaths: Dict[str, List[str]],
+        read_servers: Callable[[str], Servers],
+        write_servers: Callable[[Servers, Optional[str]], str],
+        fmt: str,
+    ) -> None:
+        self.id = client_id
+        self.display = display
+        self.relpaths = relpaths
+        self.read_servers = read_servers
+        self.write_servers = write_servers
+        self.fmt = fmt
+
+    def config_path(self, home: Path, platform: Optional[str] = None) -> Optional[Path]:
+        plat = platform or sys.platform
+        for rel in self.relpaths.get(plat, []):
+            p = home / rel
+            if p.is_file():
+                return p
+        # Fall back to the first candidate so callers can report "missing".
+        cands = self.relpaths.get(plat, [])
+        return home / cands[0] if cands else None
+
+
+CLIENTS: List[Client] = [
+    Client(
+        "claude-desktop",
+        "Claude Desktop",
+        {
+            "darwin": ["Library/Application Support/Claude/claude_desktop_config.json"],
+            "win32": ["AppData/Roaming/Claude/claude_desktop_config.json"],
+            "linux": [".config/Claude/claude_desktop_config.json"],
+        },
+        _read_json,
+        _write_json,
+        "json",
+    ),
+    Client(
+        "cursor",
+        "Cursor",
+        {
+            "darwin": [".cursor/mcp.json"],
+            "win32": [".cursor/mcp.json"],
+            "linux": [".cursor/mcp.json"],
+        },
+        _read_json,
+        _write_json,
+        "json",
+    ),
+    Client(
+        "vscode",
+        "VS Code",
+        {
+            "darwin": ["Library/Application Support/Code/User/settings.json"],
+            "win32": ["AppData/Roaming/Code/User/settings.json"],
+            "linux": [".config/Code/User/settings.json"],
+        },
+        _read_vscode,
+        _write_vscode,
+        "json",
+    ),
+    Client(
+        "codex",
+        "Codex CLI",
+        {
+            "darwin": [".codex/config.toml"],
+            "win32": [".codex/config.toml"],
+            "linux": [".codex/config.toml"],
+        },
+        _read_codex,
+        _write_codex,
+        "toml",
+    ),
+]
+
+BY_ID = {c.id: c for c in CLIENTS}
+
+# Priority order: the first client in this list that holds a duplicated server
+# keeps the canonical copy unless --prefer overrides it.
+PRIORITY = ["claude-desktop", "cursor", "vscode", "codex"]

mcp_config_dedupe-0.1.0/mcp_dedupe/findings.py

@@ -0,0 +1,179 @@
+"""Finding detection: duplicates, drift, dead links, and unreadable configs."""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+from .clients import BY_ID, CLIENTS, Client, Servers
+
+SEVERITIES = {"duplicate", "drift", "dead-link", "remote", "unreadable"}
+
+
+@dataclass
+class Finding:
+    kind: str  # duplicate | drift | dead-link | remote | unreadable
+    server: Optional[str]
+    clients: List[str] = field(default_factory=list)
+    detail: str = ""
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "kind": self.kind,
+            "server": self.server,
+            "clients": self.clients,
+            "detail": self.detail,
+        }
+
+
+@dataclass
+class ClientScan:
+    client: Client
+    path: Optional[Path]
+    servers: Servers
+    error: Optional[str] = None
+
+
+def canonical(server: Dict[str, Any]) -> str:
+    """Stable fingerprint of a server config for equality comparison."""
+    return json.dumps(server, sort_keys=True, ensure_ascii=False, default=str)
+
+
+def scan_client(client: Client, home: Path, platform: Optional[str] = None) -> ClientScan:
+    path = client.config_path(home, platform)
+    if path is None or not path.is_file():
+        return ClientScan(client, path, {})
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError as exc:
+        return ClientScan(client, path, {}, error=f"cannot read: {exc}")
+    try:
+        servers = client.read_servers(text)
+    except Exception as exc:  # malformed JSON/TOML
+        return ClientScan(client, path, {}, error=f"cannot parse ({client.fmt}): {exc}")
+    return ClientScan(client, path, servers)
+
+
+def _command_dead(server: Dict[str, Any]) -> Optional[str]:
+    cmd = server.get("command")
+    if not cmd or not isinstance(cmd, str):
+        return None
+    if os.path.isabs(cmd) or "/" in cmd or "\\" in cmd:
+        p = Path(cmd)
+        if not p.exists():
+            return f"command path does not exist: {cmd}"
+        if p.is_dir():
+            return f"command path is a directory: {cmd}"
+        if not os.access(p, os.X_OK):
+            return f"command path is not executable: {cmd}"
+        return None
+    if shutil.which(cmd) is None:
+        return f"command not found on PATH: {cmd}"
+    return None
+
+
+def _check_server_health(name: str, server: Dict[str, Any]) -> List[Tuple[str, str]]:
+    """Return (kind, detail) health findings for one server config."""
+    out: List[Tuple[str, str]] = []
+    if server.get("url"):
+        out.append(("remote", f"remote server ({server.get('url')}); not checked offline"))
+        return out
+    dead = _command_dead(server)
+    if dead:
+        out.append(("dead-link", dead))
+    cwd = server.get("cwd")
+    if isinstance(cwd, str) and cwd and not Path(cwd).expanduser().is_dir():
+        out.append(("dead-link", f"cwd does not exist: {cwd}"))
+    return out
+
+
+@dataclass
+class ScanResult:
+    scans: List[ClientScan]
+    findings: List[Finding]
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "clients": [
+                {
+                    "id": s.client.id,
+                    "display": s.client.display,
+                    "path": str(s.path) if s.path else None,
+                    "servers": sorted(s.servers),
+                    "error": s.error,
+                }
+                for s in self.scans
+            ],
+            "findings": [f.to_dict() for f in self.findings],
+        }
+
+
+def scan_all(home: Optional[Path] = None, platform: Optional[str] = None) -> ScanResult:
+    home = home or Path.home()
+    scans = [scan_client(c, home, platform) for c in CLIENTS]
+    findings: List[Finding] = []
+
+    for s in scans:
+        if s.error:
+            findings.append(
+                Finding("unreadable", None, [s.client.id], f"{s.path}: {s.error}")
+            )
+
+    # Group servers by name across clients.
+    by_name: Dict[str, List[Tuple[ClientScan, Dict[str, Any]]]] = {}
+    for s in scans:
+        for name, cfg in s.servers.items():
+            by_name.setdefault(name, []).append((s, cfg))
+
+    for name in sorted(by_name):
+        holders = by_name[name]
+        if len(holders) > 1:
+            fingerprints = {canonical(cfg) for _, cfg in holders}
+            client_ids = [s.client.id for s, _ in holders]
+            if len(fingerprints) == 1:
+                findings.append(
+                    Finding(
+                        "duplicate",
+                        name,
+                        client_ids,
+                        "identical config in multiple clients; safe to dedupe",
+                    )
+                )
+            else:
+                findings.append(
+                    Finding(
+                        "drift",
+                        name,
+                        client_ids,
+                        "same name but different config across clients",
+                    )
+                )
+
+    # Health checks per (client, server), grouped per server for readable output.
+    health_by_server: Dict[str, List[Tuple[str, str, str]]] = {}
+    for s in scans:
+        for name, cfg in s.servers.items():
+            for kind, detail in _check_server_health(name, cfg):
+                bucket = health_by_server.setdefault(name, [])
+                entry = (kind, detail, s.client.id)
+                if entry not in bucket:
+                    bucket.append(entry)
+    for name in sorted(health_by_server):
+        for kind, detail, client_id in health_by_server[name]:
+            # One finding per (server, kind, detail), listing every client.
+            clients = [c for k, d, c in health_by_server[name] if k == kind and d == detail]
+            findings.append(Finding(kind, name, clients, detail))
+
+    # Stable ordering: duplicates, drift, dead-link, remote, unreadable.
+    order = {"duplicate": 0, "drift": 1, "dead-link": 2, "remote": 3, "unreadable": 4}
+    findings.sort(key=lambda f: (order.get(f.kind, 9), f.server or "", f.detail))
+    return ScanResult(scans, findings)
+
+
+def actionable(findings: List[Finding]) -> List[Finding]:
+    return [f for f in findings if f.kind in ("duplicate", "drift", "dead-link", "unreadable")]

mcp_config_dedupe-0.1.0/mcp_dedupe/sync.py

@@ -0,0 +1,151 @@
+"""Dedupe planning and applying: compute what changes, back up, then write."""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Dict, List, Optional
+
+from . import clients as clients_mod
+from .clients import Client, Servers
+from .findings import Finding, ScanResult, canonical
+
+
+@dataclass
+class Action:
+    client: Client
+    path: Path
+    server: str
+    action: str  # "remove"
+    reason: str
+
+
+@dataclass
+class Plan:
+    actions: List[Action] = field(default_factory=list)
+    skipped: List[str] = field(default_factory=list)
+
+    def removals_by_client(self) -> Dict[str, List[str]]:
+        out: Dict[str, List[str]] = {}
+        for a in self.actions:
+            out.setdefault(a.client.id, []).append(a.server)
+        return out
+
+
+def _keeper_first(client_ids: List[str], prefer: Optional[str]) -> List[str]:
+    ordered = list(client_ids)
+    if prefer and prefer in ordered:
+        ordered.remove(prefer)
+        ordered.insert(0, prefer)
+        return ordered
+    prio = clients_mod.PRIORITY
+    return sorted(ordered, key=lambda c: prio.index(c) if c in prio else 99)
+
+
+def build_plan(
+    result: ScanResult,
+    include_drift: bool = False,
+    prune_dead: bool = False,
+    prefer: Optional[str] = None,
+) -> Plan:
+    plan = Plan()
+
+    # Map (client_id, server) -> (scan, config) for quick lookup.
+    configs: Dict[tuple, Dict] = {}
+    for s in result.scans:
+        for name, cfg in s.servers.items():
+            configs[(s.client.id, name)] = cfg
+
+    for f in result.findings:
+        if f.kind == "duplicate":
+            keepers = _keeper_first(f.clients, prefer)
+            keep = keepers[0]
+            for cid in keepers[1:]:
+                scan = next(s for s in result.scans if s.client.id == cid)
+                plan.actions.append(
+                    Action(scan.client, scan.path, f.server, "remove",
+                           f"identical duplicate; keeping copy in {keep}")
+                )
+        elif f.kind == "drift":
+            if include_drift:
+                keepers = _keeper_first(f.clients, prefer)
+                keep = keepers[0]
+                for cid in keepers[1:]:
+                    scan = next(s for s in result.scans if s.client.id == cid)
+                    plan.actions.append(
+                        Action(scan.client, scan.path, f.server, "remove",
+                               f"drifted duplicate; keeping {keep}'s config")
+                    )
+            else:
+                plan.skipped.append(
+                    f"drift '{f.server}' in {', '.join(f.clients)}: "
+                    "skipped (re-run with --include-drift to resolve)"
+                )
+        elif f.kind == "dead-link" and prune_dead:
+            for cid in f.clients:
+                # Don't double-plan a removal for the same (client, server).
+                if any(a.client.id == cid and a.server == f.server for a in plan.actions):
+                    continue
+                scan = next(s for s in result.scans if s.client.id == cid)
+                plan.actions.append(
+                    Action(scan.client, scan.path, f.server, "remove",
+                           f"dead link: {f.detail}")
+                )
+    return plan
+
+
+def backup_configs(paths: List[Path], backup_dir: Path) -> Path:
+    """Copy each config file into a timestamped backup directory."""
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    dest = backup_dir / stamp
+    dest.mkdir(parents=True, exist_ok=True)
+    for p in paths:
+        if p and p.is_file():
+            target = dest / (p.name + ".bak")
+            shutil.copy2(p, target)
+    return dest
+
+
+def apply_plan(plan: Plan, result: ScanResult, backup_dir: Path) -> Dict[str, List[str]]:
+    """Apply removals. Returns {client_id: [removed server names]}.
+
+    Backs up every touched config file first. Only JSON/TOML clients that
+    parsed cleanly are rewritten; anything else is left untouched.
+    """
+    touched = sorted({a.path for a in plan.actions if a.path})
+    backup_configs(touched, backup_dir)
+
+    # Reload each touched file fresh so we never write stale data.
+    removed: Dict[str, List[str]] = {}
+    by_path: Dict[Path, List[Action]] = {}
+    for a in plan.actions:
+        by_path.setdefault(a.path, []).append(a)
+
+    for path, actions in by_path.items():
+        client = actions[0].client
+        original = path.read_text(encoding="utf-8")
+        servers = client.read_servers(original)
+        for a in actions:
+            if a.server in servers:
+                del servers[a.server]
+                removed.setdefault(client.id, []).append(a.server)
+        path.write_text(client.write_servers(servers, original), encoding="utf-8")
+    return removed
+
+
+def describe_plan(plan: Plan) -> List[str]:
+    lines: List[str] = []
+    if not plan.actions and not plan.skipped:
+        lines.append("Nothing to dedupe: no duplicates or dead links found.")
+        return lines
+    for client_id in sorted(plan.removals_by_client()):
+        names = sorted(plan.removals_by_client()[client_id])
+        lines.append(f"  {client_id}: remove {', '.join(names)}")
+        for a in plan.actions:
+            if a.client.id == client_id:
+                lines.append(f"    - {a.server}: {a.reason}")
+    for s in plan.skipped:
+        lines.append(f"  SKIP: {s}")
+    return lines

mcp_config_dedupe-0.1.0/mcp_dedupe/toml_util.py

@@ -0,0 +1,86 @@
+"""Minimal TOML emitter (stdlib-only: tomllib can parse but not write).
+
+Covers the value shapes that appear in MCP client configs: strings, bools,
+ints, floats, lists of scalars, nested tables, and arrays of tables. Anything
+else raises a clear error so we never silently corrupt a config file.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List
+
+
+def _scalar(value: Any) -> str:
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, int):
+        return str(value)
+    if isinstance(value, float):
+        return repr(value)
+    if isinstance(value, str):
+        escaped = value.replace("\\", "\\\\").replace('"', '\\"')
+        escaped = escaped.replace("\n", "\\n").replace("\t", "\\t")
+        return f'"{escaped}"'
+    raise ValueError(f"unsupported TOML value: {type(value).__name__} ({value!r})")
+
+
+def _is_table(value: Any) -> bool:
+    return isinstance(value, dict)
+
+
+def _is_table_array(value: Any) -> bool:
+    return isinstance(value, list) and bool(value) and all(isinstance(v, dict) for v in value)
+
+
+def _is_scalar_list(value: Any) -> bool:
+    return isinstance(value, list) and all(
+        isinstance(v, (str, bool, int, float)) for v in value
+    )
+
+
+def dumps(doc: Dict[str, Any]) -> str:
+    lines: List[str] = []
+
+    def emit_table(path: List[str], table: Dict[str, Any]) -> None:
+        # Scalar / scalar-list keys first, then subtables, then table arrays.
+        for key in sorted(table):
+            value = table[key]
+            if _is_table(value) or _is_table_array(value):
+                continue
+            if isinstance(value, list) and not _is_scalar_list(value):
+                raise ValueError(f"unsupported TOML value for key {key!r}: {value!r}")
+            lines.append(f"{key} = {_scalar(value) if not isinstance(value, list) else '[' + ', '.join(_scalar(v) for v in value) + ']'}")
+        for key in sorted(table):
+            value = table[key]
+            if _is_table(value):
+                lines.append("")
+                lines.append(f"[{'.'.join(path + [key])}]")
+                emit_table(path + [key], value)
+        for key in sorted(table):
+            value = table[key]
+            if _is_table_array(value):
+                for item in value:
+                    lines.append("")
+                    lines.append(f"[[{'.'.join(path + [key])}]]")
+                    emit_table(path + [key], item)
+
+    top_scalars = {k: v for k, v in doc.items() if not _is_table(v) and not _is_table_array(v)}
+    for key in sorted(top_scalars):
+        value = top_scalars[key]
+        if isinstance(value, list) and not _is_scalar_list(value):
+            raise ValueError(f"unsupported TOML value for key {key!r}")
+        lines.append(f"{key} = {_scalar(value) if not isinstance(value, list) else '[' + ', '.join(_scalar(v) for v in value) + ']'}")
+    for key in sorted(doc):
+        value = doc[key]
+        if _is_table(value):
+            lines.append("")
+            lines.append(f"[{key}]")
+            emit_table([key], value)
+    for key in sorted(doc):
+        value = doc[key]
+        if _is_table_array(value):
+            for item in value:
+                lines.append("")
+                lines.append(f"[[{key}]]")
+                emit_table([key], item)
+    return "\n".join(lines).strip() + "\n"

mcp_config_dedupe-0.1.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-config-dedupe"
+version = "0.1.0"
+description = "Detect duplicate, drifted, and dead MCP server configs across clients — and dedupe them in one command"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "hao li", email = "haoli5933@gmail.com" }]
+keywords = ["mcp", "model-context-protocol", "config", "dedupe", "claude", "cursor", "vscode", "codex"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: System :: Systems Administration",
+    "Topic :: Utilities",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/hahahahahahahahah6/mcp-config-dedupe"
+Issues = "https://github.com/hahahahahahahahah6/mcp-config-dedupe/issues"
+
+[project.scripts]
+mcp-dedupe = "mcp_dedupe.cli:main"
+
+[tool.setuptools.packages.find]
+include = ["mcp_dedupe*"]

mcp_config_dedupe-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_config_dedupe-0.1.0/tests/test_dedupe.py

@@ -0,0 +1,233 @@
+"""Smoke tests for mcp-dedupe. Run with: python3 -m unittest discover -s tests -v"""
+
+import json
+import os
+import shutil
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent))
+
+from mcp_dedupe.cli import main as cli_main
+from mcp_dedupe.findings import scan_all
+from mcp_dedupe.sync import apply_plan, build_plan
+
+FS_SERVER = {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]}
+BRAVE_A = {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search"]}
+BRAVE_B = {"command": "npx", "args": ["-y", "@modelcontextprotocol/server-brave-search", "--other"]}
+FETCH_A = {"command": "uvx", "args": ["mcp-server-fetch"]}
+FETCH_B = {"command": "uvx", "args": ["mcp-server-fetch", "--verbose"]}
+DEAD_SERVER = {"command": "definitely-not-a-real-command-xyz-123"}
+REMOTE_SERVER = {"url": "https://example.com/mcp"}
+
+
+def write(path: Path, content: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content, encoding="utf-8")
+
+
+def json_config(servers: dict) -> str:
+    return json.dumps({"mcpServers": servers}, indent=2)
+
+
+def make_home(base: Path, files: dict) -> Path:
+    home = base / "home"
+    for rel, content in files.items():
+        write(home / rel, content)
+    return home
+
+
+class ScanTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.tmp, True)
+
+    def test_identical_duplicate_detected(self):
+        home = make_home(self.tmp, {
+            ".config/Claude/claude_desktop_config.json": json_config({"filesystem": FS_SERVER}),
+            ".cursor/mcp.json": json_config({"filesystem": FS_SERVER}),
+        })
+        result = scan_all(home=home)
+        dups = [f for f in result.findings if f.kind == "duplicate"]
+        self.assertEqual(len(dups), 1)
+        self.assertEqual(dups[0].server, "filesystem")
+        self.assertEqual(sorted(dups[0].clients), ["claude-desktop", "cursor"])
+
+    def test_drift_detected(self):
+        home = make_home(self.tmp, {
+            ".config/Claude/claude_desktop_config.json": json_config({"brave": BRAVE_A}),
+            ".cursor/mcp.json": json_config({"brave": BRAVE_B}),
+        })
+        result = scan_all(home=home)
+        drifts = [f for f in result.findings if f.kind == "drift"]
+        self.assertEqual(len(drifts), 1)
+        self.assertEqual(drifts[0].server, "brave")
+
+    def test_dead_link_command_not_found(self):
+        home = make_home(self.tmp, {
+            ".cursor/mcp.json": json_config({"oldtool": DEAD_SERVER}),
+        })
+        result = scan_all(home=home)
+        dead = [f for f in result.findings if f.kind == "dead-link"]
+        self.assertEqual(len(dead), 1)
+        self.assertEqual(dead[0].server, "oldtool")
+        self.assertIn("not found", dead[0].detail)
+
+    def test_dead_link_absolute_path(self):
+        home = make_home(self.tmp, {
+            ".cursor/mcp.json": json_config(
+                {"local": {"command": "/nonexistent/bin/server"}}),
+        })
+        result = scan_all(home=home)
+        dead = [f for f in result.findings if f.kind == "dead-link"]
+        self.assertEqual(len(dead), 1)
+        self.assertIn("does not exist", dead[0].detail)
+
+    def test_remote_url_not_flagged_dead(self):
+        home = make_home(self.tmp, {
+            ".cursor/mcp.json": json_config({"web": REMOTE_SERVER}),
+        })
+        result = scan_all(home=home)
+        dead = [f for f in result.findings if f.kind == "dead-link"]
+        self.assertEqual(dead, [])
+        remote = [f for f in result.findings if f.kind == "remote"]
+        self.assertEqual(len(remote), 1)
+
+    def test_malformed_config_reported(self):
+        home = make_home(self.tmp, {
+            ".cursor/mcp.json": "{not valid json",
+        })
+        result = scan_all(home=home)
+        bad = [f for f in result.findings if f.kind == "unreadable"]
+        self.assertEqual(len(bad), 1)
+        self.assertEqual(bad[0].clients, ["cursor"])
+
+    def test_vscode_nested_layout_parsed(self):
+        home = make_home(self.tmp, {
+            ".config/Code/User/settings.json": json.dumps(
+                {"editor.fontSize": 14, "mcp": {"servers": {"filesystem": FS_SERVER}}}),
+        })
+        result = scan_all(home=home)
+        scan = next(s for s in result.scans if s.client.id == "vscode")
+        self.assertEqual(list(scan.servers), ["filesystem"])
+
+    def test_codex_toml_parsed(self):
+        home = make_home(self.tmp, {
+            ".codex/config.toml": (
+                'model = "gpt-5"\n\n[mcp_servers.filesystem]\n'
+                'command = "npx"\nargs = ["-y", "srv"]\n'
+            ),
+        })
+        result = scan_all(home=home)
+        scan = next(s for s in result.scans if s.client.id == "codex")
+        self.assertEqual(list(scan.servers), ["filesystem"])
+        self.assertEqual(scan.servers["filesystem"]["command"], "npx")
+
+    def test_scan_json_output(self):
+        home = make_home(self.tmp, {
+            ".cursor/mcp.json": json_config({"oldtool": DEAD_SERVER}),
+        })
+        proc = subprocess.run(
+            [sys.executable, "-m", "mcp_dedupe", "scan", "--format", "json",
+             "--home", str(home)],
+            capture_output=True, text=True, cwd=str(Path(__file__).resolve().parent.parent),
+        )
+        self.assertEqual(proc.returncode, 1)  # findings present
+        data = json.loads(proc.stdout)
+        kinds = {f["kind"] for f in data["findings"]}
+        self.assertIn("dead-link", kinds)
+
+
+class DedupeTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp())
+        self.addCleanup(shutil.rmtree, self.tmp, True)
+        self.backup = self.tmp / "backups"
+
+    def _home(self):
+        return make_home(self.tmp, {
+            # "filesystem": identical in 3 clients -> duplicate
+            ".config/Claude/claude_desktop_config.json":
+                json_config({"filesystem": FS_SERVER, "brave": BRAVE_A}),
+            ".cursor/mcp.json":
+                json_config({"filesystem": FS_SERVER, "oldtool": DEAD_SERVER}),
+            # "fetch": same name, different config -> drift
+            ".codex/config.toml":
+                '[mcp_servers.filesystem]\ncommand = "npx"\n'
+                'args = ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]\n'
+                '\n[mcp_servers.fetch]\ncommand = "uvx"\nargs = ["mcp-server-fetch"]\n',
+            ".config/Code/User/settings.json": json.dumps(
+                {"mcp": {"servers": {"fetch": FETCH_B}}}),
+        })
+
+    def test_dry_run_writes_nothing(self):
+        home = self._home()
+        before = {str(p): p.read_bytes() for p in home.rglob("*") if p.is_file()}
+        result = scan_all(home=home)
+        plan = build_plan(result)
+        self.assertTrue(plan.actions)  # there is work to do...
+        # ...but a dry run must not touch anything. Just don't call apply_plan.
+        after = {str(p): p.read_bytes() for p in home.rglob("*") if p.is_file()}
+        self.assertEqual(before, after)
+
+    def test_apply_removes_duplicates_and_backs_up(self):
+        home = self._home()
+        result = scan_all(home=home)
+        plan = build_plan(result)  # drift + dead-link excluded by default
+        removed = apply_plan(plan, result, self.backup)
+        # identical duplicate: claude-desktop keeps (priority), cursor+codex lose it
+        self.assertEqual(removed.get("cursor"), ["filesystem"])
+        self.assertEqual(removed.get("codex"), ["filesystem"])
+        self.assertNotIn("claude-desktop", removed)
+        cursor_cfg = json.loads((home / ".cursor/mcp.json").read_text())
+        self.assertNotIn("filesystem", cursor_cfg["mcpServers"])
+        self.assertIn("oldtool", cursor_cfg["mcpServers"])  # dead kept: no --prune-dead
+        # backup exists
+        backups = list(self.backup.rglob("*.bak"))
+        self.assertTrue(backups)
+        # drift untouched by default
+        codex_text = (home / ".codex/config.toml").read_text()
+        self.assertIn("mcp-server-fetch", codex_text)
+
+    def test_apply_requires_explicit_yes(self):
+        home = self._home()
+        proc = subprocess.run(
+            [sys.executable, "-m", "mcp_dedupe", "dedupe", "--apply",
+             "--home", str(home)],
+            capture_output=True, text=True, cwd=str(Path(__file__).resolve().parent.parent),
+        )
+        self.assertEqual(proc.returncode, 2)
+        self.assertIn("--yes", proc.stderr + proc.stdout)
+        # nothing changed
+        cursor_cfg = json.loads((home / ".cursor/mcp.json").read_text())
+        self.assertIn("filesystem", cursor_cfg["mcpServers"])
+
+    def test_drift_resolved_with_include_drift_and_prefer(self):
+        home = self._home()
+        result = scan_all(home=home)
+        plain = build_plan(result)
+        self.assertTrue(any("drift" in s for s in plain.skipped))
+        plan = build_plan(result, include_drift=True, prefer="vscode")
+        removed = apply_plan(plan, result, self.backup)
+        # vscode preferred: its "fetch" survives, codex's copy removed
+        self.assertIn("fetch", removed.get("codex", []))
+        vscode_cfg = json.loads((home / ".config/Code/User/settings.json").read_text())
+        self.assertIn("fetch", vscode_cfg["mcp"]["servers"])
+        codex_text = (home / ".codex/config.toml").read_text()
+        self.assertNotIn("[mcp_servers.fetch]", codex_text)
+
+    def test_prune_dead_removes_dead_servers(self):
+        home = self._home()
+        result = scan_all(home=home)
+        plan = build_plan(result, prune_dead=True)
+        removed = apply_plan(plan, result, self.backup)
+        self.assertIn("oldtool", removed.get("cursor", []))
+        cursor_cfg = json.loads((home / ".cursor/mcp.json").read_text())
+        self.assertNotIn("oldtool", cursor_cfg["mcpServers"])
+
+
+if __name__ == "__main__":
+    unittest.main()