@automattic/mcp-wordpress-remote 0.5.0 → 0.5.2

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

@@ -73824,10 +73824,9 @@ var ProgressTokenSchema = union([string2(), number2().int()]);
 var CursorSchema = string2();
 var TaskCreationParamsSchema = looseObject({
   /**
-   * Time in milliseconds to keep task results available after completion.
-   * If null, the task has unlimited lifetime until manually cleaned up.
+   * Requested duration in milliseconds to retain task from creation.
    */
-  ttl: union([number2(), _null3()]).optional(),
+  ttl: number2().optional(),
   /**
    * Time in milliseconds to wait between task status requests.
    */
@@ -74122,7 +74121,11 @@ var ClientCapabilitiesSchema = object({
   /**
    * Present if the client supports task creation.
    */
-  tasks: ClientTasksCapabilitySchema.optional()
+  tasks: ClientTasksCapabilitySchema.optional(),
+  /**
+   * Extensions that the client supports. Keys are extension identifiers (vendor-prefix/extension-name).
+   */
+  extensions: record(string2(), AssertObjectSchema).optional()
 });
 var InitializeRequestParamsSchema = BaseRequestParamsSchema.extend({
   /**
@@ -74183,7 +74186,11 @@ var ServerCapabilitiesSchema = object({
   /**
    * Present if the server supports task creation.
    */
-  tasks: ServerTasksCapabilitySchema.optional()
+  tasks: ServerTasksCapabilitySchema.optional(),
+  /**
+   * Extensions that the server supports. Keys are extension identifiers (vendor-prefix/extension-name).
+   */
+  extensions: record(string2(), AssertObjectSchema).optional()
 });
 var InitializeResultSchema = ResultSchema.extend({
   /**
@@ -74375,6 +74382,12 @@ var ResourceSchema = object({
    * The MIME type of this resource, if known.
    */
   mimeType: optional(string2()),
+  /**
+   * The size of the raw resource content, in bytes (i.e., before base64 encoding or any tokenization), if known.
+   *
+   * This can be used by Hosts to display file sizes and estimate context window usage.
+   */
+  size: optional(number2()),
   /**
    * Optional annotations for the client.
    */
@@ -75393,7 +75406,12 @@ var OAuthTokensSchema = object({
   token_type: string2(),
   expires_in: coerce_exports.number().optional(),
   scope: string2().optional(),
-  refresh_token: string2().optional()
+  refresh_token: string2().optional(),
+  /**
+   * Not part of the wire format: the authorization server this value was obtained from, added by
+   * the client's `auth()` before it is stored and compared when it is read back.
+   */
+  issuer: string2().optional().catch(void 0)
 }).strip();
 var OAuthErrorResponseSchema = object({
   error: string2(),
@@ -75423,7 +75441,12 @@ var OAuthClientInformationSchema = object({
   client_id: string2(),
   client_secret: string2().optional(),
   client_id_issued_at: number2().optional(),
-  client_secret_expires_at: number2().optional()
+  client_secret_expires_at: number2().optional(),
+  /**
+   * Not part of the wire format: the authorization server this value was obtained from, added by
+   * the client's `auth()` before it is stored and compared when it is read back.
+   */
+  issuer: string2().optional().catch(void 0)
 }).strip();
 var OAuthClientInformationFullSchema = OAuthClientMetadataSchema.merge(OAuthClientInformationSchema);
 var OAuthClientRegistrationErrorSchema = object({
@@ -75530,6 +75553,10 @@ var OAUTH_ERRORS = {
   [InvalidTargetError.errorCode]: InvalidTargetError
 };
 
+// node_modules/@modelcontextprotocol/sdk/dist/esm/client/auth.js
+var TokenResponseSchema = OAuthTokensSchema.omit({ issuer: true });
+var RegistrationResponseSchema = OAuthClientInformationFullSchema.omit({ issuer: true });
+
 // src/lib/utils.ts
 import * as fs2 from "node:fs";
 import * as path3 from "node:path";
@@ -75774,7 +75801,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.2";
 function parsePositiveIntEnv(value, defaultValue) {
   if (!value) {
     return defaultValue;
@@ -75844,7 +75871,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 +76219,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 +76333,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 +76341,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;
@@ -77405,7 +77430,11 @@ var OAuthCallbackServer = class {
   async start() {
     return new Promise((resolve, reject) => {
       try {
-        this.server = this.app.listen(this.options.port, this.options.host, () => {
+        this.server = this.app.listen(this.options.port, this.options.host, (error51) => {
+          if (error51) {
+            reject(error51);
+            return;
+          }
           logger.oauth(
             `OAuth callback server listening on http://${this.options.host}:${this.options.port}`
           );