@optimizely-opal/opal-tools-sdk 0.1.6-dev → 0.1.9-dev

package/src/registerResource.ts

@@ -0,0 +1,82 @@
+import { ProteusDocument } from "./proteus";
+import { registry } from "./registry";
+
+type ResourceOptions = {
+  /** Description of the resource */
+  description?: string;
+  /** MIME type of the resource content (e.g., "application/vnd.opal.proteus+json") */
+  mimeType?: string;
+  /** Human-readable title for the resource */
+  title?: string;
+  /** The unique URI for this resource (e.g., "ui://my-app/create-form") */
+  uri: string;
+};
+
+/**
+ * Register a function as an MCP resource
+ *
+ * The handler can return either a string or a UI.Document. When returning a UI.Document,
+ * the SDK will automatically serialize it to JSON and set the MIME type to
+ * "application/vnd.opal.proteus+json" (if not already specified).
+ *
+ * @example
+ * ```typescript
+ * // Example 1: Returning a string (manual serialization)
+ * const getFormResource = registerResource('create-form', {
+ *   uri: 'ui://my-app/create-form',
+ *   description: 'Create form UI specification',
+ *   mimeType: 'application/vnd.opal.proteus+json',
+ *   title: 'Create Form'
+ * }, async () => {
+ *   return JSON.stringify(proteusSpec);
+ * });
+ *
+ * // Example 2: Returning a UI.Document (automatic serialization)
+ * import { UI } from '@optimizely-opal/opal-tools-sdk';
+ *
+ * const getDynamicForm = registerResource('create-form', {
+ *   uri: 'ui://my-app/create-form',
+ *   description: 'Create form UI specification',
+ *   title: 'Create Form'
+ * }, async () => {
+ *   return UI.Document({
+ *     appName: 'Item Manager',
+ *     title: 'Create New Item',
+ *     body: [
+ *       UI.Heading({ children: 'Create Item' }),
+ *       UI.Field({
+ *         label: 'Name',
+ *         children: UI.Input({ name: 'item_name' })
+ *       })
+ *     ],
+ *     actions: [UI.Action({ children: 'Save' })]
+ *   });
+ * });
+ * ```
+ *
+ * @param name - Name of the resource
+ * @param options - Resource options (uri, description, mimeType, title)
+ * @param handler - Async function that returns the resource content (string or UI.Document)
+ * @returns The handler function (for convenience)
+ */
+export function registerResource(
+  name: string,
+  options: ResourceOptions,
+  handler: () => Promise<ProteusDocument | string> | ProteusDocument | string,
+): typeof handler {
+  console.log(`Registering resource ${name} with URI ${options.uri}`);
+
+  // Register the resource with all services
+  for (const service of registry.services) {
+    service.registerResource(
+      options.uri,
+      name,
+      options.description,
+      options.mimeType,
+      options.title,
+      handler,
+    );
+  }
+
+  return handler;
+}

package/src/registerTool.ts

@@ -1,7 +1,5 @@
 import { z } from "zod/v4";
 
