api2ai 1.0.1

package/README.md

@@ -0,0 +1,189 @@
+# API2AI: OpenAPI to MCP-Use Server 
+
+Generate production-ready MCP servers from any OpenAPI specification using the [mcp-use](https://mcp-use.com) framework.
+
+## Features
+
+- 🚀 **Modern Framework** - Uses mcp-use for clean, maintainable code
+- 🔍 **Built-in Inspector** - Test tools immediately at `/inspector`
+- 📡 **Multiple Transports** - HTTP, SSE, and Streamable HTTP support
+- 🎨 **UI Widgets** - Compatible with ChatGPT Apps SDK and MCP-UI
+- 🔐 **Auth Support** - Bearer tokens, API keys, custom headers
+- ✨ **Zod Schemas** - Type-safe parameter validation
+- 🐳 **Production Ready** - Docker, PM2, and Kubernetes ready
+
+## Quick Start
+
+```bash
+# Generate a server from the Petstore API
+node generate-mcp-use-server.js \
+  https://petstore3.swagger.io/api/v3/openapi.json \
+  ./petstore-mcp \
+  --name petstore-api
+
+# Install and run
+cd petstore-mcp
+npm install
+npm start
+```
+
+Open http://localhost:3000/inspector to test your tools!
+
+## Usage
+
+### CLI
+
+```bash
+node generate-mcp-use-server.js <openapi-spec> [output-folder] [options]
+
+Options:
+  --name <name>      Server name (default: api-mcp-server)
+  --base-url <url>   Override API base URL
+  --port <port>      Server port (default: 3000)
+  --help             Show help
+```
+
+### Examples
+
+```bash
+# From remote URL
+node generate-mcp-use-server.js \
+  https://api.example.com/openapi.json \
+  ./my-server \
+  --name my-api
+
+# From local file
+node generate-mcp-use-server.js \
+  ./specs/my-api.yaml \
+  ./my-mcp-server \
+  --port 8080
+
+# With custom base URL
+node generate-mcp-use-server.js \
+  ./petstore.json \
+  ./petstore \
+  --base-url https://petstore.example.com/v3
+```
+
+### Programmatic Usage
+
+```javascript
+import { generateMcpServer, extractTools, loadOpenApiSpec } from './generate-mcp-use-server.js';
+
+// Generate complete server
+const result = await generateMcpServer(
+  'https://api.example.com/openapi.json',
+  './output-folder',
+  {
+    serverName: 'my-api',
+    baseUrl: 'https://api.example.com/v1',
+    port: 3000,
+  }
+);
+
+console.log(`Generated ${result.toolCount} tools`);
+
+// Or just extract tools for custom processing
+const spec = await loadOpenApiSpec('./my-spec.json');
+const tools = extractTools(spec, {
+  filterFn: (tool) => tool.method === 'get',  // Only GET endpoints
+  excludeOperationIds: ['deleteUser'],        // Exclude specific operations
+});
+```
+
+## Generated Output
+
+```
+my-mcp-server/
+├── .env              # Environment config (gitignored)
+├── .env.example      # Example environment file
+├── .gitignore
+├── package.json
+├── README.md         # Generated documentation
+└── src/
+    ├── index.js      # Main server with tool registrations
+    ├── http-client.js # HTTP utilities
+    └── tools-config.js # Tool configurations
+```
+
+## Generated Server Features
+
+### Built-in Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /inspector` | Interactive tool testing UI |
+| `POST /mcp` | MCP protocol endpoint |
+| `GET /sse` | Server-Sent Events endpoint |
+| `GET /health` | Health check |
+
+### Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `PORT` | Server port |
+| `NODE_ENV` | development/production |
+| `API_BASE_URL` | Base URL for API calls |
+| `API_KEY` | Bearer token auth |
+| `API_AUTH_HEADER` | Custom header (`Name:value`) |
+| `MCP_URL` | Public URL for widgets |
+| `ALLOWED_ORIGINS` | CORS origins (production) |
+
+
+### Connect to ChatGPT
+
+The generated server supports the OpenAI Apps SDK out of the box.
+
+## Advanced Options
+
+### Filter Tools by Method
+
+```javascript
+const result = await generateMcpServer(specUrl, outputDir, {
+  filterFn: (tool) => ['get', 'post'].includes(tool.method),
+});
+```
+
+### Exclude Dangerous Operations
+
+```javascript
+const result = await generateMcpServer(specUrl, outputDir, {
+  excludeOperationIds: [
+    'deleteUser',
+    'deleteAllData', 
+    'adminReset',
+  ],
+});
+```
+
+### Filter by Path Pattern
+
+```javascript
+const result = await generateMcpServer(specUrl, outputDir, {
+  filterFn: (tool) => tool.pathTemplate.startsWith('/api/v2/'),
+});
+```
+
+### Combine Filters
+
+```javascript
+const result = await generateMcpServer(specUrl, outputDir, {
+  excludeOperationIds: ['deleteUser'],
+  filterFn: (tool) => 
+    tool.method === 'get' && 
+    tool.pathTemplate.includes('/public/'),
+});
+```
+
+
+
+## Comparison with Raw MCP SDK
+
+| Feature | This Generator | Raw SDK |
+|---------|---------------|---------|
+| Code needed | ~50 lines | ~200+ lines |
+| Inspector | ✅ Built-in | ❌ Manual |
+| UI Widgets | ✅ Supported | ❌ Manual |
+| Zod validation | ✅ Generated | ❌ Manual |
+| Authentication | ✅ Configured | ❌ Manual |
+| Production ready | ✅ Yes | ⚠️ Requires work |

package/bun.lock

@@ -0,0 +1,17 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "api2ai",
+      "devDependencies": {
+        "js-yaml": "^4.1.0",
+      },
+    },
+  },
+  "packages": {
+    "argparse": ["argparse@2.0.1", "", {}, "sha512-8+9WqebbFzpX9OR+Wa6O29asIogeRMzcGtAINdpMHHyAg10f05aSFVBbcEqGf/PXw1EjAZ+q2/bEBg3DvurK3Q=="],
+
+    "js-yaml": ["js-yaml@4.1.1", "", { "dependencies": { "argparse": "^2.0.1" }, "bin": { "js-yaml": "bin/js-yaml.js" } }, "sha512-qQKT4zQxXl8lLwBtHMWwaTcGfFOZviOJet3Oy/xmGk2gZH677CJM9EvtfdSkgWcATZhj/55JZ0rmy3myCT5lsA=="],
+  }
+}

