[aterga]

Summary

Design docs (docs-only) for imcp2-local: a separate, minimal run-it-yourself binary that speaks MCP over stdio, talks to mainnet IC + production Internet Identity, keeps the full II session model, and drops the entire OAuth 2.1 authorization server (the stdio process boundary replaces the bearer gate on the tool surface; login is a built-in browser handshake). The shared components live in a new imcp2-core library from which either binary is composed; the existing imcp2 crate keeps its name, binary, and deployments as the hosted server built on core.

This is the bottom of a two-PR stack — the Stage 1 implementation (extract imcp2-core) sits on top in #77.

Two documents, side by side, both in the standard feature-doc structure (Summary → Problem → Non-goals → Approach → Design components → Implementation Stages):

• docs/local-deployment.md — the concise, high-level overview for stakeholders: one altitude up, no code-level detail.
• docs/scoping-local-deployment.md — the full design: code-level partitions, the AI-client capability matrix and registration snippets, file:line evidence, verification plan. Rebased on main (v0.2.0) with every claim re-verified against the current tree.

Related issues

Changes

• Add docs/local-deployment.md (concise overview) and docs/scoping-local-deployment.md (full design), cross-linked. The full doc's ten design components:
  1. Crate layout — imcp2-core as the common dependency of imcp2 and imcp2-local; imcp2 re-exports core so embedders keep compiling; core becomes a second, family-internal published crate.
  2. Per-crate dependency profile.
  3. Mainnet + prod II wiring, including a local-replica test configuration (an IC-endpoint override with a loopback-guarded fetch_root_key); integration tests run it against PocketIC (the pocket-ic dev dependency).
  4. The auth.rs OAuth-drop / II-connect-keep partition.
  5. The built-in browser II login — lazy, non-blocking, in-band authenticate tool; the loopback listener is axum and the browser opens via open::that, matching the ICP CLI's icp identity link web flow; the transient listener is the RFC 8252-style unavoidable minimum for II's redirect + #4091 origin fetch, and never serves the tool surface.
  6. AI tool client integration (Claude, Codex, Cursor, Perplexity, Antigravity) — capability matrix + registration formats.
  7. Session handling — bearer lookup on hosted, singleton in-memory session on local; identical tools.
  8. Security model — wallet-grade trust note, loopback hardening.
  9. End-user setup UX — no JSON/config editing anywhere: the double-click .mcpb bundle for Claude Desktop, an Add-to-Cursor install link, one pasted command for Claude Code and Codex, connector UIs for Perplexity (macOS) and Antigravity, an imcp2-local setup command that detects installed clients and writes their configs, and in-place upgrades following the ICP CLI's cargo-dist/axoupdater channel.
  10. Signing and provenance — the OS execution gates (macOS Developer ID + notarization; Windows Authenticode via Azure Trusted Signing/EV) versus keyless GitHub artifact attestations; the .mcpb nuance, pipeline hook-in, and DFINITY's acquisition checklist.
• Implementation Stages with exits and the verification plan (integration tests run imcp2-local in the local-replica test configuration against PocketIC with a deployed II canister; remaining unknowns are loopback mixed-content/CORS).

Testing

Docs-only change — no build/test impact.

• No code changed (docs/ only)

Checklist

• I have read the Contributing guidelines.
• Docs updated (this PR is the docs).
• 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

Documents the proposed architecture and rollout of the local stdio-based imcp2-local binary.

Changes:

• Adds a stakeholder-focused architecture overview.
• Adds detailed crate, authentication, client integration, security, packaging, and testing designs.
• Defines a three-stage implementation plan.

Reviewed changes

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

File	Description
docs/local-deployment.md	High-level local deployment overview.
docs/scoping-local-deployment.md	Detailed implementation design and verification plan.

Suppressed comments (1)

docs/scoping-local-deployment.md:203

• The net dependency inventory omits axum, although lines 188–195 require it for the loopback login listener. As written, this list cannot describe the binary that the design specifies.