-import type { BlockResponse } from "./block";
-
 import {
   AuthRequirement,
   Credentials,
@@ -23,10 +21,7 @@ export type RequestHandlerExtra = {
   mode: "headless" | "interactive";
 };
 
-type ToolOptions<
-  TSchema extends Record<string, z.ZodTypeAny>,
-  TType extends "block" | "json" = "json",
-> = {
+type ToolOptions<TSchema extends Record<string, z.ZodTypeAny>> = {
   authRequirements?: {
     provider: string;
     required?: boolean;
@@ -34,7 +29,7 @@ type ToolOptions<
   };
   description: string;
   inputSchema: TSchema;
-  type?: TType;
+  uiResource?: string;
 };
 
 /**
@@ -72,36 +67,31 @@ type ToolOptions<
  *   return fetch(params.url, { headers });
  * });
  * ```
+ *
+ * @example
+ * ```typescript
+ * // With UI resource for dynamic rendering
+ * const createTaskTool = registerTool('create_task', {
+ *   description: 'Create a new task',
+ *   inputSchema: {
+ *     title: z.string().describe('Task title'),
+ *     description: z.string().describe('Task description')
+ *   },
+ *   uiResource: 'ui://my-app/create-form'
+ * }, async (params) => {
+ *   return { id: 'task-123', ...params };
+ * });
+ * ```
  */
-// Overload for block tools
-export function registerTool<TSchema extends Record<string, z.ZodTypeAny>>(
-  name: string,
-  options: ToolOptions<TSchema, "block">,
-  handler: (
-    params: { [K in keyof TSchema]: z.infer<TSchema[K]> },
-    extra?: RequestHandlerExtra,
-  ) => BlockResponse | Promise<BlockResponse>,
-): typeof handler;
-// Overload for JSON tools (or when type is omitted)
-export function registerTool<TSchema extends Record<string, z.ZodTypeAny>>(
-  name: string,
-  options: Omit<ToolOptions<TSchema>, "type"> | ToolOptions<TSchema, "json">,
-  handler: (
-    params: { [K in keyof TSchema]: z.infer<TSchema[K]> },
-    extra?: RequestHandlerExtra,
-  ) => Promise<unknown> | unknown,
-): typeof handler;
-// Implementation
 export function registerTool<TSchema extends Record<string, z.ZodTypeAny>>(
   name: string,
-  options: ToolOptions<TSchema, "block" | "json">,
+  options: ToolOptions<TSchema>,
   handler: (
     params: { [K in keyof TSchema]: z.infer<TSchema[K]> },
     extra?: RequestHandlerExtra,
   ) => Promise<unknown> | unknown,
 ): typeof handler {
   // Register the tool with all services
-  const responseType = options.type || "json";
   for (const service of registry.services) {
     service.registerTool(
       name,
@@ -118,8 +108,8 @@ export function registerTool<TSchema extends Record<string, z.ZodTypeAny>>(
             ),
           ]
         : undefined,
-      responseType,
       true,
+      options.uiResource,
     );
   }
 

package/src/service.ts

@@ -1,12 +1,19 @@
 import express, { Express, Request, Response, Router } from "express";
 
-import { isBlockResponse } from "./block";
-import { AuthRequirement, Function, Parameter } from "./models";
+import { AuthRequirement, Function, Parameter, Resource } from "./models";
+import { ProteusDocument, UI } from "./proteus";
 import { registry } from "./registry";
 
+type ResourceRegistration = {
+  handler: () => Promise<ProteusDocument | string> | ProteusDocument | string;
+  metadata: Resource;
+};
+
 export class ToolsService {
   private app: Express;
   private functions: Function[] = [];
+  private resources: Map<string, ResourceRegistration> = new Map();
+
   private router: Router;
 
   /**
@@ -22,6 +29,31 @@ export class ToolsService {
     registry.services.push(this);
   }
 
+  /**
+   * Register a resource function
+   * @param uri The unique URI for this resource (e.g., "ui://my-app/create-form")
+   * @param name Name of the resource
+   * @param description Description of the resource (optional)
+   * @param mimeType MIME type of the resource content (optional)
+   * @param title Human-readable title for the resource (optional)
+   * @param handler Function implementing the resource (returns string or ProteusDocument)
+   */
+  registerResource(
+    uri: string,
+    name: string,
+    description: string | undefined,
+    mimeType: string | undefined,
+    title: string | undefined,
+    handler: () => Promise<ProteusDocument | string> | ProteusDocument | string,
+  ): void {
+    console.log(`Registering resource: ${name} with URI: ${uri}`);
+
+    const metadata = new Resource(uri, name, description, mimeType, title);
+
+    // Store both metadata and handler together
+    this.resources.set(uri, { handler, metadata });
+  }
+
   /**
    * Register a tool function
    * @param name Tool name
@@ -30,8 +62,8 @@ export class ToolsService {
    * @param parameters List of parameters for the tool
    * @param endpoint API endpoint for the tool
    * @param authRequirements Authentication requirements (optional)
-   * @param responseType Response type - 'json' (default) or 'block'
    * @param isNewStyle Whether this is a new-style tool (registerTool) vs legacy decorator
+   * @param uiResource URI of associated UI resource for dynamic rendering (optional)
    */
   registerTool(
     name: string,
@@ -41,8 +73,8 @@ export class ToolsService {
     parameters: Parameter[],
     endpoint: string,
     authRequirements?: AuthRequirement[],
-    responseType: "block" | "json" = "json",
     isNewStyle: boolean = false,
+    uiResource?: string,
   ): void {
     const func = new Function(
       name,
@@ -50,12 +82,10 @@ export class ToolsService {
       parameters,
       endpoint,
       authRequirements,
+      uiResource,
     );
     this.functions.push(func);
 
-    // Determine if this is a block tool
-    const isBlockTool = responseType === "block";
-
     // Register the actual endpoint
     this.router.post(endpoint, async (req: Request, res: Response) => {
       try {
@@ -106,19 +136,7 @@ export class ToolsService {
 
         console.log(`Tool ${name} returned:`, result);
 
-        // Return with appropriate content-type header
-        if (isBlockTool) {
-          // Validate that block tools return a BlockResponse
-          if (!isBlockResponse(result)) {
-            throw new Error(
-              `Block tool '${name}' must return a BlockResponse object, but returned ${typeof result}`,
-            );
-          }
-          res.set("Content-Type", "application/vnd.opal.block+json");
-          res.json(result);
-        } else {
-          res.json(result);
-        }
+        res.json(result);
       } catch (error) {
         console.error(`Error in tool ${name}:`, error);
         res.status(500).json({
@@ -129,11 +147,80 @@ export class ToolsService {
   }
 
   /**
-   * Initialize the discovery endpoint
+   * Initialize the discovery endpoint and resources/read endpoint
    */
   private initRoutes(): void {
-    this.router.get("/discovery", (req: Request, res: Response) => {
-      res.json({ functions: this.functions.map((f) => f.toJSON()) });
+    this.router.get("/discovery", (_req: Request, res: Response) => {
+      res.json({
+        functions: this.functions.map((f) => f.toJSON()),
+      });
+    });
+
+    // POST /resources/read endpoint for MCP protocol
+    this.router.post("/resources/read", async (req: Request, res: Response) => {
+      try {
+        const { uri } = req.body;
+
+        if (!uri) {
+          return res.status(400).json({
+            error: "Missing required field: uri",
+          });
+        }
+
+        console.log(`Received resource read request for URI: ${uri}`);
+
+        // Find the resource registration
+        const registration = this.resources.get(uri);
+
+        if (!registration) {
+          return res.status(404).json({
+            error: `Resource not found: ${uri}`,
+          });
+        }
+
+        // Call handler and await result
+        const content = await registration.handler();
+
+        let textContent: string;
+        let mimeType = registration.metadata.mimeType;
+
+        // Check if handler returned a ProteusDocument
+        if (
+          typeof content === "object" &&
+          content !== null &&
+          "$type" in content &&
+          content.$type === "Document"
+        ) {
+          // Auto-serialize to JSON
+          textContent = JSON.stringify(content);
+          // Auto-set MIME type if not specified
+          if (!mimeType) {
+            mimeType = UI.MIME_TYPE;
+          }
+        } else if (typeof content === "string") {
+          textContent = content;
+        } else {
+          throw new Error(
+            `Resource handler for '${uri}' must return a string or ProteusDocument, but returned ${typeof content}`,
+          );
+        }
+
+        console.log(
+          `Resource ${uri} returned content of length: ${textContent.length}`,
+        );
+
+        // Return the resource content directly
+        res.json({
+          mimeType: mimeType || "text/plain",
+          text: textContent,
+          uri,
+        });
+      } catch (error) {
+        console.error(`Error reading resource:`, error);
+        res.status(500).json({
+          error: error instanceof Error ? error.message : "Unknown error",
+        });
+      }
     });
 
     this.app.use(this.router);