feat: add code mode basics with pydantic monty (#11)

* fix: add code mode basics with pydantic monty

* feat: add tests, fix issues, update versions

* fix: add option to connect to existing mcp servers

* fix: bump cli

Author: CahidArda

README.md

@@ -44,19 +44,38 @@ export OPENAI_API_KEY=your-api-key
 npx @spec2tools/cli start --spec https://api.example.com/openapi.json
 ```
 
-### Using as MCP Server (with Claude Desktop)
-
-Add to your `claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "my-api": {
-      "command": "npx",
-      "args": ["@spec2tools/stdio-mcp", "./path/to/openapi.yaml"]
-    }
-  }
-}
+### Using as MCP Server
+
+```bash
+# Add to Claude Code (or any MCP client)
+claude mcp add --transport stdio my-api \
+  -- npx @spec2tools/stdio-mcp ./path/to/openapi.yaml
+```
+
+### Code Mode
+
+Collapse all API endpoints into just 2 tools (`search` + `execute`), cutting input token usage by ~99.9%:
+
+```bash
+# MCP server with code mode
+claude mcp add --transport stdio my-api \
+  -- npx @spec2tools/stdio-mcp ./openapi.yaml --code-mode
+```
+
+```ts
+// SDK with code mode
+const tools = await createTools({
+  spec: './openapi.yaml',
+  codeMode: true,
+});
+```
+
+You can also convert any existing AI SDK tools to code mode:
+
+```ts
+import { toCodeModeTools } from '@spec2tools/core';
+
+const codeModeTools = toCodeModeTools(existingTools);
 ```
 
 ## Thesis

package.json

