[Dumbris]

Summary

Experiment E4 (Q4 2026 promotion strategy), phase 1: spec only, no implementation. Adds specs/120-mcp-router-import/ (research, spec, clarifications, plan, data model, contracts, quickstart, tasks) for mcpproxy import --from mcp-router [--path <file>] [--dry-run]. MCP Router (2,135 stars) was archived 2026-09-18 with "new adoption is not recommended".

(Spec number: first drafted as 119, renumbered to 120 on 2026-10-25 because 119-scan-default-trust landed on main; 121 is already a remote branch. Telemetry schema is v16 on main now, so the planned bump is the next free version, 17, re-checked at implementation time.)

Format check verdict: importable

Source: mcp-router/mcp-router @ 7d6cd4e5e7e73ef54b938c29d14e0cab64850fae (final, v0.6.4). Full detail with file paths and per-file SHAs in research.md.

• Storage: SQLite mcprouter.db in Electron userData (macOS ~/Library/Application Support/MCP Router, Windows %APPDATA%\MCP Router; no official Linux build). Default workspace uses mcprouter.db; extra local workspaces use workspaces/<id>/database.db. WAL mode.
• Schema: servers table (command, args, env, server_type local|remote|remote-streamable, remote_url, bearer_token, disabled, auto_start, tool_permissions, input_params, project_id, ...). Columns were added by migrations, so old DBs lack some.
• Secrets: env is plaintext; bearer_token is encrypted by Electron safeStorage (mcpr-secret:v1: prefix). The importer never decrypts it. Remote auth is bearer-only, no OAuth.
• Export button writes {"mcpServers":{name:{command,args,env}}} (Claude-Desktop shaped, so upstream import already parses it) but is lossy: remote servers become empty-command stdio entries; disabled flags, tool toggles, tokens and other workspaces are dropped. .dxt import only; no .mcpb, no DXT export.
• Clients: MCP Router writes one mcp-router entry (npx -y @mcp_router/cli@latest connect, MCPR_TOKEN) into Claude Desktop, Cursor, Windsurf, VS Code, Codex, Cline. The importer detects them read-only and prints mcpproxy connect <client> (Cline has no MCPProxy connector).
• The format is frozen (archived), so one reader covers every real database.

Repo hygiene note: the cloned MCP Router repo's CLAUDE.md contains instructions addressed to AI agents; treated as data, not followed.

What the spec decides

• New top-level import command; upstream import untouched (its daemon mode drops Enabled and swallows add errors: recorded as a follow-up).
• Reads the DB directly (the export loses remote servers), via a verified private snapshot (os.Root containment, descriptor identity checks, bounded retries), plus the export file as a secondary input.
• Quarantine always set; secret-like values go to the OS keyring with one confirmation (--yes, --secrets-inline named opt-in); output built from a value-free DTO with fixed masks; source ${...} text is never given destination-secret semantics; deterministic hashed keyring refs, restore-on-rollback, no rollback on uncertain adds.
• Idempotent re-runs with defined comparison fields; conflict reports name fields, never values.
• Telemetry: closed-enum import_source_counts (the next schema version), recorded by the daemon through a service-owned, event-time-gated call; endpoint POST /api/v1/servers/import/report. Target: >= 25 runs by day 60.
• Web UI entry is P3, non-gating, last in the task order.

Decisions to look at (made under the zero-interruption policy)

1. New dependency modernc.org/sqlite (pure Go). Measured +6.9 MB unstripped on a hello-world (current mcpproxy is 46.9 MB). Task T003 re-measures stripped release builds on 3 platforms and falls back to export-file-only behind a build tag if any delta exceeds 10 MB.
2. macOS keyring gate: outside the tray, internal/secret refuses keyring writes unless MCPPROXY_KEYRING_WRITE=1. MCP Router users are mostly macOS with API keys in env, so a plain-terminal first run stops with a message naming the exact remedy. The importer does not override the gate. Funnel impact is a known risk; follow-up listed.
3. Daemonless runs are not counted in telemetry (documented undercount).
4. RefName's collision-suffixing is deliberately not used (idempotent repair needs deterministic refs).

Cross-model review (opencode github-copilot/gpt-6.1-sol, high; transcripts in the shared notes folder)

Artifact	Round	Verdict	Outcome
spec.md	1	ISSUES (3 P1, 14 P2, 2 P3)	all addressed: reference-syntax injection, DB path containment, placeholder secret laundering, snapshot protocol, exit matrix, telemetry ownership/opt-out, quarantine wording, Web UI made non-gating, etc.
spec.md	2	ISSUES (0 P1, 5 P2, 0 P3)	all addressed (WAL sidecar allowlist, placeholder precedence verified against MCP Router source, name-based default classification, rollback limits, SC-008 equivalence)
plan.md (+ data model, contracts, quickstart)	1	ISSUES (5 P1, 15 P2, 2 P3)	all addressed (os.Root containment, hashed refs with restore, value-free DTO, uncertain-add handling, lock + reload file sink, tri-state daemon probe, service-owned telemetry call, etc.)
plan.md	2	ISSUES (3 P1, 3 P2, 0 P3)	all addressed (import lock across the whole apply phase, no compensation without a definite rejection, env-sourced sensitive provenance, GetServers read-back, name-independent keyring comparison, URL masking)

Not re-reviewed after the last round's fixes, and tasks.md itself was not sent to Sol (two rounds per document, well under the 10-round cap). Findings were verified against the repo before applying (for example the placeholder precedence and the macOS keyring gate were confirmed in source).

Next

Implementation per tasks.md: PR-A read-only command (T001-T025), PR-B apply + secrets + idempotency, PR-C telemetry v15, PR-D report/export/docs, PR-E optional Web UI. The marketing migration page (other session) should wait for handoff-website.md (task T059) so it matches the shipped flags.

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying mcpproxy-docs with    Cloudflare Pages

Latest commit:	62f2255
Status:	✅  Deploy successful!
Preview URL:	https://7a38ffa2.mcpproxy-docs.pages.dev
Branch Preview URL:	https://claude-spec-mcp-router-impor.mcpproxy-docs.pages.dev

View logs

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[github-actions]

📦 Build Artifacts

Workflow Run: View Run
Branch: claude/spec-mcp-router-import-7ae3fb

Available Artifacts

• archive-darwin-amd64 (32 MB)
• archive-darwin-arm64 (29 MB)
• archive-linux-amd64 (19 MB)
• archive-linux-arm64 (17 MB)
• archive-windows-amd64 (32 MB)
• archive-windows-arm64 (28 MB)
• frontend-dist-pr (0 MB)
• installer-dmg-darwin-amd64 (28 MB)
• installer-dmg-darwin-arm64 (25 MB)
• smart-mcp-proxymcpproxy-goKETE3Y.dockerbuild (0 MB)

How to Download

Option 1: GitHub Web UI (easiest)

1. Go to the workflow run page linked above
2. Scroll to the bottom "Artifacts" section
3. Click on the artifact you want to download

Option 2: GitHub CLI

gh run download 40173268097 --repo smart-mcp-proxy/mcpproxy-go

Note: Artifacts expire in 14 days.