@automattic/mcp-wordpress-remote 0.4.0 → 0.5.1

package/README.md

@@ -1,6 +1,6 @@
 # MCP WordPress Remote
 
-**A Model Context Protocol (MCP) server for seamless WordPress integration**
+**A stdio-to-HTTP pass-through proxy for WordPress MCP servers**
 
 Connect AI assistants like Claude Desktop to your WordPress sites with multiple authentication methods including OAuth 2.0, JWT tokens, and application passwords.
 
@@ -19,6 +19,35 @@ Connect AI assistants like Claude Desktop to your WordPress sites with multiple
 - **Comprehensive Logging** - Structured logging with categories and levels
 - **Complete MCP Support** - Tools, resources, prompts, and more
 
+## When to use this proxy
+
+If your MCP client supports the Streamable HTTP transport and can authenticate to your site, connect it to the MCP Adapter endpoint directly. You don't need this proxy. For example, in Claude Code (`.mcp.json`), using an application password:
+
+```json
+{
+  "mcpServers": {
+    "wordpress": {
+      "type": "http",
+      "url": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
+      "headers": {
+        "Authorization": "Basic <base64 of username:application-password>"
+      }
+    }
+  }
+}
+```
+
+Other clients use their own config format. Check your client's documentation for remote or HTTP MCP servers.
+
+Use the proxy when one of these applies:
+
+1. **Your client only supports stdio.** It can launch a local command but cannot connect to an HTTP MCP server.
+2. **Your client can't authenticate the way your site requires.** The proxy can send application passwords, JWT tokens, WooCommerce keys, or [custom headers](#custom-headers), and it can run the [OAuth flow](#authentication-methods) and store tokens for clients that can't.
+3. **Your traffic must go through a proxy.** Set `SOCKS_PROXY`, `HTTPS_PROXY`, `ALL_PROXY` or `HTTP_PROXY` to route requests through it. On macOS, set `USE_SYSTEM_PROXY=true` to use the system PAC file or SOCKS proxy instead.
+4. **Your site is slow or unreliable.** `WP_API_TIMEOUT_MS` and `WP_API_INIT_TIMEOUT_MS` set the timeouts, and a failed initialize returns a degraded response instead of a broken connection (see [Forwarding behavior](#forwarding-behavior)).
+5. **You need a local record of the connection.** `LOG_FILE` with `LOG_LEVEL=3` logs each forwarded method plus connection and authentication events (see [Log Analysis](#log-analysis)).
+6. **You are building a packaged integration.** Tool-call hooks from the `/lib` bundle can send extra requests over the proxy's authenticated connection, for example for usage telemetry.
+
 ## Quick Start
 
 ### Installation
@@ -102,7 +131,7 @@ Custom headers are included in:
 
 1. **Start your MCP client** (Claude Desktop, etc.)
 2. **Choose authentication method** based on your preference:
-   - **OAuth 2.0** (default): Browser opens automatically for authorization
+   - **OAuth 2.0**: Enable `OAUTH_ENABLED=true` to open the browser for authorization
    - **JWT Token**: Set `JWT_TOKEN` environment variable
    - **Application Password**: Set `WP_API_USERNAME` and `WP_API_PASSWORD`
 3. **Start using WordPress features** in your AI assistant
@@ -111,9 +140,17 @@ Custom headers are included in:
 
 Install the [MCP Adapter](https://github.com/WordPress/mcp-adapter) plugin on your WordPress site. Once active, it registers a default MCP server at `/wp-json/mcp/mcp-adapter-default-server` — set `WP_API_URL` to that full URL (examples throughout this README show the pattern). To target a custom server id or namespace, pass the full URL of that server instead.
 
-### Legacy `wordpress-mcp` plugin
+### Forwarding behavior
+
+The proxy forwards the MCP client's messages to the configured endpoint and returns the server's messages. It does not send its own initialization probe, select an MCP version, or register a fixed set of methods. The client and server own version negotiation, capabilities, and result validation. Requests, notifications, server requests, IDs, and metadata travel through the bridge; JSON and SSE responses are supported.
 
-Earlier versions of this proxy were designed for [`Automattic/wordpress-mcp`](https://github.com/Automattic/wordpress-mcp), which exposes its endpoint at `/wp-json/wp/v2/wpmcp`. That plugin is deprecated in favor of `mcp-adapter`, but existing installs continue to work — for backwards compatibility, a bare-domain `WP_API_URL` (e.g. `https://your-wordpress-site.com`) still resolves to the `wordpress-mcp` endpoint. New setups should install `mcp-adapter` and use the full URL shown above.
+For initialization-based MCP connections, the server's selected version and session ID are used in subsequent HTTP headers. Requests carrying `io.modelcontextprotocol/protocolVersion` in `params._meta` use that version directly and do not require a proxy-generated handshake. This removes the proxy's version allowlist; it does not translate between protocol revisions or establish full compliance with every newer transport feature.
+
+Existing authentication, custom headers, timeout, logging, token-storage, and system-proxy settings remain available. A bare-domain `WP_API_URL` now resolves to `/?rest_route=/mcp/mcp-adapter-default-server`. Full endpoint URLs remain configurable. The archived `wordpress-mcp` plugin's method-only request format and automatic transport fallback have been removed.
+
+If the upstream connection fails during initialization, the proxy retains its degraded response with `experimental.connectionFailed` and no usable capabilities, using the client's offered version. Follow-up requests are rejected locally. Server-generated JSON-RPC errors are forwarded rather than converted to a successful handshake. The proxy does not silently reinitialize or retry failed client requests.
+
+Tool-call hooks and `wpRequest` from the `/lib` bundle share the live authenticated connection when the proxy is running. Hook responses remain internal and hook failures cannot change the client response. Standalone `wpRequest` retains its result-returning interface and optional session recovery; both its existing argument shapes are encoded as standard JSON-RPC.
 
 ## Authentication Methods
 
@@ -248,10 +285,11 @@ For WooCommerce-specific tools and reports:
 
 | Variable                      | Description                                      | Default              | Required              |
 | ----------------------------- | ------------------------------------------------ | -------------------- | --------------------- |
-| `WP_API_URL`                  | WordPress site URL including the MCP endpoint path (e.g. `…/wp-json/mcp/mcp-adapter-default-server`). A bare domain resolves to the deprecated `wordpress-mcp` endpoint for backwards compatibility. | - | ✅ |
-| `OAUTH_ENABLED`               | Enable OAuth authentication                      | `true`               | -                     |
+| `WP_API_URL`                  | WordPress site URL including the MCP endpoint path (e.g. `…/wp-json/mcp/mcp-adapter-default-server`). A bare domain resolves to the MCP Adapter default server. | - | ✅ |
+| `OAUTH_ENABLED`               | Enable OAuth authentication                      | `false`               | -                     |
 | `OAUTH_CALLBACK_PORT`         | OAuth callback port                              | `7665`               | -                     |
 | `OAUTH_HOST`                  | OAuth callback hostname                          | `127.0.0.1`          | -                     |
+| `OAUTH_TIMEOUT_MS`            | Time to wait for the browser OAuth login (ms)    | `30000`              | -                     |
 | `WP_OAUTH_CLIENT_ID`          | Custom OAuth client ID                           | -                    | -                     |
 | **OAuth Endpoints**           |                                                  |                      |                       |
 | `OAUTH_AUTHORIZE_ENDPOINT`    | OAuth authorization endpoint                     | -                    | ✅ (for custom OAuth) |
@@ -268,7 +306,15 @@ For WooCommerce-specific tools and reports:
 | `LOG_LEVEL`                   | Log level (0-3)                                  | `2`                  | -                     |
 | `LOG_TO_STDERR`               | Mirror all log levels to stderr (errors always are) | `false`           | -                     |
 | `WP_API_TIMEOUT_MS`           | Request timeout for tool calls (ms)              | `120000`             | -                     |
-| `WP_API_INIT_TIMEOUT_MS`      | Timeout for the initialize handshake (ms)        | `25000`              | -                     |
+| `WP_API_INIT_TIMEOUT_MS`      | Initialize timeout (ms), after OAuth login       | `25000`              | -                     |
+| `PROXY_PAC_TIMEOUT_MS`        | Timeout for PAC download and resolver setup (ms) | `5000`               | -                     |
+| **Network Proxy**             |                                                  |                      |                       |
+| `SOCKS_PROXY`                 | SOCKS proxy URL (`socks5h://` resolves DNS on the proxy) | -            | -                     |
+| `HTTPS_PROXY`                 | HTTP(S) proxy URL, used when `SOCKS_PROXY` is unset | -                 | -                     |
+| `ALL_PROXY`                   | Proxy URL, used when the above are unset         | -                    | -                     |
+| `HTTP_PROXY`                  | Proxy URL, used when the above are unset         | -                    | -                     |
+| `NO_PROXY`                    | Comma-separated hosts that bypass the proxy      | -                    | -                     |
+| `USE_SYSTEM_PROXY`            | Also detect the macOS system PAC file or SOCKS proxy when no proxy URL is set | `false` | -          |
 | **TLS / Certificates**        |                                                  |                      |                       |
 | `NODE_EXTRA_CA_CERTS`         | Path to an extra CA file to trust (mkcert/corporate CA) | -             | -                     |
 | `NODE_USE_SYSTEM_CA`          | Trust the OS certificate store (Node 22.15+)     | -                    | -                     |
@@ -466,15 +512,6 @@ Log levels:
 - **Expired token cleanup** and refresh handling
 - **Multi-instance coordination** prevents authentication conflicts
 
-## Why Use MCP WordPress Remote?
-
-1. **Multiple Authentication Methods** - Choose what works best for your setup
-2. **Enhanced Security** - OAuth 2.0 with persistent token storage
-3. **Better User Experience** - One-time setup with automatic token management
-4. **Multi-Instance Support** - Works reliably with multiple MCP clients
-5. **Comprehensive Logging** - Detailed logs for troubleshooting
-6. **Easy Setup** - No global installation required with npx
-
 ## Requirements
 
 - **Node.js 22+** (required for fetch API support)

package/dist/lib.d.ts

@@ -15,7 +15,7 @@ interface WordPressResponse {
     [key: string]: any;
 }
 
-declare const MCP_WORDPRESS_REMOTE_VERSION = "0.4.0";
+declare const MCP_WORDPRESS_REMOTE_VERSION = "0.5.1";
 /**
  * Centralized configuration for MCP WordPress Remote
  * All default values are defined here and can be overridden via environment variables
@@ -34,7 +34,7 @@ declare const CONFIG: {
     readonly OAUTH_AUTHENTICATE_ENDPOINT: string;
     readonly OAUTH_RESOURCE_INDICATOR: boolean;
     readonly OAUTH_SCOPES: string;
-    readonly OAUTH_TIMEOUT: 30000;
+    readonly OAUTH_TIMEOUT: number;
     readonly LOCK_TIMEOUT: 300000;
     readonly WP_API_TIMEOUT: number;
     readonly WP_API_INIT_TIMEOUT: number;
@@ -74,7 +74,7 @@ declare const getConfig: () => {
     /** Custom OAuth scopes (comma-separated) */
     oauthScopes: string;
     /** OAuth operation timeout in milliseconds */
-    oauthTimeout: 30000;
+    oauthTimeout: number;
     /** Lock operation timeout in milliseconds */
     lockTimeout: 300000;
     /** WordPress request timeout in milliseconds (tool calls and non-init requests) */
@@ -155,6 +155,12 @@ declare const logger: {
     config: (message: string, level?: LogLevel, ...args: any[]) => void;
 };
 
+/**
+ * Send one request to WordPress. While the proxy is running, the request rides its live
+ * connection, and session recovery is left to the connected client.
+ *
+ * @param useJsonRpc Deprecated and ignored; requests are always sent as JSON-RPC.
+ */
 declare function wpRequest(requestData: any, useJsonRpc?: boolean, options?: {
     allowSessionRecovery?: boolean;
 }): Promise<WordPressResponse>;
@@ -235,12 +241,6 @@ declare function isConfigError(error: any): error is ConfigError;
 declare function isAuthError(error: any): error is AuthError;
 declare function isAPIError(error: any): error is APIError;
 
-/**
- * Fetch API utilities for MCP WordPress Remote
- *
- * Provides fetch polyfill setup for Node.js environments that don't have native fetch
- * and proxy-aware fetch for routing through system proxies (PAC files, env-based SOCKS/HTTP proxies)
- */
 /**
  * Setup fetch polyfill for Node.js 18+ compatibility
  *
@@ -252,9 +252,9 @@ declare function setupFetchPolyfill(): Promise<void>;
 /**
  * Proxy-aware fetch that routes requests through system proxies when configured
  *
- * On macOS: Evaluates PAC file from system proxy settings to determine proxy per-URL
- * On Linux/other: Uses SOCKS_PROXY, HTTPS_PROXY, etc. environment variables
- * Falls back to direct connection if no proxy is configured or USE_SYSTEM_PROXY=false
+ * Uses SOCKS_PROXY, HTTPS_PROXY, ALL_PROXY or HTTP_PROXY when set
+ * With USE_SYSTEM_PROXY=true on macOS: Evaluates the system PAC file or SOCKS proxy
+ * Falls back to direct connection if no proxy is configured or NO_PROXY matches
  *
  * @param url - The URL to fetch
  * @param init - Optional fetch init options
@@ -289,9 +289,9 @@ declare function getFetchInfo(): {
  * Cross-platform proxy utilities for MCP WordPress Remote
  *
  * Supports:
- * - macOS: Automatic PAC file detection from system proxy settings
- * - macOS: System SOCKS proxy detection (manual "tunnel all traffic" config)
- * - All platforms: Environment variables (SOCKS_PROXY, HTTPS_PROXY, etc.)
+ * - All platforms: Environment variables (SOCKS_PROXY, HTTPS_PROXY, etc.), always
+ * - macOS, with USE_SYSTEM_PROXY=true: PAC file from system proxy settings
+ * - macOS, with USE_SYSTEM_PROXY=true: System SOCKS proxy ("tunnel all traffic")
  */
 
 type ProxyAgent = SocksProxyAgent | HttpsProxyAgent<string>;
@@ -327,17 +327,6 @@ declare function isProxyConfigured(): boolean;
  */
 declare function getProxyType(): 'pac' | 'env' | 'none';
 
-/**
- * MCP Request Types for WordPress Remote Proxy
- *
- * Type definitions for all MCP JSON-RPC request schemas
- */
-
-interface WPRequestParams {
-    method: string;
-    [key: string]: unknown;
-}
-
 /**
  * Tool-call hooks for MCP WordPress Remote.
  *
@@ -356,11 +345,10 @@ interface ToolCallContext {
     name: string;
     /**
      * Dispatch an additional request over the proxy's live, authenticated
-     * session. The request is prepared for the session's detected transport
-     * (JSON-RPC envelope or simple format) before it is sent, e.g.
+     * session. The request is prepared as JSON-RPC before it is sent, e.g.
      * `wpRequest({ method: 'tools/call', name, arguments })`.
      */
-    wpRequest: (params: WPRequestParams) => Promise<WordPressResponse>;
+    wpRequest: (params: WordPressRequestParams) => Promise<WordPressResponse>;
 }
 /** A hook fired after each completed `tools/call`. May be async. */
 type ToolCallHook = (context: ToolCallContext) => void | Promise<void>;