feat: introduce fetchTools

CLAUDE.md

@@ -54,6 +54,30 @@ This is the StackOne AI Node SDK - a TypeScript library that transforms OpenAPI
 - **Lazy Loading**: Tools are created on-demand to minimize memory usage
 - **Extensibility**: Hooks for parameter transformation and pre-execution logic
 
+### TypeScript Exhaustiveness Checks
+
+When branching on string unions, prefer the `satisfies never` pattern to guarantee compile-time exhaustiveness without introducing temporary variables. Example from `RequestBuilder.buildFetchOptions`:
+
+```ts
+switch (bodyType) {
+  case 'json':
+    // ...
+    break;
+  case 'form':
+    // ...
+    break;
+  case 'multipart-form':
+    // ...
+    break;
+  default: {
+    bodyType satisfies never; // raises a type error if a new variant is added
+    throw new Error(`Unsupported HTTP body type: ${String(bodyType)}`);
+  }
+}
+```
+
+Use this approach to keep the union definition (`type HttpBodyType = 'json' | 'multipart-form' | 'form'`) and the switch statement in sync. Adding a new union member will cause TypeScript to report the missing case at compile time.
+
 ### Testing Strategy
 
 Tests use Bun's built-in test runner with a Jest-compatible API. Key patterns:
@@ -73,4 +97,4 @@ When modifying the codebase:
 - Run tests frequently during development
 - Use `bun run rebuild` after updating OpenAPI specs
 - Ensure all generated files are committed (they're not gitignored)
-- Follow the existing patterns for error handling and logging
+- Follow the existing patterns for error handling and logging

README.md

@@ -125,6 +125,27 @@ const currentAccountId = tools.getAccountId(); // Get the current account ID
 
 [View full example](examples/account-id-usage.ts)
 
+### Loading the Latest Tool Catalog
+
+Call `fetchTools()` when you want the SDK to pull the current tool definitions directly from StackOne without maintaining local specs:
+
+```typescript
+const toolset = new StackOneToolSet({
+  baseUrl: 'https://api.stackone.com',
+});
+
+const tools = await toolset.fetchTools();
+const employeeTool = tools.getTool('hris_list_employees');
+
+const result = await employeeTool?.execute({
+  query: { limit: 5 },
+});
+```
+
+`fetchTools()` reuses the credentials you already configured (for example via `STACKONE_API_KEY`) and binds the returned tool objects to StackOne's actions client.
+
+[View full example](examples/fetch-tools.ts)
+
 ### File Upload
 
 The `StackOneToolSet` comes with built-in transformations for file uploads:

examples/README.md

@@ -129,6 +129,14 @@ Shows how to use custom base URLs for development or self-hosted instances.
 - **API Calls**: No (dry run)
 - **Key Features**: Custom API endpoints, development setup
 
+#### [`fetch-tools.ts`](./fetch-tools.ts) - Live Catalog Loading
+
+Illustrates how to pull the latest tool catalog from StackOne and execute a tool with the fetched definitions.
+
+- **Account ID**: HRIS
+- **API Calls**: Yes (requires valid credentials)
+- **Key Features**: Catalog refresh, zero local specs, production-style execution
+
 ### Advanced Features
 
 #### [`experimental-document-handling.ts`](./experimental-document-handling.ts) - Document Processing

examples/fetch-tools.ts

@@ -0,0 +1,38 @@
+/**
+ * Example: fetch the latest StackOne tool catalog and execute a tool.
+ *
+ * Set `STACKONE_API_KEY` (and optionally `STACKONE_BASE_URL`) before running.
+ * By default the script exits early in test environments where a real key is
+ * not available.
+ */
+
+import process from 'node:process';
+import { StackOneToolSet } from '../src';
+
+const apiKey = process.env.STACKONE_API_KEY;
+const isPlaceholderKey = !apiKey || apiKey === 'test-stackone-key';
+const shouldSkip = process.env.SKIP_FETCH_TOOLS_EXAMPLE !== '0' && isPlaceholderKey;
+
+if (shouldSkip) {
+  console.log(
+    'Skipping fetch-tools example. Provide STACKONE_API_KEY and set SKIP_FETCH_TOOLS_EXAMPLE=0 to run.'
+  );
+  process.exit(0);
+}
+
+const toolset = new StackOneToolSet({
+  baseUrl: process.env.STACKONE_BASE_URL ?? 'https://api.stackone.com',
+});
+
+const tools = await toolset.fetchTools();
+console.log(`Loaded ${tools.length} tools`);
+
+const tool = tools.getTool('hris_list_employees');
+if (!tool) {
+  throw new Error('Tool hris_list_employees not found in the catalog');
+}
+
+const result = await tool.execute({
+  query: { limit: 5 },
+});
+console.log('Sample execution result:', JSON.stringify(result, null, 2));

package.json

@@ -36,18 +36,22 @@
     "format": "biome format --write ."
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
     "@orama/orama": "^3.1.11",
+    "@stackone/stackone-client-ts": "^4.28.0",
     "json-schema": "^0.4.0"
   },
   "devDependencies": {
     "@ai-sdk/openai": "^1.1.14",
     "@biomejs/biome": "^1.5.3",
+    "@hono/mcp": "^0.1.4",
     "@types/bun": "^1.2.4",
     "@types/json-schema": "^7.0.15",
     "@types/node": "^22.13.5",
     "@typescript/native-preview": "^7.0.0-dev.20250623.1",
     "ai": "^4.1.46",
     "fs-fixture": "^2.8.1",
+    "hono": "^4.9.10",
     "lint-staged": "^15.2.0",
     "mkdocs": "^0.0.1",
     "msw": "^2.10.4",
@@ -56,7 +60,8 @@
     "publint": "^0.3.12",
     "tsdown": "^0.15.6",
     "type-fest": "^4.41.0",
-    "unplugin-unused": "^0.5.1"
+    "unplugin-unused": "^0.5.1",
+    "zod": "^3.23.8"
   },
   "peerDependencies": {
     "ai": "4.x",

src/mcp.ts

@@ -0,0 +1,55 @@
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+import { version } from '../package.json';
+
+interface MCPClientOptions {
+  baseUrl: string;
+  headers?: Record<string, string>;
+}
+
+interface MCPClient {
+  /** underlying MCP client */
+  client: Client;
+
+  /** underlying transport */
+  transport: StreamableHTTPClientTransport;
+
+  /** cleanup client and transport */
+  [Symbol.asyncDispose](): Promise<void>;
+}
+
+/**
+ * Create a Model Context Protocol (MCP) client.
+ *
+ * @example
+ * ```ts
+ * import { createMCPClient } from '@stackone/ai';
+ *
+ * await using clients = await createMCPClient({
+ *   baseUrl: 'https://api.modelcontextprotocol.org',
+ *   headers: {
+ *     'Authorization': 'Bearer YOUR_API_KEY',
+ *   },
+ * });
+ * ```
+ */
+export async function createMCPClient({ baseUrl, headers }: MCPClientOptions): Promise<MCPClient> {
+  const transport = new StreamableHTTPClientTransport(new URL(baseUrl), {
+    requestInit: {
+      headers,
+    },
+  });
+
+  const client = new Client({
+    name: 'StackOne AI SDK',
+    version,
+  });
+
+  return {
+    client,
+    transport,
+    async [Symbol.asyncDispose]() {
+      await Promise.all([client.close(), transport.close()]);
+    },
+  };
+}

src/modules/requestBuilder.ts

@@ -1,6 +1,7 @@
 import {
-  type ExecuteConfig,
   type ExecuteOptions,
+  type HttpBodyType,
+  type HttpExecuteConfig,
   type JsonDict,
   ParameterLocation,
 } from '../types';
@@ -19,16 +20,16 @@ class ParameterSerializationError extends Error {
 }
 
 /**
- * Builds and executes HTTP requests
+ * Builds and executes HTTP requests for tools declared with kind:'http'.
  */
 export class RequestBuilder {
   private method: string;
   private url: string;
-  private bodyType: 'json' | 'multipart-form' | 'form';
-  private params: ExecuteConfig['params'];
+  private bodyType: HttpBodyType;
+  private params: HttpExecuteConfig['params'];
   private headers: Record<string, string>;
 
-  constructor(config: ExecuteConfig, headers: Record<string, string> = {}) {
+  constructor(config: HttpExecuteConfig, headers: Record<string, string> = {}) {
     this.method = config.method;
     this.url = config.url;
     this.bodyType = config.bodyType;
@@ -144,6 +145,10 @@ export class RequestBuilder {
           // Don't set Content-Type for FormData, it will be set automatically with the boundary
           break;
         }
+        default: {
+          this.bodyType satisfies never;
+          throw new Error(`Unsupported HTTP body type: ${String(this.bodyType)}`);
+        }
       }
     }
 

src/modules/tests/requestBuilder.spec.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it } from 'bun:test';
 import { http, HttpResponse } from 'msw';
 import { server } from '../../../mocks/node.ts';
-import { ParameterLocation } from '../../types';
+import { type HttpExecuteConfig, ParameterLocation } from '../../types';
 import { StackOneAPIError } from '../../utils/errors';
 import { RequestBuilder } from '../requestBuilder';
 
@@ -16,27 +16,28 @@ describe('RequestBuilder', () => {
     return recordedRequests;
   };
   const mockConfig = {
+    kind: 'http',
     method: 'GET',
     url: 'https://api.example.com/test/{pathParam}',
-    bodyType: 'json' as const,
+    bodyType: 'json',
     params: [
-      { name: 'pathParam', location: ParameterLocation.PATH, type: 'string' as const },
-      { name: 'queryParam', location: ParameterLocation.QUERY, type: 'string' as const },
-      { name: 'headerParam', location: ParameterLocation.HEADER, type: 'string' as const },
-      { name: 'bodyParam', location: ParameterLocation.BODY, type: 'string' as const },
-      { name: 'defaultParam', location: ParameterLocation.BODY, type: 'string' as const },
-      { name: 'filter', location: ParameterLocation.QUERY, type: 'object' as const },
-      { name: 'proxy', location: ParameterLocation.QUERY, type: 'object' as const },
-      { name: 'regularObject', location: ParameterLocation.QUERY, type: 'object' as const },
-      { name: 'simple', location: ParameterLocation.QUERY, type: 'string' as const },
-      { name: 'simpleString', location: ParameterLocation.QUERY, type: 'string' as const },
-      { name: 'simpleNumber', location: ParameterLocation.QUERY, type: 'number' as const },
-      { name: 'simpleBoolean', location: ParameterLocation.QUERY, type: 'boolean' as const },
-      { name: 'complexObject', location: ParameterLocation.QUERY, type: 'object' as const },
-      { name: 'deepFilter', location: ParameterLocation.QUERY, type: 'object' as const },
-      { name: 'emptyFilter', location: ParameterLocation.QUERY, type: 'object' as const },
+      { name: 'pathParam', location: ParameterLocation.PATH, type: 'string' },
+      { name: 'queryParam', location: ParameterLocation.QUERY, type: 'string' },
+      { name: 'headerParam', location: ParameterLocation.HEADER, type: 'string' },
+      { name: 'bodyParam', location: ParameterLocation.BODY, type: 'string' },
+      { name: 'defaultParam', location: ParameterLocation.BODY, type: 'string' },
+      { name: 'filter', location: ParameterLocation.QUERY, type: 'object' },
+      { name: 'proxy', location: ParameterLocation.QUERY, type: 'object' },
+      { name: 'regularObject', location: ParameterLocation.QUERY, type: 'object' },
+      { name: 'simple', location: ParameterLocation.QUERY, type: 'string' },
+      { name: 'simpleString', location: ParameterLocation.QUERY, type: 'string' },
+      { name: 'simpleNumber', location: ParameterLocation.QUERY, type: 'number' },
+      { name: 'simpleBoolean', location: ParameterLocation.QUERY, type: 'boolean' },
+      { name: 'complexObject', location: ParameterLocation.QUERY, type: 'object' },
+      { name: 'deepFilter', location: ParameterLocation.QUERY, type: 'object' },
+      { name: 'emptyFilter', location: ParameterLocation.QUERY, type: 'object' },
     ],
-  };
+  } satisfies HttpExecuteConfig;
 
   beforeEach(() => {
     builder = new RequestBuilder(mockConfig, { 'Initial-Header': 'test' });

src/openapi/parser.ts

@@ -1,6 +1,6 @@
 import type { JSONSchema7 as JsonSchema } from 'json-schema';
 import type { OpenAPIV3, OpenAPIV3_1 } from 'openapi-types';
-import { ParameterLocation, type ToolDefinition } from '../types';
+import { type HttpExecuteConfig, ParameterLocation, type ToolDefinition } from '../types';
 // Define a type for OpenAPI document
 type OpenAPIDocument = OpenAPIV3.Document | OpenAPIV3_1.Document;
 
@@ -67,6 +67,23 @@ export class OpenAPIParser {
     return servers.length > 0 ? servers[0].url : 'https://api.stackone.com';
   }
 
+  private normalizeBodyType(bodyType: string | null): HttpExecuteConfig['bodyType'] {
+    // Map OpenAPI content types into the narrower set supported by ExecuteConfig.
+    if (!bodyType) {
+      return 'json';
+    }
+
+    if (bodyType === 'form-data' || bodyType === 'multipart-form') {
+      return 'multipart-form';
+    }
+
+    if (bodyType === 'form' || bodyType === 'application/x-www-form-urlencoded') {
+      return 'form';
+    }
+
+    return 'json';
+  }
+
   /**
    * Create a parser from a JSON string
    * @param specString OpenAPI specification as a JSON string
@@ -552,27 +569,30 @@ export class OpenAPIParser {
             );
 
             // Create tool definition with deep copies to prevent shared state
+            const executeConfig = {
+              kind: 'http',
+              method: method.toUpperCase(),
+              url: `${this._baseUrl}${path}`,
+              bodyType: this.normalizeBodyType(bodyType),
+              params: Object.entries(parameterLocations)
+                .filter(([name]) => !this.isRemovedParam(name))
+                .map(([name, location]) => {
+                  return {
+                    name,
+                    location,
+                    type: (filteredProperties[name]?.type as JsonSchema['type']) || 'string',
+                  };
+                }),
+            } satisfies HttpExecuteConfig;
+
             tools[name] = {
               description: operation.summary || '',
               parameters: {
                 type: 'object',
                 properties: filteredProperties,
                 required: filteredRequired,
               },
-              execute: {
-                method: method.toUpperCase(),
-                url: `${this._baseUrl}${path}`,
-                bodyType: (bodyType as 'json' | 'multipart-form') || 'json',
-                params: Object.entries(parameterLocations)
-                  .filter(([name]) => !this.isRemovedParam(name))
-                  .map(([name, location]) => {
-                    return {
-                      name,
-                      location,
-                      type: (filteredProperties[name]?.type as JsonSchema['type']) || 'string',
-                    };
-                  }),
-              },
+              execute: executeConfig,
             };
           } catch (operationError) {
             console.error(`Error processing operation ${name}: ${operationError}`);