feat(core): enforce project MCP trust boundaries

[sethkarten]

Core-05: project MCP declarations and trust boundaries

Draft publication for stack visibility. Validation is in progress and will be appended to this PR.

Scope

• 23 project-MCP declaration, trust, redaction, runtime-snapshot, settings, SDK/public composition, and focused test paths
• declaration/config reachability probe contracts only; transport probe execution remains Core-08
• preserves Core-02 capability wrappers and caller-provided MCP manager authority

Hard exclusions

• no cleanup/lifecycle/recovery changes
• no Core-08 transport-probe execution
• no release metadata

Parent: Core-04 #1262 at 4e9c1f2cbfe072d5226f0e49d37e799b6cdce345
Head: 6e8e33c484a26498d41022accd5f118ebe7822fc

Post-publication objective gates are in progress; valid findings will be fixed append-only.

Note

Enforce project MCP trust boundaries with admission-gated declaration snapshots

• Introduces an admission layer (mcp-project-trust.ts, project-trust-authority.ts) that gates project MCP declaration access behind validated, releasable directory-identity bindings; access is fail-closed without explicit admission.
• Adds a declarative MCP data model (mcp-declarations.ts) with strict parsing, name/URL normalization, redaction utilities, and credential-free McpDeclarationDocument type stored in settings.
• Creates an immutable, revision-tagged McpRuntimeDeclarationSnapshot combining user and (non-colliding) project declarations, used by McpManager instead of raw settings.
• Adds mcp CLI subcommands (list/inspect/preview/test/add/enable/disable/remove) with project-scope access enforced via global policy admission in public-command.ts.
• Introduces ProjectSettingsOpenat which reads/writes project declaration documents through a sandboxed Python helper operating on a retained directory fd, preventing path-based attacks.
• Risk: McpManager now sources global MCP servers only (getGlobalMcpServers); project declarations are silently omitted if admission is absent, which is a behavioral change for existing sessions that previously merged project settings.

^{Macroscope summarized eb1a438.}

Final validation

• Head: 1f23778f9a94673de05eff5eecdab15045363c01
• Non-writing Biome: all Core-05 changed paths pass (final three formatting diagnostics fixed manually)
• Root tsgo --noEmit: pass
• Configured MCP regressions: 8 files, 50/50 tests pass
• Env-sanitized daemon-mode regression: 195/195 tests pass
• git diff --check: pass; worktree clean
• Transport probing is deferred to Core-08. Core-05 mcp test is preview-only and cannot call transport.open, eliminating late-open session leakage at this layer.

---

Note

High Risk
Touches security-critical path/trust admission and changes which MCP servers the host loads: project mcpServers no longer redirect integrations unless an explicit admission is granted. Includes retained-FD and helper-process I/O that must stay fail-closed.

Overview
Introduces credential-free MCP declarations and a fail-closed project trust boundary. Project MCP settings are readable/writable only after an opaque ProjectMcpDeclarationAdmission grant from global mcpProjectTrustPolicy; forged, stale, or swapped roots stay inert.

Adds declaration parsing/redaction, an immutable runtime snapshot (user first; colliding project contributions discarded), and descriptor-relative project storage via ProjectSettingsOpenat. Session/SDK composition captures that snapshot before ordinary project settings load, and leaves caller-supplied McpManager instances untouched.

Adds the public mcp CLI (list|inspect|preview|test|add|enable|disable|remove, optional --project) for declaration-only management. Host integrations now use global-only getGlobalMcpServers(); declarations never become OAuth/transport config. mcp test remains offline preview-only.

^{Reviewed by Cursor Bugbot for commit eb1a438. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit f756913. Configure here.}