@automattic/mcp-wordpress-remote 0.4.0 → 0.5.0

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.
 
@@ -102,7 +102,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 +111,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
 
-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.
+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.
+
+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 +256,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 +277,8 @@ 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`               | -                     |
 | **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+)     | -                    | -                     |

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.0";
 /**
  * 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
  *
@@ -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>;