@optimizely-opal/opal-tools-sdk 0.1.5-dev → 0.1.8-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

@@ -0,0 +1,171 @@
+import { z } from "zod/v4";
+
+import {
+  AuthRequirement,
+  Credentials,
+  Parameter,
+  ParameterType,
+} from "./models";
+import { registry } from "./registry";
+
+/**
+ * Extra context passed to tool handlers
+ */
+export type RequestHandlerExtra = {
+  /** Authentication data if provided */
+  auth?: {
+    credentials: Credentials;
+    provider: string;
+  };
+  /** Execution mode: 'headless' for non-interactive, 'interactive' for user interaction (defaults to 'headless') */
+  mode: "headless" | "interactive";
+};
+
+type ToolOptions<TSchema extends Record<string, z.ZodTypeAny>> = {
+  authRequirements?: {
+    provider: string;
+    required?: boolean;
+    scopeBundle: string;
+  };
+  description: string;
+  inputSchema: TSchema;
+  uiResource?: string;
+};
+
+/**
+ * Register a function as an Opal tool
+ *
+ * @example
+ * ```typescript
+ * const greetTool = registerTool('greet', {
+ *   description: 'Greet a user',
+ *   inputSchema: {
+ *     name: z.string().describe('The name to greet')
+ *   }
+ * }, async (params) => {
+ *   // params is automatically typed as { name: string }
+ *   return `Hello, ${params.name}!`;
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With auth and execution mode
+ * const fetchTool = registerTool('fetch_data', {
+ *   description: 'Fetch data from API',
+ *   inputSchema: {
+ *     url: z.string().describe('URL to fetch')
+ *   },
+ *   authRequirements: {
+ *     provider: 'api-service',
+ *     scopeBundle: 'read'
+ *   }
+ * }, async (params, extra) => {
+ *   // extra.mode: 'headless' | 'interactive'
+ *   // extra.auth: { provider, credentials }
+ *   const headers = extra?.auth ? { Authorization: extra.auth.credentials.token } : {};
+ *   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 };
+ * });
+ * ```
+ */
+export function registerTool<TSchema extends Record<string, z.ZodTypeAny>>(
+  name: string,
+  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
+  for (const service of registry.services) {
+    service.registerTool(
+      name,
+      options.description,
+      handler,
+      jsonSchemaToParameters(z.toJSONSchema(z.object(options.inputSchema))),
+      `/tools/${name.replace(/_/g, "-")}`,
+      options.authRequirements
+        ? [
+            new AuthRequirement(
+              options.authRequirements.provider,
+              options.authRequirements.scopeBundle,
+              options.authRequirements.required ?? true,
+            ),
+          ]
+        : undefined,
+      true,
+      options.uiResource,
+    );
+  }
+
+  return handler;
+}
+
+/**
+ * Convert JSON Schema to Parameter definitions
+ * This converts the output of z.toJSONSchema() back to the Parameter[] format
+ * expected by the legacy discovery endpoint
+ */
+function jsonSchemaToParameters(jsonSchema: {
+  properties?: Record<string, unknown>;
+  required?: string[];
+}): Parameter[] {
+  const parameters: Parameter[] = [];
+
+  if (!jsonSchema.properties) {
+    return parameters;
+  }
+
+  const required = jsonSchema.required || [];
+
+  for (const [key, value] of Object.entries(jsonSchema.properties)) {
+    const prop = value as { description?: string; type?: string };
+    parameters.push(
+      new Parameter(
+        key,
+        jsonSchemaTypeToParameterType(prop.type || "string"),
+        prop.description || "",
+        required.includes(key),
+      ),
+    );
+  }
+
+  return parameters;
+}
+
+/**
+ * Map JSON Schema type to ParameterType
+ */
+function jsonSchemaTypeToParameterType(jsonType: string): ParameterType {
+  switch (jsonType) {
+    case "array":
+      return ParameterType.List;
+    case "boolean":
+      return ParameterType.Boolean;
+    case "integer":
+      return ParameterType.Integer;
+    case "number":
+      return ParameterType.Number;
+    case "object":
+      return ParameterType.Dictionary;
+    case "string":
+      return ParameterType.String;
+    default:
+      return ParameterType.String;
+  }
+}

package/src/registry.ts

@@ -1,8 +1,8 @@
-import { ToolsService } from './service';
+import { ToolsService } from "./service";
 
 /**
  * Internal registry for ToolsService instances
  */
 export const registry = {
-  services: [] as ToolsService[]
+  services: [] as ToolsService[],
 };

