mcp-openapi-proxy 0.3.1__tar.gz → 0.3.3__tar.gz

{mcp_openapi_proxy-0.3.1 → mcp_openapi_proxy-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-openapi-proxy
-Version: 0.3.1
+Version: 0.3.3
 Summary: MCP server for exposing OpenAPI specifications as MCP tools.
 Author-email: Matthew Hand <11550632+matthewhand@users.noreply.github.com>
 Requires-Python: >=3.10
@@ -170,6 +170,7 @@ The example configurations below were exercised against the live APIs, and the p
 | flyio | 34–35 | apps + machine health | `API_KEY` |
 | slack | 7 (exact dot-path whitelist until #27 fix) | `auth.test` + `postMessage` | `API_KEY` |
 | netbox | 9 (whitelist `/ipam/ip-addresses`) | IPAM write + read | `API_KEY` + `API_AUTH_TYPE=Token` |
+| homeassistant | 6 | `get_config` (200) + `call_service` (light.turn_on, 200) | `SERVER_URL_OVERRIDE` + `EXTRA_HEADERS` (`Authorization: Bearer ${HA_TOKEN}`) |
 
 ### Client matrix
 
@@ -935,6 +936,49 @@ Tips: set `IGNORE_SSL_TOOLS=true` only if your host serves a self-signed/mismatc
 
 </details>
 
+<details>
+<summary><b>Home Assistant Example</b> — control your smart home; <code>call_service</code> needs the >= 0.3.3 path-param body fix</summary>
+
+Exposes a small generic slice of the Home Assistant REST API: `get_config`, `list_states`,
+`get_state`, `list_services`, `call_service`, `get_history`.
+
+#### 1. Verify the OpenAPI specification
+
+```bash
+curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json
+```
+
+#### 2. Configure mcp-openapi-proxy for Home Assistant
+
+```json
+{
+    "mcpServers": {
+        "homeassistant": {
+            "command": "uvx",
+            "args": ["mcp-openapi-proxy"],
+            "env": {
+                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json",
+                "SERVER_URL_OVERRIDE": "http://homeassistant.local:8123",
+                "EXTRA_HEADERS": "Authorization: Bearer ${HA_TOKEN}"
+            }
+        }
+    }
+}
+```
+
+Key configuration points:
+- `SERVER_URL_OVERRIDE` — your instance base URL, e.g. `http://homeassistant.local:8123` or `http://<ha-host>:8123`.
+- `HA_TOKEN` — a Home Assistant **long-lived access token** (Profile → Long-Lived Access Tokens), passed via `EXTRA_HEADERS`. Never commit the token; keep it in your environment.
+- `call_service` requires **mcp-openapi-proxy >= 0.3.3**: earlier versions leaked the `{domain}`/`{service}` path params into the JSON body, which Home Assistant rejects with HTTP 400.
+
+#### 3. Testing
+
+`get_config` should return your HA configuration (200). `call_service` for `light/turn_on`
+with body `{"entity_id": "light.kitchen"}` should return 200 — the path params land in the URL
+(`/api/services/light/turn_on`), not the body.
+
+</details>
+
 ## Troubleshooting
 
 ### JSON-RPC Testing

{mcp_openapi_proxy-0.3.1 → mcp_openapi_proxy-0.3.3}/README.md

@@ -148,6 +148,7 @@ The example configurations below were exercised against the live APIs, and the p
 | flyio | 34–35 | apps + machine health | `API_KEY` |
 | slack | 7 (exact dot-path whitelist until #27 fix) | `auth.test` + `postMessage` | `API_KEY` |
 | netbox | 9 (whitelist `/ipam/ip-addresses`) | IPAM write + read | `API_KEY` + `API_AUTH_TYPE=Token` |
+| homeassistant | 6 | `get_config` (200) + `call_service` (light.turn_on, 200) | `SERVER_URL_OVERRIDE` + `EXTRA_HEADERS` (`Authorization: Bearer ${HA_TOKEN}`) |
 
 ### Client matrix
 
@@ -913,6 +914,49 @@ Tips: set `IGNORE_SSL_TOOLS=true` only if your host serves a self-signed/mismatc
 
 </details>
 
+<details>
+<summary><b>Home Assistant Example</b> — control your smart home; <code>call_service</code> needs the >= 0.3.3 path-param body fix</summary>
+
+Exposes a small generic slice of the Home Assistant REST API: `get_config`, `list_states`,
+`get_state`, `list_services`, `call_service`, `get_history`.
+
+#### 1. Verify the OpenAPI specification
+
+```bash
+curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json
+```
+
+#### 2. Configure mcp-openapi-proxy for Home Assistant
+
+```json
+{
+    "mcpServers": {
+        "homeassistant": {
+            "command": "uvx",
+            "args": ["mcp-openapi-proxy"],
+            "env": {
+                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json",
+                "SERVER_URL_OVERRIDE": "http://homeassistant.local:8123",
+                "EXTRA_HEADERS": "Authorization: Bearer ${HA_TOKEN}"
+            }
+        }
+    }
+}
+```
+
+Key configuration points:
+- `SERVER_URL_OVERRIDE` — your instance base URL, e.g. `http://homeassistant.local:8123` or `http://<ha-host>:8123`.
+- `HA_TOKEN` — a Home Assistant **long-lived access token** (Profile → Long-Lived Access Tokens), passed via `EXTRA_HEADERS`. Never commit the token; keep it in your environment.
+- `call_service` requires **mcp-openapi-proxy >= 0.3.3**: earlier versions leaked the `{domain}`/`{service}` path params into the JSON body, which Home Assistant rejects with HTTP 400.
+
+#### 3. Testing
+
+`get_config` should return your HA configuration (200). `call_service` for `light/turn_on`
+with body `{"entity_id": "light.kitchen"}` should return 200 — the path params land in the URL
+(`/api/services/light/turn_on`), not the body.
+
+</details>
+
 ## Troubleshooting
 
 ### JSON-RPC Testing

{mcp_openapi_proxy-0.3.1 → mcp_openapi_proxy-0.3.3}/mcp_openapi_proxy/server_fastmcp.py

@@ -36,6 +36,55 @@ spec = None  # Global spec for resources
 # callable via call_function.
 _FUNCTION_OPERATIONS: Dict[str, Dict] = {}
 
+
+# --- Native MCP prompts & resources for FastMCP/simple mode ---
+# Previously simple mode advertised the prompts/resources capabilities (FastMCP
+# does so automatically) but registered none, so prompts/list & resources/list
+# came back EMPTY. Register them natively here for parity with the low-level
+# server (same names/content): prompts summarize_spec + whimsical_blog, and the
+# spec_file resource.
+
+def _spec_as_json() -> str:
+    """Serialize the OpenAPI spec for the spec_file resource.
+
+    Serves the in-memory spec that run_simple_server preloads once; only
+    fetches as a lazy fallback. This avoids a live network re-fetch on every
+    resources/read, respecting the live-first-once spec lifecycle (#28).
+    Uses default=str so YAML datetime example values don't crash serialization.
+    """
+    global spec
+    if spec is None:
+        spec_url = os.environ.get("OPENAPI_SPEC_URL")
+        if not spec_url:
+            return json.dumps({"error": "OPENAPI_SPEC_URL is not configured"})
+        spec = fetch_openapi_spec(spec_url)
+    if not spec:
+        return json.dumps({"error": "Failed to fetch OpenAPI spec"})
+    if isinstance(spec, str):
+        return spec
+    return json.dumps(spec, indent=2, default=str)
+
+
+@mcp.resource("file:///openapi_spec.json", name="spec_file",
+              description="The raw OpenAPI specification JSON", mime_type="application/json")
+def _spec_file_resource() -> str:
+    """Serve the configured OpenAPI spec as a native MCP resource."""
+    return _spec_as_json()
+
+
+@mcp.prompt(name="summarize_spec", description="Summarizes the OpenAPI specification")
+def _summarize_spec_prompt() -> str:
+    return ("This OpenAPI spec defines endpoints, parameters, and responses—a "
+            "blueprint for developers to integrate effectively.")
+
+
+@mcp.prompt(name="whimsical_blog", description="A whimsical WordPress blog-post starter inspired by this API")
+def _whimsical_blog_prompt() -> str:
+    return ("Once upon a JSON, in a land of tilde keys and sticky semicolons, a pet AI "
+            "chatbot discovered it could whisper to WordPress through a magic OpenAPI proxy. "
+            "✨ Write the next whimsical chapter.")
+
+
 @mcp.tool()
 def list_functions(*, env_key: str = "OPENAPI_SPEC_URL") -> str:
     """Lists available functions derived from the OpenAPI specification."""
@@ -243,7 +292,8 @@ def call_function(*, function_name: str, parameters: Optional[Dict] = None, env_
             spec_local = json.loads(spec_local)
         if spec_local is None:
             return json.dumps({"error": "Failed to fetch OpenAPI spec"})
-        return json.dumps(spec_local, indent=2)
+        # default=str: YAML datetime example values aren't JSON-serializable
+        return json.dumps(spec_local, indent=2, default=str)
     if function_name == "list_prompts":
         return json.dumps([{"name": "summarize_spec", "description": "Summarizes the purpose of the OpenAPI specification", "arguments": []}])
     if function_name == "get_prompt":

{mcp_openapi_proxy-0.3.1 → mcp_openapi_proxy-0.3.3}/mcp_openapi_proxy/server_lowlevel.py

@@ -249,14 +249,19 @@ async def dispatcher_handler(request: types.CallToolRequest) -> types.CallToolRe
         try:
             path = path.format(**parameters)
             logger.debug(f"Substituted path using format(): {path}")
-            if method == "GET":
-                placeholder_keys = [
-                    seg.strip("{}")
-                    for seg in operation_details["original_path"].split("/")
-                    if seg.startswith("{") and seg.endswith("}")
-                ]
-                for key in placeholder_keys:
-                    parameters.pop(key, None)
+            # Path placeholders are now substituted into the URL, so drop them from
+            # `parameters` for ALL methods. Previously this ran only for GET, so on
+            # POST/PUT/PATCH/DELETE the path params leaked into request_body and
+            # strict APIs rejected the unexpected fields -- e.g. Home Assistant
+            # POST /api/services/{domain}/{service} returned HTTP 400 because the
+            # body carried domain/service.
+            placeholder_keys = [
+                seg.strip("{}")
+                for seg in operation_details["original_path"].split("/")
+                if seg.startswith("{") and seg.endswith("}")
+            ]
+            for key in placeholder_keys:
+                parameters.pop(key, None)
         except KeyError as e:
             logger.error(f"Missing parameter for substitution: {e}")
             return types.CallToolResult(

{mcp_openapi_proxy-0.3.1 → mcp_openapi_proxy-0.3.3}/mcp_openapi_proxy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-openapi-proxy
-Version: 0.3.1
+Version: 0.3.3
 Summary: MCP server for exposing OpenAPI specifications as MCP tools.
 Author-email: Matthew Hand <11550632+matthewhand@users.noreply.github.com>
 Requires-Python: >=3.10
@@ -170,6 +170,7 @@ The example configurations below were exercised against the live APIs, and the p
 | flyio | 34–35 | apps + machine health | `API_KEY` |
 | slack | 7 (exact dot-path whitelist until #27 fix) | `auth.test` + `postMessage` | `API_KEY` |
 | netbox | 9 (whitelist `/ipam/ip-addresses`) | IPAM write + read | `API_KEY` + `API_AUTH_TYPE=Token` |
+| homeassistant | 6 | `get_config` (200) + `call_service` (light.turn_on, 200) | `SERVER_URL_OVERRIDE` + `EXTRA_HEADERS` (`Authorization: Bearer ${HA_TOKEN}`) |
 
 ### Client matrix
 
@@ -935,6 +936,49 @@ Tips: set `IGNORE_SSL_TOOLS=true` only if your host serves a self-signed/mismatc
 
 </details>
 
+<details>
+<summary><b>Home Assistant Example</b> — control your smart home; <code>call_service</code> needs the >= 0.3.3 path-param body fix</summary>
+
+Exposes a small generic slice of the Home Assistant REST API: `get_config`, `list_states`,
+`get_state`, `list_services`, `call_service`, `get_history`.
+
+#### 1. Verify the OpenAPI specification
+
+```bash
+curl https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json
+```
+
+#### 2. Configure mcp-openapi-proxy for Home Assistant
+
+```json
+{
+    "mcpServers": {
+        "homeassistant": {
+            "command": "uvx",
+            "args": ["mcp-openapi-proxy"],
+            "env": {
+                "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/refs/heads/main/examples/homeassistant.openapi.json",
+                "SERVER_URL_OVERRIDE": "http://homeassistant.local:8123",
+                "EXTRA_HEADERS": "Authorization: Bearer ${HA_TOKEN}"
+            }
+        }
+    }
+}
+```
+
+Key configuration points:
+- `SERVER_URL_OVERRIDE` — your instance base URL, e.g. `http://homeassistant.local:8123` or `http://<ha-host>:8123`.
+- `HA_TOKEN` — a Home Assistant **long-lived access token** (Profile → Long-Lived Access Tokens), passed via `EXTRA_HEADERS`. Never commit the token; keep it in your environment.
+- `call_service` requires **mcp-openapi-proxy >= 0.3.3**: earlier versions leaked the `{domain}`/`{service}` path params into the JSON body, which Home Assistant rejects with HTTP 400.
+
+#### 3. Testing
+
+`get_config` should return your HA configuration (200). `call_service` for `light/turn_on`
+with body `{"entity_id": "light.kitchen"}` should return 200 — the path params land in the URL
+(`/api/services/light/turn_on`), not the body.
+
+</details>
+
 ## Troubleshooting
 
 ### JSON-RPC Testing

{mcp_openapi_proxy-0.3.1 → mcp_openapi_proxy-0.3.3}/pyproject.toml

@@ -5,7 +5,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "mcp-openapi-proxy"
 requires-python = ">=3.10"
-version = "0.3.1"
+version = "0.3.3"
 description = "MCP server for exposing OpenAPI specifications as MCP tools."
 readme = "README.md"
 authors = [