@toolgrain/mcp 0.3.0-alpha.2 → 0.3.0

package/CHANGELOG.md

@@ -1,37 +1,26 @@
 # @toolgrain/mcp
 
-## 0.3.0-alpha.2
+## 0.3.0
 
 ### Minor Changes
 
-- Add reusable fixed-URI resources with text and binary reads, request context, and endpoint authorization across both MCP revisions.
-- Add native MCP Apps protocol contracts and typed React widgets with shared-entry routing.
-
-### Patch Changes
-
-- Updated dependencies
-  - @toolgrain/protocol@0.3.0-alpha.2
-
-## 0.3.0-alpha.1
-
-### Patch Changes
-
-- Pace request-scoped progress notifications at 100 ms intervals while preserving ordered delivery, backpressure, and prompt cancellation. Reject duplicate active progress tokens on shared message connections, release tokens on completion or cancellation, and preserve isolation between independent HTTP response streams.
-- @toolgrain/protocol@0.3.0-alpha.1
-
-## 0.3.0-alpha.0
-
-### Minor Changes
-
-- Add request-scoped progress reporting through `ctx.reportProgress()` with stdio notifications and HTTP SSE delivery. The bound reporter honors client progress tokens, increasing values, backpressure, cancellation, and normal final tool results. HTTP opens SSE on the first progress update and retains JSON responses when no progress is sent.
-
+- 0e1669b: Add request-scoped progress reporting through `ctx.reportProgress()` with stdio notifications and HTTP SSE delivery. The bound reporter honors client progress tokens, increasing values, backpressure, cancellation, and normal final tool results. HTTP opens SSE on the first progress update and retains JSON responses when no progress is sent.
+  
   Custom message transports must accept progress notifications alongside protocol responses. Direct `server.handle()` integrations can supply `onNotification` for request-scoped delivery; contexts without a delivery channel use a no-op reporter.
-
+  
   Keep final HTTP SSE delivery active until it completes or is cancelled, including server shutdown while the final write is blocked by backpressure.
+- e4ac322: Add reusable fixed-URI resources with text and binary reads, request context, and endpoint authorization across both MCP revisions.
+- 1cf25e6: Add typed content helpers for text, images, audio, resource links, and embedded files, with synchronous Uint8Array encoding and readonly authoring inputs.
+- 1cde354: Add native MCP Apps protocol contracts and typed React widgets with shared-entry routing.
 
 ### Patch Changes
 
-- @toolgrain/protocol@0.3.0-alpha.0
+- 0e1669b: Pace request-scoped progress notifications at 100 ms intervals while preserving ordered delivery, backpressure, and prompt cancellation. Reject duplicate active progress tokens on shared message connections, release tokens on completion or cancellation, and preserve isolation between independent HTTP response streams.
+- Updated dependencies [414e8f5]
+- Updated dependencies [1cde354]
+- Updated dependencies [712e975]
+- Updated dependencies [1cde354]
+  - @toolgrain/protocol@0.3.0
 
 ## 0.2.0
 

package/dist/index.d.ts

