Feature/mcp apps

[KonghaYao]

Summary by CodeRabbit

• New Features

  • Added MCP Apps relay support for opening apps, reading resources, and calling tools over ACP.
  • MCP Apps can be enabled through the PERI_MCP_APPS environment setting.
  • Added capability negotiation, session validation, cancellation, cleanup, and structured error handling.
  • Added end-to-end MCP Apps verification tooling and example app resources.

• Bug Fixes

  • Prevented Git branch detection from hanging indefinitely.
  • Improved stdio protocol error responses for malformed or invalid messages.
  • Prevented concurrent session updates from overwriting terminal status.
  • Corrected tool visibility handling and snapshot refresh behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: eef3bfe8-7046-43a6-83e4-dc97954ffd56

📥 Commits

Reviewing files that changed from the base of the PR and between dea290e and 84d8c26.

📒 Files selected for processing (53)

• docs/code-index/peri-middlewares.md
• docs/design/mcp-connector-guide-v2.md
• docs/design/mcp-multiplexing.md
• peri-acp-types/src/lib.rs
• peri-acp-types/src/mcp_apps.rs
• peri-acp-types/src/mcp_apps_test.rs
• peri-acp-types/src/tools.rs
• peri-acp/src/host/assemble.rs
• peri-acp/src/host/connection.rs
• peri-acp/src/host/connection_test.rs
• peri-acp/src/host/mcp_apps.rs
• peri-acp/src/host/mcp_apps_test.rs
• peri-acp/src/host/mod.rs
• peri-acp/src/host/requests_test.rs
• peri-acp/src/host/stdio/mod.rs
• peri-acp/src/host/stdio/run_server_integration_test.rs
• peri-acp/src/host/task_scope.rs
• peri-acp/src/transport/stdio.rs
• peri-acp/src/transport/stdio_test.rs
• peri-agent/src/agent/stages/reason.rs
• peri-agent/src/agent/stages/tool_dispatch.rs
• peri-agent/src/session/tool_catalog.rs
• peri-middlewares/src/assembly.rs
• peri-middlewares/src/attribution/mod.rs
• peri-middlewares/src/attribution/mod_test.rs
• peri-middlewares/src/mcp/apps.rs
• peri-middlewares/src/mcp/apps_relay.rs
• peri-middlewares/src/mcp/apps_test.rs
• peri-middlewares/src/mcp/channel_handler.rs
• peri-middlewares/src/mcp/client.rs
• peri-middlewares/src/mcp/client/transport.rs
• peri-middlewares/src/mcp/client_oauth.rs
• peri-middlewares/src/mcp/client_test.rs
• peri-middlewares/src/mcp/dynamic/registry_test.rs
• peri-middlewares/src/mcp/dynamic/staged_connection.rs
• peri-middlewares/src/mcp/initialize.rs
• peri-middlewares/src/mcp/middleware.rs
• peri-middlewares/src/mcp/middleware_test.rs
• peri-middlewares/src/mcp/mod.rs
• peri-middlewares/src/mcp/reconnect.rs
• peri-middlewares/src/mcp/tool_bridge.rs
• peri-middlewares/src/mcp/tool_bridge_test.rs
• peri-resources/src/sessions/filesystem.rs
• peri-resources/src/sessions/filesystem_test.rs
• peri-tui/src/kit/acp_events/render.rs
• peri-tui/src/kit/acp_events_test/snapshot_test.rs
• peri-tui/src/kit/acp_events_test/subagent_loading_test.rs
• side-projects/mcp-apps/check-peri.ts
• side-projects/mcp-apps/check.ts
• side-projects/mcp-apps/package.json
• side-projects/mcp-apps/stdio-server.ts
• spec/issues/2026-08-27-mcp-apps-stdio-relay.md
• spec/issues/2026-08-29-windows-acp-prompt-silently-hangs.md

---

📝 Walkthrough

Walkthrough

Changes

The PR adds an MCP Apps stdio relay with protocol contracts, capability gating, connection-owned sessions, binding leases, resource reads, tool calls, cancellation, generation checks, and structured errors. It also adds integration checks and fixes Git probing, session metadata races, and TUI snapshot tests.

MCP Apps stdio relay

Layer / File(s)	Summary
MCP Apps contracts and tool metadata peri-acp-types/src/mcp_apps.rs, peri-acp-types/src/tools.rs, peri-agent/src/...	Defines MCP Apps envelopes, JSON-RPC shapes, raw result/resource types, relay errors, session bindings, tool visibility, and dispatch identity metadata.
Capability profiles, leases, and pooled relay peri-middlewares/src/mcp/..., peri-middlewares/src/assembly.rs	Adds deployment capability profiles, connection generations, binding leases, raw-result storage, tool visibility filtering, resource handling, and pooled app-tool dispatch.
ACP host capability and app routing peri-acp/src/host/...	Adds environment-based capability selection, connection lifecycle state, MCP Apps request handlers, cancellation cleanup, relay configuration, and session-turn tracking.
Stdio protocol validation and error responses peri-acp/src/transport/stdio.rs, peri-acp/src/transport/stdio_test.rs	Adds JSON-RPC parse and envelope validation with protocol error responses for malformed, invalid, and unsafe messages.
MCP Apps documentation and verification docs/design/..., spec/issues/2026-08-27-mcp-apps-stdio-relay.md, side-projects/mcp-apps/*	Updates the relay design boundary and adds MCP server, direct-client, and Peri end-to-end verification scripts.

Reliability and regression fixes

Layer / File(s)	Summary
Bounded Git branch probing peri-middlewares/src/attribution/*, docs/code-index/peri-middlewares.md, spec/issues/2026-08-29-windows-acp-prompt-silently-hangs.md	Adds a one-second asynchronous Git branch probe timeout, child-process cleanup, cross-platform fixtures, and regression tests.
Serialized session metadata updates peri-resources/src/sessions/*	Serializes metadata updates and tests concurrent message append and terminal status updates.
TUI snapshot and subagent assertions peri-tui/src/kit/acp_events/*	Preserves per-entry fingerprint behavior, tests subagent snapshot cache updates, and uses current-turn view models in assertions.

Estimated code review effort: 5 (Critical) | ~120 minutes

Sequence Diagram(s)

sequenceDiagram
  participant ACPClient
  participant AcpHost
  participant PoolMcpAppsRelay
  participant MCPServer
  ACPClient->>AcpHost: initialize with MCP Apps enabled
  AcpHost->>PoolMcpAppsRelay: peri/mcp/open
  PoolMcpAppsRelay->>MCPServer: resources/read and tool metadata lookup
  MCPServer-->>PoolMcpAppsRelay: raw app resource metadata
  PoolMcpAppsRelay-->>AcpHost: connection-owned app binding
  AcpHost-->>ACPClient: app session response
  ACPClient->>AcpHost: peri/mcp/resource
  AcpHost->>PoolMcpAppsRelay: read bound resource
  PoolMcpAppsRelay->>MCPServer: resources/read
  MCPServer-->>PoolMcpAppsRelay: HTML resource
  PoolMcpAppsRelay-->>ACPClient: resource response
  ACPClient->>AcpHost: peri/mcp/app tools/call
  AcpHost->>PoolMcpAppsRelay: validate binding and invoke tool
  PoolMcpAppsRelay-->>ACPClient: raw JSON-RPC tool result

Loading

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feature/mcp-apps

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}