@lovable.dev/mcp-js 0.22.1 → 0.22.2-rc.1

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.
Files changed (87) hide show
  1. package/dist/authorize-CumVyk7p.d.cts +27 -0
  2. package/dist/authorize-D6p4-9_D.d.ts +27 -0
  3. package/dist/base-DCe0kP79.d.cts +29 -0
  4. package/dist/base-DCe0kP79.d.ts +29 -0
  5. package/dist/cli/extract-manifest.cjs +116 -201
  6. package/dist/cli/extract-manifest.d.cts +1 -1
  7. package/dist/cli/extract-manifest.d.ts +1 -1
  8. package/dist/cli/extract-manifest.js +117 -156
  9. package/dist/content-D5LJAHyM.js +12 -0
  10. package/dist/content-NCYIGgOb.cjs +17 -0
  11. package/dist/context-BweeEcoA.cjs +56 -0
  12. package/dist/context-CIpPzN7P.js +51 -0
  13. package/dist/cors-C2n2LxrC.js +830 -0
  14. package/dist/cors-Cga2PWEg.cjs +913 -0
  15. package/dist/forwarded--h4efJy-.js +43 -0
  16. package/dist/forwarded-Pi8Hs5Ps.cjs +48 -0
  17. package/dist/fs-errors-CWNzOV75.cjs +11 -0
  18. package/dist/fs-errors-PA2t1TIp.js +6 -0
  19. package/dist/index.cjs +129 -329
  20. package/dist/index.d.cts +26 -26
  21. package/dist/index.d.ts +26 -26
  22. package/dist/index.js +118 -177
  23. package/dist/{io-D4srzRKc.d.ts → io-CfSPxeBN.d.ts} +6 -4
  24. package/dist/io-DPYvBqET.d.cts +15 -0
  25. package/dist/list-tools-07OV14rK.cjs +57 -0
  26. package/dist/list-tools-B4TTPEl1.d.cts +8 -0
  27. package/dist/list-tools-I8Hvub9P.js +46 -0
  28. package/dist/list-tools-bh6-eqZM.d.ts +8 -0
  29. package/dist/logger-2OXtfiIW.js +141 -0
  30. package/dist/logger-BqPOa_E1.cjs +194 -0
  31. package/dist/mcp-B6z5Givq.js +123 -0
  32. package/dist/mcp-DLv_c1O5.cjs +128 -0
  33. package/dist/metadata-path-CAkNcfyY.js +12 -0
  34. package/dist/metadata-path-zd7NSNoa.cjs +17 -0
  35. package/dist/package-CxQcGWdU.cjs +9 -0
  36. package/dist/package-xS6mk-b_.js +4 -0
  37. package/dist/paths-IS65L6TA.js +7 -0
  38. package/dist/paths-OP318a6c.cjs +18 -0
  39. package/dist/protocols/mcp/index.cjs +3 -750
  40. package/dist/protocols/mcp/index.d.cts +6 -7
  41. package/dist/protocols/mcp/index.d.ts +6 -7
  42. package/dist/protocols/mcp/index.js +2 -12
  43. package/dist/protocols/oauth-metadata.cjs +48 -539
  44. package/dist/protocols/oauth-metadata.d.cts +5 -6
  45. package/dist/protocols/oauth-metadata.d.ts +5 -6
  46. package/dist/protocols/oauth-metadata.js +52 -10
  47. package/dist/protocols/rest/index.cjs +5 -843
  48. package/dist/protocols/rest/index.d.cts +7 -10
  49. package/dist/protocols/rest/index.d.ts +7 -10
  50. package/dist/protocols/rest/index.js +3 -16
  51. package/dist/rest-CggWx00c.js +117 -0
  52. package/dist/rest-DxhK7-3b.cjs +122 -0
  53. package/dist/stacks/supabase/index.cjs +76 -1318
  54. package/dist/stacks/supabase/index.d.cts +29 -30
  55. package/dist/stacks/supabase/index.d.ts +29 -30
  56. package/dist/stacks/supabase/index.js +73 -89
  57. package/dist/stacks/supabase/vite.cjs +258 -287
  58. package/dist/stacks/supabase/vite.d.cts +24 -24
  59. package/dist/stacks/supabase/vite.d.ts +24 -24
  60. package/dist/stacks/supabase/vite.js +252 -252
  61. package/dist/stacks/tanstack/index.cjs +42 -1272
  62. package/dist/stacks/tanstack/index.d.cts +8 -9
  63. package/dist/stacks/tanstack/index.d.ts +8 -9
  64. package/dist/stacks/tanstack/index.js +36 -41
  65. package/dist/stacks/tanstack/vite.cjs +223 -312
  66. package/dist/stacks/tanstack/vite.d.cts +80 -81
  67. package/dist/stacks/tanstack/vite.d.ts +80 -81
  68. package/dist/stacks/tanstack/vite.js +216 -282
  69. package/dist/types-BYdYYTjk.d.cts +321 -0
  70. package/dist/types-BYdYYTjk.d.ts +321 -0
  71. package/package.json +4 -4
  72. package/dist/authorize-BMeXd_Sh.d.ts +0 -25
  73. package/dist/base-CM-KCpp6.d.ts +0 -28
  74. package/dist/chunk-5HVSJCKE.js +0 -114
  75. package/dist/chunk-6DXGZZA4.js +0 -6
  76. package/dist/chunk-6QFZYYUV.js +0 -11
  77. package/dist/chunk-6SZOFKGH.js +0 -58
  78. package/dist/chunk-H37EB22A.js +0 -125
  79. package/dist/chunk-IFDWUM7L.js +0 -741
  80. package/dist/chunk-IXZIFYO6.js +0 -79
  81. package/dist/chunk-MA5H6PSF.js +0 -46
  82. package/dist/chunk-TJN33K5U.js +0 -141
  83. package/dist/chunk-UQK5UO6C.js +0 -26
  84. package/dist/chunk-XQWJN6DC.js +0 -14
  85. package/dist/chunk-Y3ZFPEQH.js +0 -8
  86. package/dist/chunk-ZQXSWTPU.js +0 -6
  87. package/dist/types-qqrmJ736.d.ts +0 -321
