feat: add sandbox flags negotiation

[idosal]

Add iframe sandbox flag negotiation, allowing apps to request additional sandbox capabilities beyond the baseline (allow-scripts, allow-same-origin).

Motivation and Context

Completes #58 and a step towards addressing #320. Phase 1: Sandbox Negotiation.

Previously, apps had no mechanism to request sandbox capabilities like form submission, popups, modals, or downloads.
The spec sets the minimum support to allow-scripts allow-same-origin, which is insufficient for legitimate use cases such as form submissions and print dialogs.

This change:

1. Introduces McpUiResourceSandbox interface with negotiable flags: forms, popups, modals, downloads
2. Reduces SDK baseline to allow-scripts allow-same-origin (to fit the spec) and makes allow-forms a negotiable capability.
3. Adds buildSandboxAttribute() helper to convert structured flags to sandbox attribute strings
4. Accepts both structured flags object and raw string override via union type (@ochafik can we simply override the existing string sandbox property in favor of the structured change?)

How Has This Been Tested?

Unit tests

Breaking Changes

No breaking changes to the spec.

The SDK had an unexpected artifact that's not mentioned in the spec - a raw string sandbox property passed to the inner iframe in McpUiSandboxResourceReadyNotification. It wasn't used by any example, and it wouldn't have worked in all scenarios on its own. I overrode it with the new flag type to keep things clean (@ochafik WDYT? Did you have something else in mind when adding it?)

Basic-host loses its allow-frames (in order to comply with the spec).

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

Additional context

In the next phases of #320, we can add additional permissions and go deeper into intersecting permissions

[Copilot]

Pull request overview

This PR adds iframe sandbox flag negotiation capabilities to the MCP Apps SDK, allowing apps to request additional sandbox capabilities beyond the baseline allow-scripts and allow-same-origin flags.

Changes:

• Introduces McpUiResourceSandbox interface with negotiable flags for forms, popups, modals, and downloads
• Adds buildSandboxAttribute() helper function to convert structured flags to sandbox attribute strings
• Updates the SDK baseline to match spec requirements (allow-scripts allow-same-origin) with forms now negotiable

Reviewed changes

Copilot reviewed 8 out of 12 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
src/types.ts	Exports new McpUiResourceSandbox type and schema
src/spec.types.ts	Defines McpUiResourceSandbox interface and updates related types to support sandbox negotiation
src/generated/schema.ts	Adds Zod schema for McpUiResourceSandbox with union type support for string overrides
src/generated/schema.test.ts	Adds type inference tests for new sandbox schema
src/generated/schema.json	JSON schema definition for sandbox flags
src/app-bridge.ts	Implements buildSandboxAttribute() helper function with baseline flag handling
src/app-bridge.test.ts	Comprehensive unit tests for buildSandboxAttribute() function
specification/draft/apps.mdx	Updates documentation to describe sandbox flag negotiation
package-lock.json	Dependency lockfile changes (includes unrelated peer flag removals)
examples/basic-host/src/sandbox.ts	Updates sandbox proxy to handle structured flags and string overrides
examples/basic-host/src/index.tsx	Updates to pass sandbox configuration through initialization flow
examples/basic-host/src/implementation.ts	Updates to extract and pass sandbox metadata to proxy loader

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The parameter type for sandbox should be McpUiResourceSandbox | string (union type) to match the specification and the type of McpUiSandboxResourceReadyNotification['params']['sandbox']. The spec allows both structured flags objects and raw string overrides. While buildSandboxAttribute() will still work correctly since it only accepts McpUiResourceSandbox | undefined, the function signature should align with the spec to properly accept string values that apps might provide.