neoris/openapi-mcp-generator
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

update README

Browse Source
This commit is contained in:
harsha-iiiv 2025-04-13 23:50:50 +05:30
parent f68f8c2c64
commit bd68adee51
1 changed files with 106 additions and 88 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

192
README.md
View File

@ -4,126 +4,144 @@
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub repository](https://img.shields.io/badge/GitHub-harsha--iiiv/openapi--mcp--generator-blue.svg)](https://github.com/harsha-iiiv/openapi-mcp-generator)
A command-line tool that generates a complete, buildable Model Context Protocol (MCP) server project in TypeScript from an OpenAPI specification. This tool helps you quickly create an MCP server using **stdio transport** that acts as a bridge between LLMs (Large Language Models) and your API.
Generate [Model Context Protocol (MCP)](https://modelcontextprotocol.github.io/) servers from OpenAPI specifications.
## Features
This CLI tool automates the generation of MCP-compatible servers that proxy requests to existing REST APIs—enabling AI agents and other MCP clients to seamlessly interact with your APIs using either standard input/output or HTTP-based transport.
- **Automatic Tool Generation**: Converts each API operation in your OpenAPI spec into an MCP tool within the generated server.
- **Complete Project Setup**: Generates a full Node.js project structure (`package.json`, `tsconfig.json`, `src/index.ts`, `.gitignore`).
- **TypeScript & Build Ready**: Creates a TypeScript project configured for building into JavaScript for execution.
- **Stdio Transport**: Generated server uses standard input/output for communication with the MCP client (e.g., an LLM).
- **Runtime Argument Validation**: Integrates Zod for validating tool arguments at runtime based on the OpenAPI schema.
---
## Installation
## ✨ Features
- 🔧 **OpenAPI 3.0 Support**: Converts any OpenAPI 3.0+ spec into an MCP-compatible server.
- 🔁 **Proxy Behavior**: Proxies calls to your original REST API while validating request structure and security.
- 🔐 **Authentication Support**: API keys, Bearer tokens, Basic auth, and OAuth2 supported via environment variables.
- 🧪 **Zod Validation**: Automatically generates Zod schemas from OpenAPI definitions for runtime input validation.
- ⚙️ **Typed Server**: Fully typed, maintainable TypeScript code output.
- 💬 **Stdio & Web Transport**: Communicate over stdio or HTTP (beta, SSE support).
- 🧰 **Project Scaffold**: Generates a complete Node.js project with `tsconfig.json`, `package.json`, and entry point.
- 🧪 **Built-in HTML Test Client** *(Web mode)*: Test API interactions visually in your browser.
---
## 🚀 Installation
```bash
# Install globally from npm
npm install -g openapi-mcp-generator
# Or with yarn
yarn global add openapi-mcp-generator
# Or with pnpm
pnpm add -g openapi-mcp-generator
```
## Usage
> You can also use `yarn global add openapi-mcp-generator` or `pnpm add -g openapi-mcp-generator`
Generate an MCP server project from an OpenAPI specification:
---
## 🛠 Usage
```bash
openapi-mcp-generator -i <path_or_url_to_openapi> -o <output_directory_path> [options]
# Generate an MCP server (stdio)
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir
# Generate an MCP web server (beta)
openapi-mcp-generator --input path/to/openapi.json --output path/to/output/dir --transport=web --port=3000
```
### Command Line Options
### CLI Options
| Option | Alias | Description | Default |
| :--------------- | :---- | :-------------------------------------------------------------------------------------------------- | :------------------------------------------- |
| `--input` | `-i` | Path or URL to the OpenAPI specification file (JSON or YAML). | **(Required)** |
| `--output` | `-o` | Path to the directory where the MCP server project will be created. | **(Required)** |
| `--name` | `-n` | Name for the generated MCP server package (`package.json`). | Derived from OpenAPI title or `my-mcp-server` |
| `--version` | `-v` | Version for the generated MCP server package (`package.json`). | Derived from OpenAPI version or `0.1.0` |
| `--base-url` | `-b` | Base URL for the target API. Required if not in OpenAPI `servers` or if multiple servers specified. | Derived from OpenAPI `servers` if possible |
| `--help` | `-h` | Show help information. | |
| Option | Alias | Description | Default |
|--------------------|-------|-----------------------------------------------------------------------------------------------------|---------------------------------|
| `--input` | `-i` | Path or URL to OpenAPI specification (YAML or JSON) | **Required** |
| `--output` | `-o` | Directory to output the generated MCP project | **Required** |
| `--server-name` | `-n` | Name of the MCP server (`package.json:name`) | OpenAPI title or `mcp-api-server` |
| `--server-version` | `-v` | Version of the MCP server (`package.json:version`) | OpenAPI version or `1.0.0` |
| `--base-url` | `-b` | Base URL for API requests. Required if OpenAPI `servers` missing or ambiguous. | Auto-detected if possible |
| `--transport` | `-t` | Transport mode: `"stdio"` (default) or `"web"` (beta) | `"stdio"` |
| `--port` | `-p` | Port for web server mode | `3000` |
| `--force` | | Overwrite existing files in the output directory without confirmation | `false` |
---
### Examples
## 🧱 Project Structure
**Generate from a local OpenAPI file:**
```bash
openapi-mcp-generator -i ./specs/my-api.yaml -o ./my-api-mcp-server
```
**Generate from a remote OpenAPI URL, specifying name and base URL:**
```bash
openapi-mcp-generator \
-i https://petstore3.swagger.io/api/v3/openapi.json \
-o ./petstore-mcp \
-n petstore-server \
-b https://petstore3.swagger.io/api/v3
```
## Generated Project Structure
The tool generates the following structure in the specified output directory:
The generated project includes:
```
<output_directory>/
├── .gitignore # Standard Node.js gitignore
├── package.json # Dependencies and scripts for the generated server
├── tsconfig.json # TypeScript configuration for building
├── .gitignore
├── package.json
├── tsconfig.json
└── src/
└── index.ts # The generated MCP server source code
└── index.ts
```
## Using the Generated Server
- Uses `axios`, `zod`, `@modelcontextprotocol/sdk`, and `json-schema-to-zod`
- Secure API key/tokens via environment variables
- Tool generation for each endpoint
After generating your MCP server project:
---
1. **Navigate to the generated directory:**
```bash
cd <output_directory>
# e.g., cd ./petstore-mcp
```
## 📡 Transport Modes
2. **Install dependencies:**
```bash
npm install
```
This installs `@modelcontextprotocol/sdk`, `axios`, `zod`, `json-schema-to-zod`, and `typescript`.
### Stdio (Default)
3. **(Optional) Implement Authentication/Configuration:**
* The generator sets the `API_BASE_URL` constant in `src/index.ts` if provided or derived.
* You will need to **manually edit `src/index.ts`** to add any necessary API authentication (e.g., setting `Authorization` headers in the `AxiosRequestConfig` using environment variables or other secure methods). Look for the `// Add Authentication logic here if needed` comment within the `CallTool` handler.
Communicates with MCP clients via standard input/output. Ideal for local development or integration with LLM tools.
4. **Build the server code:**
```bash
npm run build
```
This compiles the TypeScript code from `src/` into JavaScript in the `build/` directory.
### Web Server Mode (Beta)
5. **Start the server:**
```bash
npm start
```
This runs the compiled JavaScript server (`node build/index.js`), which will listen for MCP requests on standard input/output.
Launches a fully functional HTTP server with:
## Requirements
- Server-Sent Events (SSE) for bidirectional messaging
- REST endpoint for client → server communication
- In-browser test client UI
- Multi-connection support
- Node.js v18.0.0 or higher (for both the generator and the generated server)
> ⚠️ **Note**: Web mode is experimental and may have breaking changes in future updates.
## Contributing
---
Contributions are welcome! Please feel free to submit a Pull Request to the [GitHub repository](https://github.com/harsha-iiiv/openapi-mcp-generator).
## 🔐 Environment Variables for Authentication
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
Configure auth credentials in your environment:
## License
| Auth Type | Variable Format |
|-------------|----------------------------------------------------------|
| API Key | `API_KEY_<SCHEME_NAME>` |
| Bearer | `BEARER_TOKEN_<SCHEME_NAME>` |
| Basic Auth | `BASIC_USERNAME_<SCHEME_NAME>`, `BASIC_PASSWORD_<SCHEME_NAME>` |
| OAuth2 | `OAUTH_CLIENT_ID_<SCHEME_NAME>`, `OAUTH_CLIENT_SECRET_<SCHEME_NAME>`, `OAUTH_SCOPES_<SCHEME_NAME>` |
[MIT](https://opensource.org/licenses/MIT)
---
## ▶️ Running the Generated Server
```bash
cd path/to/output/dir
npm install
# Run in stdio mode
npm start
# Run in web server mode (if generated with --transport=web)
npm run start:web
```
---
## ⚠️ Requirements
- Node.js v18 or later
---
## 🤝 Contributing
Contributions are welcome!
1. Fork the repo
2. Create a feature branch: `git checkout -b feature/amazing-feature`
3. Commit your changes: `git commit -m "Add amazing feature"`
4. Push and open a PR
📌 Repository: [github.com/harsha-iiiv/openapi-mcp-generator](https://github.com/harsha-iiiv/openapi-mcp-generator)
---
## 📄 License
MIT License — see [LICENSE](./LICENSE) for full details.