@lovable.dev/mcp-js 3.3.0 → 3.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.internal.md +38 -12
- package/README.md +144 -12
- package/dist/THIRD_PARTY_NOTICES +75 -0
- package/dist/apps-CWG3rGhB.js +132 -0
- package/dist/apps-DyoDrwfi.cjs +185 -0
- package/dist/{authorize-r6jB-Gl2.d.cts → authorize--W1XtwdB.d.cts} +1 -1
- package/dist/{authorize-DxnyFNHv.d.ts → authorize-DpNYioXM.d.ts} +1 -1
- package/dist/{base-ff0LwIA2.d.ts → base-Ce9JYirF.d.ts} +1 -1
- package/dist/{base-CzPzbI3q.d.cts → base-qEX8YVcD.d.cts} +1 -1
- package/dist/cli/check-server.cjs +1 -1
- package/dist/cli/check-server.js +1 -1
- package/dist/cli/extract-manifest.cjs +1 -1
- package/dist/cli/extract-manifest.js +1 -1
- package/dist/{cors-Bjo6NPjV.cjs → cors-DcWb13LI.cjs} +1 -1
- package/dist/{cors-COjc9O73.js → cors-M68siADv.js} +1 -1
- package/dist/dist-CIu-UFye.js +6738 -0
- package/dist/dist-CqY2qXpc.cjs +6738 -0
- package/dist/{errors-D0UPHnG3.js → errors-CfaxXr2T.js} +25 -2
- package/dist/{errors-DSHt3Jqs.cjs → errors-xJ_7Su1K.cjs} +30 -1
- package/dist/index.cjs +2 -1
- package/dist/index.d.cts +6 -2
- package/dist/index.d.ts +6 -2
- package/dist/index.js +2 -2
- package/dist/{io-CQ60Nc2J.d.ts → io-BEpyfk4G.d.ts} +1 -1
- package/dist/{io-DTz7efSK.js → io-CICYQJSM.js} +13 -3
- package/dist/{io-Dzy5Bu6h.cjs → io-DGeqWc6m.cjs} +12 -2
- package/dist/{io-DnRCu_HX.d.cts → io-Di5ljvZY.d.cts} +1 -1
- package/dist/{mcp-DIR9MCwQ.js → mcp-BT9dcts8.js} +117 -51
- package/dist/{mcp-Buu1riaY.cjs → mcp-DAUFwQ80.cjs} +116 -50
- package/dist/mcp-app.d.ts +4 -0
- package/dist/{package-DL4uNmL0.cjs → package-Cu_ynl05.cjs} +1 -1
- package/dist/{package-DV8zBoEy.js → package-N4he-Z_i.js} +1 -1
- package/dist/protocols/mcp/index.cjs +1 -1
- package/dist/protocols/mcp/index.d.cts +3 -3
- package/dist/protocols/mcp/index.d.ts +3 -3
- package/dist/protocols/mcp/index.js +1 -1
- package/dist/protocols/oauth-metadata.cjs +1 -1
- package/dist/protocols/oauth-metadata.d.cts +3 -3
- package/dist/protocols/oauth-metadata.d.ts +3 -3
- package/dist/protocols/oauth-metadata.js +1 -1
- package/dist/src-D7RtXSV0.cjs +311 -0
- package/dist/src-sWQwyLwS.js +310 -0
- package/dist/stacks/supabase/index.cjs +2 -2
- package/dist/stacks/supabase/index.d.cts +1 -1
- package/dist/stacks/supabase/index.d.ts +1 -1
- package/dist/stacks/supabase/index.js +2 -2
- package/dist/stacks/supabase/vite.cjs +10 -1
- package/dist/stacks/supabase/vite.d.cts +1 -1
- package/dist/stacks/supabase/vite.d.ts +1 -1
- package/dist/stacks/supabase/vite.js +21 -12
- package/dist/stacks/tanstack/index.cjs +33 -2
- package/dist/stacks/tanstack/index.d.cts +7 -4
- package/dist/stacks/tanstack/index.d.ts +7 -4
- package/dist/stacks/tanstack/index.js +33 -2
- package/dist/stacks/tanstack/vite.cjs +995 -15
- package/dist/stacks/tanstack/vite.d.cts +1 -1
- package/dist/stacks/tanstack/vite.d.ts +1 -1
- package/dist/stacks/tanstack/vite.js +1001 -21
- package/dist/testing/browser/LICENSE.ext-apps +218 -0
- package/dist/testing/browser/host.ts +151 -0
- package/dist/testing/browser/sandbox.ts +137 -0
- package/dist/testing/browser.cjs +382 -0
- package/dist/testing/browser.d.cts +46 -0
- package/dist/testing/browser.d.ts +46 -0
- package/dist/testing/browser.js +381 -0
- package/dist/testing/index.cjs +2 -1
- package/dist/testing/index.d.cts +2 -1
- package/dist/testing/index.d.ts +2 -1
- package/dist/testing/index.js +2 -1
- package/dist/testing/server.cjs +36 -0
- package/dist/testing/server.d.cts +6 -2
- package/dist/testing/server.d.ts +6 -2
- package/dist/testing/server.js +36 -1
- package/dist/{tool-result-DcNioyiI.js → tool-result-BG-HsSQu.js} +8 -1
- package/dist/{tool-result-rU-PpNNi.cjs → tool-result-BQcr7VV-.cjs} +8 -1
- package/dist/{types-BtoYHhdt.d.cts → types-B_dVw-zM.d.cts} +59 -1
- package/dist/{types-BtoYHhdt.d.ts → types-B_dVw-zM.d.ts} +59 -1
- package/package.json +67 -26
package/README.internal.md
CHANGED
|
@@ -25,7 +25,12 @@ Reasons:
|
|
|
25
25
|
|
|
26
26
|
TanStack's file-based router needs a route file on disk to register a URL. If we asked users to author the route file themselves, they'd own seven lines of plumbing that has to stay correct as the SDK's transport semantics evolve. Generating it lets us pin the wiring as a versioned package artifact — when the MCP SDK changes, the plugin emits a new template and every user picks it up on rebuild.
|
|
27
27
|
|
|
28
|
-
|
|
28
|
+
Generated routes pass a lazy definition loader to the stack adapter. The adapter
|
|
29
|
+
loads on each invocation and retains a handler only while the definition identity
|
|
30
|
+
is unchanged, preserving discovery caches without serving an old definition after
|
|
31
|
+
an import failure. Import/construction failures produce redacted, non-cacheable
|
|
32
|
+
responses; auth and tool execution remain request-local. Adoption requires an SDK
|
|
33
|
+
upgrade and route regeneration. Hand-owned routes do not change automatically.
|
|
29
34
|
|
|
30
35
|
### 3. Dot-prefixed URL paths use bracket escaping
|
|
31
36
|
|
|
@@ -66,14 +71,15 @@ The MCP spec promoted `title` to a top-level field on `Tool` and `Server` in 202
|
|
|
66
71
|
|
|
67
72
|
The MCP spec's legacy `annotations.title` is omitted from our `ToolAnnotations` type — use the top-level `title` instead. Two locations for the same field encourage drift.
|
|
68
73
|
|
|
69
|
-
### 7.
|
|
74
|
+
### 7. Package-owned authoring types, official SDK transport
|
|
70
75
|
|
|
71
|
-
|
|
76
|
+
Package-owned authoring types insulate handlers from changes to the MCP SDK's
|
|
77
|
+
type tree. Transport validation and lifecycle remain with the official SDK;
|
|
78
|
+
do not create a second protocol implementation. Testing APIs deliberately expose
|
|
79
|
+
official types: `/testing/server` uses the v2 client, while `/testing/browser`
|
|
80
|
+
uses the ext-apps bridge and its v1 SDK types.
|
|
72
81
|
|
|
73
|
-
|
|
74
|
-
2. **Optionality on the SDK itself.** If we ever swap or drop `@modelcontextprotocol/sdk` — different transport, in-house protocol implementation, a fork — consumers' code is the contract that matters, and it's typed against this package's surface, not the SDK's. The runtime hand-off can change without rippling through user code.
|
|
75
|
-
|
|
76
|
-
The published `.d.ts` files import only from `zod` and `vite`. Three SDK concerns were re-implemented (or re-typed) locally:
|
|
82
|
+
The authoring surface owns these types:
|
|
77
83
|
|
|
78
84
|
- **Content blocks and `ToolAnnotations`** — re-declared in `core/types.ts` to match the MCP wire format without depending on `@modelcontextprotocol/sdk/types.js`. The runtime still serializes via the SDK; only the type tree is owned.
|
|
79
85
|
- **`ZodRawShape`, `ZodType`, `infer`** — sourced directly from `zod` (a peer dep). zod v3 and v4 both export all three at the top level; `ZodType` is non-deprecated in both versions with safe generic defaults. We re-export them from `core/types.ts` as `ZodRawShape` / `ZodSchema` / `ShapeOutput` (`ZodSchema` is a no-generic alias for `ZodType`). No dependency on `@modelcontextprotocol/sdk/server/zod-compat.js` types.
|
|
@@ -97,9 +103,10 @@ Two consequences for user-authored files:
|
|
|
97
103
|
|
|
98
104
|
```
|
|
99
105
|
src/
|
|
100
|
-
index.ts # public entrypoint: defineTool/defineMcp, auth, ToolContext, public types
|
|
106
|
+
index.ts # public entrypoint: defineTool/defineApp/defineMcp, auth, ToolContext, public types
|
|
101
107
|
core/ # framework-agnostic kernel; not a published subpath
|
|
102
|
-
define.ts # defineTool, defineMcp
|
|
108
|
+
define.ts # defineTool, defineApp, defineMcp
|
|
109
|
+
apps.ts # static view validation, metadata and collection
|
|
103
110
|
types.ts # types (zod-sourced shape types, MCP wire types)
|
|
104
111
|
http.ts # Web-Standard Response helpers
|
|
105
112
|
url.ts # URL parsing/validation
|
|
@@ -130,10 +137,14 @@ src/
|
|
|
130
137
|
ssr-loader.ts # produceViaSsr: load the entry via a throwaway Vite SSR server
|
|
131
138
|
cli/
|
|
132
139
|
extract-manifest.ts # lovable-mcp-extract-manifest bin (runs runExtract on cwd)
|
|
140
|
+
check-server.ts # lovable-mcp-check bin
|
|
141
|
+
testing/ # result assertions, real MCP client checks and optional browser fixture
|
|
142
|
+
browser/ # loopback host/proxy, official bridge and policy enforcement
|
|
133
143
|
stacks/
|
|
134
144
|
tanstack/
|
|
135
145
|
handlers.ts # TanStack route-ctx adapters
|
|
136
146
|
vite.ts # mcpPlugin (route emission + stale-file cleanup; exposes McpPluginApi for the extractor)
|
|
147
|
+
mcp-app-*.ts # nested view build, canonical source boundary, CSS/assets and compatibility
|
|
137
148
|
index.ts # barrel
|
|
138
149
|
supabase/
|
|
139
150
|
handler.ts # createSupabaseHandler (URL-suffix dispatcher to protocols/*)
|
|
@@ -155,6 +166,10 @@ tests/
|
|
|
155
166
|
global-setup.ts # spawns example/tanstack on :8080
|
|
156
167
|
tools.test.ts # non-OAuth example
|
|
157
168
|
oauth.test.ts # self-contained: mock issuer + OAuth example
|
|
169
|
+
browser/apps.test.ts # official host bridge and CSP/lifecycle contracts
|
|
170
|
+
harness/ # real Vite dev/build → protocol resource checks
|
|
171
|
+
testing/ # public testing-kit contracts
|
|
172
|
+
package/ # isolated packed consumers, Zod and Apps/Vite compatibility
|
|
158
173
|
```
|
|
159
174
|
|
|
160
175
|
## Scripts
|
|
@@ -164,8 +179,13 @@ pnpm format # oxfmt --write src/ tests/
|
|
|
164
179
|
pnpm format:check # oxfmt --check src/ tests/
|
|
165
180
|
pnpm lint # format:check + oxlint (one command, both surfaces)
|
|
166
181
|
pnpm lint:fix # format + oxlint --fix
|
|
167
|
-
pnpm typecheck #
|
|
168
|
-
pnpm test #
|
|
182
|
+
pnpm typecheck # tsc --noEmit
|
|
183
|
+
pnpm test # unit + packed Zod and generic testing-kit checks; installs need registry access
|
|
184
|
+
pnpm test:harness # Vite development loading and SSR-build protocol checks
|
|
185
|
+
pnpm test:browser # Chromium lifecycle/CSP contracts; install Chromium first
|
|
186
|
+
pnpm test:package:testing # packed generic testing example
|
|
187
|
+
pnpm test:package:apps # packed authenticated Apps example
|
|
188
|
+
pnpm test:package:apps-compat # packed Apps compilation across Vite 5/6/7/8
|
|
169
189
|
pnpm test:watch # vitest --project unit
|
|
170
190
|
pnpm test:integration:tanstack # build + install tanstack example + vitest --project integration
|
|
171
191
|
pnpm test:integration:tanstack:oauth # build + install OAuth example + vitest --project integration-oauth
|
|
@@ -178,7 +198,13 @@ pnpm example:tanstack:oauth:smoke # smoke a running OAuth example, optionally
|
|
|
178
198
|
pnpm example:supabase:install # install example/supabase deps
|
|
179
199
|
```
|
|
180
200
|
|
|
181
|
-
`lint` checks
|
|
201
|
+
`lint` checks formatting and lint rules. `prepublishOnly` chains
|
|
202
|
+
`clean → typecheck → test → build → check:package`; CI enforces `lint`
|
|
203
|
+
separately. The Apps compatibility matrix and browser/packed Apps checks run
|
|
204
|
+
in Buildkite's `js-mcp-apps` lane, outside the publishing lifecycle.
|
|
205
|
+
See [harness coverage and commands](tests/harness/README.md) for local protocol
|
|
206
|
+
and browser checks, filtering and JSON output. Unit tests need the monorepo
|
|
207
|
+
checkout: the authoring-template tests read `go/api/**`.
|
|
182
208
|
|
|
183
209
|
**Integration tests** live under `tests/integration/` and run against a live HTTP server. `pnpm test:integration:tanstack` builds the SDK, installs `example/tanstack`, boots its dev server on port 8080 via a Vitest `globalSetup`, runs the suite, and tears the server down. If the server is already running at `MCP_BASE_URL` (default `http://localhost:8080`), the setup reuses it — useful when iterating on the suite. See `CHANGELOG.md` for version history.
|
|
184
210
|
|
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @lovable.dev/mcp-js
|
|
2
2
|
|
|
3
|
-
Author MCP servers for Lovable apps. Declare tools with `defineTool`, register them with `defineMcp`, and a Vite plugin emits the framework-specific routes at build time
|
|
3
|
+
Author MCP servers for Lovable apps. Declare tools with `defineTool`, register them with `defineMcp`, and a Vite plugin emits the framework-specific routes at build time for TanStack or Supabase Edge Functions.
|
|
4
4
|
|
|
5
5
|
Vite is an optional peer dependency: deployed MCP handlers do not need it. Both `/stacks/*/vite` plugins and `lovable-mcp-extract-manifest` require an explicitly installed Vite version `>=5.0.0 <9.0.0`. Keep your project's existing compatible version, or install one with `npm install -D vite@^7`. Build and manifest-extraction jobs must include dev dependencies; runtime-only deployments can omit them.
|
|
6
6
|
|
|
@@ -46,6 +46,10 @@ Manifest extraction allows **512 tools** in the evaluated `defineMcp({ tools })`
|
|
|
46
46
|
|
|
47
47
|
`inputSchema` is closed: a `tools/call` carrying an argument key the schema does not declare fails in-band (`isError: true`, naming the key) instead of silently dropping it, and `tools/list` advertises `additionalProperties: false`. Set `strict: false` on a tool to accept and drop unknown keys instead.
|
|
48
48
|
|
|
49
|
+
MCP POST bodies default to **1 MiB** and tool arguments to **10,000 combined object members and array elements**. Larger bodies receive HTTP `413`; arguments over the element limit return a tool error before the handler runs. These defaults apply to both protocol eras, including Skills and app-context requests.
|
|
50
|
+
|
|
51
|
+
For tools that need larger inputs, set `limits` in `defineMcp`, for example `limits: { maxRequestBodySize: 4 * 1024 * 1024, maxToolInputElements: 50_000 }`. `maxRequestBodySize` is measured in bytes. Each override must be a positive safe integer; zero, fractional values, `NaN` and `Infinity` are rejected when the server is declared. Omitted fields keep their defaults. Hosting-provider limits still apply.
|
|
52
|
+
|
|
49
53
|
## Task workflows as skills
|
|
50
54
|
|
|
51
55
|
**Experimental:** Skills support follows the developing [MCP Skills extension](https://modelcontextprotocol.io/extensions/skills). Client support varies, and the integration may change as the specification evolves.
|
|
@@ -179,8 +183,11 @@ export default defineAppTool({
|
|
|
179
183
|
```
|
|
180
184
|
|
|
181
185
|
The SDK runs `createAppContext` once per request: for `tools/list` when any tool
|
|
182
|
-
has `enabled`, and for a call to a conditional or app-context tool.
|
|
183
|
-
|
|
186
|
+
has `enabled`, and for a call to a conditional or app-context tool. Conditional
|
|
187
|
+
MCP App links also need context for discovery, resource listing and `ui://`
|
|
188
|
+
reads. Plain static tool calls and ping skip it unless conditional Skills need
|
|
189
|
+
context. Reading an unconditional view does not load handler-only context.
|
|
190
|
+
A throw from the factory or a predicate
|
|
184
191
|
fails the whole request with a redacted 500, including `tools/list`, so return a
|
|
185
192
|
least-privilege context for callers who lack access and throw only when the
|
|
186
193
|
lookup itself fails. Disabled tools are omitted from
|
|
@@ -383,13 +390,12 @@ Use `auth.oauth.issuer(...)`, set `resource` or `acceptedAudiences` to anchor th
|
|
|
383
390
|
|
|
384
391
|
## Testing
|
|
385
392
|
|
|
386
|
-
Test an MCP server in
|
|
393
|
+
Test an MCP server in four layers:
|
|
387
394
|
|
|
388
395
|
1. **Business and persistence logic.** Keep it in ordinary functions and services and test it with your usual runner. No MCP is involved.
|
|
389
396
|
2. **Tool results.** Assert a result directly with `assertToolResult` from `@lovable.dev/mcp-js/testing`.
|
|
390
397
|
3. **The endpoint.** Connect a real MCP client to an in-process handler or a URL with `@lovable.dev/mcp-js/testing/server` or the `lovable-mcp-check` CLI.
|
|
391
|
-
|
|
392
|
-
Browser and UI testing are not covered.
|
|
398
|
+
4. **MCP App views.** Use `createAppFixture` from `@lovable.dev/mcp-js/testing/browser` with Playwright and the official ext-apps bridge for view interactions and host messages.
|
|
393
399
|
|
|
394
400
|
```ts
|
|
395
401
|
import { assertToolResult } from "@lovable.dev/mcp-js/testing";
|
|
@@ -427,6 +433,7 @@ pnpm exec lovable-mcp-check --url https://my-app.lovable.app/mcp --bearer-env MC
|
|
|
427
433
|
What a check does and does not prove:
|
|
428
434
|
|
|
429
435
|
- Discovery never calls a tool. Only the listed `calls` run, in order. After a failed or incomplete call, or a tool whose schema can't be checked, the remaining calls are skipped.
|
|
436
|
+
- Discovery reads linked MCP App resources with the configured caller's credentials. An unreadable or mismatched HTML resource prevents selected calls from running.
|
|
430
437
|
- `passed` means no failure was observed. A successful connection does not prove that auth is enforced or that business behavior is correct; assert those separately.
|
|
431
438
|
- Reports contain only fixed, value-free diagnostics with indexed locations. Exceptions from `withMcpClient` and its callback are **not** redacted.
|
|
432
439
|
- Credential headers are never sent across a redirect or to a different endpoint, and require HTTPS to a non-loopback host unless an in-process `handler` is supplied. The kit does not mint tokens or run a deployed OAuth flow; supply your own bearer.
|
|
@@ -434,10 +441,15 @@ What a check does and does not prove:
|
|
|
434
441
|
Notes:
|
|
435
442
|
|
|
436
443
|
- `/testing/server` depends on the official MCP client, which adds install weight. The root `@lovable.dev/mcp-js` import never loads it.
|
|
437
|
-
-
|
|
444
|
+
- All three testing subpaths support ESM and CommonJS on Node 20 or later. The browser fixture requires explicit Playwright and compatible ext-apps dependencies.
|
|
438
445
|
- Keep these tests isolated from production data. Tool schemas are not sandboxed: run checks against servers you don't trust in a separate, externally time-bounded process.
|
|
439
446
|
|
|
440
|
-
See [`example/testing`](./example/testing) for
|
|
447
|
+
See [`example/testing`](./example/testing) for endpoint checks and the
|
|
448
|
+
[authenticated Apps example](example/apps-testing/README.md) for layered tests
|
|
449
|
+
with test JWTs and a compiled view. The [check contracts](src/testing/README.md)
|
|
450
|
+
name supported revisions, diagnostics and limitations. Live OAuth and external
|
|
451
|
+
services need separately authorized E2E checks. Package-contributor commands
|
|
452
|
+
live in [README.internal.md](README.internal.md#scripts).
|
|
441
453
|
|
|
442
454
|
## Security posture
|
|
443
455
|
|
|
@@ -549,11 +561,130 @@ In production the function is mounted at `https://<project-ref>.supabase.co/func
|
|
|
549
561
|
|
|
550
562
|
Ownership: the emitted `index.ts` carries a `// AUTO-GENERATED by @lovable.dev/mcp-js` banner. The plugin rewrites the banner-tagged file in place and cleans up orphans (including a `deno.json` left by a pre-bundling SDK version); banner-less files (yours) are never touched. Delete the banner line to take ownership. Deleting the `defineMcp` entry and re-running removes the SDK-owned function file.
|
|
551
563
|
|
|
564
|
+
## MCP Apps (interactive tool UI)
|
|
565
|
+
|
|
566
|
+
[MCP Apps](https://github.com/modelcontextprotocol/ext-apps) (SEP-1865, extension `io.modelcontextprotocol/ui`) let a tool ship an interactive view that a supporting host renders in a sandboxed iframe next to the tool result.
|
|
567
|
+
|
|
568
|
+
### MCP Apps beta policy
|
|
569
|
+
|
|
570
|
+
MCP Apps support is **beta**: host compatibility and authoring behavior are still being validated. It uses the package's normal public API names and release versions, not an experimental namespace or a permanent RC channel. Public API changes follow the package's normal semantic-versioning policy; breaking changes require a major version and migration guidance. This maturity label applies to MCP Apps, not the generic testing kit shipped in 3.1.0.
|
|
571
|
+
|
|
572
|
+
The view-build pipeline supports TanStack/Vite only, not the Supabase Edge Functions stack. On 2026-10-29, three synthetic TanStack apps deployed on Lovable Cloud using `3.4.0-gitee959cd` were tested with MCP Inspector 2.13.0 in Chrome on macOS: a public calculator's rendered view called its tool; OAuth-backed tasks persisted across reconnects and rejected a cross-user mutation; an OAuth-backed ticket app restricted views by role and persisted an operator's resolution. Both authenticated apps completed real OAuth sign-in, consent and token exchange. These were assisted builds with explicit integration guidance, not an unguided authoring benchmark.
|
|
573
|
+
|
|
574
|
+
Real-host interoperability with ChatGPT and Claude remains unverified. These checks and the local protocol/browser fixtures do not establish compatibility with every host or validate every app's authorization; test your app with its intended host and real authentication before release. Hosts without MCP Apps support receive the tool's text fallback.
|
|
575
|
+
|
|
576
|
+
Builder feature flags can control whether MCP Apps authoring is offered or taught; they do not change installed SDK behavior or revoke installed apps. Adopting an SDK fix requires updating the dependency and rebuilding and redeploying the app.
|
|
577
|
+
|
|
578
|
+
### Define a view
|
|
579
|
+
|
|
580
|
+
A view is a folder with an `index.html` entry, imported with the `?mcp-app` suffix and wrapped in `defineApp`:
|
|
581
|
+
|
|
582
|
+
```
|
|
583
|
+
src/lib/mcp/
|
|
584
|
+
├── index.ts
|
|
585
|
+
├── tools/sales-summary.ts
|
|
586
|
+
└── apps/sales/
|
|
587
|
+
├── index.html
|
|
588
|
+
├── main.tsx
|
|
589
|
+
└── styles.css
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
```ts
|
|
593
|
+
// src/lib/mcp/apps/sales.ts
|
|
594
|
+
import { defineApp } from "@lovable.dev/mcp-js";
|
|
595
|
+
import html from "./sales/index.html?mcp-app";
|
|
596
|
+
|
|
597
|
+
export const salesApp = defineApp({ name: "sales", title: "Sales dashboard", html });
|
|
598
|
+
```
|
|
599
|
+
|
|
600
|
+
```ts
|
|
601
|
+
// src/lib/mcp/tools/sales-summary.ts
|
|
602
|
+
import { defineTool } from "@lovable.dev/mcp-js";
|
|
603
|
+
import { z } from "zod";
|
|
604
|
+
import { salesApp } from "../apps/sales";
|
|
605
|
+
|
|
606
|
+
export default defineTool({
|
|
607
|
+
name: "sales_summary",
|
|
608
|
+
title: "Sales summary",
|
|
609
|
+
description: "Monthly sales totals.",
|
|
610
|
+
inputSchema: { months: z.number().int().min(1).max(24) },
|
|
611
|
+
outputSchema: { rows: z.array(z.object({ month: z.string(), total: z.number() })) },
|
|
612
|
+
ui: { app: salesApp },
|
|
613
|
+
handler: async ({ months }) => {
|
|
614
|
+
const rows = await loadSales(months);
|
|
615
|
+
return { content: [{ type: "text", text: `${rows.length} months` }], structuredContent: { rows } };
|
|
616
|
+
},
|
|
617
|
+
});
|
|
618
|
+
```
|
|
619
|
+
|
|
620
|
+
Use the official `@modelcontextprotocol/ext-apps@^1.7.3` browser SDK. The browser testing fixture checks its resolved bridge before starting the host and supports stable >=1.7.3 <2. Preserve compatible project pins; explain incompatible pins and agree a dependency change rather than automatically replacing them. The [executable React view](example/tanstack/src/lib/mcp/apps/sum/main.tsx) shows pre-connect handlers, delivered results, user-initiated calls, cancellation, teardown, host styles and optional model-context/message support. Its built HTML runs in the browser contract suite.
|
|
621
|
+
|
|
622
|
+
`defineMcp` is unchanged — list the tool as usual. Apps are derived from `tool.ui.app`; several tools may share one app.
|
|
623
|
+
|
|
624
|
+
App-only helper tools can declare `ui: { visibility: ["app"] }` without attaching a view. This emits visibility metadata but no resource link or extra resource. Omit `visibility` for both model and app access; `["model"]` asks hosts to reject calls from views. Visibility is a host routing rule, never server authorization. The package keeps its meaningful-`content` requirement for visibility-only tools too.
|
|
625
|
+
|
|
626
|
+
### Portable view behavior
|
|
627
|
+
|
|
628
|
+
These authoring practices complement the [protocol requirements](https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx); they are not additional wire requirements enforced by the compiler.
|
|
629
|
+
|
|
630
|
+
| Concern | Authoring contract |
|
|
631
|
+
| --- | --- |
|
|
632
|
+
| Lifecycle | Register input/result/cancel handlers in `onAppCreated`, before connection. Render delivered results; mounting or restoring a view must not replay a mutation. Partial inputs are preview-only. Clean up subscriptions, timers and outstanding requests on teardown/unmount; ignore stale completions. |
|
|
633
|
+
| Host adaptation | Apply initial and changing context with official SDK helpers. Consume host style variables/fonts with local fallbacks, merge partial context, respect safe areas and use the actual granted display mode. Check capabilities and handle rejected operations. Keep loading, empty, error, retry and keyboard paths usable at narrow widths. Pause expensive offscreen work when present. |
|
|
634
|
+
| Model context | Send concise selections or staged edits with `updateModelContext`; clear obsolete selection context. This does not request a conversational reply. Use `sendMessage` only for an explicit follow-up action, and only where supported. |
|
|
635
|
+
| State | Keep transient state local. Browser storage may be denied or evicted; optional recovery can use a server-provided view ID, with error handling. Save valuable work through authorized server tools. A view ID is not an identity or permission. |
|
|
636
|
+
| Security | The iframe is not your app's origin: do not depend on its cookies or relative API URLs. Prefer host-mediated tool calls. Keep CSP/permissions minimal; CSP does not grant CORS access, and permissions may be refused. Neither HTML nor result `_meta` is a place for credentials. |
|
|
637
|
+
|
|
638
|
+
**Build.** `mcpPlugin()` handles `?mcp-app` by compiling the view into one HTML string containing its JavaScript, CSS and imported assets. The string lives in the server-side MCP entry; client code cannot value-import that entry or its views. The nested build does not load the project's Vite/PostCSS configuration, tsconfig or dotenv files.
|
|
639
|
+
|
|
640
|
+
Apps compilation requires stable Vite >=5.0.0 <9.0.0 and rejects unsupported versions when compiling a view, not when importing the plugin. Plain HTML views do not require ext-apps; its version check belongs to the browser testing fixture. Ordinary MCP paths do not run either Apps compatibility check.
|
|
641
|
+
|
|
642
|
+
Install `lightningcss@^1.33.0` as a development dependency for Apps builds (`bun add -D lightningcss@^1.33.0`); preserve an existing compatible pin. It is an optional SDK peer loaded only when compiling a view. Ordinary MCP tools and runtime-only consumers do not need it. The generated HTML contains compiled CSS, not the compiler.
|
|
643
|
+
|
|
644
|
+
**Browser sources.** A view can read its own `src/lib/mcp/apps/<name>/` folder, shared `src/browser/` files and trusted npm dependencies. This applies transitively to modules, stylesheets and local assets, after resolving symlinks. Other project sources, Node builtins, server APIs and `*.server.*` files fail the build. Treat both browser folders as publishable; moving a file there does not remove secrets from it. Installed dependency code and build tooling remain trusted: this is not an OS sandbox.
|
|
645
|
+
|
|
646
|
+
**Reuse.** Move the components, browser helpers, assets and theme needed by both experiences into `src/browser/`, then update the normal app's imports. Keep data loading and routing in each experience's entrypoint. Small components taking data and callbacks as props make reuse straightforward; browser-safe hooks and local state are supported. Reuse is optional: a view may own its UI and styles entirely.
|
|
647
|
+
|
|
648
|
+
**Styling contract.** Target plain CSS or the current TanStack template's CSS-first Tailwind v4. Share theme CSS, not the normal app's scanning entrypoint:
|
|
649
|
+
|
|
650
|
+
| File | Contents |
|
|
651
|
+
| --- | --- |
|
|
652
|
+
| `src/browser/theme.css` | Shared `@theme`, variables, dark-mode rules, `@utility` definitions and ordinary CSS; no filesystem source scanning |
|
|
653
|
+
| `src/styles.css` | Normal app's Tailwind import and source scanning; imports `./browser/theme.css` |
|
|
654
|
+
| `src/lib/mcp/apps/<name>/styles.css` | View's Tailwind import and shared theme import; compiler scans this view and `src/browser/` |
|
|
655
|
+
|
|
656
|
+
The view's style entry is:
|
|
657
|
+
|
|
658
|
+
```css
|
|
659
|
+
@import "tailwindcss" source(none);
|
|
660
|
+
@import "@/browser/theme.css";
|
|
661
|
+
```
|
|
662
|
+
|
|
663
|
+
Install `@tailwindcss/vite` and `tailwindcss` in the project for Tailwind compilation. Filesystem `@source`/`source(path)` overrides are unsupported; `@source inline(...)` safelists remain available. Project-local JavaScript `@config`/`@plugin`, CSS modules and preprocessors are unsupported; express themes/utilities in CSS and use trusted installed npm plugins. Existing apps can migrate the reused subset, keep view-local CSS, or omit MCP Apps. See the [shared theme](example/tanstack/src/browser/theme.css), [normal entry](example/tanstack/src/styles.css), and [view entry](example/tanstack/src/lib/mcp/apps/sum/styles.css).
|
|
664
|
+
|
|
665
|
+
Keep local `image-set()` assets in ordinary CSS declarations such as `background`, not custom properties. Relative URLs in custom properties are ambiguous during bundling; use already-resolved data or external URLs there.
|
|
666
|
+
|
|
667
|
+
**Assets.** Import local images/fonts from JavaScript or CSS. Static `new URL("./asset.svg", import.meta.url)` is supported; computed asset paths, workers and computed dynamic imports are not. Keep HTML to the module-script entry and stylesheet links: local HTML asset URLs, `srcset`, inline CSS, classic scripts and `<base>` fail with an authoring diagnostic. `public/` is not served with a `ui://` resource. Runtime-generated URLs are not validated; `/logo.svg` would resolve against the host, not your app. Explicit external URLs remain external and need the corresponding CSP declaration and host permission.
|
|
668
|
+
|
|
669
|
+
**Wire format.** With at least one allowed app, the server advertises `capabilities.extensions["io.modelcontextprotocol/ui"]`, lists each allowed app as a `ui://apps/<name>` resource with MIME type `text/html;profile=mcp-app` and `_meta.ui` (`csp`, `permissions`, `domain`, `prefersBorder` when set), and puts `_meta.ui.resourceUri` (plus the pre-spec `ui/resourceUri` alias current hosts read) on the tool in `tools/list`. Servers with declared apps retain resource methods even when all views are hidden. Both protocol eras carry the same UI metadata. A UI tool's success and error results must include meaningful `content` for hosts without app support; empty content is replaced with an output-error diagnostic. `ui.visibility: ["app"]` asks supporting hosts to expose the tool only to the view; it does not prevent direct tool calls or replace handler authorization.
|
|
670
|
+
|
|
671
|
+
Handlers may return top-level `_meta` for additional view data without adding it to model-facing content. Use JSON-serializable values and do not include secrets: the MCP client receives this metadata. Accepted success and error results preserve it; validation-generated replacement errors discard the rejected result's data and metadata.
|
|
672
|
+
|
|
673
|
+
**View access.** After the endpoint's authentication and CORS checks, a view is listed and readable only if at least one tool linking it is enabled for the caller. An unconditional link grants access; all links share the request's context and each relevant predicate runs once. Hidden views return the same unknown-resource error as nonexistent URIs. Context or predicate failures fail the request with a redacted 500, even when another link grants access. Modern resource responses use `ttlMs: 0` and `cacheScope: "private"`; HTTP responses use `no-store`.
|
|
674
|
+
|
|
675
|
+
**Data boundary.** View HTML is static code, not per-user data. Hiding a view cannot revoke copies already downloaded. Keep secrets and user data out of the HTML; fetch protected data through tools with handler, service, or RLS authorization. The publish manifest remains the complete build-time catalog.
|
|
676
|
+
|
|
677
|
+
Render untrusted tool data as JSX children or `textContent`, never `innerHTML`; injected scripts in a view can call tools as the user.
|
|
678
|
+
|
|
679
|
+
**Development.** Views are rebuilt when their files change during `vite dev`. To try a view, connect a host with MCP Apps support to the deployed `/mcp` URL; the [ext-apps basic host](https://github.com/modelcontextprotocol/ext-apps/tree/main/examples/basic-host) works locally.
|
|
680
|
+
|
|
681
|
+
**Supabase stack.** Not supported: the emit step fails with an actionable error on any `?mcp-app` import.
|
|
682
|
+
|
|
552
683
|
## Subpath exports
|
|
553
684
|
|
|
554
685
|
| Subpath | Contents |
|
|
555
686
|
| --------------------------------------- | ----------------------------------------------------------------------- |
|
|
556
|
-
| `@lovable.dev/mcp-js` | `defineTool`, `defineMcp`, public types
|
|
687
|
+
| `@lovable.dev/mcp-js` | `defineTool`, `defineApp`, `defineMcp`, public types |
|
|
557
688
|
| `@lovable.dev/mcp-js/skill-imports` | Type-only declarations for skill directory imports |
|
|
558
689
|
| `@lovable.dev/mcp-js/protocols/mcp` | `createMcpProtocolHandler` — Web-Standard MCP-over-HTTP |
|
|
559
690
|
| `@lovable.dev/mcp-js/protocols/oauth-metadata` | `createOAuthProtectedResourceMetadataHandler` (the `auth` namespace lives at the root) |
|
|
@@ -561,7 +692,8 @@ Ownership: the emitted `index.ts` carries a `// AUTO-GENERATED by @lovable.dev/m
|
|
|
561
692
|
| `@lovable.dev/mcp-js/stacks/tanstack/vite` | The Vite plugin |
|
|
562
693
|
| `@lovable.dev/mcp-js/stacks/supabase` | `createSupabaseHandler` — Web-Standard Supabase Edge Function dispatcher |
|
|
563
694
|
| `@lovable.dev/mcp-js/stacks/supabase/vite` | `mcpPlugin` — the Vite plugin (Supabase variant; same name as TanStack's, picked by import path) |
|
|
564
|
-
| `@lovable.dev/mcp-js/testing`
|
|
565
|
-
| `@lovable.dev/mcp-js/testing/server`
|
|
695
|
+
| `@lovable.dev/mcp-js/testing` | `assertToolResult`, value-redacted diagnostics |
|
|
696
|
+
| `@lovable.dev/mcp-js/testing/server` | `withMcpClient`, `checkMcpServer`, `readUiResource` |
|
|
697
|
+
| `@lovable.dev/mcp-js/testing/browser` | `createAppFixture` (install Playwright and `@modelcontextprotocol/ext-apps@^1.7.3` explicitly) |
|
|
566
698
|
|
|
567
|
-
|
|
699
|
+
App runtime code uses the root import (`@lovable.dev/mcp-js`). Generated route files import from `@lovable.dev/mcp-js/stacks/tanstack` (TanStack) or `@lovable.dev/mcp-js/stacks/supabase` (Supabase). Testing entrypoints are optional and are not imported by those runtime routes.
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
This package bundles portions of the following libraries.
|
|
2
|
+
|
|
3
|
+
parse5 7.3.0
|
|
4
|
+
https://github.com/inikulin/parse5
|
|
5
|
+
|
|
6
|
+
Copyright (c) 2013-2019 Ivan Nikulin (ifaaan@gmail.com, https://github.com/inikulin)
|
|
7
|
+
|
|
8
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
9
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
10
|
+
in the Software without restriction, including without limitation the rights
|
|
11
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
12
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
13
|
+
furnished to do so, subject to the following conditions:
|
|
14
|
+
|
|
15
|
+
The above copyright notice and this permission notice shall be included in
|
|
16
|
+
all copies or substantial portions of the Software.
|
|
17
|
+
|
|
18
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
19
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
20
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
21
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
22
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
23
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
24
|
+
THE SOFTWARE.
|
|
25
|
+
|
|
26
|
+
estree-walker 3.0.3
|
|
27
|
+
https://github.com/Rich-Harris/estree-walker
|
|
28
|
+
|
|
29
|
+
Copyright (c) 2015-20 [these people](https://github.com/Rich-Harris/estree-walker/graphs/contributors)
|
|
30
|
+
|
|
31
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
32
|
+
|
|
33
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
34
|
+
|
|
35
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
|
36
|
+
|
|
37
|
+
mrmime 2.0.1
|
|
38
|
+
https://github.com/lukeed/mrmime
|
|
39
|
+
|
|
40
|
+
The MIT License (MIT)
|
|
41
|
+
|
|
42
|
+
Copyright (c) Luke Edwards <luke.edwards05@gmail.com> (https://lukeed.com)
|
|
43
|
+
|
|
44
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
45
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
46
|
+
in the Software without restriction, including without limitation the rights
|
|
47
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
48
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
49
|
+
furnished to do so, subject to the following conditions:
|
|
50
|
+
|
|
51
|
+
The above copyright notice and this permission notice shall be included in
|
|
52
|
+
all copies or substantial portions of the Software.
|
|
53
|
+
|
|
54
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
55
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
56
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
57
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
58
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
59
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
|
60
|
+
THE SOFTWARE.
|
|
61
|
+
|
|
62
|
+
entities 6.0.1
|
|
63
|
+
https://github.com/fb55/entities
|
|
64
|
+
|
|
65
|
+
Copyright (c) Felix Böhm
|
|
66
|
+
All rights reserved.
|
|
67
|
+
|
|
68
|
+
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
|
|
69
|
+
|
|
70
|
+
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
|
|
71
|
+
|
|
72
|
+
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
|
|
73
|
+
|
|
74
|
+
THIS IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS,
|
|
75
|
+
EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
//#region src/core/apps.ts
|
|
2
|
+
/** Extension id and resource MIME type from the MCP Apps spec (SEP-1865). */
|
|
3
|
+
const UI_EXTENSION_ID = "io.modelcontextprotocol/ui";
|
|
4
|
+
const APP_RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
|
|
5
|
+
const APP_NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
|
|
6
|
+
const CSP_KEYS = [
|
|
7
|
+
"connectDomains",
|
|
8
|
+
"resourceDomains",
|
|
9
|
+
"frameDomains",
|
|
10
|
+
"baseUriDomains"
|
|
11
|
+
];
|
|
12
|
+
const PERMISSION_KEYS = [
|
|
13
|
+
"camera",
|
|
14
|
+
"microphone",
|
|
15
|
+
"geolocation",
|
|
16
|
+
"clipboardWrite"
|
|
17
|
+
];
|
|
18
|
+
const VISIBILITY_VALUES = ["model", "app"];
|
|
19
|
+
function appResourceUri(name) {
|
|
20
|
+
return `ui://apps/${name}`;
|
|
21
|
+
}
|
|
22
|
+
function isPlainObject(value) {
|
|
23
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
24
|
+
}
|
|
25
|
+
function assertAppDefinitionInput(def) {
|
|
26
|
+
if (typeof def.name !== "string" || !APP_NAME_PATTERN.test(def.name)) throw new Error(`@lovable.dev/mcp-js: app name ${JSON.stringify(def.name)} must be a non-empty token of letters, digits, "_" or "-"`);
|
|
27
|
+
if (typeof def.title !== "string" || def.title.trim() === "") throw new Error(`@lovable.dev/mcp-js: app "${def.name}" title must not be empty`);
|
|
28
|
+
if (def.description !== void 0 && typeof def.description !== "string") throw new Error(`@lovable.dev/mcp-js: app "${def.name}" description must be a string`);
|
|
29
|
+
if (typeof def.html !== "string") throw new Error(`@lovable.dev/mcp-js: app "${def.name}" html must be a string; import it as "./apps/${def.name}/index.html?mcp-app"`);
|
|
30
|
+
assertAppServable(def);
|
|
31
|
+
if (def.csp !== void 0) {
|
|
32
|
+
if (!isPlainObject(def.csp)) throw new Error(`@lovable.dev/mcp-js: app "${def.name}" csp must be an object`);
|
|
33
|
+
for (const key of Object.keys(def.csp)) {
|
|
34
|
+
if (!CSP_KEYS.includes(key)) throw new Error(`@lovable.dev/mcp-js: app "${def.name}" csp has unknown key "${key}"`);
|
|
35
|
+
const value = def.csp[key];
|
|
36
|
+
if (value !== void 0 && (!Array.isArray(value) || value.some((v) => typeof v !== "string"))) throw new Error(`@lovable.dev/mcp-js: app "${def.name}" csp.${key} must be an array of origins`);
|
|
37
|
+
assertCspOrigins(def.name, key, value);
|
|
38
|
+
}
|
|
39
|
+
}
|
|
40
|
+
if (def.permissions !== void 0) {
|
|
41
|
+
if (!isPlainObject(def.permissions)) throw new Error(`@lovable.dev/mcp-js: app "${def.name}" permissions must be an object`);
|
|
42
|
+
for (const key of Object.keys(def.permissions)) {
|
|
43
|
+
if (!PERMISSION_KEYS.includes(key)) throw new Error(`@lovable.dev/mcp-js: app "${def.name}" permissions has unknown key "${key}" (allowed: ${PERMISSION_KEYS.join(", ")})`);
|
|
44
|
+
const value = def.permissions[key];
|
|
45
|
+
if (value !== void 0 && (!isPlainObject(value) || Object.keys(value).length > 0)) throw new Error(`@lovable.dev/mcp-js: app "${def.name}" permissions.${key} must be an empty object`);
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
if (def.domain !== void 0 && (typeof def.domain !== "string" || def.domain.trim() === "")) throw new Error(`@lovable.dev/mcp-js: app "${def.name}" domain must be a non-empty string`);
|
|
49
|
+
if (def.prefersBorder !== void 0 && typeof def.prefersBorder !== "boolean") throw new Error(`@lovable.dev/mcp-js: app "${def.name}" prefersBorder must be a boolean`);
|
|
50
|
+
}
|
|
51
|
+
function freezeApp(def) {
|
|
52
|
+
if (def.csp) {
|
|
53
|
+
for (const key of CSP_KEYS) if (def.csp[key]) Object.freeze(def.csp[key]);
|
|
54
|
+
Object.freeze(def.csp);
|
|
55
|
+
}
|
|
56
|
+
if (def.permissions) {
|
|
57
|
+
for (const key of PERMISSION_KEYS) if (def.permissions[key]) Object.freeze(def.permissions[key]);
|
|
58
|
+
Object.freeze(def.permissions);
|
|
59
|
+
}
|
|
60
|
+
Object.freeze(def);
|
|
61
|
+
}
|
|
62
|
+
function assertToolUi(tool) {
|
|
63
|
+
const ui = tool.ui;
|
|
64
|
+
if (ui === void 0) return;
|
|
65
|
+
if (!isPlainObject(ui) || ui.app === void 0 && ui.visibility === void 0) throw new Error(`@lovable.dev/mcp-js: tool "${tool.name}" ui must declare an app or visibility`);
|
|
66
|
+
if (ui.app !== void 0) {
|
|
67
|
+
if (!isPlainObject(ui.app)) throw new Error(`@lovable.dev/mcp-js: tool "${tool.name}" ui.app must be a defineApp(...) result`);
|
|
68
|
+
try {
|
|
69
|
+
assertAppDefinitionInput(ui.app);
|
|
70
|
+
} catch (error) {
|
|
71
|
+
const detail = error instanceof Error ? error.message.replace(/^@lovable\.dev\/mcp-js: /, "") : String(error);
|
|
72
|
+
throw new Error(`@lovable.dev/mcp-js: tool "${tool.name}" ui.app is invalid: ${detail}`);
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
if (ui.visibility === void 0) return;
|
|
76
|
+
if (!Array.isArray(ui.visibility) || ui.visibility.length === 0) throw new Error(`@lovable.dev/mcp-js: tool "${tool.name}" ui.visibility must be a non-empty array`);
|
|
77
|
+
for (const value of ui.visibility) if (!VISIBILITY_VALUES.includes(value)) throw new Error(`@lovable.dev/mcp-js: tool "${tool.name}" ui.visibility contains ${JSON.stringify(value)} (allowed: ${VISIBILITY_VALUES.join(", ")})`);
|
|
78
|
+
if (new Set(ui.visibility).size !== ui.visibility.length) throw new Error(`@lovable.dev/mcp-js: tool "${tool.name}" ui.visibility must not repeat values`);
|
|
79
|
+
}
|
|
80
|
+
function freezeToolUi(tool) {
|
|
81
|
+
if (!tool.ui) return;
|
|
82
|
+
if (tool.ui.app) freezeApp(tool.ui.app);
|
|
83
|
+
if (tool.ui.visibility) Object.freeze(tool.ui.visibility);
|
|
84
|
+
Object.freeze(tool.ui);
|
|
85
|
+
}
|
|
86
|
+
/** Distinct apps referenced by `tools[].ui.app`, in first-use order. Several
|
|
87
|
+
* tools may share one app; two different apps may not share a name. */
|
|
88
|
+
function collectApps(tools) {
|
|
89
|
+
const apps = [];
|
|
90
|
+
const byName = /* @__PURE__ */ new Map();
|
|
91
|
+
for (const tool of tools) {
|
|
92
|
+
const app = tool.ui?.app;
|
|
93
|
+
if (!app) continue;
|
|
94
|
+
const existing = byName.get(app.name);
|
|
95
|
+
if (existing === app) continue;
|
|
96
|
+
if (existing !== void 0) throw new Error(`@lovable.dev/mcp-js: two different apps share the name "${app.name}"`);
|
|
97
|
+
byName.set(app.name, app);
|
|
98
|
+
apps.push(app);
|
|
99
|
+
}
|
|
100
|
+
return apps;
|
|
101
|
+
}
|
|
102
|
+
const ORIGIN_PROTOCOLS = /* @__PURE__ */ new Set([
|
|
103
|
+
"http:",
|
|
104
|
+
"https:",
|
|
105
|
+
"ws:",
|
|
106
|
+
"wss:"
|
|
107
|
+
]);
|
|
108
|
+
function isExactOrigin(value) {
|
|
109
|
+
let parsed;
|
|
110
|
+
try {
|
|
111
|
+
parsed = new URL(value);
|
|
112
|
+
} catch {
|
|
113
|
+
return false;
|
|
114
|
+
}
|
|
115
|
+
return ORIGIN_PROTOCOLS.has(parsed.protocol) && !parsed.host.includes("*") && `${parsed.protocol}//${parsed.host}` === value;
|
|
116
|
+
}
|
|
117
|
+
function assertCspOrigins(appName, key, values) {
|
|
118
|
+
if (!values) return;
|
|
119
|
+
for (const value of values) if (!isExactOrigin(key === "resourceDomains" ? value.replace(/^(https?|wss?):\/\/\*\./, "$1://wildcard.") : value)) throw new Error(`@lovable.dev/mcp-js: app "${appName}" csp.${key} entry "${value}" must be an exact http(s)/ws(s) origin without a path, query, fragment, or trailing slash`);
|
|
120
|
+
}
|
|
121
|
+
const HTML_DOCTYPE = /^<!doctype[\t\n\f\r ]+html[\s>]/i;
|
|
122
|
+
function assertAppServable(app) {
|
|
123
|
+
let html = app.html.trimStart();
|
|
124
|
+
while (html.startsWith("<!--")) {
|
|
125
|
+
const end = html.indexOf("-->");
|
|
126
|
+
if (end === -1) break;
|
|
127
|
+
html = html.slice(end + 3).trimStart();
|
|
128
|
+
}
|
|
129
|
+
if (!HTML_DOCTYPE.test(html)) throw new Error(`@lovable.dev/mcp-js: app "${app.name}" html must include an HTML5 <!doctype html> after any leading whitespace or comments. Import the document with "?mcp-app" using the TanStack Vite plugin (MCP Apps are not supported on the Supabase stack).`);
|
|
130
|
+
}
|
|
131
|
+
//#endregion
|
|
132
|
+
export { assertAppServable as a, freezeApp as c, assertAppDefinitionInput as i, freezeToolUi as l, UI_EXTENSION_ID as n, assertToolUi as o, appResourceUri as r, collectApps as s, APP_RESOURCE_MIME_TYPE as t };
|