@@ -14,6 +14,8 @@ export type { Resource, ResourceDefinition, ResourceMetadata, ResourceReadResult
 export { resource } from "./resources/definition.js";
 export type { HandleOptions, Server, ServerOptions } from "./server.js";
 export { createServer } from "./server.js";
+export type { AudioContentOptions, BinaryContentData, ContentOptions, ImageContentOptions, ResourceContentOptions, ResourceLinkOptions, } from "./tools/content-helpers.js";
+export { content } from "./tools/content-helpers.js";
 export type { ToolClient, ToolContext, ToolContextOptions, ToolRequest, } from "./tools/context.js";
 export { toolContext } from "./tools/context.js";
 export type { Tool, ToolDefinition, ToolMetadata } from "./tools/definition.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,YAAY,EACV,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACrD,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACV,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,kBAAkB,GACnB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,YAAY,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,YAAY,EACZ,SAAS,EACT,iBAAiB,GAClB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,eAAe,CAAC;AAC3D,YAAY,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AACxD,YAAY,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACzD,YAAY,EACV,QAAQ,EACR,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AACrD,YAAY,EAAE,aAAa,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACxE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EACV,mBAAmB,EACnB,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,sBAAsB,EACtB,mBAAmB,GACpB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AACrD,YAAY,EACV,UAAU,EACV,WAAW,EACX,kBAAkB,EAClB,WAAW,GACZ,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AACjD,YAAY,EAAE,IAAI,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAChF,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,YAAY,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC;AACnD,YAAY,EACV,cAAc,EACd,SAAS,EACT,gBAAgB,EAChB,mBAAmB,GACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,YAAY,EACV,gBAAgB,EAChB,SAAS,EACT,kBAAkB,GACnB,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -7,6 +7,7 @@ export { authUrl as validateAuthUrl } from "./auth/url.js";
 export { createContext } from "./context/definition.js";
 export { resource } from "./resources/definition.js";
 export { createServer } from "./server.js";
+export { content } from "./tools/content-helpers.js";
 export { toolContext } from "./tools/context.js";
 export { tool } from "./tools/definition.js";
 export { ToolNameError } from "./tools/name.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAQtD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAQxD,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAO3C,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAShD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAQtD,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,eAAe,CAAC;AAE3D,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAQxD,OAAO,EAAE,QAAQ,EAAE,MAAM,2BAA2B,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAS3C,OAAO,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAOrD,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEjD,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAShD,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/tools/content-helpers.d.ts

@@ -0,0 +1,57 @@
+import type { AudioContent, BlobResourceContents, EmbeddedResource, ImageContent, ResourceLink, TextContent, TextResourceContents } from "@toolgrain/protocol";
+import type { DeepReadonly } from "./json-value.js";
+/** Base64-encoded data or bytes to encode synchronously; Node Buffers are accepted as Uint8Arrays. */
+export type BinaryContentData = string | Uint8Array;
+/** Optional content-block annotations and metadata, accepting readonly authoring values. */
+export type ContentOptions = DeepReadonly<Pick<TextContent, "annotations" | "_meta">>;
+/** Image content without its discriminator; data may be base64 or bytes. */
+export type ImageContentOptions = Omit<DeepReadonly<ImageContent>, "type" | "data"> & {
+    /** Base64 image data or bytes to encode; the supplied byte view is not mutated. */
+    readonly data: BinaryContentData;
+};
+/** Audio content without its discriminator; data may be base64 or bytes. */
+export type AudioContentOptions = Omit<DeepReadonly<AudioContent>, "type" | "data"> & {
+    /** Base64 audio data or bytes to encode; the supplied byte view is not mutated. */
+    readonly data: BinaryContentData;
+};
+/** A resource link's URI, required name, and optional descriptive fields. */
+export type ResourceLinkOptions = Omit<DeepReadonly<ResourceLink>, "type">;
+/** Embedded text or binary resource contents; text and blob are mutually exclusive. */
+export type ResourceContentOptions = (DeepReadonly<TextResourceContents> & {
+    readonly blob?: never;
+}) | (Omit<DeepReadonly<BlobResourceContents>, "blob"> & {
+    /** Base64 resource data or bytes to encode synchronously. */
+    readonly blob: BinaryContentData;
+    readonly text?: never;
+});
+/**
+ * Construct text content with optional annotations and metadata.
+ * Wrap the block in mcpResult() to return explicit MCP content from a tool.
+ */
+declare function text(value: string, options?: ContentOptions): DeepReadonly<TextContent>;
+/** Construct inline image content, synchronously encoding bytes when supplied. MIME type is required. */
+declare function image(options: ImageContentOptions): DeepReadonly<ImageContent>;
+/** Construct inline audio content, synchronously encoding bytes when supplied. MIME type is required. */
+declare function audio(options: AudioContentOptions): DeepReadonly<AudioContent>;
+/** Construct a link to an application-owned resource without fetching it or registering resource methods. */
+declare function resourceLink(options: ResourceLinkOptions): DeepReadonly<ResourceLink>;
+/**
+ * Embed text or binary resource contents without reading files or fetching URIs.
+ * The first argument's _meta belongs to the resource; options._meta belongs to the content block.
+ * Binary blob strings are base64; Uint8Array blobs are encoded synchronously.
+ */
+declare function resource(value: ResourceContentOptions, options?: ContentOptions): DeepReadonly<EmbeddedResource>;
+/**
+ * Typed constructors for mcpResult() content blocks. Accepts readonly inputs without mutating them.
+ * Helpers perform no I/O; the server validates and copies content during result conversion.
+ * Returned blocks have readonly authoring types; nested metadata is copied at server conversion.
+ */
+export declare const content: Readonly<{
+    text: typeof text;
+    image: typeof image;
+    audio: typeof audio;
+    resourceLink: typeof resourceLink;
+    resource: typeof resource;
+}>;
+export {};
+//# sourceMappingURL=content-helpers.d.ts.map

package/dist/tools/content-helpers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-helpers.d.ts","sourceRoot":"","sources":["../../src/tools/content-helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,oBAAoB,EACrB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAEpD,sGAAsG;AACtG,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,UAAU,CAAC;AAEpD,4FAA4F;AAC5F,MAAM,MAAM,cAAc,GAAG,YAAY,CACvC,IAAI,CAAC,WAAW,EAAE,aAAa,GAAG,OAAO,CAAC,CAC3C,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,YAAY,CAAC,YAAY,CAAC,EAC1B,MAAM,GAAG,MAAM,CAChB,GAAG;IACF,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;CAClC,CAAC;AAEF,4EAA4E;AAC5E,MAAM,MAAM,mBAAmB,GAAG,IAAI,CACpC,YAAY,CAAC,YAAY,CAAC,EAC1B,MAAM,GAAG,MAAM,CAChB,GAAG;IACF,mFAAmF;IACnF,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;CAClC,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,mBAAmB,GAAG,IAAI,CAAC,YAAY,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,CAAC;AAE3E,uFAAuF;AACvF,MAAM,MAAM,sBAAsB,GAC9B,CAAC,YAAY,CAAC,oBAAoB,CAAC,GAAG;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,GAChE,CAAC,IAAI,CAAC,YAAY,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC,GAAG;IAClD,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC;CACvB,CAAC,CAAC;AAWP;;;GAGG;AACH,iBAAS,IAAI,CACX,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,cAAmB,GAC3B,YAAY,CAAC,WAAW,CAAC,CAE3B;AAED,yGAAyG;AACzG,iBAAS,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAAC,YAAY,CAAC,CAEvE;AAED,yGAAyG;AACzG,iBAAS,KAAK,CAAC,OAAO,EAAE,mBAAmB,GAAG,YAAY,CAAC,YAAY,CAAC,CAEvE;AAED,6GAA6G;AAC7G,iBAAS,YAAY,CACnB,OAAO,EAAE,mBAAmB,GAC3B,YAAY,CAAC,YAAY,CAAC,CAE5B;AAED;;;;GAIG;AACH,iBAAS,QAAQ,CACf,KAAK,EAAE,sBAAsB,EAC7B,OAAO,GAAE,cAAmB,GAC3B,YAAY,CAAC,gBAAgB,CAAC,CAShC;AAED;;;;GAIG;AACH,eAAO,MAAM,OAAO;;;;;;EAMlB,CAAC"}

package/dist/tools/content-helpers.js

@@ -0,0 +1,55 @@
+function base64(data) {
+    if (typeof data === "string")
+        return data;
+    let binary = "";
+    // Bound the argument count for large files and encode only the supplied view.
+    for (let offset = 0; offset < data.length; offset += 0x8000)
+        binary += String.fromCharCode(...data.subarray(offset, offset + 0x8000));
+    return btoa(binary);
+}
+/**
+ * Construct text content with optional annotations and metadata.
+ * Wrap the block in mcpResult() to return explicit MCP content from a tool.
+ */
+function text(value, options = {}) {
+    return { ...options, type: "text", text: value };
+}
+/** Construct inline image content, synchronously encoding bytes when supplied. MIME type is required. */
+function image(options) {
+    return { ...options, type: "image", data: base64(options.data) };
+}
+/** Construct inline audio content, synchronously encoding bytes when supplied. MIME type is required. */
+function audio(options) {
+    return { ...options, type: "audio", data: base64(options.data) };
+}
+/** Construct a link to an application-owned resource without fetching it or registering resource methods. */
+function resourceLink(options) {
+    return { ...options, type: "resource_link" };
+}
+/**
+ * Embed text or binary resource contents without reading files or fetching URIs.
+ * The first argument's _meta belongs to the resource; options._meta belongs to the content block.
+ * Binary blob strings are base64; Uint8Array blobs are encoded synchronously.
+ */
+function resource(value, options = {}) {
+    return {
+        ...options,
+        type: "resource",
+        resource: value.blob === undefined
+            ? { ...value }
+            : { ...value, blob: base64(value.blob) },
+    };
+}
+/**
+ * Typed constructors for mcpResult() content blocks. Accepts readonly inputs without mutating them.
+ * Helpers perform no I/O; the server validates and copies content during result conversion.
+ * Returned blocks have readonly authoring types; nested metadata is copied at server conversion.
+ */
+export const content = Object.freeze({
+    text,
+    image,
+    audio,
+    resourceLink,
+    resource,
+});
+//# sourceMappingURL=content-helpers.js.map

package/dist/tools/content-helpers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-helpers.js","sourceRoot":"","sources":["../../src/tools/content-helpers.ts"],"names":[],"mappings":"AAiDA,SAAS,MAAM,CAAC,IAAuB;IACrC,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC1C,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,8EAA8E;IAC9E,KAAK,IAAI,MAAM,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,MAAM;QACzD,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC;IAC3E,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC;AAED;;;GAGG;AACH,SAAS,IAAI,CACX,KAAa,EACb,OAAO,GAAmB,EAAE;IAE5B,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACnD,CAAC;AAED,yGAAyG;AACzG,SAAS,KAAK,CAAC,OAA4B;IACzC,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;AACnE,CAAC;AAED,yGAAyG;AACzG,SAAS,KAAK,CAAC,OAA4B;IACzC,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;AACnE,CAAC;AAED,6GAA6G;AAC7G,SAAS,YAAY,CACnB,OAA4B;IAE5B,OAAO,EAAE,GAAG,OAAO,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC;AAC/C,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CACf,KAA6B,EAC7B,OAAO,GAAmB,EAAE;IAE5B,OAAO;QACL,GAAG,OAAO;QACV,IAAI,EAAE,UAAU;QAChB,QAAQ,EACN,KAAK,CAAC,IAAI,KAAK,SAAS;YACtB,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE;YACd,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE;KAC7C,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,MAAM,OAAO,GAAG,MAAM,CAAC,MAAM,CAAC;IACnC,IAAI;IACJ,KAAK;IACL,KAAK;IACL,YAAY;IACZ,QAAQ;CACT,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolgrain/mcp",
-  "version": "0.3.0-alpha.2",
+  "version": "0.3.0",
   "description": "Define reusable, typed MCP tools and servers with Zod validation.",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,7 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/",
-    "tag": "alpha"
+    "tag": "latest"
   },
   "type": "module",
   "exports": {
@@ -59,7 +59,7 @@
     "@toolgrain/repo-tools": "0.0.0"
   },
   "dependencies": {
-    "@toolgrain/protocol": "0.3.0-alpha.2"
+    "@toolgrain/protocol": "0.3.0"
   },
   "engines": {
     "node": "^24.20.0",

package/src/index.ts

@@ -25,6 +25,15 @@ export type {
 export { resource } from "./resources/definition.js";
 export type { HandleOptions, Server, ServerOptions } from "./server.js";
 export { createServer } from "./server.js";
+export type {
+  AudioContentOptions,
+  BinaryContentData,
+  ContentOptions,
+  ImageContentOptions,
+  ResourceContentOptions,
+  ResourceLinkOptions,
+} from "./tools/content-helpers.js";
+export { content } from "./tools/content-helpers.js";
 export type {
   ToolClient,
   ToolContext,

package/src/tools/content-helpers.ts

@@ -0,0 +1,117 @@
+import type {
+  AudioContent,
+  BlobResourceContents,
+  EmbeddedResource,
+  ImageContent,
+  ResourceLink,
+  TextContent,
+  TextResourceContents,
+} from "@toolgrain/protocol";
+import type { DeepReadonly } from "./json-value.js";
+
+/** Base64-encoded data or bytes to encode synchronously; Node Buffers are accepted as Uint8Arrays. */
+export type BinaryContentData = string | Uint8Array;
+
+/** Optional content-block annotations and metadata, accepting readonly authoring values. */
+export type ContentOptions = DeepReadonly<
+  Pick<TextContent, "annotations" | "_meta">
+>;
+
+/** Image content without its discriminator; data may be base64 or bytes. */
+export type ImageContentOptions = Omit<
+  DeepReadonly<ImageContent>,
+  "type" | "data"
+> & {
+  /** Base64 image data or bytes to encode; the supplied byte view is not mutated. */
+  readonly data: BinaryContentData;
+};
+
+/** Audio content without its discriminator; data may be base64 or bytes. */
+export type AudioContentOptions = Omit<
+  DeepReadonly<AudioContent>,
+  "type" | "data"
+> & {
+  /** Base64 audio data or bytes to encode; the supplied byte view is not mutated. */
+  readonly data: BinaryContentData;
+};
+
+/** A resource link's URI, required name, and optional descriptive fields. */
+export type ResourceLinkOptions = Omit<DeepReadonly<ResourceLink>, "type">;
+
+/** Embedded text or binary resource contents; text and blob are mutually exclusive. */
+export type ResourceContentOptions =
+  | (DeepReadonly<TextResourceContents> & { readonly blob?: never })
+  | (Omit<DeepReadonly<BlobResourceContents>, "blob"> & {
+      /** Base64 resource data or bytes to encode synchronously. */
+      readonly blob: BinaryContentData;
+      readonly text?: never;
+    });
+
+function base64(data: BinaryContentData): string {
+  if (typeof data === "string") return data;
+  let binary = "";
+  // Bound the argument count for large files and encode only the supplied view.
+  for (let offset = 0; offset < data.length; offset += 0x8000)
+    binary += String.fromCharCode(...data.subarray(offset, offset + 0x8000));
+  return btoa(binary);
+}
+
+/**
+ * Construct text content with optional annotations and metadata.
+ * Wrap the block in mcpResult() to return explicit MCP content from a tool.
+ */
+function text(
+  value: string,
+  options: ContentOptions = {},
+): DeepReadonly<TextContent> {
+  return { ...options, type: "text", text: value };
+}
+
+/** Construct inline image content, synchronously encoding bytes when supplied. MIME type is required. */
+function image(options: ImageContentOptions): DeepReadonly<ImageContent> {
+  return { ...options, type: "image", data: base64(options.data) };
+}
+
+/** Construct inline audio content, synchronously encoding bytes when supplied. MIME type is required. */
+function audio(options: AudioContentOptions): DeepReadonly<AudioContent> {
+  return { ...options, type: "audio", data: base64(options.data) };
+}
+
+/** Construct a link to an application-owned resource without fetching it or registering resource methods. */
+function resourceLink(
+  options: ResourceLinkOptions,
+): DeepReadonly<ResourceLink> {
+  return { ...options, type: "resource_link" };
+}
+
+/**
+ * Embed text or binary resource contents without reading files or fetching URIs.
+ * The first argument's _meta belongs to the resource; options._meta belongs to the content block.
+ * Binary blob strings are base64; Uint8Array blobs are encoded synchronously.
+ */
+function resource(
+  value: ResourceContentOptions,
+  options: ContentOptions = {},
+): DeepReadonly<EmbeddedResource> {
+  return {
+    ...options,
+    type: "resource",
+    resource:
+      value.blob === undefined
+        ? { ...value }
+        : { ...value, blob: base64(value.blob) },
+  };
+}
+
+/**
+ * Typed constructors for mcpResult() content blocks. Accepts readonly inputs without mutating them.
+ * Helpers perform no I/O; the server validates and copies content during result conversion.
+ * Returned blocks have readonly authoring types; nested metadata is copied at server conversion.
+ */
+export const content = Object.freeze({
+  text,
+  image,
+  audio,
+  resourceLink,
+  resource,
+});