@automattic/mcp-wordpress-remote 0.5.0 → 0.5.1

package/README.md

@@ -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
@@ -279,6 +308,13 @@ For WooCommerce-specific tools and reports:
 | `WP_API_TIMEOUT_MS`           | Request timeout for tool calls (ms)              | `120000`             | -                     |
 | `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+)     | -                    | -                     |
@@ -476,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.5.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
@@ -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>;

package/dist/lib.js

@@ -75774,7 +75774,7 @@ async function selectCallbackPort(serverUrl, specifiedPort, _unused) {
 }
 
 // src/lib/config.ts
-var MCP_WORDPRESS_REMOTE_VERSION = "0.5.0";
+var MCP_WORDPRESS_REMOTE_VERSION = "0.5.1";
 function parsePositiveIntEnv(value, defaultValue) {
   if (!value) {
     return defaultValue;
@@ -75844,7 +75844,7 @@ var CONFIG = {
   NODE_ENV: process.env.NODE_ENV || "development",
   // Proxy Configuration
   USE_SYSTEM_PROXY: process.env.USE_SYSTEM_PROXY === "true"
-  // Enable system proxy detection (PAC files, env vars)
+  // Enable macOS system proxy detection (PAC file, system SOCKS)
 };
 var getConfig = () => ({
   /** WordPress site API endpoint */
@@ -76192,6 +76192,11 @@ async function doInitializeProxy(detectMacOs) {
     logger.info(`Proxy configured from environment: ${sanitizeProxyUrl(envProxy.url)}`, "PROXY");
     return;
   }
+  if (!getConfig().useSystemProxy) {
+    logger.debug("No proxy configured (system proxy detection disabled)", "PROXY");
+    proxyConfig = { type: "none" };
+    return;
+  }
   const macProxy = detectMacOs();
   if (macProxy?.pacUrl) {
     try {
@@ -76301,11 +76306,7 @@ async function setupFetchPolyfill() {
   } else {
     logger.info("Using native fetch API", "SYSTEM");
   }
-  if (getConfig().useSystemProxy) {
-    await initializeProxy();
-  } else {
-    logger.debug("System proxy support disabled (USE_SYSTEM_PROXY=false)", "PROXY");
-  }
+  await initializeProxy();
 }
 async function proxyFetch(url2, init) {
   const headers = new Headers(init?.headers);
@@ -76313,9 +76314,6 @@ async function proxyFetch(url2, init) {
     headers.set("User-Agent", clientProduct ? `${clientProduct} ${PROXY_PRODUCT}` : PROXY_PRODUCT);
   }
   init = { ...init, headers };
-  if (!getConfig().useSystemProxy) {
-    return fetch(url2, init);
-  }
   const agent = await getAgentForUrl(url2);
   if (agent) {
     const nodeFetch = (await Promise.resolve().then(() => (init_src(), src_exports))).default;

package/dist/proxy.js

@@ -76507,7 +76507,7 @@ async function selectCallbackPort(serverUrl, specifiedPort, _unused) {
 }
 
 // src/lib/config.ts
-var MCP_WORDPRESS_REMOTE_VERSION = "0.5.0";
+var MCP_WORDPRESS_REMOTE_VERSION = "0.5.1";
 function parsePositiveIntEnv(value, defaultValue) {
   if (!value) {
     return defaultValue;
@@ -76577,7 +76577,7 @@ var CONFIG = {
   NODE_ENV: process.env.NODE_ENV || "development",
   // Proxy Configuration
   USE_SYSTEM_PROXY: process.env.USE_SYSTEM_PROXY === "true"
-  // Enable system proxy detection (PAC files, env vars)
+  // Enable macOS system proxy detection (PAC file, system SOCKS)
 };
 var getConfig = () => ({
   /** WordPress site API endpoint */
@@ -76944,6 +76944,11 @@ async function doInitializeProxy(detectMacOs) {
     logger.info(`Proxy configured from environment: ${sanitizeProxyUrl(envProxy.url)}`, "PROXY");
     return;
   }
+  if (!getConfig().useSystemProxy) {
+    logger.debug("No proxy configured (system proxy detection disabled)", "PROXY");
+    proxyConfig = { type: "none" };
+    return;
+  }
   const macProxy = detectMacOs();
   if (macProxy?.pacUrl) {
     try {
@@ -77056,11 +77061,7 @@ async function setupFetchPolyfill() {
   } else {
     logger.info("Using native fetch API", "SYSTEM");
   }
-  if (getConfig().useSystemProxy) {
-    await initializeProxy();
-  } else {
-    logger.debug("System proxy support disabled (USE_SYSTEM_PROXY=false)", "PROXY");
-  }
+  await initializeProxy();
 }
 async function proxyFetch(url2, init) {
   const headers = new Headers(init?.headers);
@@ -77068,9 +77069,6 @@ async function proxyFetch(url2, init) {
     headers.set("User-Agent", clientProduct ? `${clientProduct} ${PROXY_PRODUCT}` : PROXY_PRODUCT);
   }
   init = { ...init, headers };
-  if (!getConfig().useSystemProxy) {
-    return fetch(url2, init);
-  }
   const agent = await getAgentForUrl(url2);
   if (agent) {
     const nodeFetch = (await Promise.resolve().then(() => (init_src(), src_exports))).default;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automattic/mcp-wordpress-remote",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "MCP WordPress Remote proxy server",
   "engines": {
     "node": ">=18.0.0"