@@ -7,6 +7,7 @@
   "scripts": {
     "build": "pnpm -r run build",
     "dev": "pnpm -r run dev",
+    "test": "pnpm -r run test",
     "typecheck": "pnpm -r run typecheck",
     "clean": "pnpm -r exec rm -rf dist node_modules",
     "changeset": "changeset",

packages/cli/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @spec2tools/cli
 
+## 0.2.1
+
+### Patch Changes
+
+- Re-release
+
+## 0.2.0
+
+### Minor Changes
+
+- Add code mode MCP option
+
+### Patch Changes
+
+- Updated dependencies
+  - @spec2tools/core@0.2.0
+
 ## 0.1.2
 
 ### Patch Changes

packages/cli/README.md

@@ -38,6 +38,9 @@ npx @spec2tools/cli start --spec ./openapi.yaml --no-auth
 
 # Provide API key directly
 npx @spec2tools/cli start --spec ./openapi.yaml --api-key "your-api-key"
+
+# Enable code mode (2 tools: search + execute)
+npx @spec2tools/cli start --spec ./openapi.yaml --code-mode
 ```
 
 ### Chat Mode

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spec2tools/cli",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "CLI for interacting with OpenAPI-based AI tools",
   "type": "module",
   "main": "dist/index.js",

packages/cli/src/agent.ts

@@ -1,6 +1,6 @@
-import { generateText, tool, stepCountIs, ModelMessage } from 'ai';
+import { generateText, stepCountIs, ModelMessage } from 'ai';
 import { openai } from '@ai-sdk/openai';
-import { type Tool, ToolExecutionError } from '@spec2tools/core';
+import { type ToolSet, ToolExecutionError } from '@spec2tools/core';
 import chalk from 'chalk';
 
 const MAX_OUTPUT_LENGTH = 500;
@@ -17,7 +17,7 @@ function trimOutput(value: unknown): string {
 }
 
 interface AgentConfig {
-  tools: Tool[];
+  tools: ToolSet;
   model?: string;
   maxSteps?: number;
 }
@@ -26,7 +26,7 @@ interface AgentConfig {
  * AI Agent that uses OpenAPI tools
  */
 export class Agent {
-  private tools: Tool[];
+  private tools: ToolSet;
   private model: string;
   private maxSteps: number;
   private conversationHistory: ModelMessage[];
@@ -42,12 +42,15 @@ export class Agent {
    * Get available tools description for the agent
    */
   getToolsDescription(): string {
-    if (this.tools.length === 0) {
+    const names = Object.keys(this.tools);
+    if (names.length === 0) {
       return 'No tools available.';
     }
 
-    const toolDescriptions = this.tools.map((tool) => {
-      return `- ${tool.name}: ${tool.description}`;
+    const toolDescriptions = names.map((name) => {
+      const t = this.tools[name];
+      const desc = 'description' in t ? t.description : '';
+      return `- ${name}: ${desc}`;
     });
 
     return `I have access to the following tools:\n${toolDescriptions.join('\n')}`;
@@ -64,36 +67,32 @@ export class Agent {
     });
 
     try {
-      // Build AI SDK tools from our tool definitions
-      const aiTools: Parameters<typeof generateText>[0]['tools'] = {};
-
-      for (const t of this.tools) {
-        const toolExecute = t.execute;
-        const toolName = t.name;
-
-        aiTools![t.name] = tool({
-          description: t.description,
-          inputSchema: t.parameters,
-          execute: async (params) => {
-            console.log(
-              chalk.dim(`\n[Calling ${toolName} with ${JSON.stringify(params)}]`)
-            );
-
-            try {
-              const result = await toolExecute(params);
-              console.log(
-                chalk.dim(`[${toolName} returned: ${trimOutput(result)}]\n`)
-              );
-              return result;
-            } catch (error) {
-              if (error instanceof ToolExecutionError) {
-                console.log(chalk.red(`[${toolName} failed: ${error.message}]\n`));
-                throw error;
+      // Wrap each tool to add CLI logging
+      const wrappedTools: ToolSet = {};
+      for (const [name, t] of Object.entries(this.tools)) {
+        const originalExecute = 'execute' in t ? t.execute : undefined;
+        wrappedTools[name] = {
+          ...t,
+          execute: originalExecute
+            ? async (params: unknown, options: unknown) => {
+                console.log(
+                  chalk.dim(`\n[Calling ${name} with ${JSON.stringify(params)}]`)
+                );
+                try {
+                  const result = await (originalExecute as Function)(params, options);
+                  console.log(
+                    chalk.dim(`[${name} returned: ${trimOutput(result)}]\n`)
+                  );
+                  return result;
+                } catch (error) {
+                  if (error instanceof ToolExecutionError) {
+                    console.log(chalk.red(`[${name} failed: ${error.message}]\n`));
+                  }
+                  throw error;
+                }
               }
-              throw error;
-            }
-          },
-        });
+            : undefined,
+        } as ToolSet[string];
       }
 
       // Build system prompt
@@ -107,7 +106,7 @@ If a tool call fails, explain the error to the user.`;
         model: openai(this.model),
         system: systemPrompt,
         messages: this.conversationHistory,
-        tools: aiTools,
+        tools: wrappedTools,
         stopWhen: stepCountIs(this.maxSteps),
       });
 
