@miragon/mcp-toolkit-core 0.10.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 (174) hide show
  1. package/README.md +32 -0
  2. package/dist/engine/context-builder.d.ts +5 -0
  3. package/dist/engine/context-builder.d.ts.map +1 -0
  4. package/dist/engine/context-builder.js +22 -0
  5. package/dist/engine/context-builder.js.map +1 -0
  6. package/dist/engine/pipeline-executor.d.ts +21 -0
  7. package/dist/engine/pipeline-executor.d.ts.map +1 -0
  8. package/dist/engine/pipeline-executor.js +80 -0
  9. package/dist/engine/pipeline-executor.js.map +1 -0
  10. package/dist/framework/active-modules.d.ts +30 -0
  11. package/dist/framework/active-modules.d.ts.map +1 -0
  12. package/dist/framework/active-modules.js +44 -0
  13. package/dist/framework/active-modules.js.map +1 -0
  14. package/dist/framework/catalogue.d.ts +148 -0
  15. package/dist/framework/catalogue.d.ts.map +1 -0
  16. package/dist/framework/catalogue.js +132 -0
  17. package/dist/framework/catalogue.js.map +1 -0
  18. package/dist/framework/dashboard-store.d.ts +136 -0
  19. package/dist/framework/dashboard-store.d.ts.map +1 -0
  20. package/dist/framework/dashboard-store.js +301 -0
  21. package/dist/framework/dashboard-store.js.map +1 -0
  22. package/dist/framework/layout-schemas.d.ts +106 -0
  23. package/dist/framework/layout-schemas.d.ts.map +1 -0
  24. package/dist/framework/layout-schemas.js +67 -0
  25. package/dist/framework/layout-schemas.js.map +1 -0
  26. package/dist/framework/layout-types.d.ts +25 -0
  27. package/dist/framework/layout-types.d.ts.map +1 -0
  28. package/dist/framework/layout-types.js +7 -0
  29. package/dist/framework/layout-types.js.map +1 -0
  30. package/dist/framework/manifest.d.ts +65 -0
  31. package/dist/framework/manifest.d.ts.map +1 -0
  32. package/dist/framework/manifest.js +47 -0
  33. package/dist/framework/manifest.js.map +1 -0
  34. package/dist/framework/render-view.d.ts +53 -0
  35. package/dist/framework/render-view.d.ts.map +1 -0
  36. package/dist/framework/render-view.js +73 -0
  37. package/dist/framework/render-view.js.map +1 -0
  38. package/dist/framework/view-builders.d.ts +79 -0
  39. package/dist/framework/view-builders.d.ts.map +1 -0
  40. package/dist/framework/view-builders.js +113 -0
  41. package/dist/framework/view-builders.js.map +1 -0
  42. package/dist/i18n/index.d.ts +3 -0
  43. package/dist/i18n/index.d.ts.map +1 -0
  44. package/dist/i18n/index.js +6 -0
  45. package/dist/i18n/index.js.map +1 -0
  46. package/dist/i18n/translator.d.ts +59 -0
  47. package/dist/i18n/translator.d.ts.map +1 -0
  48. package/dist/i18n/translator.js +48 -0
  49. package/dist/i18n/translator.js.map +1 -0
  50. package/dist/index.d.ts +31 -0
  51. package/dist/index.d.ts.map +1 -0
  52. package/dist/index.js +27 -0
  53. package/dist/index.js.map +1 -0
  54. package/dist/middleware/org-gate.d.ts +22 -0
  55. package/dist/middleware/org-gate.d.ts.map +1 -0
  56. package/dist/middleware/org-gate.js +28 -0
  57. package/dist/middleware/org-gate.js.map +1 -0
  58. package/dist/middleware/role-filter.d.ts +79 -0
  59. package/dist/middleware/role-filter.d.ts.map +1 -0
  60. package/dist/middleware/role-filter.js +95 -0
  61. package/dist/middleware/role-filter.js.map +1 -0
  62. package/dist/registry/app-loader.d.ts +35 -0
  63. package/dist/registry/app-loader.d.ts.map +1 -0
  64. package/dist/registry/app-loader.js +55 -0
  65. package/dist/registry/app-loader.js.map +1 -0
  66. package/dist/registry/step-registry.d.ts +27 -0
  67. package/dist/registry/step-registry.d.ts.map +1 -0
  68. package/dist/registry/step-registry.js +53 -0
  69. package/dist/registry/step-registry.js.map +1 -0
  70. package/dist/registry/widget-registry.d.ts +15 -0
  71. package/dist/registry/widget-registry.d.ts.map +1 -0
  72. package/dist/registry/widget-registry.js +28 -0
  73. package/dist/registry/widget-registry.js.map +1 -0
  74. package/dist/rest/client.d.ts +3 -0
  75. package/dist/rest/client.d.ts.map +1 -0
  76. package/dist/rest/client.js +155 -0
  77. package/dist/rest/client.js.map +1 -0
  78. package/dist/rest/errors.d.ts +14 -0
  79. package/dist/rest/errors.d.ts.map +1 -0
  80. package/dist/rest/errors.js +21 -0
  81. package/dist/rest/errors.js.map +1 -0
  82. package/dist/rest/index.d.ts +6 -0
  83. package/dist/rest/index.d.ts.map +1 -0
  84. package/dist/rest/index.js +4 -0
  85. package/dist/rest/index.js.map +1 -0
  86. package/dist/rest/tool.d.ts +60 -0
  87. package/dist/rest/tool.d.ts.map +1 -0
  88. package/dist/rest/tool.js +81 -0
  89. package/dist/rest/tool.js.map +1 -0
  90. package/dist/rest/types.d.ts +66 -0
  91. package/dist/rest/types.d.ts.map +1 -0
  92. package/dist/rest/types.js +2 -0
  93. package/dist/rest/types.js.map +1 -0
  94. package/dist/tools/app-resource-uri.d.ts +28 -0
  95. package/dist/tools/app-resource-uri.d.ts.map +1 -0
  96. package/dist/tools/app-resource-uri.js +30 -0
  97. package/dist/tools/app-resource-uri.js.map +1 -0
  98. package/dist/tools/backend-registry.d.ts +111 -0
  99. package/dist/tools/backend-registry.d.ts.map +1 -0
  100. package/dist/tools/backend-registry.js +154 -0
  101. package/dist/tools/backend-registry.js.map +1 -0
  102. package/dist/tools/create-framework-app.d.ts +147 -0
  103. package/dist/tools/create-framework-app.d.ts.map +1 -0
  104. package/dist/tools/create-framework-app.js +111 -0
  105. package/dist/tools/create-framework-app.js.map +1 -0
  106. package/dist/tools/index.d.ts +22 -0
  107. package/dist/tools/index.d.ts.map +1 -0
  108. package/dist/tools/index.js +15 -0
  109. package/dist/tools/index.js.map +1 -0
  110. package/dist/tools/register-catalogue-tool.d.ts +22 -0
  111. package/dist/tools/register-catalogue-tool.d.ts.map +1 -0
  112. package/dist/tools/register-catalogue-tool.js +45 -0
  113. package/dist/tools/register-catalogue-tool.js.map +1 -0
  114. package/dist/tools/register-dashboard-tools.d.ts +32 -0
  115. package/dist/tools/register-dashboard-tools.d.ts.map +1 -0
  116. package/dist/tools/register-dashboard-tools.js +149 -0
  117. package/dist/tools/register-dashboard-tools.js.map +1 -0
  118. package/dist/tools/register-framework-tools.d.ts +83 -0
  119. package/dist/tools/register-framework-tools.d.ts.map +1 -0
  120. package/dist/tools/register-framework-tools.js +154 -0
  121. package/dist/tools/register-framework-tools.js.map +1 -0
  122. package/dist/tools/register-tool.d.ts +45 -0
  123. package/dist/tools/register-tool.d.ts.map +1 -0
  124. package/dist/tools/register-tool.js +82 -0
  125. package/dist/tools/register-tool.js.map +1 -0
  126. package/dist/tools/register-widget-tool.d.ts +51 -0
  127. package/dist/tools/register-widget-tool.d.ts.map +1 -0
  128. package/dist/tools/register-widget-tool.js +45 -0
  129. package/dist/tools/register-widget-tool.js.map +1 -0
  130. package/dist/tools/tool-call-name.d.ts +53 -0
  131. package/dist/tools/tool-call-name.d.ts.map +1 -0
  132. package/dist/tools/tool-call-name.js +92 -0
  133. package/dist/tools/tool-call-name.js.map +1 -0
  134. package/dist/tools/with-tool-errors.d.ts +16 -0
  135. package/dist/tools/with-tool-errors.d.ts.map +1 -0
  136. package/dist/tools/with-tool-errors.js +28 -0
  137. package/dist/tools/with-tool-errors.js.map +1 -0
  138. package/dist/types/app.d.ts +44 -0
  139. package/dist/types/app.d.ts.map +1 -0
  140. package/dist/types/app.js +2 -0
  141. package/dist/types/app.js.map +1 -0
  142. package/dist/types/config.d.ts +15 -0
  143. package/dist/types/config.d.ts.map +1 -0
  144. package/dist/types/config.js +2 -0
  145. package/dist/types/config.js.map +1 -0
  146. package/dist/types/context.d.ts +18 -0
  147. package/dist/types/context.d.ts.map +1 -0
  148. package/dist/types/context.js +2 -0
  149. package/dist/types/context.js.map +1 -0
  150. package/dist/types/index.d.ts +10 -0
  151. package/dist/types/index.d.ts.map +1 -0
  152. package/dist/types/index.js +2 -0
  153. package/dist/types/index.js.map +1 -0
  154. package/dist/types/meta.d.ts +99 -0
  155. package/dist/types/meta.d.ts.map +1 -0
  156. package/dist/types/meta.js +66 -0
  157. package/dist/types/meta.js.map +1 -0
  158. package/dist/types/pipeline.d.ts +9 -0
  159. package/dist/types/pipeline.d.ts.map +1 -0
  160. package/dist/types/pipeline.js +2 -0
  161. package/dist/types/pipeline.js.map +1 -0
  162. package/dist/types/step.d.ts +51 -0
  163. package/dist/types/step.d.ts.map +1 -0
  164. package/dist/types/step.js +2 -0
  165. package/dist/types/step.js.map +1 -0
  166. package/dist/types/view-data.d.ts +67 -0
  167. package/dist/types/view-data.d.ts.map +1 -0
  168. package/dist/types/view-data.js +2 -0
  169. package/dist/types/view-data.js.map +1 -0
  170. package/dist/types/widget.d.ts +57 -0
  171. package/dist/types/widget.d.ts.map +1 -0
  172. package/dist/types/widget.js +2 -0
  173. package/dist/types/widget.js.map +1 -0
  174. package/package.json +50 -0