Net minimal local deps: `imcp2-core` +
`rmcp{server,macros,transport-io}` + `tokio` +
`anyhow` + `serde_json` + `url`/`urlencoding` + `tracing`/`tracing-subscriber` + a
browser-opener (`open` crate, or `std::process::Command`).

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

Pull request overview

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

Suppressed comments (1)

docs/scoping-local-deployment.md:407

• Singleton(String) cannot support reauthentication after the grant expires or is revoked. registration_pubkey_b64 is idempotent for a session ID (src/identities.rs:582-605), while the existing session contract requires a fresh connect/session key after Unauthorized (src/identities.rs:138-143); the inherited connect link currently requests only a 3,600-second grant (src/auth.rs:128-129). A long-lived stdio handler would therefore remain pinned to a dead ID until the AI client restarts. Make the local source replaceable and publish a fresh session ID after each successful authenticate (or explicitly rebuild the handler), and cover same-process reauthentication.

- add `session: SessionSource { Bearer, Singleton(String) }` to `IcTools` (`tools.rs:52`);
- one `current_session_id(&self, &ctx) -> Option<String>` method replacing the free fn;

[Copilot]

Pull request overview

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

Suppressed comments (1)

docs/scoping-local-deployment.md:395

• This router placement conflicts with the dependency partition: the authenticate methods must start the listener and browser driver owned by imcp2-local, but an impl compiled in imcp2-core cannot directly call code from its dependent crate, and core intentionally excludes axum/open. Define the missing composition seam—for example, a local wrapper handler that merges/delegates the core router, or an injected login-driver trait/callback—so the local-only tools can invoke the local implementation without reversing the dependency direction.

*(Implementation: `authenticate`/`auth_status` are **local-only** tools, and construction
mode alone would not hide them — rmcp's `#[tool_router]` generates the router per impl
block, type-level. So they live in their **own small router** (a second `#[tool_router]`
impl in `imcp2-core`) that only the local binary composes onto `IcTools`'s router; the
hosted server never composes it in, and a hosted-side test asserts its `tools/list` does

[Copilot]

Pull request overview

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

Suppressed comments (1)

docs/scoping-local-deployment.md:570

• This exit criterion cannot pass as written because #77 reports transitive tower-http in the standalone core graph via rmcp/reqwest. Make the criterion distinguish direct hosted dependencies from unavoidable transitive packages.

compiles standalone with no `axum`/`tower-http`/`prometheus`/OAuth in its graph.

[Copilot]

Pull request overview

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

Suppressed comments (3)

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

docs/scoping-local-deployment.md:109

• The current tools.rs contains 27 #[tool] methods, so this exact count is stale. Update it to 27; the later “~26” references should also be aligned when describing the local total.

  - `tools.rs` — the **entire** MCP tool surface. The `#[tool_router]` / 26×`#[tool]` /

docs/scoping-local-deployment.md:124

• This says the newly public core composition types are re-exported by imcp2, but lines 160–165 say the re-export set is exactly the pre-split surface and core-only seams are not re-exported. IcTools, Identities, and their composition entry points are currently crate-private, so re-exporting them would expand—not preserve—the imcp2 API. Clarify that they are public in imcp2-core but remain core-only unless already public before the split.

  - The move is not visibility-neutral: workspace packages share no crate-private access,
    so the items the binaries compose against — `IcTools`/`IcTools::new` with
    `SessionSource`, the `Identities` registration/redeem entry points above, the
    `iiconnect` builders — graduate from `pub(crate)` behind one binary to core's
    deliberate **public API** (`imcp2` re-exports it below, so embedders see no change).

docs/scoping-local-deployment.md:591

• The stage plan defers the PocketIC integration tests to Stage 3, even though Stage 2 exits only after login works and the Verification section (lines 616–624) explicitly makes both the PocketIC flow and real-browser compatibility a Stage 2 gate. Move those verification deliverables into Stage 2 so the stage cannot be declared complete before its login path is validated.

wallet-grade trust note; integration tests via the local-replica test configuration
(component 3), extending the PocketIC e2e harness to the local login flow (see
Verification); optional keychain-backed session persistence.