mcp-openapi-proxy 0.1.1741340797__tar.gz

mcp_openapi_proxy-0.1.1741340797/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 mhand
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_openapi_proxy-0.1.1741340797/PKG-INFO

@@ -0,0 +1,225 @@
+Metadata-Version: 2.2
+Name: mcp-openapi-proxy
+Version: 0.1.1741340797
+Summary: MCP server for exposing OpenAPI specifications as MCP tools.
+Author-email: Matthew Hand <matthewhandau@gmail.com>
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: python-dotenv>=1.0.1
+Requires-Dist: requests>=2.25.0
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: prance>=23.6.21.0
+Requires-Dist: openapi-spec-validator>=0.7.1
+
+# mcp-openapi-proxy
+
+**mcp-openapi-proxy** is a Python package implementing a Model Context Protocol (MCP) server that dynamically exposes REST APIs defined by OpenAPI specifications as MCP tools. This allows you to easily integrate any OpenAPI-described API into MCP-based workflows.
+
+## Overview
+
+The package supports two operation modes:
+
+- **Low-Level Mode (Default):** Dynamically registers tools for all API endpoints defined in an OpenAPI specification eg. /chat/completions becomes chat_completions().
+- **FastMCP Mode (Simple Mode):** Provides a simplified mode for exposing specific pre-configured API endpoints as tools ie. list_functions() and call_functions().
+
+## Features
+
+- **Dynamic Tool Generation:** Automatically creates MCP tools from OpenAPI endpoint definitions.
+- **Simple Mode Option:** Offers a static configuration option with FastMCP mode.
+- **OpenAPI Specification Support:** Works with OpenAPI v3 specifications, and potentially v2.
+- **Flexible Filtering:** Supports filtering endpoints by tags, paths, methods, etc. (if implemented)
+- **MCP Integration:** Integrates seamlessly with MCP ecosystems to invoke REST APIs as tools.
+
+## Installation
+
+### MCP Ecosystem Integration
+
+Add **mcp-openapi-proxy** to your MCP ecosystem by configuring your `mcpServers`. Generic example:
+
+```json
+{
+    "mcpServers": {
+        "mcp-openapi-proxy": {
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/matthewhand/mcp-openapi-proxy",
+                "mcp-openapi-proxy"
+            ],
+            "env": {
+                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
+                "API_AUTH_BEARER": "",
+                "TOOL_WHITELIST": "",
+                "TOOL_NAME_PREFIX": ""
+            }
+        }
+    }
+}
+```
+
+For examples of real world APIs like GetZep, Open-Webui, Netlify, Vercel, etc refer to [examples](./examples).
+
+
+## Modes of Operation
+
+### FastMCP Mode (Simple Mode)
+
+- **Enabled by:** Setting `OPENAPI_SIMPLE_MODE=true`
+- **Description:** Exposes a pre-defined set of tools based on specific OpenAPI endpoints defined in code.
+- **Configuration:** Requires environment variables for tool definitions.
+
+### Low-Level Mode (Default)
+
+- **Description:** Dynamically registers all valid API endpoints from the provided OpenAPI specification as separate tools.
+- **Tool Naming:** Tools are named based on normalized OpenAPI path and method.
+- **Behavior:** Descriptions are generated from the OpenAPI operation summaries and descriptions.
+
+## Environment Variables
+
+- `OPENAPI_SPEC_URL`: URL to the OpenAPI specification JSON file (required).
+- `OPENAPI_LOGFILE_PATH`: (Optional) Path for the log file.
+- `OPENAPI_SIMPLE_MODE`: (Optional) Set to `true` for FastMCP mode.
+- `TOOL_WHITELIST`: (Optional) A prefix filter to select only certain tools.
+- `TOOL_NAME_PREFIX`: (Optional) A string to prepend to all tool names when mapping.
+
+## Examples
+
+### OpenWebUI Example
+
+**1. Confirming the OpenAPI Endpoint**
+
+Run the following command to retrieve the OpenAPI specification:
+ 
+```bash
+curl http://localhost:3000/openapi.json
+```
+ 
+If the output is a valid OpenAPI JSON document, it confirms that the endpoint is working correctly.
+
+**2. Configuring mcp-openapi-proxy**
+
+In your MCP ecosystem configuration file, set the `OPENAPI_SPEC_URL` to the above endpoint. For example:
+ 
+```json
+{
+    "mcpServers": {
+        "mcp-openapi-proxy": {
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/matthewhand/mcp-openapi-proxy",
+                "mcp-openapi-proxy"
+            ],
+            "env": {
+                "OPENAPI_SPEC_URL": "http://localhost:3000/openapi.json",
+                "SERVER_URL_OVERRIDE": "http://localhost:3000/v1",
+                "TOOL_WHITELIST": "/models,/chat/completion",
+                "API_AUTH_BEARER": "your_openwebui_token_here"
+            }
+        }
+    }
+}
+```
+ 
+- **OPENAPI_SPEC_URL**: The URL to the OpenAPI specification.
+- **SERVER_URL_OVERRIDE**: Should the spec not include servers, or you wish to use a different URL.
+- **TOOL_WHITELIST**: A comma-separated list of endpoint paths to expose as tools. In this example, only the `/api/models` and `/api/chat/completions` endpoints are allowed.
+- **API_AUTH_BEARER**: The bearer token for endpoints requiring authentication.  Alternatively use ${OPENWEBUI_API_KEY} if configured as an environment variable or stored securely in a `.env` file.
+
+**3. Resulting Tools**
+
+With this configuration, the MCP server will dynamically generate tools for the whitelisted endpoints. For example:
+
+```json
+[
+    {
+        "name": "api_models",
+        "description": "Fetches available models from /api/models"
+    },
+    {
+        "name": "api_chat_completions",
+        "description": "Generates chat completions via /api/chat/completions"
+    }
+]
+```
+ 
+**4. Visual Verification**
+ 
+You can verify the registration of these tools by inspecting the MCP server logs or using your MCP client.
+
+ 
+## Fly.io Example
+
+**1. Verify the OpenAPI Endpoint**
+
+Run the following command to retrieve the Fly.io OpenAPI JSON specification:
+
+```bash
+curl https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json
+```
+
+Ensure the response is a valid OpenAPI JSON document containing an "openapi" field (e.g., "openapi": "3.0.0") and defined API paths.
+
+**2. Configure mcp-openapi-proxy for Fly.io**
+
+Update your MCP ecosystem configuration to point to the Fly.io endpoint. For example:
+
+```json
+{
+    "mcpServers": {
+        "mcp-openapi-proxy": {
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/matthewhand/mcp-openapi-proxy",
+                "mcp-openapi-proxy"
+            ],
+            "env": {
+                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
+                "SERVER_URL_OVERRIDE": "https://api.machines.dev",
+                "TOOL_WHITELIST": "/machines/list,/machines/start,/machines/status",
+                "API_AUTH_BEARER": "${FLY_API_TOKEN}"
+            }
+        }
+    }
+}
+```
+
+**3. Resulting Tools**
+
+With this configuration, the MCP server will dynamically generate tools for the whitelisted endpoints. For example:
+ 
+```json
+[
+    {
+        "name": "machines_list",
+        "description": "Fetches machine listing from /machines/list"
+    },
+    {
+        "name": "machines_start",
+        "description": "Initiates machine start via /machines/start"
+    },
+    {
+        "name": "machines_status",
+        "description": "Retrieves machine status from /machines/status"
+    }
+]
+```
+
+## Troubleshooting
+
+- **Missing OPENAPI_SPEC_URL:** Verify that the `OPENAPI_SPEC_URL` environment variable is set and points to a valid OpenAPI JSON file.
+- **Invalid OpenAPI Spec:** Ensure the JSON specification complies with the OpenAPI standard.
+- **Filtering Issues:** Check that `TOOL_WHITELIST` is correctly defined to filter the desired classes.
+- **Logging:** Consult the logs (as defined by `MCP_OPENAPI_LOGFILE_PATH`) for debugging information.
+- **Verify `uvx`** Run the server directly from the GitHub repository using `uvx`:
+
+```bash
+uvx --from git+https://github.com/matthewhand/mcp-openapi-proxy mcp-openapi-proxy
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

mcp_openapi_proxy-0.1.1741340797/README.md

@@ -0,0 +1,210 @@
+# mcp-openapi-proxy
+
+**mcp-openapi-proxy** is a Python package implementing a Model Context Protocol (MCP) server that dynamically exposes REST APIs defined by OpenAPI specifications as MCP tools. This allows you to easily integrate any OpenAPI-described API into MCP-based workflows.
+
+## Overview
+
+The package supports two operation modes:
+
+- **Low-Level Mode (Default):** Dynamically registers tools for all API endpoints defined in an OpenAPI specification eg. /chat/completions becomes chat_completions().
+- **FastMCP Mode (Simple Mode):** Provides a simplified mode for exposing specific pre-configured API endpoints as tools ie. list_functions() and call_functions().
+
+## Features
+
+- **Dynamic Tool Generation:** Automatically creates MCP tools from OpenAPI endpoint definitions.
+- **Simple Mode Option:** Offers a static configuration option with FastMCP mode.
+- **OpenAPI Specification Support:** Works with OpenAPI v3 specifications, and potentially v2.
+- **Flexible Filtering:** Supports filtering endpoints by tags, paths, methods, etc. (if implemented)
+- **MCP Integration:** Integrates seamlessly with MCP ecosystems to invoke REST APIs as tools.
+
+## Installation
+
+### MCP Ecosystem Integration
+
+Add **mcp-openapi-proxy** to your MCP ecosystem by configuring your `mcpServers`. Generic example:
+
+```json
+{
+    "mcpServers": {
+        "mcp-openapi-proxy": {
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/matthewhand/mcp-openapi-proxy",
+                "mcp-openapi-proxy"
+            ],
+            "env": {
+                "OPENAPI_SPEC_URL": "${OPENAPI_SPEC_URL}",
+                "API_AUTH_BEARER": "",
+                "TOOL_WHITELIST": "",
+                "TOOL_NAME_PREFIX": ""
+            }
+        }
+    }
+}
+```
+
+For examples of real world APIs like GetZep, Open-Webui, Netlify, Vercel, etc refer to [examples](./examples).
+
+
+## Modes of Operation
+
+### FastMCP Mode (Simple Mode)
+
+- **Enabled by:** Setting `OPENAPI_SIMPLE_MODE=true`
+- **Description:** Exposes a pre-defined set of tools based on specific OpenAPI endpoints defined in code.
+- **Configuration:** Requires environment variables for tool definitions.
+
+### Low-Level Mode (Default)
+
+- **Description:** Dynamically registers all valid API endpoints from the provided OpenAPI specification as separate tools.
+- **Tool Naming:** Tools are named based on normalized OpenAPI path and method.
+- **Behavior:** Descriptions are generated from the OpenAPI operation summaries and descriptions.
+
+## Environment Variables
+
+- `OPENAPI_SPEC_URL`: URL to the OpenAPI specification JSON file (required).
+- `OPENAPI_LOGFILE_PATH`: (Optional) Path for the log file.
+- `OPENAPI_SIMPLE_MODE`: (Optional) Set to `true` for FastMCP mode.
+- `TOOL_WHITELIST`: (Optional) A prefix filter to select only certain tools.
+- `TOOL_NAME_PREFIX`: (Optional) A string to prepend to all tool names when mapping.
+
+## Examples
+
+### OpenWebUI Example
+
+**1. Confirming the OpenAPI Endpoint**
+
+Run the following command to retrieve the OpenAPI specification:
+ 
+```bash
+curl http://localhost:3000/openapi.json
+```
+ 
+If the output is a valid OpenAPI JSON document, it confirms that the endpoint is working correctly.
+
+**2. Configuring mcp-openapi-proxy**
+
+In your MCP ecosystem configuration file, set the `OPENAPI_SPEC_URL` to the above endpoint. For example:
+ 
+```json
+{
+    "mcpServers": {
+        "mcp-openapi-proxy": {
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/matthewhand/mcp-openapi-proxy",
+                "mcp-openapi-proxy"
+            ],
+            "env": {
+                "OPENAPI_SPEC_URL": "http://localhost:3000/openapi.json",
+                "SERVER_URL_OVERRIDE": "http://localhost:3000/v1",
+                "TOOL_WHITELIST": "/models,/chat/completion",
+                "API_AUTH_BEARER": "your_openwebui_token_here"
+            }
+        }
+    }
+}
+```
+ 
+- **OPENAPI_SPEC_URL**: The URL to the OpenAPI specification.
+- **SERVER_URL_OVERRIDE**: Should the spec not include servers, or you wish to use a different URL.
+- **TOOL_WHITELIST**: A comma-separated list of endpoint paths to expose as tools. In this example, only the `/api/models` and `/api/chat/completions` endpoints are allowed.
+- **API_AUTH_BEARER**: The bearer token for endpoints requiring authentication.  Alternatively use ${OPENWEBUI_API_KEY} if configured as an environment variable or stored securely in a `.env` file.
+
+**3. Resulting Tools**
+
+With this configuration, the MCP server will dynamically generate tools for the whitelisted endpoints. For example:
+
+```json
+[
+    {
+        "name": "api_models",
+        "description": "Fetches available models from /api/models"
+    },
+    {
+        "name": "api_chat_completions",
+        "description": "Generates chat completions via /api/chat/completions"
+    }
+]
+```
+ 
+**4. Visual Verification**
+ 
+You can verify the registration of these tools by inspecting the MCP server logs or using your MCP client.
+
+ 
+## Fly.io Example
+
+**1. Verify the OpenAPI Endpoint**
+
+Run the following command to retrieve the Fly.io OpenAPI JSON specification:
+
+```bash
+curl https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json
+```
+
+Ensure the response is a valid OpenAPI JSON document containing an "openapi" field (e.g., "openapi": "3.0.0") and defined API paths.
+
+**2. Configure mcp-openapi-proxy for Fly.io**
+
+Update your MCP ecosystem configuration to point to the Fly.io endpoint. For example:
+
+```json
+{
+    "mcpServers": {
+        "mcp-openapi-proxy": {
+            "command": "uvx",
+            "args": [
+                "--from",
+                "git+https://github.com/matthewhand/mcp-openapi-proxy",
+                "mcp-openapi-proxy"
+            ],
+            "env": {
+                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/abhiaagarwal/peristera/refs/heads/main/fly-machines-gen/fixed_spec.json",
+                "SERVER_URL_OVERRIDE": "https://api.machines.dev",
+                "TOOL_WHITELIST": "/machines/list,/machines/start,/machines/status",
+                "API_AUTH_BEARER": "${FLY_API_TOKEN}"
+            }
+        }
+    }
+}
+```
+
+**3. Resulting Tools**
+
+With this configuration, the MCP server will dynamically generate tools for the whitelisted endpoints. For example:
+ 
+```json
+[
+    {
+        "name": "machines_list",
+        "description": "Fetches machine listing from /machines/list"
+    },
+    {
+        "name": "machines_start",
+        "description": "Initiates machine start via /machines/start"
+    },
+    {
+        "name": "machines_status",
+        "description": "Retrieves machine status from /machines/status"
+    }
+]
+```
+
+## Troubleshooting
+
+- **Missing OPENAPI_SPEC_URL:** Verify that the `OPENAPI_SPEC_URL` environment variable is set and points to a valid OpenAPI JSON file.
+- **Invalid OpenAPI Spec:** Ensure the JSON specification complies with the OpenAPI standard.
+- **Filtering Issues:** Check that `TOOL_WHITELIST` is correctly defined to filter the desired classes.
+- **Logging:** Consult the logs (as defined by `MCP_OPENAPI_LOGFILE_PATH`) for debugging information.
+- **Verify `uvx`** Run the server directly from the GitHub repository using `uvx`:
+
+```bash
+uvx --from git+https://github.com/matthewhand/mcp-openapi-proxy mcp-openapi-proxy
+```
+
+## License
+
+This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.

mcp_openapi_proxy-0.1.1741340797/mcp_openapi_proxy/__main__.py

@@ -0,0 +1,53 @@
+"""
+Entry point for the mcp_openapi_proxy package.
+
+This script determines which server to run based on the presence of
+the OPENAPI_SIMPLE_MODE environment variable:
+- Low-Level Server: For dynamic tool creation from OpenAPI spec.
+- FastMCP Server: For static tool configurations defined in code.
+"""
+ 
+import os
+import sys
+from dotenv import load_dotenv
+from mcp_openapi_proxy.utils import setup_logging
+ 
+# Load environment variables from .env if present
+load_dotenv()
+
+def main():
+    """
+    Main entry point for the mcp_openapi_proxy package.
+
+    Depending on the OPENAPI_SIMPLE_MODE environment variable, this function
+    launches either:
+    - Low-Level Server (dynamic tools from OpenAPI spec)
+    - FastMCP Server (static tools defined in server_fastmcp.py)
+    """
+    # Configure logging
+    DEBUG = os.getenv("DEBUG", "").lower() in ("true", "1", "yes")
+    logger = setup_logging(debug=DEBUG)
+
+    logger.debug("Starting mcp_openapi_proxy package entry point.")
+
+    # Default to Low-Level Mode unless SIMPLE_MODE is explicitly enabled
+    OPENAPI_SIMPLE_MODE = os.getenv("OPENAPI_SIMPLE_MODE", "false").lower() in ("true", "1", "yes") # Default to false, enable with "true" etc.
+    if OPENAPI_SIMPLE_MODE:
+        logger.debug("OPENAPI_SIMPLE_MODE is enabled. Launching FastMCP Server.")
+        from mcp_openapi_proxy.server_fastmcp import run_simple_server
+        selected_server = run_simple_server
+    else:
+        logger.debug("OPENAPI_SIMPLE_MODE is disabled. Launching Low-Level Server.")
+        from mcp_openapi_proxy.server_lowlevel import run_server
+        selected_server = run_server
+
+    # Run the selected server
+    try:
+        selected_server()
+    except Exception as e:
+        logger.critical("Unhandled exception occurred while running the server.", exc_info=True)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()