@ggui-ai/artifact-manifest 0.6.3 → 0.8.0

package/dist/artifact-manifest.d.ts

@@ -32,6 +32,10 @@ import { z } from 'zod';
  */
 export declare const artifactManifestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     connect: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    mcpTools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        server: z.ZodOptional<z.ZodString>;
+        tool: z.ZodString;
+    }, z.core.$strict>>>>;
     tags: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     author: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;
@@ -92,6 +96,10 @@ export declare const artifactManifestSchema: z.ZodDiscriminatedUnion<[z.ZodObjec
     intent: z.ZodOptional<z.ZodString>;
     generatorProtocolVersion: z.ZodOptional<z.ZodString>;
     toolIdentityCatalogHash: z.ZodOptional<z.ZodString>;
+    mcpTools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        server: z.ZodOptional<z.ZodString>;
+        tool: z.ZodString;
+    }, z.core.$strict>>>>;
 }, z.core.$strict>], "kind">;
 /**
  * Static TypeScript type derived from {@link artifactManifestSchema}.

package/dist/artifact-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"artifact-manifest.d.ts","sourceRoot":"","sources":["../src/artifact-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAGjC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAatE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,sBAAsB,CAAC,SAAS,CAAC,CAErD"}
+{"version":3,"file":"artifact-manifest.d.ts","sourceRoot":"","sources":["../src/artifact-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAOxB;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAGjC,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,sBAAsB,CAAC,CAAC;AAatE;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,gBAAgB,CAEpE;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,sBAAsB,CAAC,SAAS,CAAC,CAErD"}

package/dist/blueprint-manifest.d.ts

@@ -94,6 +94,10 @@ export declare const blueprintManifestSchema: z.ZodObject<{
     intent: z.ZodOptional<z.ZodString>;
     generatorProtocolVersion: z.ZodOptional<z.ZodString>;
     toolIdentityCatalogHash: z.ZodOptional<z.ZodString>;
+    mcpTools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        server: z.ZodOptional<z.ZodString>;
+        tool: z.ZodString;
+    }, z.core.$strict>>>>;
 }, z.core.$strict>;
 /**
  * Static TypeScript type derived from {@link blueprintManifestSchema}.

package/dist/blueprint-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blueprint-manifest.d.ts","sourceRoot":"","sources":["../src/blueprint-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGlB,MAAM,mBAAmB,CAAC;AA+B3B;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;kBAwElC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAmBxE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,wBAAwB,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAEtE;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,uBAAuB,CAAC,SAAS,CAAC,CAEtD"}
+{"version":3,"file":"blueprint-manifest.d.ts","sourceRoot":"","sources":["../src/blueprint-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,EACL,KAAK,iBAAiB,EACtB,KAAK,YAAY,EAGlB,MAAM,mBAAmB,CAAC;AAgC3B;;;;;;;;GAQG;AACH,eAAO,MAAM,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA+ElC,CAAC;AAEH;;;;;;;;GAQG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,uBAAuB,CAAC,CAAC;AAmBxE;;;;GAIG;AACH,eAAO,MAAM,4BAA4B,wBAAwB,CAAC;AAElE;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG,iBAAiB,CAEtE;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,uBAAuB,CAAC,SAAS,CAAC,CAEtD"}

package/dist/blueprint-manifest.js

@@ -61,6 +61,7 @@
 import { z } from 'zod';
 import { blueprintVarianceSchema, dataContractSchema, } from '@ggui-ai/protocol';
 import { ArtifactScopeSchema, ArtifactVersionSchema, ArtifactVisibilitySchema, BLUEPRINT_NAME_RE, sharedMetadataShape, } from './base.js';
+import { mcpToolsSchema } from './mcp-tool-bindings.js';
 /**
  * Blueprint name regex — the same kebab-case rule as gadgets. See
  * {@link BLUEPRINT_NAME_RE} for the rationale.
@@ -130,6 +131,10 @@ export const blueprintManifestSchema = z.strictObject({
         .min(1)
         .optional()
         .describe('SHA256(16) of the tool-identity catalog used to canonicalize `contract` at authoring time. Importers re-canonicalize against their own catalog and recompute the key; a divergence means the same intent would mis-key and silently cold-gen, so it is rejected. Optional — most marketplace blueprints are authored without a live tool catalog, which leaves the import gate’s re-key check inert.'),
+    // ---- Optional MCP tool bindings (search metadata only) ----
+    mcpTools: mcpToolsSchema
+        .optional()
+        .describe('MCP tool bindings this blueprint renders — surfaced in registry search results and matched by the `tool` / `server` search filters. When absent, registry publish derives bare tool-name bindings from the contract (`propsSpec.properties[*].sourceTool` plus `streamSpec[*].source.tool`); declaring this field disables derivation entirely (declared wins, no merge). Bindings are publisher claims, not an endorsement by the named server. Search metadata only — never part of `blueprintKey` or any cache identity. Max 16 entries, charset `[A-Za-z0-9_.-]`, case-sensitive; exact-duplicate `(server, tool)` pairs rejected.'),
     // ---- Shared metadata ----
     ...sharedMetadataShape,
 });

package/dist/gadget-manifest.d.ts

@@ -81,6 +81,10 @@ export declare const gadgetExportSchema: z.ZodUnion<readonly [z.ZodObject<{
  */
 export declare const gadgetManifestSchema: z.ZodObject<{
     connect: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    mcpTools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodObject<{
+        server: z.ZodOptional<z.ZodString>;
+        tool: z.ZodString;
+    }, z.core.$strict>>>>;
     tags: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
     author: z.ZodOptional<z.ZodObject<{
         name: z.ZodString;

package/dist/gadget-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gadget-manifest.d.ts","sourceRoot":"","sources":["../src/gadget-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAsFxB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;oBAwB7B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAwH/B,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,oBAAoB,CAAC,SAAS,CAAC,CAEnD"}
+{"version":3,"file":"gadget-manifest.d.ts","sourceRoot":"","sources":["../src/gadget-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqDG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAuFxB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB;;;;;;;;;;;;oBAwB7B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA+H/B,CAAC;AAEH;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,qBAAqB,CAAC;AAE5D;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,GAAG,cAAc,CAEhE;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,OAAO,GACX,UAAU,CAAC,OAAO,oBAAoB,CAAC,SAAS,CAAC,CAEnD"}

package/dist/gadget-manifest.js

@@ -55,6 +55,7 @@
 import { z } from 'zod';
 import { BUNDLE_HOST_RE, gadgetRequiresSchema, jsonValueSchema, } from '@ggui-ai/protocol';
 import { ArtifactScopeSchema, ArtifactVersionSchema, ArtifactVisibilitySchema, GADGET_NAME_RE, sharedMetadataShape, } from './base.js';
+import { mcpToolsSchema } from './mcp-tool-bindings.js';
 /**
  * Gadget name — kebab-case identifier without scope prefix. The
  * scope lives on its own field. Examples: `weather-card`, `leaflet`,
@@ -220,7 +221,7 @@ export const gadgetManifestSchema = z.strictObject({
         .string()
         .regex(BUNDLE_HOST_RE)
         .optional()
-        .describe("Optional author-default registry hostname (no scheme, no path). The server prepends `https://` and appends `/bundles/<scope>/<name>/<version>/{bundle.js,style.css}` at push time. Omit to inherit the spec default (`registry.ggui.ai`). Operators can override per-gadget via `ggui.json#app.gadgets[*].bundleHost`."),
+        .describe("Optional author-default registry hostname (no scheme, no path). The server prepends `https://` and appends `/bundles/public/<scope>/<name>/<version>/{bundle.js,style.css}` at push time (the public prefix of the registry's visibility-split bundle layout). Omit to inherit the spec default (`registry.ggui.ai`). Operators can override per-gadget via `ggui.json#app.gadgets[*].bundleHost`."),
     // ---- Shared metadata ----
     // `description` is intentionally NOT spread from here — gadgets
     // require it (declared above) while blueprints inherit the
@@ -233,6 +234,10 @@ export const gadgetManifestSchema = z.strictObject({
     })(),
     // ---- Optional wire allowlist (mirrors gadgetEntry.connect) ----
     connect: GadgetConnectSchema.optional().describe("URLs the wrapper's runtime may speak to. Merged into the iframe CSP `connect-src` at boot. Shape mirrors `gadgetDescriptorSchema.connect` in `@ggui-ai/protocol` — a flat readonly string list."),
+    // ---- Optional MCP tool bindings (search metadata only) ----
+    mcpTools: mcpToolsSchema
+        .optional()
+        .describe('MCP tool bindings this gadget renders — surfaced in registry search results and matched by the `tool` / `server` search filters (`tool` matches any entry with that tool name; `server` matches entries declaring that server; both together match the exact pair). Bindings are publisher claims, not an endorsement by the named server. Search metadata only — never part of any cache identity. Max 16 entries, charset `[A-Za-z0-9_.-]`, case-sensitive; exact-duplicate `(server, tool)` pairs rejected.'),
 });
 /**
  * Canonical filename — always at the gadget repo root, always this

package/dist/index.d.ts

@@ -24,6 +24,8 @@ export type { BlueprintManifest } from './blueprint-manifest.js';
 export { artifactManifestSchema, parseArtifactManifest, safeParseArtifactManifest, } from './artifact-manifest.js';
 export type { ArtifactManifest } from './artifact-manifest.js';
 export { GADGET_NAME_RE, BLUEPRINT_NAME_RE, ArtifactScopeSchema, ArtifactVersionSchema, } from './base.js';
+export { MCP_TOOL_BINDING_NAME_RE, mcpToolBindingSchema, mcpToolsSchema, resolveMcpToolBindings, } from './mcp-tool-bindings.js';
+export type { McpToolBinding, McpToolBindingSource } from './mcp-tool-bindings.js';
 export { manifestToRegistryEntry, type ManifestToRegistryEntryFields, } from './manifest-to-registry-entry.js';
 export { POOL_ARTIFACT_CODES_DIR, POOL_ARTIFACT_CODE_REF_PATTERN, POOL_ARTIFACT_MANIFEST_FILENAME, POOL_ARTIFACT_SCHEMA_VERSION, POOL_ARTIFACT_V1_REJECTION, buildPoolArtifactManifest, parsePoolArtifactManifest, poolArtifactCodeRef, serializePoolArtifactManifest, type ParsePoolArtifactManifestResult, type PoolArtifactManifest, type PoolArtifactManifestEntry, } from './pool-artifact.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAGjE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAS/D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AAMnB,OAAO,EACL,uBAAuB,EACvB,KAAK,6BAA6B,GACnC,MAAM,iCAAiC,CAAC;AAMzC,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,+BAA+B,EAC/B,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,6BAA6B,EAC7B,KAAK,+BAA+B,EACpC,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,GAC/B,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAGH,OAAO,EACL,yBAAyB,EACzB,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,uBAAuB,GACxB,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAG3D,OAAO,EACL,4BAA4B,EAC5B,uBAAuB,EACvB,sBAAsB,EACtB,0BAA0B,GAC3B,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAGjE,OAAO,EACL,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,GAC1B,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAS/D,OAAO,EACL,cAAc,EACd,iBAAiB,EACjB,mBAAmB,EACnB,qBAAqB,GACtB,MAAM,WAAW,CAAC;AAQnB,OAAO,EACL,wBAAwB,EACxB,oBAAoB,EACpB,cAAc,EACd,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,cAAc,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAMnF,OAAO,EACL,uBAAuB,EACvB,KAAK,6BAA6B,GACnC,MAAM,iCAAiC,CAAC;AAMzC,OAAO,EACL,uBAAuB,EACvB,8BAA8B,EAC9B,+BAA+B,EAC/B,4BAA4B,EAC5B,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,mBAAmB,EACnB,6BAA6B,EAC7B,KAAK,+BAA+B,EACpC,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,GAC/B,MAAM,oBAAoB,CAAC"}

package/dist/index.js

@@ -31,6 +31,13 @@ export { artifactManifestSchema, parseArtifactManifest, safeParseArtifactManifes
 // validation; reuse keeps the CLI and registry-side validation on a
 // single regex source.
 export { GADGET_NAME_RE, BLUEPRINT_NAME_RE, ArtifactScopeSchema, ArtifactVersionSchema, } from './base.js';
+// MCP tool bindings — the `mcpTools` search-metadata field shared by
+// both manifest kinds, plus the declared-vs-derived resolver registry
+// publish flows use to compute the effective binding set. Registry
+// search input validation (`tool=` / `server=` filters) imports
+// `MCP_TOOL_BINDING_NAME_RE` from here so the wire filters and the
+// manifest field stay on a single charset rule.
+export { MCP_TOOL_BINDING_NAME_RE, mcpToolBindingSchema, mcpToolsSchema, resolveMcpToolBindings, } from './mcp-tool-bindings.js';
 // Manifest → registry-entry translator. The install CLI, programmatic
 // publish flows, and any future register-by-manifest tool all go
 // through this one function. Round-trip validated in the companion

package/dist/mcp-tool-bindings.d.ts

@@ -0,0 +1,95 @@
+/**
+ * MCP tool bindings — the `mcpTools` search-metadata field shared by
+ * both artifact-manifest kinds, plus the declared-vs-derived resolver
+ * registry publish flows use to compute the effective binding set.
+ *
+ * A binding names an MCP tool (optionally scoped to an MCP server,
+ * `serverInfo.name` semantics) that the artifact renders a UI for.
+ * Bindings are search metadata ONLY:
+ *
+ *   - They MUST NOT enter contract canonicalization, `blueprintKey`,
+ *     or any cache identity — declaring or removing bindings never
+ *     re-keys an artifact.
+ *   - They are publisher claims. A binding MUST NOT be presented as
+ *     an endorsement by the named server or its authors.
+ *
+ * Precedence ({@link resolveMcpToolBindings}): a declared `mcpTools`
+ * field wins entirely — derivation never runs, no merge. Blueprints
+ * without the field derive bare tool-name bindings from their
+ * contract (`propsSpec.properties[*].sourceTool` union
+ * `streamSpec[*].source.tool`). Gadgets never derive (they carry no
+ * contract).
+ */
+import { z } from "zod";
+import type { BlueprintManifest } from "./blueprint-manifest.js";
+import type { GadgetManifest } from "./gadget-manifest.js";
+/**
+ * Charset for both `server` and `tool` binding names — 1-128 chars
+ * of `[A-Za-z0-9_.-]`, the practical MCP tool-name grammar.
+ * Case-sensitive throughout (MCP tool names are). Registry search
+ * input validation (`tool=` / `server=` filters) imports this via
+ * the package barrel so the wire filters and the manifest field
+ * stay on a single charset rule.
+ */
+export declare const MCP_TOOL_BINDING_NAME_RE: RegExp;
+/**
+ * One MCP tool binding. `server` optional — omit for a
+ * server-agnostic tool-name binding.
+ */
+export declare const mcpToolBindingSchema: z.ZodObject<{
+    server: z.ZodOptional<z.ZodString>;
+    tool: z.ZodString;
+}, z.core.$strict>;
+/** Static TS type for one binding entry. */
+export type McpToolBinding = z.infer<typeof mcpToolBindingSchema>;
+/**
+ * Bounded binding list. Caps protect the index and wire payload
+ * size — 16 entries covers every realistic multi-tool artifact
+ * while bounding worst-case spam (same rationale as the 20-tag
+ * cap on `tags`). Exact-duplicate `(server, tool)` pairs are
+ * rejected; the same tool under different servers (or bare +
+ * server-scoped) is legal.
+ */
+export declare const mcpToolsSchema: z.ZodReadonly<z.ZodArray<z.ZodObject<{
+    server: z.ZodOptional<z.ZodString>;
+    tool: z.ZodString;
+}, z.core.$strict>>>;
+/**
+ * Provenance of a resolved binding set — declared verbatim on the
+ * manifest, or derived from a blueprint contract's tool names.
+ */
+export type McpToolBindingSource = "declared" | "derived";
+/**
+ * Compute the effective binding set for a manifest. Pure.
+ *
+ * Precedence: a declared `mcpTools` field wins entirely (result
+ * marked `declared`; derivation never runs, no merge). Otherwise,
+ * blueprint manifests with a contract derive bare `{tool}` entries
+ * from the union of `contract.propsSpec.properties[*].sourceTool`
+ * and `contract.streamSpec[*].source.tool` (contracts carry no
+ * server identity), marked `derived`. Derivation stays INSIDE the
+ * same envelope a declared list is validated against — it composes
+ * the envelope, it does not relax it:
+ *
+ *   - Every candidate tool name is filtered through
+ *     {@link MCP_TOOL_BINDING_NAME_RE}; a name failing the charset
+ *     (including the empty string — just one case of the charset
+ *     filter) is dropped silently rather than rejected. Contract
+ *     lineage is agent/tool-authored data, not an author
+ *     declaration, so malformed lineage is noise to filter, not a
+ *     manifest error.
+ *   - Survivors are deduped first-seen — props entries in
+ *     declaration order, then stream channels in declaration order —
+ *     then capped at {@link MCP_TOOL_BINDING_MAX_ENTRIES} in that
+ *     same first-appearance order, matching the bound a declared
+ *     list is schema-capped at.
+ *
+ * Returns `undefined` when nothing declares or derives (gadgets
+ * without `mcpTools`, contract-less blueprints, contracts naming no
+ * valid tools) — such artifacts are simply not findable by tool.
+ */
+export declare function resolveMcpToolBindings(manifest: GadgetManifest | BlueprintManifest): {
+    source: McpToolBindingSource;
+    bindings: ReadonlyArray<McpToolBinding>;
+} | undefined;
+//# sourceMappingURL=mcp-tool-bindings.d.ts.map

package/dist/mcp-tool-bindings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-tool-bindings.d.ts","sourceRoot":"","sources":["../src/mcp-tool-bindings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AACjE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D;;;;;;;GAOG;AACH,eAAO,MAAM,wBAAwB,QAA4B,CAAC;AASlE;;;GAGG;AACH,eAAO,MAAM,oBAAoB;;;kBAkB/B,CAAC;AAEH,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,oBAAoB,CAAC,CAAC;AAElE;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc;;;oBAkBxB,CAAC;AAEJ;;;GAGG;AACH,MAAM,MAAM,oBAAoB,GAAG,UAAU,GAAG,SAAS,CAAC;AAE1D;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,cAAc,GAAG,iBAAiB,GAC3C;IAAE,MAAM,EAAE,oBAAoB,CAAC;IAAC,QAAQ,EAAE,aAAa,CAAC,cAAc,CAAC,CAAA;CAAE,GAAG,SAAS,CAuBvF"}

package/dist/mcp-tool-bindings.js

@@ -0,0 +1,137 @@
+/**
+ * MCP tool bindings — the `mcpTools` search-metadata field shared by
+ * both artifact-manifest kinds, plus the declared-vs-derived resolver
+ * registry publish flows use to compute the effective binding set.
+ *
+ * A binding names an MCP tool (optionally scoped to an MCP server,
+ * `serverInfo.name` semantics) that the artifact renders a UI for.
+ * Bindings are search metadata ONLY:
+ *
+ *   - They MUST NOT enter contract canonicalization, `blueprintKey`,
+ *     or any cache identity — declaring or removing bindings never
+ *     re-keys an artifact.
+ *   - They are publisher claims. A binding MUST NOT be presented as
+ *     an endorsement by the named server or its authors.
+ *
+ * Precedence ({@link resolveMcpToolBindings}): a declared `mcpTools`
+ * field wins entirely — derivation never runs, no merge. Blueprints
+ * without the field derive bare tool-name bindings from their
+ * contract (`propsSpec.properties[*].sourceTool` union
+ * `streamSpec[*].source.tool`). Gadgets never derive (they carry no
+ * contract).
+ */
+import { z } from "zod";
+/**
+ * Charset for both `server` and `tool` binding names — 1-128 chars
+ * of `[A-Za-z0-9_.-]`, the practical MCP tool-name grammar.
+ * Case-sensitive throughout (MCP tool names are). Registry search
+ * input validation (`tool=` / `server=` filters) imports this via
+ * the package barrel so the wire filters and the manifest field
+ * stay on a single charset rule.
+ */
+export const MCP_TOOL_BINDING_NAME_RE = /^[A-Za-z0-9_.-]{1,128}$/;
+/**
+ * Shared entry-count bound for a binding list, declared OR derived —
+ * one envelope, referenced everywhere a cap applies rather than a
+ * second magic `16` drifting from this one.
+ */
+const MCP_TOOL_BINDING_MAX_ENTRIES = 16;
+/**
+ * One MCP tool binding. `server` optional — omit for a
+ * server-agnostic tool-name binding.
+ */
+export const mcpToolBindingSchema = z.strictObject({
+    server: z
+        .string()
+        .regex(MCP_TOOL_BINDING_NAME_RE, {
+        message: "server must be 1-128 chars of `[A-Za-z0-9_.-]` (MCP server name charset).",
+    })
+        .optional()
+        .describe("MCP server identity this binding targets — `serverInfo.name` semantics, matched case-sensitively. Omit for a server-agnostic binding that matches the tool name on any server. 1-128 chars, charset `[A-Za-z0-9_.-]`."),
+    tool: z
+        .string()
+        .regex(MCP_TOOL_BINDING_NAME_RE, {
+        message: "tool must be 1-128 chars of `[A-Za-z0-9_.-]` (MCP tool name charset).",
+    })
+        .describe("MCP tool name this artifact renders. Matched case-sensitively by the registry search `tool` filter. 1-128 chars, charset `[A-Za-z0-9_.-]`."),
+});
+/**
+ * Bounded binding list. Caps protect the index and wire payload
+ * size — 16 entries covers every realistic multi-tool artifact
+ * while bounding worst-case spam (same rationale as the 20-tag
+ * cap on `tags`). Exact-duplicate `(server, tool)` pairs are
+ * rejected; the same tool under different servers (or bare +
+ * server-scoped) is legal.
+ */
+export const mcpToolsSchema = z
+    .array(mcpToolBindingSchema)
+    .min(1, { message: "mcpTools must declare at least one binding." })
+    .max(MCP_TOOL_BINDING_MAX_ENTRIES, {
+    message: `at most ${MCP_TOOL_BINDING_MAX_ENTRIES} MCP tool bindings per artifact.`,
+})
+    .readonly()
+    .refine((bindings) => {
+    const seen = new Set();
+    for (const binding of bindings) {
+        const key = JSON.stringify([binding.server ?? null, binding.tool]);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+    }
+    return true;
+}, { message: "duplicate `(server, tool)` binding pairs are not allowed." });
+/**
+ * Compute the effective binding set for a manifest. Pure.
+ *
+ * Precedence: a declared `mcpTools` field wins entirely (result
+ * marked `declared`; derivation never runs, no merge). Otherwise,
+ * blueprint manifests with a contract derive bare `{tool}` entries
+ * from the union of `contract.propsSpec.properties[*].sourceTool`
+ * and `contract.streamSpec[*].source.tool` (contracts carry no
+ * server identity), marked `derived`. Derivation stays INSIDE the
+ * same envelope a declared list is validated against — it composes
+ * the envelope, it does not relax it:
+ *
+ *   - Every candidate tool name is filtered through
+ *     {@link MCP_TOOL_BINDING_NAME_RE}; a name failing the charset
+ *     (including the empty string — just one case of the charset
+ *     filter) is dropped silently rather than rejected. Contract
+ *     lineage is agent/tool-authored data, not an author
+ *     declaration, so malformed lineage is noise to filter, not a
+ *     manifest error.
+ *   - Survivors are deduped first-seen — props entries in
+ *     declaration order, then stream channels in declaration order —
+ *     then capped at {@link MCP_TOOL_BINDING_MAX_ENTRIES} in that
+ *     same first-appearance order, matching the bound a declared
+ *     list is schema-capped at.
+ *
+ * Returns `undefined` when nothing declares or derives (gadgets
+ * without `mcpTools`, contract-less blueprints, contracts naming no
+ * valid tools) — such artifacts are simply not findable by tool.
+ */
+export function resolveMcpToolBindings(manifest) {
+    if (manifest.mcpTools !== undefined) {
+        return { source: "declared", bindings: manifest.mcpTools };
+    }
+    if (manifest.kind !== "blueprint" || manifest.contract === undefined) {
+        return undefined;
+    }
+    const seen = new Set();
+    const tools = [];
+    const add = (tool) => {
+        if (tool === undefined || !MCP_TOOL_BINDING_NAME_RE.test(tool) || seen.has(tool))
+            return;
+        seen.add(tool);
+        tools.push(tool);
+    };
+    for (const entry of Object.values(manifest.contract.propsSpec?.properties ?? {})) {
+        add(entry.sourceTool);
+    }
+    for (const entry of Object.values(manifest.contract.streamSpec ?? {})) {
+        add(entry.source?.tool);
+    }
+    if (tools.length === 0)
+        return undefined;
+    const capped = tools.slice(0, MCP_TOOL_BINDING_MAX_ENTRIES);
+    return { source: "derived", bindings: capped.map((tool) => ({ tool })) };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ggui-ai/artifact-manifest",
-  "version": "0.6.3",
+  "version": "0.8.0",
   "description": "Strict zod schemas + parsers for ggui marketplace artifact manifests — ggui.gadget.json (gadget bundles) and ggui.blueprint.json (cached UI blueprints).",
   "license": "Apache-2.0",
   "keywords": [
@@ -27,11 +27,12 @@
   },
   "dependencies": {
     "zod": "^4.3.6",
-    "@ggui-ai/protocol": "0.6.3"
+    "@ggui-ai/protocol": "0.8.0"
   },
   "devDependencies": {
     "typescript": "^5.0.0",
-    "vitest": "^3.2.6"
+    "vitest": "^3.2.6",
+    "@ggui-ai/protocol-conformance": "0.8.0"
   },
   "repository": {
     "type": "git",