mcp-openapi-proxy 0.3.2__tar.gz → 0.3.4__tar.gz

{mcp_openapi_proxy-0.3.2 → mcp_openapi_proxy-0.3.4}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: mcp-openapi-proxy
-Version: 0.3.2
+Version: 0.3.4
 Summary: MCP server for exposing OpenAPI specifications as MCP tools.
 Author-email: Matthew Hand <11550632+matthewhand@users.noreply.github.com>
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: mcp[cli]<2,>=1.2.0
 Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: requests>=2.25.0
 Requires-Dist: fastapi>=0.100.0
@@ -170,13 +170,14 @@ 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 | 21 | `get_config` (200) + `call_service` (light.turn_on, 200) | `SERVER_URL_OVERRIDE` + `API_KEY` (`${HA_TOKEN}`, sent as Bearer) |
 
 ### Client matrix
 
 | Agent CLI | Model used (live test) | MCP attach mechanism | Tool calls | Prompts/Resources surfaced to model? |
 |---|---|---|---|---|
 | **opencode** | (CLI default) | `~/.config/opencode/opencode.json` `mcp` | ✅ native | **prompts: ✅ (slash) · resources: ✅** — most complete ‖ |
-| Codex | `gpt-5-codex` (OpenAI API) | `codex exec -c mcp_servers.*` | ✅ native | prompts: ❌ (no prompt meta-tools) · resources: ✅ (`read_mcp_resource`) ‖ |
+| Codex | `gpt-5-codex` (OpenAI API) | `codex exec -c mcp_servers.*` | ✅ native | prompts: ❌ low-level · ✅ fastmcp (via `call_function`→`get_prompt`) · resources: ✅ (`read_mcp_resource`) ‖ |
 | Kilocode | `kilo-auto/free` | global `settings/mcp_settings.json` | ✅ native | prompts: ❌ (no prompt mechanism) · resources: ✅ (`access_mcp_resource`) ‖ |
 | Qwen | `agent` group via local LiteLLM gateway | project `.qwen/settings.json` | ✅ native (live invoke auth-blocked) | prompts: ✅ (slash `/summarize_spec`) · resources: ❌ (no client support) ‖ |
 | Gemini | Google OAuth free tier (CLI default model) | project `.gemini/settings.json` `mcpServers` | ✅ native | prompts: interactive slash only · resources: interactive `@` only (neither reaches the model headless) ‖ |
@@ -188,11 +189,17 @@ The example configurations below were exercised against the live APIs, and the p
 > resources. **mcp-openapi-proxy serves all three, advertised by default since 0.3.0.**
 > Whether they reach the model is up to the *client*, and that varies:
 >
-> - **‖ re-verified 2026-06-14 against the published 0.3.0 release** with **no** flags set
->   (validating the default-on advertising), driving each **real client binary**.
+> - **‖ re-verified 2026-06-15 against the published 0.3.3 release** with **no** flags set
+>   (validating the default-on advertising), driving each **real client binary**, in
+>   **both** server modes (low-level and FastMCP simple). Per-client results were the
+>   same across modes except where noted.
 > - **Tools** work on every client tested. **Prompts→model**: opencode & Qwen (slash
 >   commands); Gemini interactive-only. **Resources→model**: opencode, Codex, Kilocode.
