@optimizely-opal/opal-tools-sdk 0.1.5-dev → 0.1.8-dev

package/dist/proteus.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * Generated by json-schema-to-typescript
+ * DO NOT MODIFY - This file is auto-generated from proteus-document-spec.json
+ * Run 'npm run generate:proteus' to regenerate
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UI = void 0;
+/**
+ * Builder namespace for Adaptive UI Document components.
+ *
+ * Usage:
+ *   UI.Document({ children: [...] })
+ *   UI.Heading({ children: "Title", level: "2" })
+ *   UI.Input({ name: "field_name", placeholder: "Enter..." })
+ */
+exports.UI = {
+    Action: (props) => ({
+        $type: "Action",
+        ...props,
+    }),
+    CancelAction: (props) => ({ $type: "CancelAction", ...props }),
+    Document: (props) => ({
+        $type: "Document",
+        ...props,
+    }),
+    Field: (props) => ({
+        $type: "Field",
+        ...props,
+    }),
+    Group: (props) => ({
+        $type: "Group",
+        ...props,
+    }),
+    Heading: (props) => ({
+        $type: "Heading",
+        ...props,
+    }),
+    Image: (props) => ({
+        $type: "Image",
+        ...props,
+    }),
+    Input: (props) => ({
+        $type: "Input",
+        ...props,
+    }),
+    Link: (props) => ({
+        $type: "Link",
+        ...props,
+    }),
+    Map: (props) => ({
+        $type: "Map",
+        ...props,
+    }),
+    MIME_TYPE: "application/vnd.opal.proteus+json",
+    Range: (props) => ({
+        $type: "Range",
+        ...props,
+    }),
+    Select: (props) => ({
+        $type: "Select",
+        ...props,
+    }),
+    SelectContent: (props) => ({ $type: "SelectContent", ...props }),
+    SelectTrigger: (props) => ({ $type: "SelectTrigger", ...props }),
+    Separator: (props) => ({
+        $type: "Separator",
+        ...props,
+    }),
+    Show: (props) => ({
+        $type: "Show",
+        ...props,
+    }),
+    Text: (props) => ({
+        $type: "Text",
+        ...props,
+    }),
+    Textarea: (props) => ({
+        $type: "Textarea",
+        ...props,
+    }),
+    Value: (props) => ({
+        $type: "Value",
+        ...props,
+    }),
+};

package/dist/registerResource.d.ts

@@ -0,0 +1,60 @@
+import { ProteusDocument } from "./proteus";
+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 declare function registerResource(name: string, options: ResourceOptions, handler: () => Promise<ProteusDocument | string> | ProteusDocument | string): typeof handler;
+export {};

package/dist/registerResource.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerResource = registerResource;
+const registry_1 = require("./registry");
+/**
+ * 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)
+ */
+function registerResource(name, options, handler) {
+    console.log(`Registering resource ${name} with URI ${options.uri}`);
+    // Register the resource with all services
+    for (const service of registry_1.registry.services) {
+        service.registerResource(options.uri, name, options.description, options.mimeType, options.title, handler);
+    }
+    return handler;
+}

package/dist/registerTool.d.ts

