MCP OpenAPI Template

# MCP OpenAPI Template A template for building MCP (Model Context Protocol) servers from OpenAPI specifications. This template provides a production-ready foundation for creating MCP servers that expose any REST API with an OpenAPI specification to LLM-powered tools. ## Features - **Dynamic Tool Generation**: Automatically creates MCP tools from OpenAPI specs - **Auth Gateway Integration**: Centralized authentication via Auth Gateway - **Dual Transport**: Supports both `stdio` (local) and `sse` (remote) transports - **Configurable Validation**: Customizable ID patterns and input validation - **Tool Policies**: Risk-based policies for blocking/logging operations - **Docker Ready**: Production-ready Dockerfile and docker-compose ## Quick Start ### 1. Clone/Use Template ```bash # Using GitHub template feature (recommended) # Click "Use this template" on GitHub # Or clone directly git clone https://github.com/jesusperezdeveloper/mcp_openapi_template my-api-mcp cd my-api-mcp ``` ### 2. Initialize Your Service ```bash python -m scripts.init_service \ --name "github" \ --display-name "GitHub" \ --base-url "https://api.github.com" \ --openapi-url "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.json" ``` ### 3. Configure Auth Gateway Edit `.env` with your Auth Gateway credentials: ```env AUTH_GATEWAY_URL=https://your-auth-gateway.com AUTH_GATEWAY_API_KEY=your-api-key ``` ### 4. Download OpenAPI Spec ```bash python -m scripts.fetch_openapi ``` ### 5. Run the Server ```bash # Local mode (stdio) PYTHONPATH=vendor python -m src.server # Remote mode (SSE) MCP_TRANSPORT=sse PYTHONPATH=vendor python -m src.server ``` ## Project Structure ``` mcp_openapi_template/ ├── src/ │ ├── server.py # Main MCP server │ ├── config.py # Configuration loader │ ├── openapi_tools.py # Dynamic tool generator │ ├── auth_gateway.py # Auth Gateway integration │ ├── validation.py # Input validation │ └── tool_policies.py # Risk policies ├── config/ │ ├── service.yaml # Service configuration │ ├── mcp.local.json # Local MCP config │ └── mcp.remote.json # Remote MCP config ├── scripts/ │ ├── fetch_openapi.py # Download OpenAPI spec │ └── init_service.py # Initialize new service ├── examples/ │ └── trello/ # Complete Trello example ├── openapi/ # OpenAPI specs (downloaded) ├── vendor/mcp/ # Vendorized MCP SDK ├── Dockerfile └── docker-compose.yml ``` ## Configuration ### service.yaml The main configuration file (`config/service.yaml`) defines: ```yaml service: name: "myservice" display_name: "My Service" api: base_url: "https://api.example.com" openapi_spec_url: "https://api.example.com/openapi.json" tool_prefix: "myservice" auth: gateway_endpoint: "/credentials/myservice" credentials_format: - name: "api_key" query_param: "key" validation: id_pattern: "^[a-zA-Z0-9]+$" policies: blocked_patterns: - "delete_organization" ``` ### Environment Variables | Variable | Required | Description | |----------|----------|-------------| | `AUTH_GATEWAY_URL` | Yes | Auth Gateway URL | | `AUTH_GATEWAY_API_KEY` | Yes | API Key for Auth Gateway | | `API_BASE_URL` | No | Override API base URL | | `MCP_TRANSPORT` | No | `stdio` (default) or `sse` | | `MCP_PORT` | No | Port for SSE mode (default: 8000) | ## Authentication Flow 1. User obtains JWT from Auth Gateway (login) 2. User calls `set_auth_token(jwt)` in the MCP 3. MCP fetches API credentials from Auth Gateway 4. Credentials are cached for the session 5. User can now use all available tools ## Adding Custom Helper Tools See `examples/trello/helpers.py` for a complete example of adding user-friendly wrapper tools. ```python # In src/helpers.py def register_helper_tools(mcp, auth_params, client_factory, require_auth): @mcp.tool(description="My custom tool") async def my_tool(param: str) -> dict: require_auth() # Implementation pass ``` ## Docker Deployment ```bash # Build with OpenAPI spec docker build \ --build-arg OPENAPI_SPEC_URL="https://api.example.com/openapi.json" \ -t my-mcp . # Run docker run -p 8000:8000 --env-file .env my-mcp ``` ## Examples See the `examples/` directory for complete configurations: - **Trello**: Full configuration with helper tools, validation, and policies ## License MIT ## Contributing Contributions are welcome! Please feel free to submit a Pull Request.