Add {AGENTS,CLAUDE}.md for AI assistant guidance

AGENTS.md

@@ -0,0 +1,87 @@
+# MCP Apps SDK
+
+## Project Overview
+
+MCP Apps SDK (`@modelcontextprotocol/ext-apps`) enables MCP servers to display interactive UIs in conversational clients.
+
+Key abstractions:
+
+- **Guest** - UI running in an iframe, uses `App` class with `PostMessageTransport` to communicate with host
+- **Host** - Chat client embedding the iframe, uses `AppBridge` class to proxy MCP requests
+- **Server** - MCP server that registers tools/resources with UI metadata
+
+Specification (draft): `specification/draft/apps.mdx`
+
+## Commands
+
+```bash
+# Install dependencies
+npm install
+
+# Build the SDK only (generates schemas + bundles, does not build examples)
+npm run build
+
+# Build everything (SDK + all examples)
+npm run build:all
+
+# Type check + build a single example
+npm run --workspace examples/<example-name> build
+
+# Run all examples (starts server at http://localhost:8080)
+npm start
+
+# Run E2E tests (primary testing mechanism - starts examples server automatically)
+npm run test:e2e
+
+# Run unit tests (E2E tests have broader coverage; unit tests cover specific modules)
+npm test
+
+# Check JSDoc comment syntax and `{@link}` references
+npm exec typedoc -- --treatValidationWarningsAsErrors --emit none
+
+# Regenerate package-lock.json (especially on setups w/ custom npm registry)
+rm -fR  package-lock.json node_modules && \
+  docker run  --rm -it --platform linux/amd64 -v $PWD:/src:rw -w /src node:latest npm i && \
+  rm -fR node_modules && \
+  npm  i  --cache=~/.npm-mcp-apps --registry=https://registry.npmjs.org/
+```
+
+## Architecture
+
+### SDK Entry Points
+
+- `@modelcontextprotocol/ext-apps` - Main SDK for Apps (`App` class, `PostMessageTransport`)
+- `@modelcontextprotocol/ext-apps/react` - React hooks (`useApp`, `useHostStyleVariables`, etc.)
+- `@modelcontextprotocol/ext-apps/app-bridge` - SDK for hosts (`AppBridge` class)
+- `@modelcontextprotocol/ext-apps/server` - Server helpers (`registerAppTool`, `registerAppResource`)
+
+### Key Source Files
+
+- `src/app.ts` - `App` class extends MCP Protocol, handles guest initialization, tool calls, messaging
+- `src/app-bridge.ts` - `AppBridge` class for hosts, proxies MCP requests, sends tool input/results to guests
+- `src/server/index.ts` - Helpers for MCP servers to register tools/resources with UI metadata
+- `src/types.ts` - Protocol types re-exported from `spec.types.ts` and Zod schemas from `generated/schema.ts` (auto-generated during build)
+- `src/message-transport.ts` - `PostMessageTransport` for iframe communication
+- `src/react/` - React hooks: `useApp`, `useHostStyles`, `useAutoResize`, `useDocumentTheme`
+
+### Protocol Flow
+
+```
+Guest UI (App) <--PostMessageTransport--> Host (AppBridge) <--MCP Client--> MCP Server
+```
+
+1. Host creates iframe with Guest UI HTML
+2. Guest UI creates `App` instance and calls `connect()` with `PostMessageTransport`
+3. App sends `ui/initialize` request, receives host capabilities and context
+4. Host sends `sendToolInput()` with tool arguments after initialization
+5. Guest UI can call server tools via `app.callServerTool()` or send messages via `app.sendMessage()`
+6. Host sends `sendToolResult()` when tool execution completes
+7. Host calls `teardownResource()` before unmounting iframe
+
+## Examples
+
+Uses npm workspaces. Examples in `examples/` are separate packages:
+
+- `basic-server-*` - Starter templates (vanillajs, react, vue, svelte, preact, solid). Use these as the basis for new examples.
+- `basic-host` - Reference host implementation
+- Other examples showcase specific features (charts, 3D, video, etc.)

CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md