->   **opencode is the only client that surfaces all three.** Vibe is tools-only.
+>   **opencode is the only client that surfaces all three** in any mode.
+> - **FastMCP simple mode exception:** a client with no native prompt surface can still
+>   reach prompts through the static `call_function`→`get_prompt` indirection. Observed
+>   with **Codex** (prompts ❌ in low-level, ✅ in FastMCP simple mode). Vibe stays
+>   tools-only regardless of mode.
 > - **‡ unknown** — Letta can't be exercised without standing up a Letta server + model;
 >   left untested rather than guessed.
 > - Every cell on the proxy side was confirmed via a raw stdio handshake (`initialize`
@@ -935,6 +942,54 @@ 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 generic slice of the [Home Assistant REST API](https://developers.home-assistant.io/docs/api/rest/)
+(21 operations) — read state (`get_config`, `list_states`, `get_state`, `list_services`,
+`get_history`/`get_history_now`, `get_logbook`, `list_calendars`, `get_calendar_events`,
+`get_camera_image`, `get_error_log`, `list_components`, `list_events`, `get_api_status`) and
+act (`call_service`, `set_state`, `delete_state`, `fire_event`, `render_template`,
+`check_config`, `handle_intent`). HA ships no official OpenAPI spec, so this is hand-rolled
+from the official docs.
+
+#### 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",
+                "API_KEY": "${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 `API_KEY`; the proxy sends it as `Authorization: Bearer <token>` (its default scheme), so no `EXTRA_HEADERS` needed. 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.2 → mcp_openapi_proxy-0.3.4}/README.md

@@ -148,13 +148,14 @@ 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 | 21 | `get_config` (200) + `call_service` (light.turn_on, 200) | `SERVER_URL_OVERRIDE` + `API_KEY` (`${HA_TOKEN}`, sent as Bearer) |
 
 ### Client matrix
 
 | Agent CLI | Model used (live test) | MCP attach mechanism | Tool calls | Prompts/Resources surfaced to model? |
 |---|---|---|---|---|
 | **opencode** | (CLI default) | `~/.config/opencode/opencode.json` `mcp` | ✅ native | **prompts: ✅ (slash) · resources: ✅** — most complete ‖ |
-| Codex | `gpt-5-codex` (OpenAI API) | `codex exec -c mcp_servers.*` | ✅ native | prompts: ❌ (no prompt meta-tools) · resources: ✅ (`read_mcp_resource`) ‖ |
+| Codex | `gpt-5-codex` (OpenAI API) | `codex exec -c mcp_servers.*` | ✅ native | prompts: ❌ low-level · ✅ fastmcp (via `call_function`→`get_prompt`) · resources: ✅ (`read_mcp_resource`) ‖ |
 | Kilocode | `kilo-auto/free` | global `settings/mcp_settings.json` | ✅ native | prompts: ❌ (no prompt mechanism) · resources: ✅ (`access_mcp_resource`) ‖ |
 | Qwen | `agent` group via local LiteLLM gateway | project `.qwen/settings.json` | ✅ native (live invoke auth-blocked) | prompts: ✅ (slash `/summarize_spec`) · resources: ❌ (no client support) ‖ |
 | Gemini | Google OAuth free tier (CLI default model) | project `.gemini/settings.json` `mcpServers` | ✅ native | prompts: interactive slash only · resources: interactive `@` only (neither reaches the model headless) ‖ |
@@ -166,11 +167,17 @@ The example configurations below were exercised against the live APIs, and the p
 > resources. **mcp-openapi-proxy serves all three, advertised by default since 0.3.0.**
 > Whether they reach the model is up to the *client*, and that varies:
 >
-> - **‖ re-verified 2026-06-14 against the published 0.3.0 release** with **no** flags set
->   (validating the default-on advertising), driving each **real client binary**.
+> - **‖ re-verified 2026-06-15 against the published 0.3.3 release** with **no** flags set
+>   (validating the default-on advertising), driving each **real client binary**, in
+>   **both** server modes (low-level and FastMCP simple). Per-client results were the
+>   same across modes except where noted.
 > - **Tools** work on every client tested. **Prompts→model**: opencode & Qwen (slash
 >   commands); Gemini interactive-only. **Resources→model**: opencode, Codex, Kilocode.
->   **opencode is the only client that surfaces all three.** Vibe is tools-only.
+>   **opencode is the only client that surfaces all three** in any mode.
+> - **FastMCP simple mode exception:** a client with no native prompt surface can still
+>   reach prompts through the static `call_function`→`get_prompt` indirection. Observed
+>   with **Codex** (prompts ❌ in low-level, ✅ in FastMCP simple mode). Vibe stays
+>   tools-only regardless of mode.
 > - **‡ unknown** — Letta can't be exercised without standing up a Letta server + model;
 >   left untested rather than guessed.
 > - Every cell on the proxy side was confirmed via a raw stdio handshake (`initialize`
@@ -913,6 +920,54 @@ 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 generic slice of the [Home Assistant REST API](https://developers.home-assistant.io/docs/api/rest/)
+(21 operations) — read state (`get_config`, `list_states`, `get_state`, `list_services`,
+`get_history`/`get_history_now`, `get_logbook`, `list_calendars`, `get_calendar_events`,
+`get_camera_image`, `get_error_log`, `list_components`, `list_events`, `get_api_status`) and
+act (`call_service`, `set_state`, `delete_state`, `fire_event`, `render_template`,
+`check_config`, `handle_intent`). HA ships no official OpenAPI spec, so this is hand-rolled
+from the official docs.
+
+#### 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",
+                "API_KEY": "${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 `API_KEY`; the proxy sends it as `Authorization: Bearer <token>` (its default scheme), so no `EXTRA_HEADERS` needed. 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.2 → mcp_openapi_proxy-0.3.4}/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.2 → mcp_openapi_proxy-0.3.4}/mcp_openapi_proxy.egg-info/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: mcp-openapi-proxy
-Version: 0.3.2
+Version: 0.3.4
 Summary: MCP server for exposing OpenAPI specifications as MCP tools.
 Author-email: Matthew Hand <11550632+matthewhand@users.noreply.github.com>
 Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: mcp[cli]>=1.2.0
+Requires-Dist: mcp[cli]<2,>=1.2.0
 Requires-Dist: python-dotenv>=1.0.1
 Requires-Dist: requests>=2.25.0
 Requires-Dist: fastapi>=0.100.0
@@ -170,13 +170,14 @@ 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 | 21 | `get_config` (200) + `call_service` (light.turn_on, 200) | `SERVER_URL_OVERRIDE` + `API_KEY` (`${HA_TOKEN}`, sent as Bearer) |
 
 ### Client matrix
 
 | Agent CLI | Model used (live test) | MCP attach mechanism | Tool calls | Prompts/Resources surfaced to model? |
 |---|---|---|---|---|
 | **opencode** | (CLI default) | `~/.config/opencode/opencode.json` `mcp` | ✅ native | **prompts: ✅ (slash) · resources: ✅** — most complete ‖ |
-| Codex | `gpt-5-codex` (OpenAI API) | `codex exec -c mcp_servers.*` | ✅ native | prompts: ❌ (no prompt meta-tools) · resources: ✅ (`read_mcp_resource`) ‖ |
+| Codex | `gpt-5-codex` (OpenAI API) | `codex exec -c mcp_servers.*` | ✅ native | prompts: ❌ low-level · ✅ fastmcp (via `call_function`→`get_prompt`) · resources: ✅ (`read_mcp_resource`) ‖ |
 | Kilocode | `kilo-auto/free` | global `settings/mcp_settings.json` | ✅ native | prompts: ❌ (no prompt mechanism) · resources: ✅ (`access_mcp_resource`) ‖ |
 | Qwen | `agent` group via local LiteLLM gateway | project `.qwen/settings.json` | ✅ native (live invoke auth-blocked) | prompts: ✅ (slash `/summarize_spec`) · resources: ❌ (no client support) ‖ |
 | Gemini | Google OAuth free tier (CLI default model) | project `.gemini/settings.json` `mcpServers` | ✅ native | prompts: interactive slash only · resources: interactive `@` only (neither reaches the model headless) ‖ |
@@ -188,11 +189,17 @@ The example configurations below were exercised against the live APIs, and the p
 > resources. **mcp-openapi-proxy serves all three, advertised by default since 0.3.0.**
 > Whether they reach the model is up to the *client*, and that varies:
 >
-> - **‖ re-verified 2026-06-14 against the published 0.3.0 release** with **no** flags set
->   (validating the default-on advertising), driving each **real client binary**.
+> - **‖ re-verified 2026-06-15 against the published 0.3.3 release** with **no** flags set
+>   (validating the default-on advertising), driving each **real client binary**, in
+>   **both** server modes (low-level and FastMCP simple). Per-client results were the
+>   same across modes except where noted.
 > - **Tools** work on every client tested. **Prompts→model**: opencode & Qwen (slash
 >   commands); Gemini interactive-only. **Resources→model**: opencode, Codex, Kilocode.
->   **opencode is the only client that surfaces all three.** Vibe is tools-only.
+>   **opencode is the only client that surfaces all three** in any mode.
+> - **FastMCP simple mode exception:** a client with no native prompt surface can still
+>   reach prompts through the static `call_function`→`get_prompt` indirection. Observed
+>   with **Codex** (prompts ❌ in low-level, ✅ in FastMCP simple mode). Vibe stays
+>   tools-only regardless of mode.
 > - **‡ unknown** — Letta can't be exercised without standing up a Letta server + model;
 >   left untested rather than guessed.
 > - Every cell on the proxy side was confirmed via a raw stdio handshake (`initialize`
@@ -935,6 +942,54 @@ 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 generic slice of the [Home Assistant REST API](https://developers.home-assistant.io/docs/api/rest/)
+(21 operations) — read state (`get_config`, `list_states`, `get_state`, `list_services`,
+`get_history`/`get_history_now`, `get_logbook`, `list_calendars`, `get_calendar_events`,
+`get_camera_image`, `get_error_log`, `list_components`, `list_events`, `get_api_status`) and
+act (`call_service`, `set_state`, `delete_state`, `fire_event`, `render_template`,
+`check_config`, `handle_intent`). HA ships no official OpenAPI spec, so this is hand-rolled
+from the official docs.
+
+#### 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",
+                "API_KEY": "${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 `API_KEY`; the proxy sends it as `Authorization: Bearer <token>` (its default scheme), so no `EXTRA_HEADERS` needed. 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.2 → mcp_openapi_proxy-0.3.4}/mcp_openapi_proxy.egg-info/requires.txt

@@ -1,4 +1,4 @@
-mcp[cli]>=1.2.0
+mcp[cli]<2,>=1.2.0
 python-dotenv>=1.0.1
 requests>=2.25.0
 fastapi>=0.100.0

{mcp_openapi_proxy-0.3.2 → mcp_openapi_proxy-0.3.4}/pyproject.toml

@@ -5,14 +5,17 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "mcp-openapi-proxy"
 requires-python = ">=3.10"
-version = "0.3.2"
+version = "0.3.4"
 description = "MCP server for exposing OpenAPI specifications as MCP tools."
 readme = "README.md"
 authors = [
   { name = "Matthew Hand", email = "11550632+matthewhand@users.noreply.github.com" }
 ]
 dependencies = [
-  "mcp[cli]>=1.2.0",
+  # mcp 2.x is a breaking rewrite (FastMCP renamed to MCPServer, Resource.uri type
+  # change, etc.) that crashes both server modes at import. Pin to 1.x; see
+  # tests/unit/test_mcp_version_pin.py before relaxing this bound.
+  "mcp[cli]>=1.2.0,<2",
   "python-dotenv>=1.0.1",
   "requests>=2.25.0",
   "fastapi>=0.100.0", # For OpenAPI parsing utils if used later, and data validation