mcp-openapi-proxy 0.2.0__tar.gz → 0.2.1__tar.gz

{mcp_openapi_proxy-0.2.0 → mcp_openapi_proxy-0.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-openapi-proxy
-Version: 0.2.0
+Version: 0.2.1
 Summary: MCP server for exposing OpenAPI specifications as MCP tools.
 Author-email: Matthew Hand <11550632+matthewhand@users.noreply.github.com>
 Requires-Python: >=3.10
@@ -31,10 +31,11 @@ Dynamic: license-file
 - ✅ **Codex**, **Gemini**, **Qwen**, **Kilocode**, **opencode** — native tool calls over stdio
 - ✅ **Vibe** — native discovery and read calls (writes were CLI-flaky, not a proxy issue)
 - ✅ **Letta** — Cloud (via a remote streamable-HTTP MCP URL) and self-hosted (via stdio)
-- ⚠️ **agy** — could not attach in headless mode; MCP tool enablement is interactive-only in agy (an agy limitation, not the proxy)
 
 See the [client matrix](#client-matrix) for attach mechanisms, models, and exact results.
 
+> 📄 Full write-up: [**Verification case study**](docs/verification-case-study.md) — what the proxy is, the API + client matrices, and every defect found & fixed.
+
 **Prompts and resources are real now — including custom resources.** Both MCP surfaces are functional and tested: the `summarize_spec` / `whimsical_blog` prompts and the `spec_file` resource, plus a new `ADDITIONAL_RESOURCES` env var that serves your *own* use-case documents (e.g. a NetBox naming policy or an Asana project-layout guide) as MCP resources — see `examples/resources/`.
 
 **Bug fixes (every one live-verified):**
@@ -63,7 +64,7 @@ Full environment-variable reference is in [Environment Variables](#environment-v
 - [Environment Variables](#environment-variables)
 - [Verified Clients & Live Results (2026-06-12)](#verified-clients--live-results-2026-06-12)
   - [Tips](#tips)
-- [Examples](#examples) — Glama, Fly.io, Render, Slack, GetZep, Virustotal, Notion, Asana, APIs.guru, NetBox, Box, WolframAlpha (collapsed)
+- [Examples](#examples) — Glama, Fly.io, Render, Slack, GetZep, Virustotal, Notion, Asana, APIs.guru, NetBox, Box, WolframAlpha, WordPress (collapsed)
 - [Troubleshooting](#troubleshooting)
 - [License](#license)
 
@@ -868,6 +869,55 @@ You can now use the MCP ecosystem to list and invoke WolframAlpha API tools. For
 
 </details>
 
+<details>
+<summary><b>Letta (self-hosted + Cloud)</b> — agent platform; stdio for self-hosted, authenticated remote HTTP for Cloud</summary>
+
+Letta runs agents on a server, so attachment differs by deployment:
+
+- **Self-hosted Letta** accepts a **stdio** MCP server via `PUT /v1/tools/mcp/servers` — no network exposure.
+- **Letta Cloud** rejects stdio and needs a **remote streamable-HTTP** MCP URL behind authentication.
+
+Both were verified live (an agent autonomously called `get_v1_attributes` from the Glama spec through the proxy). Full setup for both paths, including the supergateway wrapper and the security note for the Cloud endpoint, is in [`examples/letta/README.md`](examples/letta/README.md).
+
+</details>
+
+<details>
+<summary><b>WordPress Example</b> — publish to a real WordPress blog from any MCP agent</summary>
+
+This example turns the WordPress REST API into MCP tools so an agent can **create, read, update, and trash blog posts**. It is the example behind a real-world demonstration: a fleet of agent CLIs published to the live blog at **[matthewhand.mywebcommunity.org](https://matthewhand.mywebcommunity.org/)** through this proxy — see the write-up [*“Turning Any API into Agent Tools”*](https://matthewhand.mywebcommunity.org/2026/06/12/turning-any-api-into-agent-tools-a-real-world-test-of-mcp-openapi-proxy/), itself posted via the proxy.
+
+Example config — `examples/wordpress-claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "uvx",
+      "args": ["mcp-openapi-proxy"],
+      "env": {
+        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/main/examples/wordpress-openapi.json",
+        "SERVER_URL_OVERRIDE": "https://your-site.example.com/wp-json",
+        "EXTRA_HEADERS": "Authorization: Basic BASE64_OF_USERNAME_COLON_APPLICATION_PASSWORD",
+        "IGNORE_SSL_TOOLS": "false",
+        "TOOL_WHITELIST": "/wp/v2/posts"
+      }
+    }
+  }
+}
+```
+
+Exposed tools (from the bundled `examples/wordpress-openapi.json`): `get_wp_v2_posts`, `post_wp_v2_posts` (create), `get_wp_v2_posts_by_id`, `post_wp_v2_posts_by_id` (update), and `delete_wp_v2_posts_by_id` (trash) — the full post lifecycle.
+
+**Auth — use a WordPress *Application Password*, not your login password.** WordPress REST rejects login passwords for Basic auth. In `wp-admin → Users → (your user) → Application Passwords`, create one, then base64-encode `username:application-password` for the `EXTRA_HEADERS` value:
+
+```bash
+printf 'myuser:xxxx xxxx xxxx xxxx xxxx xxxx' | base64 -w0
+```
+
+Tips: set `IGNORE_SSL_TOOLS=true` only if your host serves a self-signed/mismatched cert; give each agent its own (revocable) application password; keep `TOOL_WHITELIST=/wp/v2/posts` so the agent can touch only posts.
+
+</details>
+
 ## Troubleshooting
 
 ### JSON-RPC Testing

{mcp_openapi_proxy-0.2.0 → mcp_openapi_proxy-0.2.1}/README.md

@@ -9,10 +9,11 @@
 - ✅ **Codex**, **Gemini**, **Qwen**, **Kilocode**, **opencode** — native tool calls over stdio
 - ✅ **Vibe** — native discovery and read calls (writes were CLI-flaky, not a proxy issue)
 - ✅ **Letta** — Cloud (via a remote streamable-HTTP MCP URL) and self-hosted (via stdio)
-- ⚠️ **agy** — could not attach in headless mode; MCP tool enablement is interactive-only in agy (an agy limitation, not the proxy)
 
 See the [client matrix](#client-matrix) for attach mechanisms, models, and exact results.
 
+> 📄 Full write-up: [**Verification case study**](docs/verification-case-study.md) — what the proxy is, the API + client matrices, and every defect found & fixed.
+
 **Prompts and resources are real now — including custom resources.** Both MCP surfaces are functional and tested: the `summarize_spec` / `whimsical_blog` prompts and the `spec_file` resource, plus a new `ADDITIONAL_RESOURCES` env var that serves your *own* use-case documents (e.g. a NetBox naming policy or an Asana project-layout guide) as MCP resources — see `examples/resources/`.
 
 **Bug fixes (every one live-verified):**
@@ -41,7 +42,7 @@ Full environment-variable reference is in [Environment Variables](#environment-v
 - [Environment Variables](#environment-variables)
 - [Verified Clients & Live Results (2026-06-12)](#verified-clients--live-results-2026-06-12)
   - [Tips](#tips)
-- [Examples](#examples) — Glama, Fly.io, Render, Slack, GetZep, Virustotal, Notion, Asana, APIs.guru, NetBox, Box, WolframAlpha (collapsed)
+- [Examples](#examples) — Glama, Fly.io, Render, Slack, GetZep, Virustotal, Notion, Asana, APIs.guru, NetBox, Box, WolframAlpha, WordPress (collapsed)
 - [Troubleshooting](#troubleshooting)
 - [License](#license)
 
@@ -846,6 +847,55 @@ You can now use the MCP ecosystem to list and invoke WolframAlpha API tools. For
 
 </details>
 
+<details>
+<summary><b>Letta (self-hosted + Cloud)</b> — agent platform; stdio for self-hosted, authenticated remote HTTP for Cloud</summary>
+
+Letta runs agents on a server, so attachment differs by deployment:
+
+- **Self-hosted Letta** accepts a **stdio** MCP server via `PUT /v1/tools/mcp/servers` — no network exposure.
+- **Letta Cloud** rejects stdio and needs a **remote streamable-HTTP** MCP URL behind authentication.
+
+Both were verified live (an agent autonomously called `get_v1_attributes` from the Glama spec through the proxy). Full setup for both paths, including the supergateway wrapper and the security note for the Cloud endpoint, is in [`examples/letta/README.md`](examples/letta/README.md).
+
+</details>
+
+<details>
+<summary><b>WordPress Example</b> — publish to a real WordPress blog from any MCP agent</summary>
+
+This example turns the WordPress REST API into MCP tools so an agent can **create, read, update, and trash blog posts**. It is the example behind a real-world demonstration: a fleet of agent CLIs published to the live blog at **[matthewhand.mywebcommunity.org](https://matthewhand.mywebcommunity.org/)** through this proxy — see the write-up [*“Turning Any API into Agent Tools”*](https://matthewhand.mywebcommunity.org/2026/06/12/turning-any-api-into-agent-tools-a-real-world-test-of-mcp-openapi-proxy/), itself posted via the proxy.
+
+Example config — `examples/wordpress-claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "uvx",
+      "args": ["mcp-openapi-proxy"],
+      "env": {
+        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/main/examples/wordpress-openapi.json",
+        "SERVER_URL_OVERRIDE": "https://your-site.example.com/wp-json",
+        "EXTRA_HEADERS": "Authorization: Basic BASE64_OF_USERNAME_COLON_APPLICATION_PASSWORD",
+        "IGNORE_SSL_TOOLS": "false",
+        "TOOL_WHITELIST": "/wp/v2/posts"
+      }
+    }
+  }
+}
+```
+
+Exposed tools (from the bundled `examples/wordpress-openapi.json`): `get_wp_v2_posts`, `post_wp_v2_posts` (create), `get_wp_v2_posts_by_id`, `post_wp_v2_posts_by_id` (update), and `delete_wp_v2_posts_by_id` (trash) — the full post lifecycle.
+
+**Auth — use a WordPress *Application Password*, not your login password.** WordPress REST rejects login passwords for Basic auth. In `wp-admin → Users → (your user) → Application Passwords`, create one, then base64-encode `username:application-password` for the `EXTRA_HEADERS` value:
+
+```bash
+printf 'myuser:xxxx xxxx xxxx xxxx xxxx xxxx' | base64 -w0
+```
+
+Tips: set `IGNORE_SSL_TOOLS=true` only if your host serves a self-signed/mismatched cert; give each agent its own (revocable) application password; keep `TOOL_WHITELIST=/wp/v2/posts` so the agent can touch only posts.
+
+</details>
+
 ## Troubleshooting
 
 ### JSON-RPC Testing

{mcp_openapi_proxy-0.2.0 → mcp_openapi_proxy-0.2.1}/mcp_openapi_proxy/server_lowlevel.py

@@ -408,7 +408,7 @@ async def read_resource(request: types.ReadResourceRequest) -> types.ReadResourc
                 ]
             )
         logger.debug("Dumping spec to JSON...")
-        spec_json = json.dumps(spec_data, indent=2)
+        spec_json = json.dumps(spec_data, indent=2, default=str)
         logger.debug(f"Forcing spec JSON return: {spec_json[:50]}...")
         return types.ReadResourceResult(
             contents=[

{mcp_openapi_proxy-0.2.0 → mcp_openapi_proxy-0.2.1}/mcp_openapi_proxy/utils.py

@@ -14,6 +14,28 @@ from mcp import types
 # Import the configured logger
 from .logging_setup import logger
 
+
+class _NoTimestampSafeLoader(yaml.SafeLoader):
+    """SafeLoader that keeps unquoted RFC3339 timestamps as plain strings.
+
+    PyYAML's SafeLoader auto-converts values like ``2015-02-22T20:00:45.000Z``
+    into Python ``datetime`` objects. Such objects are not JSON-serializable,
+    which crashed spec caching and ``resources/read`` for specs that carry
+    datetime example values (e.g. the apis.guru directory spec). Loading specs
+    with this loader keeps every scalar JSON-safe.
+    """
+
+
+_NoTimestampSafeLoader.yaml_implicit_resolvers = {
+    key: [(tag, regexp) for tag, regexp in resolvers if tag != "tag:yaml.org,2002:timestamp"]
+    for key, resolvers in yaml.SafeLoader.yaml_implicit_resolvers.items()
+}
+
+
+def yaml_load_safe(content: str):
+    """Parse YAML with timestamps preserved as strings (JSON-safe)."""
+    return yaml.load(content, Loader=_NoTimestampSafeLoader)
+
 def setup_logging(debug: bool = False):
     """
     Configure logging for the application.
@@ -196,7 +218,7 @@ def _spec_cache_store(url: str, spec: Dict) -> None:
     try:
         path = _spec_cache_path(url)
         with open(path + ".tmp", "w") as f:
-            json.dump(spec, f)
+            json.dump(spec, f, default=str)
         os.replace(path + ".tmp", path)
         logger.debug(f"Cached spec for {url} at {path}")
     except OSError as exc:
@@ -226,7 +248,7 @@ def fetch_openapi_spec(url: str, retries: int = 3) -> Optional[Dict]:
                 logger.debug(f"Using {spec_format.upper()} parser based on OPENAPI_SPEC_FORMAT env var")
                 if spec_format == "yaml":
                     try:
-                        spec = yaml.safe_load(content)
+                        spec = yaml_load_safe(content)
                         logger.debug(f"Parsed as YAML from {url}")
                     except yaml.YAMLError as ye:
                         logger.error(f"YAML parsing failed: {ye}. Raw content: {content[:500]}...")
@@ -252,7 +274,7 @@ def fetch_openapi_spec(url: str, retries: int = 3) -> Optional[Dict]:
                     logger.debug(f"Parsed as JSON from {url}")
                 except json.JSONDecodeError:
                     try:
-                        spec = yaml.safe_load(content)
+                        spec = yaml_load_safe(content)
                         logger.debug(f"Parsed as YAML from {url}")
                     except yaml.YAMLError as ye:
                         logger.error(f"YAML parsing failed: {ye}. Raw content: {content[:500]}...")

{mcp_openapi_proxy-0.2.0 → mcp_openapi_proxy-0.2.1}/mcp_openapi_proxy.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mcp-openapi-proxy
-Version: 0.2.0
+Version: 0.2.1
 Summary: MCP server for exposing OpenAPI specifications as MCP tools.
 Author-email: Matthew Hand <11550632+matthewhand@users.noreply.github.com>
 Requires-Python: >=3.10
@@ -31,10 +31,11 @@ Dynamic: license-file
 - ✅ **Codex**, **Gemini**, **Qwen**, **Kilocode**, **opencode** — native tool calls over stdio
 - ✅ **Vibe** — native discovery and read calls (writes were CLI-flaky, not a proxy issue)
 - ✅ **Letta** — Cloud (via a remote streamable-HTTP MCP URL) and self-hosted (via stdio)
-- ⚠️ **agy** — could not attach in headless mode; MCP tool enablement is interactive-only in agy (an agy limitation, not the proxy)
 
 See the [client matrix](#client-matrix) for attach mechanisms, models, and exact results.
 
+> 📄 Full write-up: [**Verification case study**](docs/verification-case-study.md) — what the proxy is, the API + client matrices, and every defect found & fixed.
+
 **Prompts and resources are real now — including custom resources.** Both MCP surfaces are functional and tested: the `summarize_spec` / `whimsical_blog` prompts and the `spec_file` resource, plus a new `ADDITIONAL_RESOURCES` env var that serves your *own* use-case documents (e.g. a NetBox naming policy or an Asana project-layout guide) as MCP resources — see `examples/resources/`.
 
 **Bug fixes (every one live-verified):**
@@ -63,7 +64,7 @@ Full environment-variable reference is in [Environment Variables](#environment-v
 - [Environment Variables](#environment-variables)
 - [Verified Clients & Live Results (2026-06-12)](#verified-clients--live-results-2026-06-12)
   - [Tips](#tips)
-- [Examples](#examples) — Glama, Fly.io, Render, Slack, GetZep, Virustotal, Notion, Asana, APIs.guru, NetBox, Box, WolframAlpha (collapsed)
+- [Examples](#examples) — Glama, Fly.io, Render, Slack, GetZep, Virustotal, Notion, Asana, APIs.guru, NetBox, Box, WolframAlpha, WordPress (collapsed)
 - [Troubleshooting](#troubleshooting)
 - [License](#license)
 
@@ -868,6 +869,55 @@ You can now use the MCP ecosystem to list and invoke WolframAlpha API tools. For
 
 </details>
 
+<details>
+<summary><b>Letta (self-hosted + Cloud)</b> — agent platform; stdio for self-hosted, authenticated remote HTTP for Cloud</summary>
+
+Letta runs agents on a server, so attachment differs by deployment:
+
+- **Self-hosted Letta** accepts a **stdio** MCP server via `PUT /v1/tools/mcp/servers` — no network exposure.
+- **Letta Cloud** rejects stdio and needs a **remote streamable-HTTP** MCP URL behind authentication.
+
+Both were verified live (an agent autonomously called `get_v1_attributes` from the Glama spec through the proxy). Full setup for both paths, including the supergateway wrapper and the security note for the Cloud endpoint, is in [`examples/letta/README.md`](examples/letta/README.md).
+
+</details>
+
+<details>
+<summary><b>WordPress Example</b> — publish to a real WordPress blog from any MCP agent</summary>
+
+This example turns the WordPress REST API into MCP tools so an agent can **create, read, update, and trash blog posts**. It is the example behind a real-world demonstration: a fleet of agent CLIs published to the live blog at **[matthewhand.mywebcommunity.org](https://matthewhand.mywebcommunity.org/)** through this proxy — see the write-up [*“Turning Any API into Agent Tools”*](https://matthewhand.mywebcommunity.org/2026/06/12/turning-any-api-into-agent-tools-a-real-world-test-of-mcp-openapi-proxy/), itself posted via the proxy.
+
+Example config — `examples/wordpress-claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "command": "uvx",
+      "args": ["mcp-openapi-proxy"],
+      "env": {
+        "OPENAPI_SPEC_URL": "https://raw.githubusercontent.com/matthewhand/mcp-openapi-proxy/main/examples/wordpress-openapi.json",
+        "SERVER_URL_OVERRIDE": "https://your-site.example.com/wp-json",
+        "EXTRA_HEADERS": "Authorization: Basic BASE64_OF_USERNAME_COLON_APPLICATION_PASSWORD",
+        "IGNORE_SSL_TOOLS": "false",
+        "TOOL_WHITELIST": "/wp/v2/posts"
+      }
+    }
+  }
+}
+```
+
+Exposed tools (from the bundled `examples/wordpress-openapi.json`): `get_wp_v2_posts`, `post_wp_v2_posts` (create), `get_wp_v2_posts_by_id`, `post_wp_v2_posts_by_id` (update), and `delete_wp_v2_posts_by_id` (trash) — the full post lifecycle.
+
+**Auth — use a WordPress *Application Password*, not your login password.** WordPress REST rejects login passwords for Basic auth. In `wp-admin → Users → (your user) → Application Passwords`, create one, then base64-encode `username:application-password` for the `EXTRA_HEADERS` value:
+
+```bash
+printf 'myuser:xxxx xxxx xxxx xxxx xxxx xxxx' | base64 -w0
+```
+
+Tips: set `IGNORE_SSL_TOOLS=true` only if your host serves a self-signed/mismatched cert; give each agent its own (revocable) application password; keep `TOOL_WHITELIST=/wp/v2/posts` so the agent can touch only posts.
+
+</details>
+
 ## Troubleshooting
 
 ### JSON-RPC Testing

{mcp_openapi_proxy-0.2.0 → mcp_openapi_proxy-0.2.1}/pyproject.toml

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