openapi-to-mcp

# OpenAPI-to-MCP Generate AI-friendly interfaces from your existing Swagger/OpenAPI specs. This tool converts APIs into Model Control Protocol (MCP) format — used to control tools and environments via large language models. ## Overview This tool converts OpenAPI/Swagger specifications into Model Control Protocol (MCP) format, making it easy to create AI agents that can interact with your APIs. ## Project Structure This is a monorepo containing two packages: - `packages/core`: The main OpenAPI-to-MCP CLI tool and library - `packages/playground`: A web application for testing the tool in your browser ## Features - 📥 Generate universal mcp.json from OpenAPI/Swagger files - 🔄 Auto-extract state schema from suitable GET endpoints - 📤 Export to multiple formats: - 📜 Prompt instructions with state information - 🧱 JSON action templates with getState action - 🔧 Function schemas with getState function (OpenAI compatible) - 🚀 MCP server TypeScript file compatible with Claude Desktop - 🔌 Standalone executor for API interaction (LangChain/Web compatible) - 📂 Plug-and-play handler files with README - 🔗 LangChain tools with argsSchema and toolloader - 🔌 OpenAI plugin manifest with deployment instructions - 🧪 Simulation mode for testing without backend changes ## Use Cases - **Build Claude Desktop-compatible tools in seconds** — Generate an MCP server that works directly with Claude - **Turn any OpenAPI spec into LangChain/AutoGPT tools** — Use the executor or LangChain tools for AI interfaces in any framework - **Power AI interfaces for existing microservices** — No backend changes required, works with existing APIs - **Create ChatGPT plugins effortlessly** — Generate OpenAI plugin manifests with proper schemas - **Prototype AI agents with minimal setup** — Use simulation mode to test AI interaction with your API - **Create custom handler logic** — Extend handlers with preprocessing, caching, or business logic ## Installation ```bash # Install globally npm install -g openapi-to-mcp # Or use directly with npx npx openapi-to-mcp <swagger-file> ``` ## Usage ```bash # Basic usage - generates all outputs openapi-to-mcp path/to/swagger.yaml # Specify output directory openapi-to-mcp path/to/swagger.yaml -o ./custom-output # Generate only specific formats openapi-to-mcp path/to/swagger.yaml --prompt --functions # Generate MCP server for Claude Desktop openapi-to-mcp path/to/swagger.yaml --server --api-url https://your-api.com # Generate standalone executor for any framework openapi-to-mcp path/to/swagger.yaml --executor --api-url https://your-api.com # Generate individual handler files for customization openapi-to-mcp path/to/swagger.yaml --handlers --api-url https://your-api.com # Generate LangChain tools for your API openapi-to-mcp path/to/swagger.yaml --langchain --api-url https://your-api.com # Generate OpenAI plugin manifest files openapi-to-mcp path/to/swagger.yaml --openai-plugin --api-url https://your-api.com # Specify a particular endpoint for state schema openapi-to-mcp path/to/swagger.yaml --state-endpoint /status # Simulate AI interaction with your API openapi-to-mcp path/to/swagger.yaml --simulate "list all available pets" --api-url https://your-api.com # Simulate using Claude instead of OpenAI (default) openapi-to-mcp path/to/swagger.yaml --simulate "add a new pet" --provider claude --api-url https://your-api.com # See all options openapi-to-mcp --help ``` ## Output Files Running the generator creates the following files: - `generated.mcp.json`: The MCP specification for your API - `prompt.txt`: Prompt instructions for LLMs - `templates.json`: JSON action templates - `functionSchemas.json`: OpenAI-compatible function schemas - `mcp-server.ts`: Ready-to-use TypeScript MCP server implementation for Claude Desktop - `executor.ts`: Standalone executor for using API actions in any framework - `handlers/`: Directory with individual handler implementations for each action - `langchain-tools.ts`: Ready-to-use LangChain tools with Zod validation - `langchain-toolloader.ts`: Helper for selective tool loading - `.well-known/ai-plugin.json`: OpenAI plugin manifest file - `OPENAI-PLUGIN-README.md`: Deployment instructions for the OpenAI plugin ## Using the Generated Files ### MCP Server for Claude Desktop 1. Install dependencies: `npm install @modelcontextprotocol/sdk zod` 2. Compile the server: `tsc mcp-server.ts --esModuleInterop --module nodenext` 3. Run with Claude Desktop: `claude tools register mcp-server.js` ### Standalone Executor ```typescript // Example usage with any framework import { ApiExecutor } from "./executor"; async function main() { const api = new ApiExecutor("https://your-api.com"); // Get API state const state = await api.getState(); console.log("Current state:", state); // Execute an action const result = await api.execute("listPets", { limit: 10 }); console.log("Pets:", result); } ``` ### LangChain Tools ```typescript // Example usage with LangChain import { ChatOpenAI } from "langchain/chat_models/openai"; import { AgentExecutor, createStructuredChatAgent } from "langchain/agents"; import { loadTools } from "./langchain-toolloader"; async function main() { const model = new ChatOpenAI({ temperature: 0, modelName: "gpt-4-turbo", }); // Load all tools or specify which ones to load const tools = loadTools(["listPets", "getPet", "getState"]); const agent = createStructuredChatAgent({ llm: model, tools, }); const agentExecutor = new AgentExecutor({ agent, tools, }); const result = await agentExecutor.invoke({ input: "What pets are available and can you show me details of pet with ID 1?", }); console.log(result.output); } ``` ### OpenAI Plugin Follow the instructions in `OPENAI-PLUGIN-README.md` to deploy your OpenAI plugin: 1. Host your API on a public server 2. Copy the `.well-known/ai-plugin.json` to your server 3. Ensure your OpenAPI spec is available at the URL specified in the plugin manifest 4. Register your plugin with OpenAI ### Simulation Mode Simulation mode lets you test AI interaction with your API without requiring setup: ```bash # Set your API key (required for simulation) export OPENAI_API_KEY=your_key_here # Or for Claude export CLAUDE_API_KEY=your_key_here # Run a simulation openapi-to-mcp path/to/swagger.yaml --simulate "find pets with tag 'dog'" --api-url https://pet-api.com ``` This will: 1. Parse your OpenAPI spec 2. Generate necessary handler files 3. Send the request to the LLM with function schemas 4. Execute API call via the executor 5. Return the LLM's final response with data ## State Integration The tool integrates state information into all exports: 1. **MCP JSON**: Includes a complete `stateSchema` section with structure and examples 2. **Prompt Text**: Describes the state structure and provides an example 3. **Function Schemas**: Adds a `getState` function for retrieving the current state 4. **Action Templates**: Includes a `getState` action with empty parameters 5. **Executor**: Includes a `getState()` method for retrieving current state 6. **Handler Files**: Includes a `getState.ts` handler file 7. **LangChain Tools**: Includes a `getState` tool for retrieving current state 8. **OpenAI Plugin**: Includes state description in the plugin manifest ## State Schema Detection The tool automatically searches for suitable GET endpoints to use as state schema sources, with priority given to endpoints with names containing: - state - status - scene - objects - tracks - world You can also manually specify an endpoint using the `--state-endpoint` option. ## Development ### Local Development 1. Clone the repository 2. Install dependencies: ```bash npm install ``` 3. Build all packages: ```bash npm run build ``` 4. Run the core package locally: ```bash npm start --workspace=openapi-to-mcp -- path/to/swagger.yaml ``` 5. Start the playground: ```bash npm run dev --workspace=openapi-to-mcp-playground ``` ### Publishing to npm #### Manual Publishing 1. Log in to npm: ```bash npm login ``` 2. Build and publish: ```bash npm run build npm publish --workspace=openapi-to-mcp --access public ``` #### Automated Publishing via GitHub Actions This project uses GitHub Actions for CI/CD to automatically publish new versions to npm when a new tag is pushed: 1. Update version in package.json: ```bash npm version patch --workspace=openapi-to-mcp # or minor/major ``` This will automatically create a git tag. 2. Push the new tag to GitHub: ```bash git push origin --tags ``` 3. The GitHub Action will trigger and publish the new version to npm. ### Setting up CI/CD for Your Fork If you fork this project, you'll need to set up your own npm publishing: 1. Create an npm account and get an access token from npmjs.com → Access Tokens 2. Add this token to your GitHub repository as a secret named `NPM_TOKEN` 3. Update the package name in package.json to avoid conflicts ## Contributing We welcome contributions from the community! Please read our [contribution guidelines](CONTRIBUTING.md) before submitting a pull request. ## License [ISC](LICENSE) © 2025 [Rustho](https://github.com/rustho). Free to use, modify and distribute.