package/src/service.ts

@@ -1,11 +1,20 @@
-import express, { Express, Request, Response, Router } from 'express';
-import { Function, AuthRequirement, Parameter } from './models';
-import { registry } from './registry';
+import express, { Express, Request, Response, Router } from "express";
+
+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 router: Router;
   private functions: Function[] = [];
+  private resources: Map<string, ResourceRegistration> = new Map();
+
+  private router: Router;
 
   /**
    * Initialize a new tools service
@@ -15,20 +24,34 @@ export class ToolsService {
     this.app = app;
     this.router = express.Router();
     this.initRoutes();
-    
+
     // Register this service in the global registry
     registry.services.push(this);
   }
 
   /**
-   * Initialize the discovery endpoint
+   * 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)
    */
-  private initRoutes(): void {
-    this.router.get('/discovery', (req: Request, res: Response) => {
-      res.json({ functions: this.functions.map(f => f.toJSON()) });
-    });
+  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}`);
 
-    this.app.use(this.router);
+    const metadata = new Resource(uri, name, description, mimeType, title);
+
+    // Store both metadata and handler together
+    this.resources.set(uri, { handler, metadata });
   }
 
   /**
@@ -39,23 +62,35 @@ export class ToolsService {
    * @param parameters List of parameters for the tool
    * @param endpoint API endpoint for the tool
    * @param authRequirements Authentication requirements (optional)
+   * @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,
     description: string,
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
     handler: any, // Changed from Function to any to avoid confusion with built-in Function type
     parameters: Parameter[],
     endpoint: string,
-    authRequirements?: AuthRequirement[]
+    authRequirements?: AuthRequirement[],
+    isNewStyle: boolean = false,
+    uiResource?: string,
   ): void {
-    const func = new Function(name, description, parameters, endpoint, authRequirements);
+    const func = new Function(
+      name,
+      description,
+      parameters,
+      endpoint,
+      authRequirements,
+      uiResource,
+    );
     this.functions.push(func);
-    
+
     // Register the actual endpoint
     this.router.post(endpoint, async (req: Request, res: Response) => {
       try {
         console.log(`Received request for ${endpoint}:`, req.body);
-        
+
         // Extract parameters from the request body
         let params;
         if (req.body && req.body.parameters) {
@@ -64,35 +99,130 @@ export class ToolsService {
           console.log(`Extracted parameters from 'parameters' key:`, params);
         } else {
           // Fallback for direct testing: { "name": "value" }
-          console.log(`Warning: 'parameters' key not found in request body. Using body directly.`);
+          console.log(
+            `Warning: 'parameters' key not found in request body. Using body directly.`,
+          );
           params = req.body;
         }
-        
+
         // Extract auth data if available
         const authData = req.body && req.body.auth;
         if (authData) {
-          console.log(`Auth data provided for provider: ${authData.provider || 'unknown'}`);
+          console.log(
+            `Auth data provided for provider: ${authData.provider || "unknown"}`,
+          );
         }
-        
-        // Call the handler with extracted parameters and auth data
-        // Check if handler accepts auth as third parameter
-        const handlerParamCount = handler.length;
+
+        // Call the handler with extracted parameters
         let result;
-        
-        if (handlerParamCount >= 2) {
-          // Handler accepts auth data
-          result = await handler(params, authData);
+
+        if (isNewStyle) {
+          result = await handler(params, {
+            mode: (req.body && req.body.execution_mode) || "headless",
+            ...(authData && { auth: authData }),
+          });
         } else {
-          // Handler doesn't accept auth data
-          result = await handler(params);
+          // Check if handler accepts auth as third parameter
+          const handlerParamCount = handler.length;
+
+          if (handlerParamCount >= 2) {
+            // Handler accepts auth data
+            result = await handler(params, authData);
+          } else {
+            // Handler doesn't accept auth data
+            result = await handler(params);
+          }
         }
-        
+
         console.log(`Tool ${name} returned:`, result);
+
         res.json(result);
-      } catch (error: any) {
+      } catch (error) {
         console.error(`Error in tool ${name}:`, error);
-        res.status(500).json({ error: error.message || 'Unknown error' });
+        res.status(500).json({
+          error: error instanceof Error ? error.message : "Unknown error",
+        });
       }
     });
   }
+
+  /**
+   * 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()),
+      });
+    });
+
+    // 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);
+  }
 }