@spec2tools/cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# @spec2tools/cli
+
+CLI for interacting with OpenAPI-based AI tools.
+
+## Installation
+
+```bash
+npm install -g @spec2tools/cli
+```
+
+Or use directly with npx:
+
+```bash
+npx @spec2tools/cli start --spec ./openapi.yaml
+```
+
+## Usage
+
+### Set Environment Variables
+
+Define a `.env` file and set the `OPENAI_API_KEY` environment variable:
+
+```
+OPENAI_API_KEY=your-api-key
+```
+
+### Start the Agent
+
+```bash
+# With a remote OpenAPI spec URL
+npx @spec2tools/cli start --spec https://api.example.com/openapi.json
+
+# With a local file
+npx @spec2tools/cli start --spec ./openapi.yaml
+
+# Skip authentication
+npx @spec2tools/cli start --spec ./openapi.yaml --no-auth
+
+# Provide token directly
+npx @spec2tools/cli start --spec ./openapi.yaml --token "your-access-token"
+```
+
+### Chat Mode
+
+Once started, you can interact with the AI agent naturally:
+
+```
+> What can you do?
+I have access to the following tools:
+- createUser: Create a new user
+- getUser: Retrieve user by ID
+- listUsers: List all users
+
+> Create a user named John with email john@example.com
+[Calling createUser with {"name":"John","email":"john@example.com"}]
+Created user successfully: { id: "123", name: "John", email: "john@example.com" }
+```
+
+### Special Commands
+
+```bash
+# List available tools
+> /tools
+
+# Call a tool directly
+> /call createUser --name "John" --email "john@example.com"
+
+# Show tool schema
+> /schema createUser
+
+# Clear conversation history
+> /clear
+
+# Show help
+> /help
+
+# Exit
+> /exit
+```
+
+## Examples
+
+The `examples/` directory contains sample OpenAPI specifications:
+
+- `sample-api.yaml` - Simple API without authentication
+- `authenticated-api.yaml` - API with OAuth2 authentication
+- `context7.yaml` - Context7 API with OAuth2 (PKCE + dynamic client registration)
+
+## Supported OpenAPI Features
+
+### Supported
+- `GET`, `POST`, `PUT`, `PATCH`, `DELETE` operations
+- Path parameters (string, number, boolean)
+- Query parameters (string, number, boolean)
+- Request body with simple JSON schemas (primitives, flat objects)
+- Security schemes: OAuth2 (authorization code with PKCE), API Key, Bearer token
+- OAuth2 Dynamic Client Registration (auto-registers client with the auth server)
+
+### Not Supported (throws error)
+- Nested objects beyond 1 level
+- Arrays of objects
+- `anyOf`, `oneOf`, `allOf` schemas
+- File uploads
+- `$ref` references
+
+## License
+
+MIT

package/dist/agent.d.ts

@@ -0,0 +1,38 @@
+import { type Tool } from '@spec2tools/core';
+interface AgentConfig {
+    tools: Tool[];
+    model?: string;
+    maxSteps?: number;
+}
+/**
+ * AI Agent that uses OpenAPI tools
+ */
+export declare class Agent {
+    private tools;
+    private model;
+    private maxSteps;
+    private conversationHistory;
+    constructor(config: AgentConfig);
+    /**
+     * Get available tools description for the agent
+     */
+    getToolsDescription(): string;
+    /**
+     * Process a user message and return the response
+     */
+    chat(userMessage: string): Promise<string>;
+    /**
+     * Clear conversation history
+     */
+    clearHistory(): void;
+    /**
+     * Get the list of tool names
+     */
+    getToolNames(): string[];
+    /**
+     * Get a specific tool by name
+     */
+    getTool(name: string): Tool | undefined;
+}
+export {};
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.js

