---
summary: MCP Apps integration — appTool and appResource builders, _meta passthrough, linter pairing rules, template echo app, and comprehensive test coverage
breaking: false
---

# 0.3.0 — 2026-04-06

MCP Apps integration — `appTool()` and `appResource()` builders, `_meta` passthrough, linter rules for app tool/resource pairing, template examples, and comprehensive test coverage.

## Added

- **MCP Apps builders** — `appTool()` and `appResource()` convenience builders (`src/mcp-server/apps/appBuilders.ts`). `appTool()` auto-populates `_meta.ui.resourceUri` and the backwards-compat `ui/resourceUri` key. `appResource()` defaults `mimeType` to `text/html;profile=mcp-app` and `annotations.audience` to `['user']`. Both re-exported from the main entry point.
- **`APP_RESOURCE_MIME_TYPE` constant** — Exported from main entry point, matches `@modelcontextprotocol/ext-apps/server` without requiring the peer dep.
- **`_meta` passthrough** — `ResourceDefinition` and `TaskToolDefinition` interfaces now accept `_meta`. Tool and resource registration passes `_meta` through to the SDK.
- **Linter: `_meta.ui` validation** — New rules `meta-ui-type`, `meta-ui-resource-uri-required`, and `meta-ui-resource-uri-scheme` validate tool `_meta.ui` fields at startup.
- **Linter: app tool ↔ resource pairing** — `lintAppToolResourcePairing()` cross-checks that every tool declaring `_meta.ui.resourceUri` has a matching registered resource. Warns on mismatch. Supports RFC 6570 URI template matching.
- **Template: echo app** — `templates/src/mcp-server/tools/definitions/echo-app.app-tool.ts` and `templates/src/mcp-server/resources/definitions/echo-app-ui.app-resource.ts` demonstrate the full MCP Apps pattern for scaffolded servers.
- **`add-app-tool` skill** — Step-by-step guide for scaffolding MCP App tool + UI resource pairs.

## Fixed

- **`appTool()` clobbered `extraMeta.ui` fields** — The builder overwrote caller-supplied `_meta.ui` sub-fields (e.g. `visibility`) with only `{ resourceUri }`. Now merges `extraMeta.ui` fields with the auto-populated `resourceUri` (which still wins over any `extraMeta.ui.resourceUri`).
- **Linter false positive on `{+path}` URI templates** — `lintAppToolResourcePairing()` replaced all RFC 6570 expressions with `[^/]+`, causing `{+var}` (reserved expansion) and `{/var}` (path segments) to fail matching URIs containing `/`. Now uses `.+` for slash-expanding operators.
- **Template echo app missing CSP allowlist** — The scaffolded echo app resource imports `@modelcontextprotocol/ext-apps` from `unpkg.com` but did not declare `_meta.ui.csp.resourceDomains`. Hosts enforcing deny-by-default CSP would block the import. Added `resourceDomains: ['https://unpkg.com']` to the template and skill doc.
- **CSP field name casing** — Corrected `resource_domains` (snake_case) to `resourceDomains` (camelCase) in JSDoc examples and tests to match the `McpUiResourceCsp` interface from `@modelcontextprotocol/ext-apps`.

## Tests

- `appBuilders.test.ts` — 414 lines covering `appTool()` and `appResource()` field passthrough, `_meta` population, defaults, and edge cases.
- `tool-rules.test.ts` — 285 lines covering `lintToolDefinition` `_meta.ui` validation and `lintAppToolResourcePairing` cross-check.
- `validate.test.ts` — +195 lines for `_meta.ui` rules and app tool ↔ resource pairing in the integration linter.
- `resource-registration.test.ts` — +39 lines for `_meta` passthrough to `server.resource`.
- `tool-registration.test.ts` — +62 lines for `_meta` passthrough to `server.registerTool` and `registerToolTask`.
- `mcp-apps.int.test.ts` — 258-line end-to-end integration test covering builder output → linter validation → handler execution → format output.
- `template-echo-app.app-tool.test.ts` — 115-line smoke test for the echo app tool pattern.
- `echo-app-ui.app-resource.test.ts` — 95-line smoke test for the echo app UI resource pattern.

## Dependencies

- `dotenv` 17.4.0 → 17.4.1
- `hono` 4.12.10 → 4.12.11
- `@cloudflare/workers-types` ^4.20260403.1 → ^4.20260405.1
- `msw` ^2.12.14 → ^2.13.0
- `vite` 8.0.3 → 8.0.5
- `biome.json` schema 2.4.9 → 2.4.10
