@spec2tools/sdk 0.1.2 → 0.2.0

package/README.md

@@ -27,6 +27,47 @@ const result = await generateText({
 console.log(result.text);
 ```
 
+### Code Mode
+
+Enable code mode to collapse all endpoints into 2 tools (`search` + `execute`), reducing token usage by ~99.9%:
+
+```ts
+const tools = await createTools({
+  spec: './openapi.yaml',
+  codeMode: true,
+});
+```
+
+### Code Mode for MCP Clients
+
+Use `convertToolsToCodeMode` to apply code mode to tools from any source, such as `createMCPClient` from `@ai-sdk/mcp`:
+
+```ts
+import { createMCPClient } from '@ai-sdk/mcp';
+import { convertToolsToCodeMode } from '@spec2tools/sdk';
+import { generateText, stepCountIs } from 'ai';
+import { openai } from '@ai-sdk/openai';
+
+const client = await createMCPClient({
+  transport: { type: 'sse', url: 'http://localhost:3000/sse' },
+});
+
+try {
+  const tools = convertToolsToCodeMode(await client.tools());
+
+  const result = await generateText({
+    model: openai('gpt-4o'),
+    tools,
+    prompt: 'List all users',
+    stopWhen: stepCountIs(3),
+  });
+
+  console.log(result.text);
+} finally {
+  await client.close();
+}
+```
+
 ## API
 
 ### `createTools(options: Spec2ToolsOptions): Promise<ToolSet>`
@@ -36,6 +77,7 @@ Creates AI SDK-compatible tools from an OpenAPI specification.
 #### Options
 
 - `spec` (string, required): Path or URL to the OpenAPI specification file (JSON or YAML)
+- `codeMode` (boolean, optional): When `true`, returns 2 code-mode tools instead of one per endpoint
 
 #### Returns
 
@@ -43,12 +85,11 @@ A `Promise` that resolves to an object of AI SDK tools.
 
 #### Throws
 
-- `Error` if the API requires authentication. For authenticated APIs, use the `@spec2tools/cli` package instead.
+- `Error` if the API requires authentication (unless `codeMode` is enabled). For authenticated APIs, use the `@spec2tools/cli` package instead.
 
-## Notes
+### `convertToolsToCodeMode(tools: ToolSet): ToolSet`
 
-- `createTools()` only works with APIs that don't require authentication
-- For authenticated APIs, use the CLI: `npx @spec2tools/cli start --spec ./openapi.yaml`
+Converts an existing AI SDK ToolSet into code mode (2 tools: `search` + `execute`). Useful when you have tools from another source (e.g. `createMCPClient` from `@ai-sdk/mcp`) and want to reduce token usage.
 
 ## License
 

package/dist/index.d.ts

@@ -1,2 +1,2 @@
-export { createTools, type Spec2ToolsOptions } from './lib.js';
+export { createTools, convertToolsToCodeMode, type Spec2ToolsOptions } from './lib.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,2 +1,2 @@
-export { createTools } from './lib.js';
+export { createTools, convertToolsToCodeMode } from './lib.js';
 //# sourceMappingURL=index.js.map

package/dist/lib.d.ts

@@ -1,8 +1,28 @@
-import { generateText } from 'ai';
-type ToolSet = NonNullable<Parameters<typeof generateText>[0]['tools']>;
+import { toCodeModeTools, type ToolSet } from '@spec2tools/core';
+/**
+ * Convert an existing AI SDK ToolSet into code mode (2 tools: search + execute).
+ *
+ * Useful when you already have tools from another source (e.g. `createMCPClient`)
+ * and want to reduce token usage by collapsing them into code mode.
+ *
+ * @example
+ * ```ts
+ * import { createMCPClient } from '@ai-sdk/mcp';
+ * import { convertToolsToCodeMode } from '@spec2tools/sdk';
+ *
+ * const client = await createMCPClient({
+ *   transport: { type: 'sse', url: 'http://localhost:3000/sse' },
+ * });
+ * const tools = await client.tools();
+ * const codeModeTools = convertToolsToCodeMode(tools);
+ * ```
+ */
+export declare const convertToolsToCodeMode: typeof toCodeModeTools;
 export interface Spec2ToolsOptions {
     /** Path or URL to OpenAPI specification */
     spec: string;
+    /** Use code mode (2 tools: search + execute) instead of one tool per endpoint */
+    codeMode?: boolean;
 }
 /**
  * Create AI SDK tools from an OpenAPI specification.
@@ -22,8 +42,7 @@ export interface Spec2ToolsOptions {
  * });
  * ```
  *
- * @throws Error if the API requires authentication
+ * @throws Error if the API requires authentication (unless codeMode is enabled)
  */
 export declare function createTools(options: Spec2ToolsOptions): Promise<ToolSet>;
-export {};
 //# sourceMappingURL=lib.d.ts.map

package/dist/lib.js

@@ -1,5 +1,23 @@
-import { tool } from 'ai';
-import { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, AuthManager, ToolExecutionError, } from '@spec2tools/core';
+import { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, createExecutableTools, toAISDKTools, toCodeModeTools, AuthManager, } from '@spec2tools/core';
+/**
+ * Convert an existing AI SDK ToolSet into code mode (2 tools: search + execute).
+ *
+ * Useful when you already have tools from another source (e.g. `createMCPClient`)
+ * and want to reduce token usage by collapsing them into code mode.
+ *
+ * @example
+ * ```ts
+ * import { createMCPClient } from '@ai-sdk/mcp';
+ * import { convertToolsToCodeMode } from '@spec2tools/sdk';
+ *
+ * const client = await createMCPClient({
+ *   transport: { type: 'sse', url: 'http://localhost:3000/sse' },
+ * });
+ * const tools = await client.tools();
+ * const codeModeTools = convertToolsToCodeMode(tools);
+ * ```
+ */
+export const convertToolsToCodeMode = toCodeModeTools;
 /**
  * Create AI SDK tools from an OpenAPI specification.
  *
@@ -18,80 +36,25 @@ import { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, Au
  * });
  * ```
  *
- * @throws Error if the API requires authentication
+ * @throws Error if the API requires authentication (unless codeMode is enabled)
  */
 export async function createTools(options) {
     const spec = await loadOpenAPISpec(options.spec);
     const baseUrl = extractBaseUrl(spec);
     const authConfig = extractAuthConfig(spec);
-    // Check if auth is required
-    if (authConfig.type !== 'none') {
+    // Check if auth is required (skip in code mode — auth is handled internally)
+    if (!options.codeMode && authConfig.type !== 'none') {
         throw new Error(`This API requires authentication (${authConfig.type}). ` +
             `The createTools() function only supports APIs without authentication. ` +
             `Use the CLI for authenticated APIs: npx @spec2tools/cli start --spec ${options.spec}`);
     }
     const toolDefs = parseOperations(spec);
     const authManager = new AuthManager(authConfig);
-    // Build AI SDK tools
-    const tools = {};
-    for (const toolDef of toolDefs) {
-        const { name, description, parameters, httpMethod, path } = toolDef;
-        tools[name] = tool({
-            description,
-            inputSchema: parameters,
-            execute: async (params) => {
-                // Build URL with path parameters
-                let url = `${baseUrl}${path}`;
-                const queryParams = {};
-                const bodyParams = {};
-                for (const [key, value] of Object.entries(params)) {
-                    if (value === undefined)
-                        continue;
-                    if (url.includes(`{${key}}`)) {
-                        // Path parameter
-                        url = url.replace(`{${key}}`, encodeURIComponent(String(value)));
-                    }
-                    else if (httpMethod === 'GET' || httpMethod === 'DELETE') {
-                        // Query parameter for GET/DELETE
-                        queryParams[key] = String(value);
-                    }
-                    else {
-                        // Body parameter for POST/PUT/PATCH
-                        bodyParams[key] = value;
-                    }
-                }
-                // Add query parameters
-                const queryString = new URLSearchParams(queryParams).toString();
-                if (queryString) {
-                    url += `?${queryString}`;
-                }
-                // Build request options
-                const fetchOptions = {
-                    method: httpMethod,
-                    headers: {
-                        'Content-Type': 'application/json',
-                        ...authManager.getAuthHeaders(),
-                    },
-                };
-                // Add body for non-GET/DELETE requests
-                if (Object.keys(bodyParams).length > 0 &&
-                    httpMethod !== 'GET' &&
-                    httpMethod !== 'DELETE') {
-                    fetchOptions.body = JSON.stringify(bodyParams);
-                }
-                const response = await fetch(url, fetchOptions);
-                if (!response.ok) {
-                    const errorText = await response.text();
-                    throw new ToolExecutionError(name, new Error(`HTTP ${response.status}: ${errorText}`));
-                }
-                const contentType = response.headers.get('content-type');
-                if (contentType?.includes('application/json')) {
-                    return await response.json();
-                }
-                return await response.text();
-            },
-        });
+    const tools = createExecutableTools(toolDefs, baseUrl, authManager);
+    let aiTools = toAISDKTools(tools);
+    if (options.codeMode) {
+        aiTools = toCodeModeTools(aiTools);
     }
-    return tools;
+    return aiTools;
 }
 //# sourceMappingURL=lib.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec2tools/sdk",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "description": "Create AI SDK tools from OpenAPI specifications",
   "type": "module",
   "main": "dist/index.js",
@@ -32,14 +32,15 @@
   "dependencies": {
     "ai": "^6.0.68",
     "zod": "^3.24.0",
-    "@spec2tools/core": "0.1.2"
+    "@spec2tools/core": "0.2.0"
   },
   "peerDependencies": {
     "zod": "^3.24.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^4.0.18"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -47,6 +48,8 @@
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest"
   }
 }