From bd68adee51cefa98ec93394415fa9f47a05053a6 Mon Sep 17 00:00:00 2001 From: harsha-iiiv Date: Sun, 13 Apr 2025 23:50:50 +0530 Subject: [PATCH] update README --- README.md | 194 +++++++++++++++++++++++++++++------------------------- 1 file changed, 106 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index 7d99ff4..d949ac7 100644 --- a/README.md +++ b/README.md @@ -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 -o [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: ``` / -β”œβ”€β”€ .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 - # 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_` | +| Bearer | `BEARER_TOKEN_` | +| Basic Auth | `BASIC_USERNAME_`, `BASIC_PASSWORD_` | +| OAuth2 | `OAUTH_CLIENT_ID_`, `OAUTH_CLIENT_SECRET_`, `OAUTH_SCOPES_` | -[MIT](https://opensource.org/licenses/MIT) -``` \ No newline at end of file +--- + +## ▢️ 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. \ No newline at end of file