@@ -0,0 +1,79 @@
+import { z } from "zod/v4";
+import { Credentials } from "./models";
+/**
+ * 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 declare 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;
+export {};

package/dist/registerTool.js

@@ -0,0 +1,106 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerTool = registerTool;
+const v4_1 = require("zod/v4");
+const models_1 = require("./models");
+const registry_1 = require("./registry");
+/**
+ * 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 };
+ * });
+ * ```
+ */
+function registerTool(name, options, handler) {
+    // Register the tool with all services
+    for (const service of registry_1.registry.services) {
+        service.registerTool(name, options.description, handler, jsonSchemaToParameters(v4_1.z.toJSONSchema(v4_1.z.object(options.inputSchema))), `/tools/${name.replace(/_/g, "-")}`, options.authRequirements
+            ? [
+                new models_1.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) {
+    const parameters = [];
+    if (!jsonSchema.properties) {
+        return parameters;
+    }
+    const required = jsonSchema.required || [];
+    for (const [key, value] of Object.entries(jsonSchema.properties)) {
+        const prop = value;
+        parameters.push(new models_1.Parameter(key, jsonSchemaTypeToParameterType(prop.type || "string"), prop.description || "", required.includes(key)));
+    }
+    return parameters;
+}
+/**
+ * Map JSON Schema type to ParameterType
+ */
+function jsonSchemaTypeToParameterType(jsonType) {
+    switch (jsonType) {
+        case "array":
+            return models_1.ParameterType.List;
+        case "boolean":
+            return models_1.ParameterType.Boolean;
+        case "integer":
+            return models_1.ParameterType.Integer;
+        case "number":
+            return models_1.ParameterType.Number;
+        case "object":
+            return models_1.ParameterType.Dictionary;
+        case "string":
+            return models_1.ParameterType.String;
+        default:
+            return models_1.ParameterType.String;
+    }
+}

package/dist/registry.d.ts

@@ -1,4 +1,4 @@
-import { ToolsService } from './service';
+import { ToolsService } from "./service";
 /**
  * Internal registry for ToolsService instances
  */

package/dist/registry.js

@@ -5,5 +5,5 @@ exports.registry = void 0;
  * Internal registry for ToolsService instances
  */
 exports.registry = {
-    services: []
+    services: [],
 };

package/dist/service.d.ts

@@ -1,18 +1,26 @@
-import { Express } from 'express';
-import { AuthRequirement, Parameter } from './models';
+import { Express } from "express";
+import { AuthRequirement, Parameter } from "./models";
+import { ProteusDocument } from "./proteus";
 export declare class ToolsService {
     private app;
-    private router;
     private functions;
+    private resources;
+    private router;
     /**
      * Initialize a new tools service
      * @param app Express application
      */
     constructor(app: Express);
     /**
-     * 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;
+    registerResource(uri: string, name: string, description: string | undefined, mimeType: string | undefined, title: string | undefined, handler: () => Promise<ProteusDocument | string> | ProteusDocument | string): void;
     /**
      * Register a tool function
      * @param name Tool name
@@ -21,7 +29,13 @@ export declare 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, handler: any, // Changed from Function to any to avoid confusion with built-in Function type
-    parameters: Parameter[], endpoint: string, authRequirements?: AuthRequirement[]): void;
+    parameters: Parameter[], endpoint: string, authRequirements?: AuthRequirement[], isNewStyle?: boolean, uiResource?: string): void;
+    /**
+     * Initialize the discovery endpoint and resources/read endpoint
+     */
+    private initRoutes;
 }

package/dist/service.js

@@ -6,6 +6,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.ToolsService = void 0;
 const express_1 = __importDefault(require("express"));
 const models_1 = require("./models");
+const proteus_1 = require("./proteus");
 const registry_1 = require("./registry");
 class ToolsService {
     /**
@@ -14,6 +15,7 @@ class ToolsService {
      */
     constructor(app) {
         this.functions = [];
+        this.resources = new Map();
         this.app = app;
         this.router = express_1.default.Router();
         this.initRoutes();
@@ -21,13 +23,19 @@ class ToolsService {
         registry_1.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)
      */
-    initRoutes() {
-        this.router.get('/discovery', (req, res) => {
-            res.json({ functions: this.functions.map(f => f.toJSON()) });
-        });
-        this.app.use(this.router);
+    registerResource(uri, name, description, mimeType, title, handler) {
+        console.log(`Registering resource: ${name} with URI: ${uri}`);
+        const metadata = new models_1.Resource(uri, name, description, mimeType, title);
+        // Store both metadata and handler together
+        this.resources.set(uri, { handler, metadata });
     }
     /**
      * Register a tool function
@@ -37,10 +45,14 @@ 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, description, handler, // Changed from Function to any to avoid confusion with built-in Function type
-    parameters, endpoint, authRequirements) {
-        const func = new models_1.Function(name, description, parameters, endpoint, authRequirements);
+    registerTool(name, description, 
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    handler, // Changed from Function to any to avoid confusion with built-in Function type
+    parameters, endpoint, authRequirements, isNewStyle = false, uiResource) {
+        const func = new models_1.Function(name, description, parameters, endpoint, authRequirements, uiResource);
         this.functions.push(func);
         // Register the actual endpoint
         this.router.post(endpoint, async (req, res) => {
@@ -61,28 +73,103 @@ class ToolsService {
                 // 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) {
                 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
+     */
+    initRoutes() {
+        this.router.get("/discovery", (_req, res) => {
+            res.json({
+                functions: this.functions.map((f) => f.toJSON()),
+            });
+        });
+        // POST /resources/read endpoint for MCP protocol
+        this.router.post("/resources/read", async (req, res) => {
+            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;
+                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 = proteus_1.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);
     }
 }
 exports.ToolsService = ToolsService;

package/eslint.config.js

@@ -0,0 +1,20 @@
+const typescript = require("typescript-eslint");
+const perfectionist = require("eslint-plugin-perfectionist");
+
+module.exports = typescript.config(
+  {
+    ignores: ["dist/**", "node_modules/**", "*.config.js"],
+  },
+  ...typescript.configs.recommended,
+  perfectionist.configs["recommended-natural"],
+  {
+    files: ["**/*.ts"],
+    ignores: ["*.config.ts"],
+    languageOptions: {
+      parserOptions: {
+        projectService: true,
+        tsconfigRootDir: __dirname,
+      },
+    },
+  },
+);