package/example-petstore/.env.example

@@ -0,0 +1,14 @@
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+
+# API Configuration  
+API_BASE_URL=/api/v3
+
+# Authentication
+API_KEY=your-api-key-here
+# API_AUTH_HEADER=Header-Name:header-value
+
+# MCP Configuration
+# MCP_URL=https://your-mcp-server.com
+# ALLOWED_ORIGINS=https://allowed-origin.com

package/example-petstore/README.md

@@ -0,0 +1,145 @@
+# petstore-api
+
+MCP server auto-generated from OpenAPI specification using the [mcp-use](https://mcp-use.com) framework.
+
+## Features
+
+- 🛠️ **19 API Tools** - All operations from the OpenAPI spec
+- 🔍 **Built-in Inspector** - Test tools at `/inspector`
+- 📡 **Streamable HTTP** - Modern MCP transport
+- 🔐 **Authentication Support** - Bearer tokens & custom headers
+- 🎨 **UI Widgets** - Compatible with ChatGPT and MCP-UI
+
+## Quick Start
+
+```bash
+# Install dependencies
+npm install
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your API credentials
+
+# Start the server
+npm start
+
+# Or with hot reload
+npm run dev
+```
+
+Then open http://localhost:3000/inspector to test your tools!
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | Server port | 3000 |
+| `NODE_ENV` | Environment (development/production) | development |
+| `API_BASE_URL` | Base URL for API requests | /api/v3 |
+| `API_KEY` | Bearer token for Authorization header | - |
+| `API_AUTH_HEADER` | Custom auth header (format: `Header:value`) | - |
+| `MCP_URL` | Public MCP server URL (for widgets) | http://localhost:3000 |
+| `ALLOWED_ORIGINS` | Allowed origins in production (comma-separated) | - |
+
+## Connect to Claude Desktop
+
+Add to your Claude Desktop configuration:
+
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "petstore-api": {
+      "url": "http://localhost:3000/mcp"
+    }
+  }
+}
+```
+
+## Connect to ChatGPT
+
+This server supports the OpenAI Apps SDK. Configure your ChatGPT integration to use:
+
+```
+http://localhost:3000/mcp
+```
+
+## Available Tools
+
+| Tool | Method | Path | Description |
+|------|--------|------|-------------|
+| `addPet` | POST | /pet | Add a new pet to the store. |
+| `updatePet` | PUT | /pet | Update an existing pet. |
+| `findPetsByStatus` | GET | /pet/findByStatus | Finds Pets by status. |
+| `findPetsByTags` | GET | /pet/findByTags | Finds Pets by tags. |
+| `getPetById` | GET | /pet/{petId} | Find pet by ID. |
+| `updatePetWithForm` | POST | /pet/{petId} | Updates a pet in the store with form data. |
+| `deletePet` | DELETE | /pet/{petId} | Deletes a pet. |
+| `uploadFile` | POST | /pet/{petId}/uploadImage | Uploads an image. |
+| `getInventory` | GET | /store/inventory | Returns pet inventories by status. |
+| `placeOrder` | POST | /store/order | Place an order for a pet. |
+| `getOrderById` | GET | /store/order/{orderId} | Find purchase order by ID. |
+| `deleteOrder` | DELETE | /store/order/{orderId} | Delete purchase order by identifier. |
+| `createUser` | POST | /user | Create user. |
+| `createUsersWithListInput` | POST | /user/createWithList | Creates list of users with given input array. |
+| `loginUser` | GET | /user/login | Logs user into the system. |
+| `logoutUser` | GET | /user/logout | Logs out current logged in user session. |
+| `getUserByName` | GET | /user/{username} | Get user by user name. |
+| `updateUser` | PUT | /user/{username} | Update user resource. |
+| `deleteUser` | DELETE | /user/{username} | Delete user resource. |
+
+## API Endpoints
+
+| Endpoint | Description |
+|----------|-------------|
+| `GET /inspector` | Interactive tool testing UI |
+| `POST /mcp` | MCP protocol endpoint |
+| `GET /sse` | Server-Sent Events endpoint |
+| `GET /health` | Health check endpoint |
+
+## Project Structure
+
+```
+petstore-api/
+├── .env              # Environment configuration
+├── .env.example      # Example environment file
+├── package.json      # Dependencies
+├── README.md         # This file
+└── src/
+    ├── index.js      # Main server with tool registrations
+    ├── http-client.js # HTTP utilities for API calls
+    └── tools-config.js # Tool configurations from OpenAPI
+```
+
+## Production Deployment
+
+### Docker
+
+```dockerfile
+FROM node:20-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY . .
+ENV NODE_ENV=production
+EXPOSE 3000
+CMD ["npm", "start"]
+```
+
+### PM2
+
+```bash
+pm2 start src/index.js --name petstore-api
+```
+
+## Source
+
+- **OpenAPI Spec**: `https://petstore3.swagger.io/api/v3/openapi.json`
+- **Generated**: 2025-12-30T23:36:57.107Z
+- **Framework**: [mcp-use](https://mcp-use.com)
+
+## License
+
+MIT