@@ -1,79 +0,0 @@
1
- import {
2
- JSON_HEADERS,
3
- corsPreflightResponse,
4
- getOAuthRuntime,
5
- headResponse,
6
- methodNotAllowed,
7
- oauthConfigurationErrorResponse,
8
- resolveProtectedResource,
9
- withCors
10
- } from "./chunk-IFDWUM7L.js";
11
- import {
12
- describeError,
13
- log
14
- } from "./chunk-H37EB22A.js";
15
-
16
- // src/protocols/oauth-metadata.ts
17
- function notFound() {
18
- return withCors(
19
- new Response(JSON.stringify({ error: "not found" }), {
20
- status: 404,
21
- // `no-store` so a 404 (OAuth unconfigured) isn't heuristically cached and
22
- // then served past a later deploy that enables OAuth and starts returning 200.
23
- headers: { ...JSON_HEADERS, "Cache-Control": "no-store" }
24
- })
25
- );
26
- }
27
- async function buildProtectedResourceMetadata(mcp, auth, request, options, discovery) {
28
- const issuer = await discovery.resolveIssuer();
29
- const body = {
30
- resource: resolveProtectedResource(auth, request, options),
31
- authorization_servers: [issuer],
32
- bearer_methods_supported: ["header"],
33
- resource_name: auth.resourceName ?? mcp.title,
34
- resource_documentation: auth.resourceDocumentation
35
- };
36
- if (auth.requiredScopes && auth.requiredScopes.length > 0)
37
- body.scopes_supported = auth.requiredScopes;
38
- return body;
39
- }
40
- function createOAuthProtectedResourceMetadataHandler(mcp, options = {}) {
41
- const runtime = getOAuthRuntime(mcp, options);
42
- if (runtime.kind === "configured" && runtime.auth.protectedResourceMetadataUrl === void 0 && runtime.auth.resource === void 0 && runtime.options.resourcePath === void 0) {
43
- throw new Error(
44
- `@lovable.dev/mcp-js: auth.resource or a resourcePath is required so the protected-resource metadata doesn't advertise the well-known URL as the resource`
45
- );
46
- }
47
- return async (request) => {
48
- if (runtime.kind !== "configured" || runtime.auth.protectedResourceMetadataUrl !== void 0)
49
- return notFound();
50
- if (request.method === "OPTIONS")
51
- return corsPreflightResponse("GET, HEAD, OPTIONS");
52
- if (request.method !== "GET" && request.method !== "HEAD")
53
- return withCors(methodNotAllowed("GET, HEAD, OPTIONS"));
54
- const headers = {
55
- ...JSON_HEADERS,
56
- "Cache-Control": "public, max-age=300",
57
- Vary: "Host"
58
- };
59
- try {
60
- const metadata = await buildProtectedResourceMetadata(
61
- mcp,
62
- runtime.auth,
63
- request,
64
- runtime.options,
65
- runtime.discovery
66
- );
67
- const response = withCors(Response.json(metadata, { headers }));
68
- return request.method === "HEAD" ? headResponse(response) : response;
69
- } catch (err) {
70
- log.error("oauth.metadata.config_error", { ...describeError(err), outcome: "500 oauth configuration error" });
71
- const response = withCors(oauthConfigurationErrorResponse());
72
- return request.method === "HEAD" ? headResponse(response) : response;
73
- }
74
- };
75
- }
76
-
77
- export {
78
- createOAuthProtectedResourceMetadataHandler
79
- };
@@ -1,46 +0,0 @@
1
- // src/auth/context.ts
2
- var ToolContext = class {
3
- #auth;
4
- constructor(auth) {
5
- this.#auth = auth;
6
- }
7
- /** Whether the in-flight tool call carries a verified auth context. */
8
- isAuthenticated() {
9
- return this.#auth !== void 0;
10
- }
11
- /** The verified bearer token, or `undefined` when unauthenticated. Pass it to downstream APIs; never return or log it. */
12
- getToken() {
13
- return this.#auth?.bearer.token;
14
- }
15
- /** The verified user id (the token `sub`), or `undefined`. */
16
- getUserId() {
17
- return this.#auth?.principal.sub;
18
- }
19
- /** The verified user email, or `undefined` when absent. */
20
- getUserEmail() {
21
- return this.#auth?.principal.email;
22
- }
23
- /** The verified OAuth `client_id`, or `undefined`. */
24
- getClientId() {
25
- return this.#auth?.principal.clientId;
26
- }
27
- /** The verified OAuth scopes, or `undefined` when unauthenticated. */
28
- getScopes() {
29
- return this.#auth?.principal.scopes;
30
- }
31
- /** The verified token issuer, or `undefined`. */
32
- getIssuer() {
33
- return this.#auth?.principal.issuer;
34
- }
35
- /**
36
- * The full verified JWT claims, or `undefined`. Use this for app/business
37
- * authorization on issuer-specific claims that have no dedicated accessor.
38
- */
39
- getClaims() {
40
- return this.#auth?.principal.claims;
41
- }
42
- };
43
-
44
- export {
45
- ToolContext
46
- };
@@ -1,141 +0,0 @@
1
- import {
2
- extractTextContent
3
- } from "./chunk-6QFZYYUV.js";
4
- import {
5
- ToolContext
6
- } from "./chunk-MA5H6PSF.js";
7
- import {
8
- JSON_HEADERS,
9
- assertRestResourceBinding,
10
- corsPreflightResponse,
11
- createNoopRecorder,
12
- createRequestAuthorizer,
13
- methodNotAllowed,
14
- nowMs,
15
- withCors
16
- } from "./chunk-IFDWUM7L.js";
17
-
18
- // src/protocols/rest/invoke-tool.ts
19
- import { getParseErrorMessage, objectFromShape, safeParseAsync } from "@modelcontextprotocol/sdk/server/zod-compat.js";
20
- var MAX_REFLECTED_TOOL_NAME = 256;
21
- function safeReflectName(name) {
22
- const text = String(name);
23
- return text.length > MAX_REFLECTED_TOOL_NAME ? `${text.slice(0, MAX_REFLECTED_TOOL_NAME)}\u2026` : text;
24
- }
25
- function isEmptyArgs(value) {
26
- if (value == null)
27
- return true;
28
- if (typeof value !== "object" || Array.isArray(value))
29
- return false;
30
- return Object.keys(value).length === 0;
31
- }
32
- function createInvokeToolHandler(mcp, options = {}) {
33
- assertRestResourceBinding(mcp, options);
34
- const authorizer = createRequestAuthorizer(mcp, options);
35
- const handle = async (request, toolName, recorder) => {
36
- const authResult = await authorizer.authorize(request, recorder);
37
- if (!authResult.ok)
38
- return authResult.response;
39
- const endUserId = authResult.auth?.principal.sub;
40
- if (request.method !== "POST")
41
- return methodNotAllowed("POST, OPTIONS");
42
- const tool = mcp.tools.find((t) => t.name === toolName);
43
- if (!tool) {
44
- return new Response(JSON.stringify({ error: `unknown tool: ${safeReflectName(toolName)}` }), {
45
- status: 404,
46
- headers: JSON_HEADERS
47
- });
48
- }
49
- let rawArgs = {};
50
- const text = await request.text();
51
- if (text) {
52
- try {
53
- rawArgs = JSON.parse(text);
54
- } catch {
55
- return new Response(JSON.stringify({ error: "invalid JSON body" }), {
56
- status: 400,
57
- headers: JSON_HEADERS
58
- });
59
- }
60
- }
61
- let args = rawArgs;
62
- if (tool.inputSchema) {
63
- try {
64
- const schema = objectFromShape(tool.inputSchema);
65
- const parsed = await safeParseAsync(schema, rawArgs);
66
- if (!parsed.success) {
67
- return new Response(
68
- JSON.stringify({
69
- error: "validation failed",
70
- details: getParseErrorMessage(parsed.error)
71
- }),
72
- { status: 400, headers: JSON_HEADERS }
73
- );
74
- }
75
- args = parsed.data;
76
- } catch {
77
- return new Response(JSON.stringify({ error: "schema error", tool: toolName }), {
78
- status: 500,
79
- headers: JSON_HEADERS
80
- });
81
- }
82
- } else if (!isEmptyArgs(rawArgs)) {
83
- return new Response(JSON.stringify({ error: "tool has no inputSchema; expected empty body" }), {
84
- status: 400,
85
- headers: JSON_HEADERS
86
- });
87
- }
88
- let result;
89
- const start = nowMs();
90
- try {
91
- result = await tool.handler(args, new ToolContext(authResult.auth));
92
- } catch {
93
- await recorder.emit({
94
- tool: tool.name,
95
- method: "tools/call",
96
- outcome: "handler_error",
97
- durationMs: nowMs() - start,
98
- endUserId
99
- });
100
- return new Response(JSON.stringify({ error: "handler threw", tool: toolName }), {
101
- status: 500,
102
- headers: JSON_HEADERS
103
- });
104
- }
105
- if (result == null) {
106
- await recorder.emit({
107
- tool: tool.name,
108
- method: "tools/call",
109
- outcome: "handler_error",
110
- durationMs: nowMs() - start,
111
- endUserId
112
- });
113
- return new Response(JSON.stringify({ error: `tool "${toolName}" returned no result` }), {
114
- status: 500,
115
- headers: JSON_HEADERS
116
- });
117
- }
118
- await recorder.emit({
119
- tool: tool.name,
120
- method: "tools/call",
121
- outcome: result.isError ? "tool_error" : "ok",
122
- durationMs: nowMs() - start,
123
- errorText: result.isError ? extractTextContent(result.content) : void 0,
124
- endUserId
125
- });
126
- return Response.json({
127
- content: result.content ?? [],
128
- structuredContent: result.structuredContent,
129
- isError: result.isError
130
- });
131
- };
132
- return async (request, toolName, recorder = createNoopRecorder()) => {
133
- if (request.method === "OPTIONS")
134
- return corsPreflightResponse("POST, OPTIONS");
135
- return withCors(await handle(request, toolName, recorder));
136
- };
137
- }
138
-
139
- export {
140
- createInvokeToolHandler
141
- };
@@ -1,26 +0,0 @@
1
- // src/core/forwarded.ts
2
- function applyForwardedOrigin(request, options) {
3
- const proto = options.trustForwardedProto ? firstForwardedValue(request, "x-forwarded-proto") : void 0;
4
- const host = options.trustForwardedHost ? firstForwardedValue(request, "x-forwarded-host") : void 0;
5
- if (proto === void 0 && host === void 0)
6
- return request;
7
- const url = new URL(request.url);
8
- let changed = false;
9
- if (proto !== void 0 && `${proto}:` !== url.protocol) {
10
- url.protocol = `${proto}:`;
11
- changed = true;
12
- }
13
- if (host !== void 0 && host !== url.host) {
14
- url.host = host;
15
- changed = true;
16
- }
17
- return changed ? new Request(url.href, request) : request;
18
- }
19
- function firstForwardedValue(request, header) {
20
- const value = request.headers.get(header)?.split(",")[0]?.trim();
21
- return value ? value : void 0;
22
- }
23
-
24
- export {
25
- applyForwardedOrigin
26
- };
@@ -1,14 +0,0 @@
1
- // src/stacks/supabase/paths.ts
2
- var FUNCTIONS_MOUNT_PREFIX = "/functions/v1/";
3
- function assertFunctionName(value, label = "functionName") {
4
- if (!/^[a-zA-Z0-9_-]+$/.test(value)) {
5
- throw new Error(
6
- `@lovable.dev/mcp-js: ${label} must be a single path segment matching [A-Za-z0-9_-], got ${JSON.stringify(value)}`
7
- );
8
- }
9
- }
10
-
11
- export {
12
- FUNCTIONS_MOUNT_PREFIX,
13
- assertFunctionName
14
- };
@@ -1,8 +0,0 @@
1
- // src/core/fs-errors.ts
2
- function isFileMissing(err) {
3
- return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
4
- }
5
-
6
- export {
7
- isFileMissing
8
- };
@@ -1,6 +0,0 @@
1
- // package.json
2
- var version = "0.22.1";
3
-
4
- export {
5
- version
6
- };
@@ -1,321 +0,0 @@
1
- import { ZodRawShape as ZodRawShape$1, ZodType, TypeOf } from 'zod';
2
-
3
- type JwtClaims = Record<string, unknown> & {
4
- iss?: string;
5
- sub?: string;
6
- aud?: string | string[];
7
- exp?: number;
8
- iat?: number;
9
- nbf?: number;
10
- scope?: string;
11
- client_id?: string;
12
- email?: string;
13
- /** RFC 8707 resource indicator(s) the token was granted for (Lovable OAuth convention). */
14
- resource?: string | string[];
15
- };
16
- /**
17
- * The safe-to-surface half of the auth context, reachable by tools only through
18
- * `ToolContext` accessors (`getUserId()`, `getClaims()`, …). Carries no
19
- * credential — the bearer is isolated in `OAuthBearer`.
20
- */
21
- interface OAuthPrincipal {
22
- claims: JwtClaims;
23
- issuer: string;
24
- resource: string;
25
- acceptedAudiences: readonly string[];
26
- scopes: string[];
27
- sub?: string;
28
- email?: string;
29
- clientId?: string;
30
- }
31
- /**
32
- * The raw bearer, isolated from the safe fields. Pass it only into outbound
33
- * `fetch`/client construction; never return or log it — a leaked token stays
34
- * valid at the AS until it expires. `token` is a non-enumerable property, so
35
- * `JSON.stringify`, object spread, and `console.log` omit it by construction.
36
- */
37
- interface OAuthBearer {
38
- readonly token: string;
39
- }
40
- interface McpAuthContext {
41
- type: "oauth";
42
- principal: OAuthPrincipal;
43
- bearer: OAuthBearer;
44
- }
45
- interface McpAuthConfig {
46
- readonly type: "oauth";
47
- readonly issuer: string;
48
- readonly resource?: string;
49
- readonly resourceName?: string;
50
- readonly resourceDocumentation?: string;
51
- /**
52
- * Absolute URL of an externally hosted RFC 9728 protected-resource metadata
53
- * document. When set, the SDK advertises this URL in the 401
54
- * `WWW-Authenticate: resource_metadata` challenge and does not generate or
55
- * serve its own metadata (the `/.well-known/oauth-protected-resource` handler
56
- * 404s). Use it when the resource server already publishes its own PRM.
57
- *
58
- * Mutually exclusive with the Vite plugin's `metadataPath`: that option has
59
- * the SDK serve the document itself at a custom path, so configuring both is
60
- * rejected at handler construction.
61
- */
62
- readonly protectedResourceMetadataUrl?: string;
63
- readonly requireOAuthClientClaim?: boolean;
64
- readonly acceptedAudiences?: readonly string[];
65
- /**
66
- * Accept a token whose RFC 8707 `resource` claim matches an accepted
67
- * audience (trailing slashes ignored) when its `aud` is an empty array or
68
- * absent — the shape Lovable's OAuth server mints; applies to any configured
69
- * issuer. A populated `aud` is always authoritative and is never overridden.
70
- * Defaults to true. Set false to require a matching `aud` (strict RFC 9068).
71
- */
72
- readonly acceptResourceClaim?: boolean;
73
- readonly requiredScopes?: readonly string[];
74
- readonly jwksUri?: string;
75
- readonly algorithms?: readonly string[];
76
- readonly clockToleranceSeconds?: number;
77
- /**
78
- * Allowed values for the access token's JOSE `typ` header. Defaults to
79
- * `["at+jwt", "JWT"]` so both the RFC 9068 access-token shape and the plain
80
- * user-JWT shape (notably Supabase GoTrue's OAuth tokens) are accepted out of
81
- * the box. Pin to `["at+jwt"]` to enforce strict RFC 9068. The header `typ`
82
- * must be present and string-typed; this option only controls which values pass.
83
- */
84
- readonly accessTokenTyp?: readonly string[];
85
- }
86
-
87
- /**
88
- * The auth surface passed to every tool handler as its second argument. It wraps
89
- * the verified per-request auth context in a private field, so the context — and
90
- * the bearer token inside it — can't be read, enumerated, spread, or
91
- * `JSON.stringify`'d off the instance; the accessors below are the only way out.
92
- * `getToken()` is the single intentional escape hatch for the raw bearer.
93
- */
94
- declare class ToolContext {
95
- #private;
96
- constructor(auth: McpAuthContext | undefined);
97
- /** Whether the in-flight tool call carries a verified auth context. */
98
- isAuthenticated(): boolean;
99
- /** The verified bearer token, or `undefined` when unauthenticated. Pass it to downstream APIs; never return or log it. */
100
- getToken(): string | undefined;
101
- /** The verified user id (the token `sub`), or `undefined`. */
102
- getUserId(): string | undefined;
103
- /** The verified user email, or `undefined` when absent. */
104
- getUserEmail(): string | undefined;
105
- /** The verified OAuth `client_id`, or `undefined`. */
106
- getClientId(): string | undefined;
107
- /** The verified OAuth scopes, or `undefined` when unauthenticated. */
108
- getScopes(): string[] | undefined;
109
- /** The verified token issuer, or `undefined`. */
110
- getIssuer(): string | undefined;
111
- /**
112
- * The full verified JWT claims, or `undefined`. Use this for app/business
113
- * authorization on issuer-specific claims that have no dedicated accessor.
114
- */
115
- getClaims(): JwtClaims | undefined;
116
- }
117
-
118
- /**
119
- * Usage-metrics options. Pass a boolean to the Vite plugins for the common
120
- * on/off case, or this object to override the ingest endpoint (e.g. to
121
- * self-host the collector outside Lovable).
122
- */
123
- interface MetricsOptions {
124
- /** Master switch. Default `true`; metrics still self-disable at runtime when
125
- * the API key env var is absent. */
126
- enabled?: boolean;
127
- /** OTLP/HTTP (JSON) logs URL to POST each invocation to — the default Lovable
128
- * route or any OTLP collector. Must be an absolute http(s) URL.
129
- * @default "https://api.lovable.dev/v1/app-mcp-usage" */
130
- endpoint?: string;
131
- /** Extra request headers — e.g. the auth token for a private OTLP collector.
132
- * Sent verbatim with every request (and baked into the build output, so source
133
- * your own build-time env for secrets). Ignored for the default Lovable
134
- * endpoint, which authenticates with `LOVABLE_API_KEY` instead. `content-type`
135
- * cannot be overridden (OTLP/HTTP JSON requires `application/json`). */
136
- headers?: Record<string, string>;
137
- }
138
- /** Either the bare on/off toggle or the full options object. */
139
- type MetricsConfig = boolean | MetricsOptions;
140
-
141
- /**
142
- * Any zod schema. Aliased to zod's `ZodType` (no generics) — non-deprecated
143
- * in both v3 and v4. Use this when you need to type an individual schema;
144
- * for the `{ text: z.string() }` shape passed to `defineTool`'s
145
- * `inputSchema`, use `ZodRawShape`.
146
- */
147
- type ZodSchema = ZodType;
148
- /**
149
- * A raw zod shape (`{ text: z.string(), n: z.number() }`) — the format
150
- * `defineTool`'s `inputSchema`/`outputSchema` expects.
151
- */
152
- type ZodRawShape = ZodRawShape$1;
153
- /**
154
- * Infer the parsed-output type of a zod raw shape — given
155
- * `{ text: ZodString, n: ZodNumber }`, produces `{ text: string, n: number }`.
156
- */
157
- type ShapeOutput<Shape extends ZodRawShape> = {
158
- [K in keyof Shape]: Shape[K] extends ZodType ? TypeOf<Shape[K]> : unknown;
159
- };
160
- /**
161
- * Per-content-block metadata. Distinct from `ToolAnnotations`, which
162
- * decorates the tool as a whole — these decorate a single piece of
163
- * content (an image, a text block, etc.) within the tool's result.
164
- */
165
- interface ContentAnnotations {
166
- /** Which side of the conversation the content is addressed at. */
167
- audience?: ("user" | "assistant")[];
168
- /** Higher = more important. Used by clients that summarise content. */
169
- priority?: number;
170
- /** ISO 8601 timestamp. */
171
- lastModified?: string;
172
- }
173
- interface ContentBlockBase {
174
- annotations?: ContentAnnotations;
175
- _meta?: Record<string, unknown>;
176
- }
177
- interface TextContent extends ContentBlockBase {
178
- type: "text";
179
- text: string;
180
- }
181
- interface ImageContent extends ContentBlockBase {
182
- type: "image";
183
- data: string;
184
- mimeType: string;
185
- }
186
- interface AudioContent extends ContentBlockBase {
187
- type: "audio";
188
- data: string;
189
- mimeType: string;
190
- }
191
- interface EmbeddedTextResource extends ContentBlockBase {
192
- type: "resource";
193
- resource: {
194
- uri: string;
195
- mimeType?: string;
196
- text: string;
197
- _meta?: Record<string, unknown>;
198
- };
199
- }
200
- interface EmbeddedBlobResource extends ContentBlockBase {
201
- type: "resource";
202
- resource: {
203
- uri: string;
204
- mimeType?: string;
205
- blob: string;
206
- _meta?: Record<string, unknown>;
207
- };
208
- }
209
- type EmbeddedResource = EmbeddedTextResource | EmbeddedBlobResource;
210
- /**
211
- * Optional icon entry on `ResourceLink`. Clients that display a resource
212
- * with a glyph (file browsers, side panels, etc.) pick the best match by
213
- * MIME type, `sizes`, and the active `theme`. All fields besides `src`
214
- * are optional — `src` is typically a `file://`, `data:`, or `https:` URI.
215
- */
216
- interface ResourceLinkIcon {
217
- src: string;
218
- mimeType?: string;
219
- /** Space-separated dimension string, HTML `<link sizes>` convention (e.g. `"16x16 32x32"`). */
220
- sizes?: string;
221
- theme?: "light" | "dark";
222
- }
223
- interface ResourceLink extends ContentBlockBase {
224
- type: "resource_link";
225
- uri: string;
226
- name: string;
227
- title?: string;
228
- description?: string;
229
- mimeType?: string;
230
- icons?: ResourceLinkIcon[];
231
- }
232
- /**
233
- * A single content block in a tool result. Matches the MCP wire format
234
- * for `tools/call` responses (`type: "text" | "image" | "audio" |
235
- * "resource" | "resource_link"`).
236
- */
237
- type ContentBlock = TextContent | ImageContent | AudioContent | EmbeddedResource | ResourceLink;
238
- /**
239
- * The shape of `ToolHandlerResult.content` — an array of content blocks
240
- * the tool returns to the caller.
241
- */
242
- type ToolContent = ContentBlock[];
243
- /**
244
- * Per-tool client hints (not enforcement). `annotations.title` is
245
- * intentionally omitted — use `ToolDefinition.title`, which the MCP
246
- * 2025-06-18+ spec promoted to top-level.
247
- */
248
- interface ToolAnnotations {
249
- /** Tool does not modify state. */
250
- readOnlyHint?: boolean;
251
- /** Tool may make irreversible changes. Only meaningful when readOnlyHint is false. */
252
- destructiveHint?: boolean;
253
- /** Calling N times has the same effect as calling once. */
254
- idempotentHint?: boolean;
255
- /** Tool interacts with external/unbounded systems (DB, network, third-party APIs). */
256
- openWorldHint?: boolean;
257
- }
258
- interface ToolHandlerResult {
259
- content?: ToolContent;
260
- structuredContent?: Record<string, unknown>;
261
- isError?: boolean;
262
- }
263
-
264
- interface ToolDefinition<TInput extends ZodRawShape | undefined = ZodRawShape | undefined, TOutput extends ZodRawShape | undefined = ZodRawShape | undefined> {
265
- readonly name: string;
266
- /** Human-readable display name shown to the user in MCP clients. Required. */
267
- readonly title: string;
268
- /** Prose read by the LLM to decide whether to call this tool. Required. */
269
- readonly description: string;
270
- readonly inputSchema?: TInput;
271
- readonly outputSchema?: TOutput;
272
- readonly annotations?: ToolAnnotations;
273
- readonly handler: TInput extends ZodRawShape ? (args: ShapeOutput<TInput>, ctx: ToolContext) => ToolHandlerResult | Promise<ToolHandlerResult> : (args: Record<string, never> | undefined, ctx: ToolContext) => ToolHandlerResult | Promise<ToolHandlerResult>;
274
- }
275
- /**
276
- * Type-erased element of `McpDefinition.tools`. Per-tool generic typing
277
- * happens at the `defineTool` call site; see README §6 for the rationale.
278
- */
279
- interface AnyToolDefinition {
280
- readonly name: string;
281
- readonly title: string;
282
- readonly description: string;
283
- readonly inputSchema?: ZodRawShape;
284
- readonly outputSchema?: ZodRawShape;
285
- readonly annotations?: ToolAnnotations;
286
- readonly handler: (args: any, ctx: ToolContext) => ToolHandlerResult | Promise<ToolHandlerResult>;
287
- }
288
- /**
289
- * Fields a caller supplies when constructing an MCP definition. Pass this
290
- * shape to `defineMcp(...)` — its return type is the branded `McpDefinition`,
291
- * which is the type every internal factory (`createInvokeToolHandler`,
292
- * `createMcpProtocolHandler`, …) consumes. The brand forces consumers
293
- * through `defineMcp`'s `assertUniqueNames` + freeze.
294
- */
295
- interface McpDefinitionInput {
296
- readonly name: string;
297
- /** Human-readable display name shown to MCP clients. Required. */
298
- readonly title: string;
299
- readonly version: string;
300
- readonly auth?: McpAuthConfig;
301
- /**
302
- * Server-level prose the LLM reads as context for all tools on this server.
303
- * Required for the same reason `ToolDefinition.description` is — optional
304
- * fields encourage drift in production agent behavior. Pass an explicit
305
- * empty string to opt out.
306
- */
307
- readonly instructions: string;
308
- readonly tools: readonly AnyToolDefinition[];
309
- /**
310
- * Usage-metrics emission (runtime telemetry), on by default. `false` opts out;
311
- * `{ endpoint, headers }` sends to your own OTLP collector. Self-disables at
312
- * runtime without `LOVABLE_API_KEY` on the default Lovable endpoint.
313
- */
314
- readonly metrics?: MetricsConfig;
315
- }
316
- declare const McpDefinitionBrand: unique symbol;
317
- type McpDefinition = McpDefinitionInput & {
318
- readonly [McpDefinitionBrand]: never;
319
- };
320
-
321
- export { type AudioContent as A, type ContentAnnotations as C, type EmbeddedBlobResource as E, type ImageContent as I, type JwtClaims as J, type McpAuthConfig as M, type ResourceLink as R, type TextContent as T, type ZodRawShape as Z, type ContentBlock as a, type EmbeddedResource as b, type EmbeddedTextResource as c, type McpDefinition as d, type McpDefinitionInput as e, type MetricsConfig as f, type MetricsOptions as g, type ResourceLinkIcon as h, type ToolAnnotations as i, type ToolContent as j, ToolContext as k, type ToolDefinition as l, type ToolHandlerResult as m, type ZodSchema as n };