[aterga]

Summary

Stage 3 of the local-deployment design (docs merged in #148, Stage 1 in #77; stacked on Stage 2 in #150 — merge that first, GitHub retargets this PR automatically): the polish stage — the setup end-user registration command (component 9), the PocketIC end-to-end test of the real login flow (component 3 / Verification), and the dist release pipeline with provenance attestations (components 9/10), plus the crate README with the wallet-grade trust note (component 8).

Related issues

Implements Implementation Stages → Stage 3 of the design docs merged in #148.

Changes

• imcp2-local setup — one command, no JSON/TOML editing for the user:
  • Detects installed clients and writes each one's own registration: Claude Desktop / Cursor / Antigravity (mcpServers JSON, other keys preserved), Codex (~/.codex/config.toml via toml_edit, comments and formatting preserved), Claude Code (via its own claude mcp add --scope user, which owns that config), Perplexity macOS (UI-only; the steps + JSON to paste are printed).
  • setup --remove undoes exactly those registrations; setup --print only shows the steps; corrupt configs are refused, never overwritten; the first modification of an existing file keeps a one-time .imcp2-bak backup.
  • The binary also grows --help/--version; serving stays the bare no-argument path client registrations invoke.
• PocketIC end-to-end login (src/e2e_local_login.rs, feature e2e + optional pocket-ic, mirroring the hosted harness's gating): a live II canister issues a genuine canister-signed registration delegation; the login driver binds its real loopback listener; the test plays the browser over real HTTP (pinned page, #4091 allow-list fetch, redeem POST); the driver redeems via mcp_register_v2 on the live II — asserting {"done": true}, the filled session slot, signed-in status with the real principal, "already signed in" on a repeat authenticate, and listener teardown.
• Release pipeline — dist (cargo-dist 0.31, the ICP CLI's setup): dist-workspace.toml + the generated .github/workflows/imcp2-local-release.yml; five targets (macOS arm64/x64, Linux x64/arm64, Windows x64), shell/PowerShell installers, install-updater = true (one imcp2-local-update upgrades in place), GitHub artifact attestations on every artifact, pinned action SHAs. Tag namespaces stay separate: releases announce only on imcp2-local-v* tags, so the plain v* namespace remains the crates.io publish trigger and a crate release never implicitly ships binaries.
• crates/imcp2-local/README.md — install, per-client registration, signing in, upgrading, configuration, the wallet-grade security note, and download verification (gh attestation verify … -R dfinity/imcp2).

Deliberately not in this PR (with the design's own reasoning):

• Apple/Windows code signing + the .mcpb bundle: both need the organization's signing credentials (Apple Developer ID + notarization; Azure Trusted Signing) — the design notes Gatekeeper checks the binary inside an .mcpb, so shipping the bundle before signing exists would produce exactly the blocked double-click the design warns about. The acquisition list and the pipeline hook points are in component 10; until then the installer channels (not subject to the OS gates) are the supported path.
• The real-browser compatibility gate (automated Chromium/Firefox + manual Safari) and optional keychain persistence remain follow-ups.

Testing

• cargo build --workspace --all-targets / cargo test --workspace --all-targets — 225 passed, 0 failed (imcp2-local now 16: 5 new setup tests covering the apply→remove round-trip with foreign-key/comment preservation, skip-not-invent detection, print-only mode, corrupt-config refusal, first-run-only backups)
• The PocketIC e2e was actually run and passes (pocket-ic server 15.0.0 + II release-2026-07-17): the full local login against a live II canister in ~3.8s — and the hosted e2e passes with the same artifacts as a cross-check
• setup exercised live in this container: --print, apply against a scratch home (correct skips, real claude mcp add execution honoring $HOME, "already exists" refusal surfaced cleanly)
• dist plan --tag imcp2-local-v0.2.0 plans the full matrix; a real dist build of the Linux artifact produced the archive + updater companion + checksum, and the packaged binary runs
• cargo check --features e2e --all-targets for both crates; cargo fmt clean on the new files; internal-identifier scan clean over the whole range
• The generated release workflow triggers only on imcp2-local* version tags (verified pattern), so existing v* crate publishes are unaffected

Checklist

• I have read the Contributing guidelines.
• Docs: crates/imcp2-local/README.md added; the design docs (Design docs: IMCP2 local deployment (minimal stdio binary, no OAuth) #148) describe this stage.
• No secrets, credentials, or internal-only information are included.

---

🤖 Generated with Claude Code

https://claude.ai/code/session_01AqNkpMQiQHzYxC2djTfvBK

---

Generated by Claude Code

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 5 comments.

Suppressed comments (3)

crates/imcp2-local/src/setup.rs:468

• A first invocation of setup --remove can modify an existing JSON config without creating the promised one-time backup; backup_once is called only by the apply path. Create the backup before this write so removal cannot delete a pre-existing imcp2 registration without a recovery copy.

    std::fs::write(path, format!("{:#}\n", root))
        .with_context(|| format!("write {}", path.display()))?;

crates/imcp2-local/src/setup.rs:550

• The Codex removal path also skips backup_once, so running setup --remove before apply deletes an existing table without the backup promised for the first config modification. Back up the parsed file immediately before writing the removal.

    std::fs::write(path, doc.to_string()).with_context(|| format!("write {}", path.display()))?;

.github/workflows/imcp2-local-release.yml:206

• The global artifacts produced here (installers and checksums) are uploaded and released, but only build-local-artifacts has an attestation step. This contradicts the PR's claim of attestations on every artifact. Either grant this job id-token/attestations permissions and attest its upload files, or narrow the release guarantee to platform archives.

      - id: cargo-dist
        shell: bash
        run: |
          dist build ${{ needs.plan.outputs.tag-flag }} --output-format=json "--artifacts=global" > dist-manifest.json

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

Suppressed comments (7)

Previously missed (2) — in code that hasn't changed since the last review.

crates/imcp2-local/src/setup.rs:89

• A non-UTF-8 executable path is accepted here, but every generated registration later uses display()/to_string_lossy(), replacing bytes with U+FFFD and registering a nonexistent command while reporting success. Reject paths that cannot be represented as UTF-8 before constructing Env.

        let exe = exe.canonicalize().unwrap_or(exe);

crates/imcp2-local/README.md:37

• --remove does not necessarily “undo exactly” what setup added: it intentionally removes the reserved imcp2 entry by name even if that entry predated setup or was later changed, and it does not restore the backup. Describe the name-keyed removal semantics so users do not mistake this for exact restoration.

imcp2-local setup --remove   # undo exactly that

.github/workflows/imcp2-local-release.yml:18

• The workflow grants contents: write to every job, including the PR/tag planning job that executes a downloaded installer and repository-controlled dist configuration. Only the publishing job should receive release-write authority; default the workflow to contents: read and grant contents: write explicitly to host.

permissions:
  "contents": "write"

crates/imcp2-local/src/setup.rs:457

• This truncates the live client config in place. A crash or write failure can leave invalid JSON (and newly created files have no backup); a concurrent client read can also observe partial content. Serialize to a sibling temporary file and atomically replace the destination, and use the same persistence helper in the JSON removal and both TOML paths.

    std::fs::write(path, format!("{:#}\n", root))
        .with_context(|| format!("write {}", path.display()))?;

crates/imcp2-local/src/setup.rs:483

• The removal path also truncates the live JSON config in place, so interruption can leave the client unable to parse any of its registrations. Use the same cross-platform atomic replacement helper as the apply path.

    std::fs::write(path, format!("{:#}\n", root))
        .with_context(|| format!("write {}", path.display()))?;

crates/imcp2-local/src/setup.rs:537

• The Codex apply path truncates config.toml in place, so a crash or write failure can corrupt the user's entire Codex configuration. Persist through the same sibling-temp-and-atomic-replace helper as the JSON paths.

    std::fs::write(path, doc.to_string()).with_context(|| format!("write {}", path.display()))?;

crates/imcp2-local/src/setup.rs:570

• The Codex removal path likewise truncates the live TOML file in place and can leave it partially written. Route this write through the shared atomic replacement helper as well.

    std::fs::write(path, doc.to_string()).with_context(|| format!("write {}", path.display()))?;

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

crates/imcp2-local/README.md:113

• The release matrix includes Windows, whose cargo-dist archive is a .zip, so this .tar.xz command cannot verify the Windows download. Use a format-neutral placeholder (or show both extensions) so every documented platform can follow the verification instructions.

gh attestation verify imcp2-local-<target>.tar.xz -R dfinity/imcp2 \
  --signer-workflow dfinity/imcp2/.github/workflows/imcp2-local-release.yml

crates/imcp2-local/src/setup.rs:557

• A valid Codex entry written as an inline table ([mcp_servers] imcp2 = { command = "...", args = [...] }) is not returned by as_table_mut(), so this branch replaces the whole entry and silently drops args, env, and other settings. Handle both regular and inline TOML tables when updating command.

    match servers.get_mut(SERVER_NAME).and_then(|i| i.as_table_mut()) {
        Some(entry) => {
            entry.insert("command", toml_edit::value(exe.to_string_lossy().as_ref()));
        }

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 1 comment.

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

crates/imcp2-local/src/setup.rs:46

• Because each flag overwrites mode, setup --print --remove removes registrations even though --print promises that nothing is written and the usage marks these options as mutually exclusive. Reject conflicting modes instead of letting the last flag win.

            "--remove" => mode = Mode::Remove,
            "--print" => mode = Mode::Print,

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

crates/imcp2-local/src/setup.rs:490

• When retargeting an existing entry, preserving args can leave this registration unusable. imcp2-local serves only with no arguments, so arguments from a previous command are passed to the new binary and make main reject them as unknown. Remove the owned invocation's stale args field while retaining compatible additions such as env.

This issue also appears on line 572 of the same file.

            entry.insert(
                "command".to_string(),
                serde_json::Value::from(exe.to_string_lossy().as_ref()),
            );

crates/imcp2-local/src/setup.rs:516

• Apply mode explicitly treats an empty JSON config as an empty object, but remove mode parses the same file as JSON and fails. Thus setup --remove reports a failure even though an empty config cannot contain the registration. Handle blank content as the same clean “nothing to remove” case used for a missing file.

    let text = std::fs::read_to_string(path).with_context(|| format!("read {}", path.display()))?;
    let mut root: serde_json::Value = serde_json::from_str(&text)
        .with_context(|| format!("{} is not valid JSON", path.display()))?;

crates/imcp2-local/src/setup.rs:576

• The Codex merge likewise preserves a prior server's args. After changing command to imcp2-local, Codex will still launch it with those arguments, but this binary only serves on its no-argument path and exits on any unknown argument. Clear args in both regular and inline tables when retargeting the entry.

            if let Some(entry) = item.as_table_mut() {
                entry.insert("command", toml_edit::value(exe_text.as_ref()));
                true
            } else if let Some(entry) = item.as_inline_table_mut() {
                entry.insert("command", toml_edit::Value::from(exe_text.as_ref()));

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 8 out of 9 changed files in this pull request and generated no new comments.

Suppressed comments (3)

Previously missed (2) — in code that hasn't changed since the last review.

crates/imcp2-local/src/setup.rs:133

• is_file() also accepts non-executable PATH entries. On Unix, a stale non-executable codex file is treated as an installation; its probe then fails and this command falls back to creating ~/.codex/config.toml, while the equivalent Claude case reports a registration failure. Filter extensionless PATH candidates by executable permission before returning them.

        let candidate = dir.join(name);
        if candidate.is_file() {
            return Some(candidate);

crates/imcp2-local/src/setup.rs:408

• This misses a valid per-user macOS installation in ~/Applications/Perplexity.app, so an installed client is reported as absent and its connector instructions are omitted in apply mode. Check both the system and per-user Applications directories.

            target: if env.applications_dir.join("Perplexity.app").exists() {
                Target::Manual
            } else {
                Target::NotDetected("Perplexity.app is not in /Applications".into())

crates/imcp2-local/src/setup.rs:512

• This preserves only the metadata represented by std::fs::Permissions; on Windows that is just the read-only flag, not the file's DACL. Because the temporary file inherits the directory ACL and then replaces the destination, an existing config with a restricted ACL can become accessible to additional users even though MCP configs may contain API keys. Use a Windows replacement API that preserves the destination DACL (or explicitly copy its security descriptor) before replacing it.

    if let Ok(meta) = std::fs::metadata(path) {
        if let Err(e) = std::fs::set_permissions(&tmp, meta.permissions()) {
            let _ = std::fs::remove_file(&tmp);
            return Err(e).with_context(|| format!("carry permissions onto {}", tmp.display()));
        }