@@ -143,13 +142,13 @@ If a tool call fails, explain the error to the user.`;
    * Get the list of tool names
    */
   getToolNames(): string[] {
-    return this.tools.map((t) => t.name);
+    return Object.keys(this.tools);
   }
 
   /**
    * Get a specific tool by name
    */
-  getTool(name: string): Tool | undefined {
-    return this.tools.find((t) => t.name === name);
+  getTool(name: string): ToolSet[string] | undefined {
+    return this.tools[name];
   }
 }

packages/cli/src/cli.ts

@@ -12,12 +12,15 @@ import {
   AuthManager,
   createExecutableTools,
   executeToolByName,
+  toAISDKTools,
+  toCodeModeTools,
   UnsupportedSchemaError,
   AuthenticationError,
   ToolExecutionError,
   SpecLoadError,
   type Session,
   type Tool,
+  type ToolSet,
 } from '@spec2tools/core';
 import { Agent } from './agent.js';
 
@@ -37,6 +40,7 @@ export function createCLI(): Command {
     .requiredOption('-s, --spec <path>', 'Path or URL to OpenAPI specification')
     .option('--no-auth', 'Skip authentication even if required by spec')
     .option('--api-key <key>', 'Provide API key or access token directly')
+    .option('--code-mode', 'Use code mode (2 tools: search + execute)')
     .action(async (options) => {
       await startAgent(options);
     });
@@ -48,6 +52,7 @@ interface StartOptions {
   spec: string;
   auth: boolean;
   apiKey?: string;
+  codeMode?: boolean;
 }
 
 async function startAgent(options: StartOptions): Promise<void> {
@@ -100,6 +105,14 @@ async function startAgent(options: StartOptions): Promise<void> {
     // Create executable tools
     const tools = createExecutableTools(toolDefs, baseUrl, authManager);
 
+    // Convert to AI SDK tools
+    let aiTools = toAISDKTools(tools);
+
+    if (options.codeMode) {
+      aiTools = toCodeModeTools(aiTools);
+      console.log(chalk.green('Code mode enabled (2 tools: search + execute)'));
+    }
+
     // Initialize session
     const session: Session = {
       baseUrl,
@@ -109,7 +122,7 @@ async function startAgent(options: StartOptions): Promise<void> {
     };
 
     // Start chat loop
-    await startChatLoop(session);
+    await startChatLoop(session, aiTools, options.codeMode ?? false);
   } catch (error) {
     spinner.fail();
 
@@ -136,9 +149,9 @@ async function startAgent(options: StartOptions): Promise<void> {
   }
 }
 
-async function startChatLoop(session: Session): Promise<void> {
+async function startChatLoop(session: Session, aiTools: ToolSet, codeMode: boolean): Promise<void> {
   // Initialize agent
-  const agent = new Agent({ tools: session.tools });
+  const agent = new Agent({ tools: aiTools });
 
   console.log(chalk.bold('\n--- Spec2Tools ---'));
   console.log(chalk.dim('Type your message or use special commands:'));
@@ -167,7 +180,7 @@ async function startChatLoop(session: Session): Promise<void> {
       rl.pause();
 
       try {
-        await handleInput(trimmedInput, session, agent);
+        await handleInput(trimmedInput, session, agent, codeMode, aiTools);
       } catch (error) {
         console.error(
           chalk.red(
@@ -192,11 +205,13 @@ async function startChatLoop(session: Session): Promise<void> {
 async function handleInput(
   input: string,
   session: Session,
-  agent: Agent
+  agent: Agent,
+  codeMode: boolean,
+  aiTools: ToolSet
 ): Promise<void> {
   // Handle special commands
   if (input.startsWith('/')) {
-    await handleCommand(input, session, agent);
+    await handleCommand(input, session, agent, codeMode, aiTools);
     return;
   }
 
@@ -216,15 +231,21 @@ async function handleInput(
 async function handleCommand(
   input: string,
   session: Session,
-  agent: Agent
+  agent: Agent,
+  codeMode: boolean,
+  aiTools: ToolSet
 ): Promise<void> {
   const parts = input.slice(1).split(/\s+/);
   const command = parts[0].toLowerCase();
   const args = parts.slice(1);
 
   switch (command) {
     case 'tools':
-      listTools(session.tools);
+      if (codeMode) {
+        listCodeModeTools(aiTools);
+      } else {
+        listTools(session.tools);
+      }
       break;
 
     case 'call':
@@ -267,6 +288,18 @@ function listTools(tools: Tool[]): void {
   console.log('');
 }
 
+function listCodeModeTools(aiTools: ToolSet): void {
+  console.log(chalk.bold('\nCode mode tools:'));
+
+  Object.entries(aiTools).forEach(([name, t], index) => {
+    const desc = 'description' in t ? (t.description as string) || '' : '';
+    console.log(chalk.cyan(`${index + 1}. ${name}`));
+    console.log(chalk.dim(`   ${desc}`));
+  });
+
+  console.log('');
+}
+
 async function callTool(tools: Tool[], args: string[]): Promise<void> {
   if (args.length === 0) {
     console.log(chalk.yellow('Usage: /call <toolName> [--param value ...]'));

packages/core/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @spec2tools/core
 
+## 0.2.0
+
+### Minor Changes
+
+- Add code mode MCP option
+
 ## 0.1.2
 
 ### Patch Changes