@@ -0,0 +1,45 @@
1
+ import { z } from "zod";
2
+ import { uiMeta } from "../types/meta.js";
3
+ import { withToolErrors } from "./with-tool-errors.js";
4
+ /** Normalizes the {@link WidgetToolConfig.visibility} option into a flag set. */
5
+ function resolveVisibility(visibility) {
6
+ const list = visibility === undefined ? ["app"] : Array.isArray(visibility) ? visibility : [visibility];
7
+ return { app: list.includes("app"), model: list.includes("model") };
8
+ }
9
+ export function createWidgetToolRegistrar(server, client, resourceUri, metaDefaults) {
10
+ return function register(config) {
11
+ const { app, model } = resolveVisibility(config.visibility);
12
+ // `"model"`-visible tools must not carry the app-only `visibility` marker so
13
+ // the LLM still sees them; otherwise mark app-only. The `resourceUri` is
14
+ // always present so the host knows which bundle renders the result.
15
+ // Model-visible tools additionally get the dual-protocol widget contract
16
+ // (flat `ui/resourceUri` + `openai/*` keys) ext-apps hosts key on.
17
+ const ui = uiMeta({
18
+ resourceUri,
19
+ appOnly: app && !model,
20
+ title: config.title ?? config.name,
21
+ invoking: config.invoking,
22
+ invoked: config.invoked,
23
+ widgetDescription: config.description,
24
+ widgetCSP: metaDefaults?.widgetCSP,
25
+ });
26
+ server.tool({
27
+ name: config.name,
28
+ title: config.title,
29
+ description: config.description,
30
+ schema: config.inputSchema ? z.object(config.inputSchema) : undefined,
31
+ annotations: config.annotations,
32
+ _meta: { ...config.meta, ...ui },
33
+ },
34
+ // The SDK validates params against the schema above, so the loose
35
+ // callback param is safely the handler's precise `ToolArgs<TShape>`.
36
+ withToolErrors(async (looseParams) => {
37
+ const result = await config.handler(client, looseParams);
38
+ return {
39
+ content: [{ type: "text", text: result.text }],
40
+ structuredContent: result.structuredContent,
41
+ };
42
+ }));
43
+ };
44
+ }
45
+ //# sourceMappingURL=register-widget-tool.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"register-widget-tool.js","sourceRoot":"","sources":["../../src/tools/register-widget-tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,EAAE,MAAM,EAA+B,MAAM,kBAAkB,CAAA;AACtE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AAsDtD,iFAAiF;AACjF,SAAS,iBAAiB,CAAC,UAA4C;IAIrE,MAAM,IAAI,GACR,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAA;IAC5F,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAA;AACrE,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,MAAiB,EACjB,MAAe,EACf,WAAmB,EACnB,YAAqC;IAErC,OAAO,SAAS,QAAQ,CACtB,MAAyC;QAEzC,MAAM,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,iBAAiB,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QAC3D,6EAA6E;QAC7E,yEAAyE;QACzE,oEAAoE;QACpE,yEAAyE;QACzE,mEAAmE;QACnE,MAAM,EAAE,GAAG,MAAM,CAAC;YAChB,WAAW;YACX,OAAO,EAAE,GAAG,IAAI,CAAC,KAAK;YACtB,KAAK,EAAE,MAAM,CAAC,KAAK,IAAI,MAAM,CAAC,IAAI;YAClC,QAAQ,EAAE,MAAM,CAAC,QAAQ;YACzB,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,iBAAiB,EAAE,MAAM,CAAC,WAAW;YACrC,SAAS,EAAE,YAAY,EAAE,SAAS;SACnC,CAAC,CAAA;QAEF,MAAM,CAAC,IAAI,CACT;YACE,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,KAAK,EAAE,MAAM,CAAC,KAAK;YACnB,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,MAAM,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,SAAS;YACrE,WAAW,EAAE,MAAM,CAAC,WAAW;YAC/B,KAAK,EAAE,EAAE,GAAG,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE;SACjC;QACD,kEAAkE;QAClE,qEAAqE;QACrE,cAAc,CAAC,KAAK,EAAE,WAA0B,EAAE,EAAE;YAClD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,WAA+B,CAAC,CAAA;YAC5E,OAAO;gBACL,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC;gBACvD,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;aAC5C,CAAA;QACH,CAAC,CAAC,CACH,CAAA;IACH,CAAC,CAAA;AACH,CAAC"}
@@ -0,0 +1,53 @@
1
+ import { type McpServerInstance } from "mcp-use/server";
2
+ /**
3
+ * Resolves the tool name of the in-flight `tools/call` request, or
4
+ * `undefined` when called outside a tool-call request scope.
5
+ *
6
+ * Backs the role-filter's `tools/call` guard: mcp-use 1.28 passes only the
7
+ * tool *arguments* to `mcp:tools/call` middleware as `ctx.params`, so the
8
+ * `params.name` its typings declare is never populated at runtime. This
9
+ * resolver recovers the real name from the JSON-RPC envelope captured at the
10
+ * HTTP layer.
11
+ */
12
+ export type ToolNameResolver = () => string | undefined;
13
+ /**
14
+ * The resolver returned by {@link installToolCallNameCapture}: callable as a
15
+ * plain {@link ToolNameResolver} (first `tools/call` name — the common case
16
+ * and the logging-friendly one), with `.all()` exposing every name the
17
+ * in-flight envelope carries. A JSON-RPC *batch* can contain several
18
+ * `tools/call` requests, and a guard that only checks one of them can be
19
+ * bypassed by the others — the role filter therefore consumes `.all()`.
20
+ */
21
+ export interface ToolNameCapture extends ToolNameResolver {
22
+ /** Every `tools/call` name in the in-flight envelope, or `undefined` outside a capture scope. */
23
+ all: () => string[] | undefined;
24
+ }
25
+ /**
26
+ * Parse a JSON-RPC request body and return the `params.name` of every
27
+ * `tools/call` request it carries: a single request yields zero or one entry,
28
+ * a batch array yields one entry per `tools/call` it contains. Batches are a
29
+ * real-world shape, not an edge case — Streamable-HTTP revision 2025-03-26
30
+ * allows them, and claude.ai (via mcp-remote) frames single calls as
31
+ * one-element batches.
32
+ *
33
+ * Pure and side-effect free so it can be unit-tested without an HTTP server.
34
+ * Tolerates arbitrary `unknown` input: malformed bodies, malformed batch
35
+ * entries, and non-`tools/call` methods contribute nothing rather than throw.
36
+ */
37
+ export declare function extractToolCallNames(body: unknown): string[];
38
+ /**
39
+ * First `tools/call` name of a JSON-RPC request body (single request or batch
40
+ * array), or `undefined` when it carries none. Sufficient for logging; guards
41
+ * must use {@link extractToolCallNames} — a batch can carry several calls.
42
+ */
43
+ export declare function extractToolCallName(body: unknown): string | undefined;
44
+ /**
45
+ * Whether `path` is one of the MCP transport endpoints mcp-use mounts the
46
+ * Streamable-HTTP handler at. Both `/mcp` and `/sse` accept `tools/call`, so
47
+ * the tool-name capture (and the role-filter guard that reads it) must cover
48
+ * both — matching only `/mcp` leaves a `tools/call` over `/sse` unguarded.
49
+ * Exported so the endpoint contract is pinned by a unit test.
50
+ */
51
+ export declare function isMcpTransportPath(path: string): boolean;
52
+ export declare function installToolCallNameCapture(server: McpServerInstance<boolean>): ToolNameCapture;
53
+ //# sourceMappingURL=tool-call-name.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tool-call-name.d.ts","sourceRoot":"","sources":["../../src/tools/tool-call-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAS1E;;;;;;;;;GASG;AACH,MAAM,MAAM,gBAAgB,GAAG,MAAM,MAAM,GAAG,SAAS,CAAA;AAEvD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,iGAAiG;IACjG,GAAG,EAAE,MAAM,MAAM,EAAE,GAAG,SAAS,CAAA;CAChC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,EAAE,CAU5D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAErE;AA0BD;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AAED,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,GAAG,eAAe,CAuB9F"}
@@ -0,0 +1,92 @@
1
+ import { getRequestContext } from "mcp-use/server";
2
+ /**
3
+ * Parse a JSON-RPC request body and return the `params.name` of every
4
+ * `tools/call` request it carries: a single request yields zero or one entry,
5
+ * a batch array yields one entry per `tools/call` it contains. Batches are a
6
+ * real-world shape, not an edge case — Streamable-HTTP revision 2025-03-26
7
+ * allows them, and claude.ai (via mcp-remote) frames single calls as
8
+ * one-element batches.
9
+ *
10
+ * Pure and side-effect free so it can be unit-tested without an HTTP server.
11
+ * Tolerates arbitrary `unknown` input: malformed bodies, malformed batch
12
+ * entries, and non-`tools/call` methods contribute nothing rather than throw.
13
+ */
14
+ export function extractToolCallNames(body) {
15
+ if (Array.isArray(body)) {
16
+ return body.flatMap((entry) => extractToolCallNames(entry));
17
+ }
18
+ if (typeof body !== "object" || body === null)
19
+ return [];
20
+ const { method, params } = body;
21
+ if (method !== "tools/call")
22
+ return [];
23
+ if (typeof params !== "object" || params === null)
24
+ return [];
25
+ const { name } = params;
26
+ return typeof name === "string" ? [name] : [];
27
+ }
28
+ /**
29
+ * First `tools/call` name of a JSON-RPC request body (single request or batch
30
+ * array), or `undefined` when it carries none. Sufficient for logging; guards
31
+ * must use {@link extractToolCallNames} — a batch can carry several calls.
32
+ */
33
+ export function extractToolCallName(body) {
34
+ return extractToolCallNames(body)[0];
35
+ }
36
+ /**
37
+ * Capture the `tools/call` tool name at the HTTP layer and expose it to the
38
+ * MCP middleware chain.
39
+ *
40
+ * Registers a Hono middleware on the server that, for `POST` requests to an
41
+ * MCP transport endpoint, clones the request body (so the MCP transport can
42
+ * still read it), parses the JSON-RPC envelope, and — when it's a
43
+ * `tools/call` — stashes the tool name in a `WeakMap` keyed by the
44
+ * request-scoped Hono context. The returned resolver reads that map back via
45
+ * `getRequestContext()`, which yields the same context inside the MCP
46
+ * middleware chain.
47
+ *
48
+ * mcp-use mounts the *same* Streamable-HTTP handler at both `/mcp` and `/sse`
49
+ * (`for (const endpoint of ["/mcp", "/sse"])`), so the capture must match both
50
+ * — otherwise a `tools/call` sent to `/sse` executes but its name is never
51
+ * captured, and the role-filter guard that depends on this resolver silently
52
+ * falls open. Matching both endpoints closes that bypass.
53
+ *
54
+ * The `WeakMap` keying keeps the capture request-isolated: entries are
55
+ * garbage-collected with their context and never leak across concurrent
56
+ * requests.
57
+ */
58
+ const MCP_TRANSPORT_PATHS = new Set(["/mcp", "/sse"]);
59
+ /**
60
+ * Whether `path` is one of the MCP transport endpoints mcp-use mounts the
61
+ * Streamable-HTTP handler at. Both `/mcp` and `/sse` accept `tools/call`, so
62
+ * the tool-name capture (and the role-filter guard that reads it) must cover
63
+ * both — matching only `/mcp` leaves a `tools/call` over `/sse` unguarded.
64
+ * Exported so the endpoint contract is pinned by a unit test.
65
+ */
66
+ export function isMcpTransportPath(path) {
67
+ return MCP_TRANSPORT_PATHS.has(path);
68
+ }
69
+ export function installToolCallNameCapture(server) {
70
+ const toolNamesByRequest = new WeakMap();
71
+ server.use(async (c, next) => {
72
+ if (c.req.method === "POST" && isMcpTransportPath(c.req.path)) {
73
+ const body = await c.req.raw
74
+ .clone()
75
+ .json()
76
+ .catch(() => undefined);
77
+ const toolNames = extractToolCallNames(body);
78
+ if (toolNames.length > 0) {
79
+ toolNamesByRequest.set(c, toolNames);
80
+ }
81
+ }
82
+ await next();
83
+ });
84
+ const all = () => {
85
+ const requestContext = getRequestContext();
86
+ if (!requestContext)
87
+ return undefined;
88
+ return toolNamesByRequest.get(requestContext);
89
+ };
90
+ return Object.assign(() => all()?.[0], { all });
91
+ }
92
+ //# sourceMappingURL=tool-call-name.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"tool-call-name.js","sourceRoot":"","sources":["../../src/tools/tool-call-name.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAA0B,MAAM,gBAAgB,CAAA;AAkC1E;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,oBAAoB,CAAC,IAAa;IAChD,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACxB,OAAO,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,oBAAoB,CAAC,KAAK,CAAC,CAAC,CAAA;IAC7D,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI;QAAE,OAAO,EAAE,CAAA;IACxD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,IAA8C,CAAA;IACzE,IAAI,MAAM,KAAK,YAAY;QAAE,OAAO,EAAE,CAAA;IACtC,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI;QAAE,OAAO,EAAE,CAAA;IAC5D,MAAM,EAAE,IAAI,EAAE,GAAG,MAA4B,CAAA;IAC7C,OAAO,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;AAC/C,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAa;IAC/C,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAA;AACtC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAErD;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,OAAO,mBAAmB,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;AACtC,CAAC;AAED,MAAM,UAAU,0BAA0B,CAAC,MAAkC;IAC3E,MAAM,kBAAkB,GAAG,IAAI,OAAO,EAAyB,CAAA;IAE/D,MAAM,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QAC3B,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YAC9D,MAAM,IAAI,GAAY,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG;iBAClC,KAAK,EAAE;iBACP,IAAI,EAAE;iBACN,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAA;YACzB,MAAM,SAAS,GAAG,oBAAoB,CAAC,IAAI,CAAC,CAAA;YAC5C,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBACzB,kBAAkB,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;YACtC,CAAC;QACH,CAAC;QACD,MAAM,IAAI,EAAE,CAAA;IACd,CAAC,CAAC,CAAA;IAEF,MAAM,GAAG,GAAG,GAAyB,EAAE;QACrC,MAAM,cAAc,GAAG,iBAAiB,EAAE,CAAA;QAC1C,IAAI,CAAC,cAAc;YAAE,OAAO,SAAS,CAAA;QACrC,OAAO,kBAAkB,CAAC,GAAG,CAAC,cAAc,CAAC,CAAA;IAC/C,CAAC,CAAA;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,CAAA;AACjD,CAAC"}
@@ -0,0 +1,16 @@
1
+ import { error } from "mcp-use/server";
2
+ /**
3
+ * Wraps a raw `server.tool()` handler so thrown exceptions surface as the same
4
+ * `error("[code] message")` tool result the toolkit's registrars produce. This
5
+ * is the single source of truth for the registrar error format — both
6
+ * `createToolRegistrar` and `createWidgetToolRegistrar` route their `catch`
7
+ * paths through here, and tools that bypass the registrars (widget tools,
8
+ * `*_data` feeds) can wrap their handlers to follow the house "use `error()`,
9
+ * don't throw" convention.
10
+ *
11
+ * Code precedence matches the registrars: an HTTP-ish `status` (e.g. `404`)
12
+ * wins over a domain error `code` (e.g. `ENGINE_NOT_SELECTED`); both may be a
13
+ * `string` or `number`. When neither is present the message is returned as-is.
14
+ */
15
+ export declare function withToolErrors<TArgs extends unknown[], TResult>(handler: (...args: TArgs) => Promise<TResult>): (...args: TArgs) => Promise<TResult | ReturnType<typeof error>>;
16
+ //# sourceMappingURL=with-tool-errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"with-tool-errors.d.ts","sourceRoot":"","sources":["../../src/tools/with-tool-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEtC;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,SAAS,OAAO,EAAE,EAAE,OAAO,EAC7D,OAAO,EAAE,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,GAC5C,CAAC,GAAG,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,GAAG,UAAU,CAAC,OAAO,KAAK,CAAC,CAAC,CAWjE"}
@@ -0,0 +1,28 @@
1
+ import { error } from "mcp-use/server";
2
+ /**
3
+ * Wraps a raw `server.tool()` handler so thrown exceptions surface as the same
4
+ * `error("[code] message")` tool result the toolkit's registrars produce. This
5
+ * is the single source of truth for the registrar error format — both
6
+ * `createToolRegistrar` and `createWidgetToolRegistrar` route their `catch`
7
+ * paths through here, and tools that bypass the registrars (widget tools,
8
+ * `*_data` feeds) can wrap their handlers to follow the house "use `error()`,
9
+ * don't throw" convention.
10
+ *
11
+ * Code precedence matches the registrars: an HTTP-ish `status` (e.g. `404`)
12
+ * wins over a domain error `code` (e.g. `ENGINE_NOT_SELECTED`); both may be a
13
+ * `string` or `number`. When neither is present the message is returned as-is.
14
+ */
15
+ export function withToolErrors(handler) {
16
+ return async (...args) => {
17
+ try {
18
+ return await handler(...args);
19
+ }
20
+ catch (e) {
21
+ const message = e instanceof Error ? e.message : String(e);
22
+ const { status, code } = (e ?? {});
23
+ const errorCode = status ?? code;
24
+ return error(errorCode ? `[${errorCode}] ${message}` : message);
25
+ }
26
+ };
27
+ }
28
+ //# sourceMappingURL=with-tool-errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"with-tool-errors.js","sourceRoot":"","sources":["../../src/tools/with-tool-errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAA;AAEtC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,cAAc,CAC5B,OAA6C;IAE7C,OAAO,KAAK,EAAE,GAAG,IAAI,EAAE,EAAE;QACvB,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;QAC/B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,OAAO,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;YAC1D,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAyD,CAAA;YAC1F,MAAM,SAAS,GAAG,MAAM,IAAI,IAAI,CAAA;YAChC,OAAO,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,SAAS,KAAK,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,CAAA;QACjE,CAAC;IACH,CAAC,CAAA;AACH,CAAC"}
@@ -0,0 +1,44 @@
1
+ import type { WidgetToolMetaDefaults } from "./meta.js";
2
+ import type { PipelineStepDefinition } from "./step.js";
3
+ import type { WidgetDefinition } from "./widget.js";
4
+ export interface AppDefinition {
5
+ name: string;
6
+ steps: PipelineStepDefinition<any>[];
7
+ widgets: WidgetDefinition[];
8
+ }
9
+ /**
10
+ * An AppPlugin bundles everything an app contributes to the framework:
11
+ * - The AppDefinition (steps + widgets)
12
+ * - Optional functions to register domain tools and widget tools on an MCP server
13
+ *
14
+ * The server type is generic so consumers can pass the concrete `MCPServer`
15
+ * type from `mcp-use/server` without the toolkit itself having to import from
16
+ * `mcp-use`. This keeps the core barrel free of mcp-use type dependencies,
17
+ * which avoids transitive type leaks (hono versions, langchain chunks, etc.)
18
+ * when the pre-built core `dist/` is shared between projects with diverging
19
+ * peer dep resolutions.
20
+ *
21
+ * Each app exports a `createPlugin(config)` factory that returns an
22
+ * `AppPlugin<MCPServer>`.
23
+ */
24
+ export interface AppPlugin<TServer = unknown> {
25
+ definition: AppDefinition;
26
+ /**
27
+ * Configuration handed to this plugin's pipeline steps as their second
28
+ * `execute` argument. May carry closures — e.g. a typed `callTool` bound to
29
+ * the module's own store or client — which the pipeline executor rewraps
30
+ * with the per-request user context (see `pipeline-executor.ts:bindAppConfig`).
31
+ */
32
+ appConfig?: Record<string, unknown>;
33
+ registerTools?: (server: TServer) => void;
34
+ /**
35
+ * Registers the plugin's widget tools against the shared app resource.
36
+ * The optional `metaDefaults` carry app-level widget `_meta` defaults
37
+ * (currently the Apps SDK CSP) — forward them into
38
+ * `createWidgetToolRegistrar` / `uiMeta` so every widget tool advertises
39
+ * the same contract as the framework's own `render-view`. Implementations
40
+ * may ignore the parameter; their tools then simply omit those keys.
41
+ */
42
+ registerWidgetTools?: (server: TServer, resourceUri: string, metaDefaults?: WidgetToolMetaDefaults) => void;
43
+ }
44
+ //# sourceMappingURL=app.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/types/app.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AACvD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAEnD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IAMZ,KAAK,EAAE,sBAAsB,CAAC,GAAG,CAAC,EAAE,CAAA;IACpC,OAAO,EAAE,gBAAgB,EAAE,CAAA;CAC5B;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,WAAW,SAAS,CAAC,OAAO,GAAG,OAAO;IAC1C,UAAU,EAAE,aAAa,CAAA;IACzB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACnC,aAAa,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAA;IACzC;;;;;;;OAOG;IACH,mBAAmB,CAAC,EAAE,CACpB,MAAM,EAAE,OAAO,EACf,WAAW,EAAE,MAAM,EACnB,YAAY,CAAC,EAAE,sBAAsB,KAClC,IAAI,CAAA;CACV"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=app.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"app.js","sourceRoot":"","sources":["../../src/types/app.ts"],"names":[],"mappings":""}
@@ -0,0 +1,15 @@
1
+ import type { PipelineConfig } from "./pipeline.js";
2
+ export interface AppConfigEntry {
3
+ app: string;
4
+ config: Record<string, unknown>;
5
+ }
6
+ export interface AppConfig {
7
+ activeApps: AppConfigEntry[];
8
+ pipelines: Record<string, PipelineConfig>;
9
+ }
10
+ export interface ValidationResult {
11
+ valid: boolean;
12
+ issues: string[];
13
+ availableKeys: string[];
14
+ }
15
+ //# sourceMappingURL=config.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,eAAe,CAAA;AAEnD,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,cAAc,EAAE,CAAA;IAC5B,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,CAAC,CAAA;CAC1C;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,OAAO,CAAA;IACd,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,aAAa,EAAE,MAAM,EAAE,CAAA;CACxB"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/types/config.ts"],"names":[],"mappings":""}
@@ -0,0 +1,18 @@
1
+ export interface StepOutput {
2
+ data: unknown;
3
+ keys: Record<string, unknown>;
4
+ _app: string;
5
+ _step: string;
6
+ }
7
+ export interface StepResult extends StepOutput {
8
+ _dataType: string;
9
+ }
10
+ export interface PipelineContext {
11
+ steps: Record<string, StepResult>;
12
+ keys: Record<string, unknown>;
13
+ errors: {
14
+ stepId: string;
15
+ reason: string;
16
+ }[];
17
+ }
18
+ //# sourceMappingURL=context.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/types/context.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,UAAW,SAAQ,UAAU;IAC5C,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAA;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,MAAM,EAAE;QACN,MAAM,EAAE,MAAM,CAAA;QACd,MAAM,EAAE,MAAM,CAAA;KACf,EAAE,CAAA;CACJ"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=context.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context.js","sourceRoot":"","sources":["../../src/types/context.ts"],"names":[],"mappings":""}
@@ -0,0 +1,10 @@
1
+ export type { StepOutput, StepResult, PipelineContext } from "./context.js";
2
+ export type { PipelineStepDefinition, OptionalKeyDeclaration } from "./step.js";
3
+ export type { WidgetProps, WidgetSize, WidgetDefinition } from "./widget.js";
4
+ export type { AppDefinition, AppPlugin } from "./app.js";
5
+ export type { PipelineConfig, PipelineStepRef } from "./pipeline.js";
6
+ export type { AppConfig, AppConfigEntry, ValidationResult } from "./config.js";
7
+ export type { ViewStructuredContent, StepDataEntry, RefreshParams } from "./view-data.js";
8
+ export { APP_ONLY_META, uiMeta } from "./meta.js";
9
+ export type { UiMetaOptions, UiToolMeta, WidgetCspMeta, WidgetToolMetaDefaults } from "./meta.js";
10
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAC3E,YAAY,EAAE,sBAAsB,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAC/E,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC5E,YAAY,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACxD,YAAY,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AACpE,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9E,YAAY,EAAE,qBAAqB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAA;AACzF,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA;AACjD,YAAY,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA"}
@@ -0,0 +1,2 @@
1
+ export { APP_ONLY_META, uiMeta } from "./meta.js";
2
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/types/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,WAAW,CAAA"}
@@ -0,0 +1,99 @@
1
+ /**
2
+ * Shared `_meta` shapes for widget tools: the SEP-1865 tool-visibility
3
+ * convention plus the dual-protocol widget contract (MCP Apps + OpenAI
4
+ * Apps SDK) that ext-apps hosts key on.
5
+ *
6
+ * Browser-bundle-safe: this module is a pure object/function with no
7
+ * `mcp-use/server` or `node:*` imports, so it can be re-exported from the core
8
+ * Root barrel and consumed by UI bundles as well as server registrars. The
9
+ * dual-protocol key literals are therefore written out here instead of being
10
+ * imported from `mcp-use/server`; `meta.test.ts` pins them against the
11
+ * adapters mcp-use itself emits (`McpAppsAdapter`/`AppsSdkAdapter`), so a
12
+ * contract drift in a future mcp-use bump fails CI instead of silently
13
+ * breaking widget rendering on Claude Desktop / claude.ai again.
14
+ *
15
+ * SEP-1865 (`_meta.ui.visibility`): conforming MCP hosts hide tools marked
16
+ * `visibility: ["app"]` from the LLM's `tools/list` while keeping them callable
17
+ * from inside a widget iframe via `callTool`. Non-conforming hosts ignore the
18
+ * marker and fall back to the tool description.
19
+ */
20
+ /**
21
+ * App-only marker — hides a tool from the LLM tool surface while leaving it
22
+ * callable from widgets. Deliberately carries no `resourceUri`: app-only tools
23
+ * (`*_data` feeds, catalogue/refresh hooks) return JSON, they do not render UI.
24
+ */
25
+ export declare const APP_ONLY_META: {
26
+ readonly ui: {
27
+ readonly visibility: readonly ["app"];
28
+ };
29
+ };
30
+ /**
31
+ * The Apps SDK `openai/widgetCSP` shape (snake_cased, as emitted on the wire
32
+ * by mcp-use's `AppsSdkAdapter`). All domains are full origins
33
+ * (e.g. `https://server.example`).
34
+ */
35
+ export interface WidgetCspMeta {
36
+ /** Origins allowed for fetch/XHR/WebSocket from inside the widget iframe. */
37
+ connect_domains?: string[];
38
+ /** Origins allowed for images, scripts, stylesheets, fonts. */
39
+ resource_domains?: string[];
40
+ /** Allowed iframe origins. */
41
+ frame_domains?: string[];
42
+ /** Allowed `base-uri` origins (SEP-1865). */
43
+ base_uri_domains?: string[];
44
+ }
45
+ /**
46
+ * Per-app widget-tool `_meta` defaults the framework threads into each
47
+ * plugin's `registerWidgetTools` hook (third parameter) so every widget tool
48
+ * can advertise them without knowing app-level configuration.
49
+ */
50
+ export interface WidgetToolMetaDefaults {
51
+ /** Content-security policy advertised to Apps SDK hosts (`openai/widgetCSP`). */
52
+ widgetCSP?: WidgetCspMeta;
53
+ }
54
+ /** Options for {@link uiMeta}. */
55
+ export interface UiMetaOptions {
56
+ /**
57
+ * The MCP UI resource URI hosting the widget bundle. When set, the host
58
+ * renders the tool result into that resource instead of returning it.
59
+ */
60
+ resourceUri?: string;
61
+ /** When `true`, marks the tool app-only via SEP-1865 `visibility: ["app"]`. */
62
+ appOnly?: boolean;
63
+ /**
64
+ * Display name used to derive the default `invoking`/`invoked` status
65
+ * strings (mirroring mcp-use's `Loading <name>...` / `<name> ready`
66
+ * defaults). Typically the tool title.
67
+ */
68
+ title?: string;
69
+ /** Host status line while the tool call runs (`openai/toolInvocation/invoking`). */
70
+ invoking?: string;
71
+ /** Host status line once the tool call finished (`openai/toolInvocation/invoked`). */
72
+ invoked?: string;
73
+ /** Widget description surfaced to Apps SDK hosts (`openai/widgetDescription`). */
74
+ widgetDescription?: string;
75
+ /** Content-security policy advertised to Apps SDK hosts (`openai/widgetCSP`). */
76
+ widgetCSP?: WidgetCspMeta;
77
+ }
78
+ /** Return shape of {@link uiMeta}: the nested `ui` block plus flat wire keys. */
79
+ export interface UiToolMeta extends Record<string, unknown> {
80
+ ui: Record<string, unknown>;
81
+ }
82
+ /**
83
+ * Builds the `_meta` object for a tool from a {@link UiMetaOptions}, keeping
84
+ * the SEP-1865 visibility / resourceUri literals in one place. Omitted fields
85
+ * are left off entirely so the emitted `_meta` matches the hand-written
86
+ * literals it replaces.
87
+ *
88
+ * Widget-RENDERING tools (a `resourceUri` and not app-only) additionally get
89
+ * the dual-protocol widget contract that mcp-use emits natively for `mcpApps`
90
+ * widgets — the flat SEP-1865 key plus the `openai/*` Apps SDK keys. Ext-apps
91
+ * hosts (Claude Desktop / claude.ai) key on these to recognise the tool as
92
+ * widget-producing and to deliver `structuredContent` to the iframe; without
93
+ * them every widget hangs on its loading skeleton. App-only tools stay free
94
+ * of the widget keys on purpose: their results are consumed by an already
95
+ * rendered widget via `callTool`, and advertising an output template would
96
+ * invite hosts to render them.
97
+ */
98
+ export declare function uiMeta(opts: UiMetaOptions): UiToolMeta;
99
+ //# sourceMappingURL=meta.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"meta.d.ts","sourceRoot":"","sources":["../../src/types/meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,eAAO,MAAM,aAAa;;;;CAA2C,CAAA;AAErE;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,6EAA6E;IAC7E,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;IAC1B,+DAA+D;IAC/D,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;IAC3B,8BAA8B;IAC9B,aAAa,CAAC,EAAE,MAAM,EAAE,CAAA;IACxB,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,iFAAiF;IACjF,SAAS,CAAC,EAAE,aAAa,CAAA;CAC1B;AAED,kCAAkC;AAClC,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,sFAAsF;IACtF,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,kFAAkF;IAClF,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,iFAAiF;IACjF,SAAS,CAAC,EAAE,aAAa,CAAA;CAC1B;AAED,iFAAiF;AACjF,MAAM,WAAW,UAAW,SAAQ,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IACzD,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC5B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,MAAM,CAAC,IAAI,EAAE,aAAa,GAAG,UAAU,CAqBtD"}
@@ -0,0 +1,66 @@
1
+ /**
2
+ * Shared `_meta` shapes for widget tools: the SEP-1865 tool-visibility
3
+ * convention plus the dual-protocol widget contract (MCP Apps + OpenAI
4
+ * Apps SDK) that ext-apps hosts key on.
5
+ *
6
+ * Browser-bundle-safe: this module is a pure object/function with no
7
+ * `mcp-use/server` or `node:*` imports, so it can be re-exported from the core
8
+ * Root barrel and consumed by UI bundles as well as server registrars. The
9
+ * dual-protocol key literals are therefore written out here instead of being
10
+ * imported from `mcp-use/server`; `meta.test.ts` pins them against the
11
+ * adapters mcp-use itself emits (`McpAppsAdapter`/`AppsSdkAdapter`), so a
12
+ * contract drift in a future mcp-use bump fails CI instead of silently
13
+ * breaking widget rendering on Claude Desktop / claude.ai again.
14
+ *
15
+ * SEP-1865 (`_meta.ui.visibility`): conforming MCP hosts hide tools marked
16
+ * `visibility: ["app"]` from the LLM's `tools/list` while keeping them callable
17
+ * from inside a widget iframe via `callTool`. Non-conforming hosts ignore the
18
+ * marker and fall back to the tool description.
19
+ */
20
+ /**
21
+ * App-only marker — hides a tool from the LLM tool surface while leaving it
22
+ * callable from widgets. Deliberately carries no `resourceUri`: app-only tools
23
+ * (`*_data` feeds, catalogue/refresh hooks) return JSON, they do not render UI.
24
+ */
25
+ export const APP_ONLY_META = { ui: { visibility: ["app"] } };
26
+ /**
27
+ * Builds the `_meta` object for a tool from a {@link UiMetaOptions}, keeping
28
+ * the SEP-1865 visibility / resourceUri literals in one place. Omitted fields
29
+ * are left off entirely so the emitted `_meta` matches the hand-written
30
+ * literals it replaces.
31
+ *
32
+ * Widget-RENDERING tools (a `resourceUri` and not app-only) additionally get
33
+ * the dual-protocol widget contract that mcp-use emits natively for `mcpApps`
34
+ * widgets — the flat SEP-1865 key plus the `openai/*` Apps SDK keys. Ext-apps
35
+ * hosts (Claude Desktop / claude.ai) key on these to recognise the tool as
36
+ * widget-producing and to deliver `structuredContent` to the iframe; without
37
+ * them every widget hangs on its loading skeleton. App-only tools stay free
38
+ * of the widget keys on purpose: their results are consumed by an already
39
+ * rendered widget via `callTool`, and advertising an output template would
40
+ * invite hosts to render them.
41
+ */
42
+ export function uiMeta(opts) {
43
+ const ui = {};
44
+ if (opts.resourceUri !== undefined)
45
+ ui.resourceUri = opts.resourceUri;
46
+ if (opts.appOnly)
47
+ ui.visibility = ["app"];
48
+ const meta = { ui };
49
+ if (opts.resourceUri !== undefined && !opts.appOnly) {
50
+ meta["ui/resourceUri"] = opts.resourceUri;
51
+ meta["openai/outputTemplate"] = opts.resourceUri;
52
+ meta["openai/toolInvocation/invoking"] =
53
+ opts.invoking ?? (opts.title ? `Loading ${opts.title}...` : "Loading view...");
54
+ meta["openai/toolInvocation/invoked"] =
55
+ opts.invoked ?? (opts.title ? `${opts.title} ready` : "View ready");
56
+ meta["openai/widgetAccessible"] = true;
57
+ meta["openai/resultCanProduceWidget"] = true;
58
+ if (opts.widgetDescription !== undefined) {
59
+ meta["openai/widgetDescription"] = opts.widgetDescription;
60
+ }
61
+ if (opts.widgetCSP !== undefined)
62
+ meta["openai/widgetCSP"] = opts.widgetCSP;
63
+ }
64
+ return meta;
65
+ }
66
+ //# sourceMappingURL=meta.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"meta.js","sourceRoot":"","sources":["../../src/types/meta.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,EAAE,EAAE,EAAE,EAAE,UAAU,EAAE,CAAC,KAAK,CAAC,EAAE,EAAW,CAAA;AA0DrE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,MAAM,CAAC,IAAmB;IACxC,MAAM,EAAE,GAA4B,EAAE,CAAA;IACtC,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS;QAAE,EAAE,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAA;IACrE,IAAI,IAAI,CAAC,OAAO;QAAE,EAAE,CAAC,UAAU,GAAG,CAAC,KAAK,CAAC,CAAA;IAEzC,MAAM,IAAI,GAAe,EAAE,EAAE,EAAE,CAAA;IAC/B,IAAI,IAAI,CAAC,WAAW,KAAK,SAAS,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC;QACpD,IAAI,CAAC,gBAAgB,CAAC,GAAG,IAAI,CAAC,WAAW,CAAA;QACzC,IAAI,CAAC,uBAAuB,CAAC,GAAG,IAAI,CAAC,WAAW,CAAA;QAChD,IAAI,CAAC,gCAAgC,CAAC;YACpC,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,KAAK,KAAK,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAA;QAChF,IAAI,CAAC,+BAA+B,CAAC;YACnC,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAA;QACrE,IAAI,CAAC,yBAAyB,CAAC,GAAG,IAAI,CAAA;QACtC,IAAI,CAAC,+BAA+B,CAAC,GAAG,IAAI,CAAA;QAC5C,IAAI,IAAI,CAAC,iBAAiB,KAAK,SAAS,EAAE,CAAC;YACzC,IAAI,CAAC,0BAA0B,CAAC,GAAG,IAAI,CAAC,iBAAiB,CAAA;QAC3D,CAAC;QACD,IAAI,IAAI,CAAC,SAAS,KAAK,SAAS;YAAE,IAAI,CAAC,kBAAkB,CAAC,GAAG,IAAI,CAAC,SAAS,CAAA;IAC7E,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC"}
@@ -0,0 +1,9 @@
1
+ export interface PipelineConfig {
2
+ steps?: PipelineStepRef[];
3
+ }
4
+ export interface PipelineStepRef {
5
+ id: string;
6
+ step: string;
7
+ optional?: boolean;
8
+ }
9
+ //# sourceMappingURL=pipeline.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../src/types/pipeline.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,eAAe,EAAE,CAAA;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB"}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=pipeline.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"pipeline.js","sourceRoot":"","sources":["../../src/types/pipeline.ts"],"names":[],"mappings":""}