@@ -0,0 +1,126 @@
+import { generateText, tool, stepCountIs } from 'ai';
+import { openai } from '@ai-sdk/openai';
+import { ToolExecutionError } from '@spec2tools/core';
+import chalk from 'chalk';
+const MAX_OUTPUT_LENGTH = 500;
+/**
+ * Trim a string if it exceeds the maximum length
+ */
+function trimOutput(value) {
+    const str = typeof value === 'string' ? value : JSON.stringify(value);
+    if (str.length > MAX_OUTPUT_LENGTH) {
+        return str.substring(0, MAX_OUTPUT_LENGTH) + '...';
+    }
+    return str;
+}
+/**
+ * AI Agent that uses OpenAPI tools
+ */
+export class Agent {
+    tools;
+    model;
+    maxSteps;
+    conversationHistory;
+    constructor(config) {
+        this.tools = config.tools;
+        this.model = config.model || 'gpt-5.1-chat-latest';
+        this.maxSteps = config.maxSteps || 10;
+        this.conversationHistory = [];
+    }
+    /**
+     * Get available tools description for the agent
+     */
+    getToolsDescription() {
+        if (this.tools.length === 0) {
+            return 'No tools available.';
+        }
+        const toolDescriptions = this.tools.map((tool) => {
+            return `- ${tool.name}: ${tool.description}`;
+        });
+        return `I have access to the following tools:\n${toolDescriptions.join('\n')}`;
+    }
+    /**
+     * Process a user message and return the response
+     */
+    async chat(userMessage) {
+        // Add user message to history
+        this.conversationHistory.push({
+            role: 'user',
+            content: userMessage,
+        });
+        try {
+            // Build AI SDK tools from our tool definitions
+            const aiTools = {};
+            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;
+                            }
+                            throw error;
+                        }
+                    },
+                });
+            }
+            // Build system prompt
+            const systemPrompt = `You are a helpful AI assistant with access to various API tools.
+When the user asks you to perform actions, use the available tools to help them.
+Always explain what you're doing and present results in a clear, readable format.
+If a tool call fails, explain the error to the user.`;
+            // Generate response with tool use
+            const result = await generateText({
+                model: openai(this.model),
+                system: systemPrompt,
+                messages: this.conversationHistory,
+                tools: aiTools,
+                stopWhen: stepCountIs(this.maxSteps),
+            });
+            // Add assistant response to history
+            this.conversationHistory.push({
+                role: 'assistant',
+                content: result.text,
+            });
+            return result.text;
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // Add error response to history
+            this.conversationHistory.push({
+                role: 'assistant',
+                content: `I encountered an error: ${errorMessage}`,
+            });
+            throw error;
+        }
+    }
+    /**
+     * Clear conversation history
+     */
+    clearHistory() {
+        this.conversationHistory = [];
+    }
+    /**
+     * Get the list of tool names
+     */
+    getToolNames() {
+        return this.tools.map((t) => t.name);
+    }
+    /**
+     * Get a specific tool by name
+     */
+    getTool(name) {
+        return this.tools.find((t) => t.name === name);
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+import { Command } from 'commander';
+export declare function createCLI(): Command;
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,312 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import ora from 'ora';
+import * as readline from 'readline';
+import { loadOpenAPISpec, extractBaseUrl, extractAuthConfig, parseOperations, formatToolSchema, formatToolSignature, AuthManager, createExecutableTools, executeToolByName, UnsupportedSchemaError, AuthenticationError, ToolExecutionError, SpecLoadError, } from '@spec2tools/core';
+import { Agent } from './agent.js';
+const VERSION = '0.1.6';
+export function createCLI() {
+    const program = new Command();
+    program
+        .name('spec2tools')
+        .description('Dynamically convert OpenAPI specs into AI agent tools at runtime')
+        .version(VERSION);
+    program
+        .command('start')
+        .description('Start the agent with an OpenAPI specification')
+        .requiredOption('-s, --spec <path>', 'Path or URL to OpenAPI specification')
+        .option('--no-auth', 'Skip authentication even if required by spec')
+        .option('--token <token>', 'Provide access token directly')
+        .action(async (options) => {
+        await startAgent(options);
+    });
+    return program;
+}
+async function startAgent(options) {
+    const spinner = ora();
+    try {
+        // Load OpenAPI spec
+        spinner.start('Loading OpenAPI specification...');
+        const spec = await loadOpenAPISpec(options.spec);
+        spinner.succeed(`Loaded: ${spec.info.title} v${spec.info.version}`);
+        // Extract base URL
+        const baseUrl = extractBaseUrl(spec);
+        console.log(chalk.dim(`Base URL: ${baseUrl}`));
+        // Extract auth config
+        const authConfig = extractAuthConfig(spec);
+        // Parse operations
+        spinner.start('Parsing operations...');
+        const toolDefs = parseOperations(spec);
+        spinner.succeed(`Found ${toolDefs.length} operations`);
+        if (toolDefs.length === 0) {
+            console.log(chalk.yellow('No operations found in the specification.'));
+            return;
+        }
+        // Initialize auth manager
+        const authManager = new AuthManager(authConfig);
+        // Handle authentication
+        if (options.token) {
+            authManager.setAccessToken(options.token);
+            console.log(chalk.green('Using provided access token'));
+        }
+        else if (options.auth && authManager.requiresAuth()) {
+            console.log(chalk.yellow(`\nAuthentication required (${authConfig.type})`));
+            await authManager.authenticate();
+            console.log(chalk.green('Authentication successful!'));
+        }
+        else if (authManager.requiresAuth()) {
+            console.log(chalk.yellow('\nWarning: API requires authentication but --no-auth was specified'));
+        }
+        // Create executable tools
+        const tools = createExecutableTools(toolDefs, baseUrl, authManager);
+        // Initialize session
+        const session = {
+            baseUrl,
+            tools,
+            authConfig,
+            accessToken: authManager.getAccessToken(),
+        };
+        // Start chat loop
+        await startChatLoop(session);
+    }
+    catch (error) {
+        spinner.fail();
+        if (error instanceof UnsupportedSchemaError) {
+            console.error(chalk.red(`\nSchema Error: ${error.message}`));
+            console.error(chalk.dim('This OpenAPI specification contains features that are not supported.'));
+        }
+        else if (error instanceof AuthenticationError) {
+            console.error(chalk.red(`\nAuth Error: ${error.message}`));
+        }
+        else if (error instanceof SpecLoadError) {
+            console.error(chalk.red(`\nSpec Error: ${error.message}`));
+        }
+        else {
+            console.error(chalk.red(`\nError: ${error instanceof Error ? error.message : String(error)}`));
+        }
+        process.exit(1);
+    }
+}
+async function startChatLoop(session) {
+    // Initialize agent
+    const agent = new Agent({ tools: session.tools });
+    console.log(chalk.bold('\n--- Spec2Tools ---'));
+    console.log(chalk.dim('Type your message or use special commands:'));
+    console.log(chalk.dim('  /tools  - List available tools'));
+    console.log(chalk.dim('  /call   - Call a tool directly'));
+    console.log(chalk.dim('  /schema - Show tool schema'));
+    console.log(chalk.dim('  /help   - Show help'));
+    console.log(chalk.dim('  /exit   - Exit the CLI'));
+    console.log('');
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const prompt = () => {
+        rl.question(chalk.cyan('> '), async (input) => {
+            const trimmedInput = input.trim();
+            if (!trimmedInput) {
+                prompt();
+                return;
+            }
+            // Pause readline during async operations to prevent corruption
+            rl.pause();
+            try {
+                await handleInput(trimmedInput, session, agent);
+            }
+            catch (error) {
+                console.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+            }
+            finally {
+                rl.resume();
+                prompt();
+            }
+        });
+    };
+    rl.on('close', () => {
+        console.log(chalk.dim('\nGoodbye!'));
+        process.exit(0);
+    });
+    prompt();
+}
+async function handleInput(input, session, agent) {
+    // Handle special commands
+    if (input.startsWith('/')) {
+        await handleCommand(input, session, agent);
+        return;
+    }
+    // Regular chat message
+    const spinner = ora('Thinking...').start();
+    try {
+        const response = await agent.chat(input);
+        spinner.stop();
+        console.log(chalk.white('\n' + response + '\n'));
+    }
+    catch (error) {
+        spinner.fail('Failed to get response');
+        throw error;
+    }
+}
+async function handleCommand(input, session, agent) {
+    const parts = input.slice(1).split(/\s+/);
+    const command = parts[0].toLowerCase();
+    const args = parts.slice(1);
+    switch (command) {
+        case 'tools':
+            listTools(session.tools);
+            break;
+        case 'call':
+            await callTool(session.tools, args);
+            break;
+        case 'schema':
+            showSchema(session.tools, args[0]);
+            break;
+        case 'help':
+            showHelp();
+            break;
+        case 'exit':
+        case 'quit':
+            console.log(chalk.dim('Goodbye!'));
+            process.exit(0);
+        case 'clear':
+            agent.clearHistory();
+            console.log(chalk.dim('Conversation history cleared.'));
+            break;
+        default:
+            console.log(chalk.yellow(`Unknown command: ${command}`));
+            console.log(chalk.dim('Type /help for available commands.'));
+    }
+}
+function listTools(tools) {
+    console.log(chalk.bold('\nAvailable tools:'));
+    tools.forEach((tool, index) => {
+        const signature = formatToolSignature(tool);
+        console.log(chalk.cyan(`${index + 1}. ${signature}`));
+        console.log(chalk.dim(`   ${tool.description}`));
+    });
+    console.log('');
+}
+async function callTool(tools, args) {
+    if (args.length === 0) {
+        console.log(chalk.yellow('Usage: /call <toolName> [--param value ...]'));
+        console.log(chalk.dim('Example: /call createUser --name "John" --email "john@example.com"'));
+        return;
+    }
+    const toolName = args[0];
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+        console.log(chalk.red(`Tool not found: ${toolName}`));
+        console.log(chalk.dim('Use /tools to see available tools.'));
+        return;
+    }
+    // Parse remaining args as --key value pairs
+    const params = parseCallArgs(args.slice(1));
+    const spinner = ora(`Calling ${toolName}...`).start();
+    try {
+        const result = await executeToolByName(tools, toolName, params);
+        spinner.succeed(`${toolName} completed`);
+        console.log(chalk.white('\nResult:'));
+        console.log(JSON.stringify(result, null, 2));
+        console.log('');
+    }
+    catch (error) {
+        spinner.fail(`${toolName} failed`);
+        if (error instanceof ToolExecutionError) {
+            console.error(chalk.red(error.message));
+        }
+        else {
+            console.error(chalk.red(`Error: ${error instanceof Error ? error.message : String(error)}`));
+        }
+    }
+}
+function parseCallArgs(args) {
+    const params = {};
+    let i = 0;
+    while (i < args.length) {
+        const arg = args[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const value = args[i + 1];
+            if (value === undefined) {
+                params[key] = true;
+                i++;
+            }
+            else if (value.startsWith('--')) {
+                params[key] = true;
+                i++;
+            }
+            else {
+                // Try to parse as JSON, number, or boolean
+                params[key] = parseValue(value);
+                i += 2;
+            }
+        }
+        else {
+            i++;
+        }
+    }
+    return params;
+}
+function parseValue(value) {
+    // Remove quotes if present
+    if ((value.startsWith('"') && value.endsWith('"')) ||
+        (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    // Try parsing as number
+    const num = Number(value);
+    if (!isNaN(num)) {
+        return num;
+    }
+    // Check for boolean
+    if (value.toLowerCase() === 'true')
+        return true;
+    if (value.toLowerCase() === 'false')
+        return false;
+    // Try parsing as JSON
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+}
+function showSchema(tools, toolName) {
+    if (!toolName) {
+        console.log(chalk.yellow('Usage: /schema <toolName>'));
+        return;
+    }
+    const tool = tools.find((t) => t.name === toolName);
+    if (!tool) {
+        console.log(chalk.red(`Tool not found: ${toolName}`));
+        console.log(chalk.dim('Use /tools to see available tools.'));
+        return;
+    }
+    console.log(chalk.bold(`\nSchema for ${toolName}:`));
+    console.log(chalk.white(formatToolSchema(tool)));
+    console.log('');
+}
+function showHelp() {
+    console.log(chalk.bold('\nAgent CLI Help'));
+    console.log('');
+    console.log(chalk.cyan('Chat Mode:'));
+    console.log('  Just type your message to chat with the AI agent.');
+    console.log('  The agent can use available tools to help you.');
+    console.log('');
+    console.log(chalk.cyan('Special Commands:'));
+    console.log(chalk.white('  /tools') + chalk.dim('  - List all available tools'));
+    console.log(chalk.white('  /call <tool> [args]') +
+        chalk.dim('  - Call a tool directly'));
+    console.log(chalk.white('  /schema <tool>') + chalk.dim('  - Show tool parameter schema'));
+    console.log(chalk.white('  /clear') + chalk.dim('  - Clear conversation history'));
+    console.log(chalk.white('  /help') + chalk.dim('  - Show this help message'));
+    console.log(chalk.white('  /exit') + chalk.dim('  - Exit the CLI'));
+    console.log('');
+    console.log(chalk.cyan('Examples:'));
+    console.log(chalk.dim('  > What can you do?'));
+    console.log(chalk.dim('  > Create a user named John with email john@example.com'));
+    console.log(chalk.dim('  > /call createUser --name "John" --email "john@example.com"'));
+    console.log(chalk.dim('  > /schema createUser'));
+    console.log('');
+}
+//# sourceMappingURL=cli.js.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+import 'dotenv/config';
+import { createCLI } from './cli.js';
+const program = createCLI();
+program.parse(process.argv);
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@spec2tools/cli",
+  "version": "0.1.0",
+  "description": "CLI for interacting with OpenAPI-based AI tools",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "spec2tools": "./dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts"
+  ],
+  "keywords": [
+    "openapi",
+    "cli",
+    "ai",
+    "agent",
+    "tools",
+    "ai-sdk"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CahidArda/spec2tools.git",
+    "directory": "packages/cli"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^3.0.25",
+    "ai": "^6.0.68",
+    "chalk": "^5.3.0",
+    "commander": "^14.0.0",
+    "dotenv": "^17.2.3",
+    "ora": "^8.1.0",
+    "@spec2tools/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "postbuild": "chmod +x dist/index.js",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  }
+}