@automattic/mcp-wordpress-remote 0.2.21 → 0.3.1

package/README.md

@@ -38,7 +38,7 @@ Add to your MCP client configuration (e.g., Claude Desktop's `claude_desktop_con
       "command": "npx",
       "args": ["-y", "@automattic/mcp-wordpress-remote"],
       "env": {
-        "WP_API_URL": "https://your-wordpress-site.com"
+        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server"
       }
     }
   }
@@ -58,7 +58,7 @@ You can add custom headers to all API requests using the `CUSTOM_HEADERS` enviro
       "command": "npx",
       "args": ["-y", "@automattic/mcp-wordpress-remote"],
       "env": {
-        "WP_API_URL": "https://your-wordpress-site.com",
+        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
         "CUSTOM_HEADERS": "{\"X-MCP-API-Key\": \"*Ibo7tweixlbfuwaiufxgakjyefctwajcetb*\", \"X-Custom-Header\": \"value\"}"
       }
     }
@@ -75,7 +75,7 @@ You can add custom headers to all API requests using the `CUSTOM_HEADERS` enviro
       "command": "npx",
       "args": ["-y", "@automattic/mcp-wordpress-remote"],
       "env": {
-        "WP_API_URL": "https://your-wordpress-site.com",
+        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
         "CUSTOM_HEADERS": "X-MCP-API-Key:IOskncfyes78U8on3q7ry43o487tybrc,X-Custom-Header:value"
       }
     }
@@ -87,7 +87,7 @@ You can add custom headers to all API requests using the `CUSTOM_HEADERS` enviro
 
 ```bash
 CUSTOM_HEADERS='{"X-MCP-API-Key": "wc_mcp_FaQduhQcW0mfVaZgP3yaaqDuXaZ3mw7j"}' \
-WP_API_URL="https://your-site.com" \
+WP_API_URL="https://your-site.com/wp-json/mcp/mcp-adapter-default-server" \
 npx @automattic/mcp-wordpress-remote
 ```
 
@@ -109,7 +109,11 @@ Custom headers are included in:
 
 ## WordPress MCP Plugin
 
-You need to install the [wordpress-mcp](https://github.com/WordPress/mcp-adapter) plugin on your WordPress website and enable MCP Functionality in Settings > MCP Settings.
+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
+
+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.
 
 ## Authentication Methods
 
@@ -126,7 +130,7 @@ OAuth 2.1 provides the most secure and user-friendly experience with full MCP Au
       "command": "npx",
       "args": ["-y", "@automattic/mcp-wordpress-remote"],
       "env": {
-        "WP_API_URL": "https://your-wordpress-site.com",
+        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
         "OAUTH_ENABLED": "true"
       }
     }
@@ -163,7 +167,7 @@ For server-to-server authentication or when OAuth is not available.
       "command": "npx",
       "args": ["-y", "@automattic/mcp-wordpress-remote"],
       "env": {
-        "WP_API_URL": "https://your-wordpress-site.com",
+        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
         "JWT_TOKEN": "your-jwt-token-here"
       }
     }
@@ -182,7 +186,7 @@ Uses WordPress username and application password for basic authentication.
       "command": "npx",
       "args": ["-y", "@automattic/mcp-wordpress-remote"],
       "env": {
-        "WP_API_URL": "https://your-wordpress-site.com",
+        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
         "WP_API_USERNAME": "your-username",
         "WP_API_PASSWORD": "your-application-password",
         "OAUTH_ENABLED": "false"
@@ -210,7 +214,7 @@ To create an application password:
       "command": "npx",
       "args": ["-y", "@automattic/mcp-wordpress-remote"],
       "env": {
-        "WP_API_URL": "https://your-wordpress-site.com",
+        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
         "OAUTH_CALLBACK_PORT": "7665",
         "OAUTH_HOST": "127.0.0.1",
         "WP_OAUTH_CLIENT_ID": "your-custom-client-id"
@@ -231,7 +235,7 @@ For WooCommerce-specific tools and reports:
       "command": "npx",
       "args": ["-y", "@automattic/mcp-wordpress-remote"],
       "env": {
-        "WP_API_URL": "https://your-wordpress-site.com",
+        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server",
         "WOO_CUSTOMER_KEY": "ck_your-consumer-key",
         "WOO_CUSTOMER_SECRET": "cs_your-consumer-secret"
       }
@@ -244,7 +248,7 @@ For WooCommerce-specific tools and reports:
 
 | Variable                      | Description                                      | Default              | Required              |
 | ----------------------------- | ------------------------------------------------ | -------------------- | --------------------- |
-| `WP_API_URL`                  | WordPress site URL                               | -                    | ✅                    |
+| `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`               | -                     |
 | `OAUTH_CALLBACK_PORT`         | OAuth callback port                              | `7665`               | -                     |
 | `OAUTH_HOST`                  | OAuth callback hostname                          | `127.0.0.1`          | -                     |
@@ -317,7 +321,7 @@ Configure your MCP client to use the local version:
       "command": "node",
       "args": ["/path/to/your/mcp-wordpress-remote/dist/proxy.js"],
       "env": {
-        "WP_API_URL": "https://your-wordpress-site.com"
+        "WP_API_URL": "https://your-wordpress-site.com/wp-json/mcp/mcp-adapter-default-server"
       }
     }
   }
@@ -403,9 +407,8 @@ If you see "waiting for other instance" messages, this is normal behavior.
 
 **API endpoint not found:**
 
-- Verify WordPress MCP plugin is installed and activated
-- Check plugin is enabled in WordPress admin
-- Confirm `WP_API_URL` is correct
+- Verify the [MCP Adapter](https://github.com/WordPress/mcp-adapter) plugin is installed and active
+- Confirm `WP_API_URL` points at the server route (e.g. `…/wp-json/mcp/mcp-adapter-default-server`)
 
 **Permission denied:**
 
@@ -469,7 +472,7 @@ Log levels:
 ## Requirements
 
 - **Node.js 22+** (required for fetch API support)
-- **WordPress site** with [wordpress-mcp](https://github.com/Automattic/wordpress-mcp) plugin
+- **WordPress site** with the [MCP Adapter](https://github.com/WordPress/mcp-adapter) plugin installed and active
 - **WordPress user account** with appropriate permissions
 
 ## License
@@ -484,7 +487,7 @@ Contributions welcome! This project is maintained by Automattic Inc.
 
 - **Issues:** [GitHub Issues](https://github.com/Automattic/mcp-wordpress-remote/issues)
 - **Documentation:** Check the troubleshooting section above
-- **WordPress MCP Plugin:** [Plugin Repository](https://github.com/Automattic/wordpress-mcp)
+- **WordPress MCP Plugin:** [WordPress/mcp-adapter](https://github.com/WordPress/mcp-adapter)
 
 ---
 

package/dist/lib.d.ts

@@ -15,7 +15,7 @@ interface WordPressResponse {
     [key: string]: any;
 }
 
-declare const MCP_WORDPRESS_REMOTE_VERSION = "0.2.19";
+declare const MCP_WORDPRESS_REMOTE_VERSION = "0.3.0";
 /**
  * Centralized configuration for MCP WordPress Remote
  * All default values are defined here and can be overridden via environment variables
@@ -149,7 +149,9 @@ declare const logger: {
     config: (message: string, level?: LogLevel, ...args: any[]) => void;
 };
 
-declare function wpRequest(requestData: any, useJsonRpc?: boolean): Promise<WordPressResponse>;
+declare function wpRequest(requestData: any, useJsonRpc?: boolean, options?: {
+    allowSessionRecovery?: boolean;
+}): Promise<WordPressResponse>;
 
 /**
  * WordPress OAuth types and error definitions

package/dist/lib.js

@@ -91,13 +91,13 @@ var require_ponyfill_es2018 = __commonJS({
       typeof exports === "object" && typeof module !== "undefined" ? factory(exports) : typeof define === "function" && define.amd ? define(["exports"], factory) : (global2 = typeof globalThis !== "undefined" ? globalThis : global2 || self, factory(global2.WebStreamsPolyfill = {}));
     })(exports, function(exports2) {
       "use strict";
-      function noop2() {
+      function noop3() {
         return void 0;
       }
       function typeIsObject(x2) {
         return typeof x2 === "object" && x2 !== null || typeof x2 === "function";
       }
-      const rethrowAssertionErrorRejection = noop2;
+      const rethrowAssertionErrorRejection = noop3;
       function setFunctionName(fn, name) {
         try {
           Object.defineProperty(fn, "name", {
@@ -2726,7 +2726,7 @@ var require_ponyfill_es2018 = __commonJS({
               return newPromise((resolveRead, rejectRead) => {
                 ReadableStreamDefaultReaderRead(reader, {
                   _chunkSteps: (chunk) => {
-                    currentWrite = PerformPromiseThen(WritableStreamDefaultWriterWrite(writer, chunk), void 0, noop2);
+                    currentWrite = PerformPromiseThen(WritableStreamDefaultWriterWrite(writer, chunk), void 0, noop3);
                     resolveRead(false);
                   },
                   _closeSteps: () => resolveRead(true),
@@ -3407,7 +3407,7 @@ var require_ponyfill_es2018 = __commonJS({
       function ReadableStreamFromIterable(asyncIterable) {
         let stream;
         const iteratorRecord = GetIterator(asyncIterable, "async");
-        const startAlgorithm = noop2;
+        const startAlgorithm = noop3;
         function pullAlgorithm() {
           let nextResult;
           try {
@@ -3459,7 +3459,7 @@ var require_ponyfill_es2018 = __commonJS({
       }
       function ReadableStreamFromDefaultReader(reader) {
         let stream;
-        const startAlgorithm = noop2;
+        const startAlgorithm = noop3;
         function pullAlgorithm() {
           let readPromise;
           try {
@@ -3778,7 +3778,7 @@ var require_ponyfill_es2018 = __commonJS({
           });
         }
         const sourceCancelPromise = stream._readableStreamController[CancelSteps](reason);
-        return transformPromiseWith(sourceCancelPromise, noop2);
+        return transformPromiseWith(sourceCancelPromise, noop3);
       }
       function ReadableStreamClose(stream) {
         stream._state = "closed";
@@ -4999,7 +4999,7 @@ async function toFormData(Body2, ct) {
   parser.end();
   return formData;
 }
-var s, S, f2, F, LF, CR, SPACE, HYPHEN, COLON, A, Z, lower, noop, MultipartParser;
+var s, S, f2, F, LF, CR, SPACE, HYPHEN, COLON, A, Z, lower, noop2, MultipartParser;
 var init_multipart_parser = __esm({
   "node_modules/node-fetch/src/utils/multipart-parser.js"() {
     "use strict";
@@ -5031,7 +5031,7 @@ var init_multipart_parser = __esm({
     A = 97;
     Z = 122;
     lower = (c) => c | 32;
-    noop = () => {
+    noop2 = () => {
     };
     MultipartParser = class {
       /**
@@ -5040,13 +5040,13 @@ var init_multipart_parser = __esm({
       constructor(boundary) {
         this.index = 0;
         this.flags = 0;
-        this.onHeaderEnd = noop;
-        this.onHeaderField = noop;
-        this.onHeadersEnd = noop;
-        this.onHeaderValue = noop;
-        this.onPartBegin = noop;
-        this.onPartData = noop;
-        this.onPartEnd = noop;
+        this.onHeaderEnd = noop2;
+        this.onHeaderField = noop2;
+        this.onHeadersEnd = noop2;
+        this.onHeaderValue = noop2;
+        this.onPartBegin = noop2;
+        this.onPartData = noop2;
+        this.onPartEnd = noop2;
         this.boundaryChars = {};
         boundary = "\r\n--" + boundary;
         const ui8a = new Uint8Array(boundary.length);
@@ -7881,7 +7881,7 @@ var require_destroy = __commonJS({
       }
       if (isEventEmitter(stream) && suppress) {
         stream.removeAllListeners("error");
-        stream.addListener("error", noop2);
+        stream.addListener("error", noop3);
       }
       return stream;
     }
@@ -7936,7 +7936,7 @@ var require_destroy = __commonJS({
     function isZlibStream(stream) {
       return stream instanceof Zlib.Gzip || stream instanceof Zlib.Gunzip || stream instanceof Zlib.Deflate || stream instanceof Zlib.DeflateRaw || stream instanceof Zlib.Inflate || stream instanceof Zlib.InflateRaw || stream instanceof Zlib.Unzip;
     }
-    function noop2() {
+    function noop3() {
     }
     function onDrainClearBinding() {
       this._binding.clear();
@@ -30288,6 +30288,109 @@ var require_express2 = __commonJS({
   }
 });
 
+// node_modules/eventsource-parser/dist/index.js
+var ParseError = class extends Error {
+  constructor(message, options) {
+    super(message), this.name = "ParseError", this.type = options.type, this.field = options.field, this.value = options.value, this.line = options.line;
+  }
+};
+function noop(_arg) {
+}
+function createParser(callbacks) {
+  if (typeof callbacks == "function")
+    throw new TypeError(
+      "`callbacks` must be an object, got a function instead. Did you mean `{onEvent: fn}`?"
+    );
+  const { onEvent = noop, onError = noop, onRetry = noop, onComment } = callbacks;
+  let incompleteLine = "", isFirstChunk = true, id, data = "", eventType = "";
+  function feed(newChunk) {
+    const chunk = isFirstChunk ? newChunk.replace(/^\xEF\xBB\xBF/, "") : newChunk, [complete, incomplete] = splitLines(`${incompleteLine}${chunk}`);
+    for (const line of complete)
+      parseLine(line);
+    incompleteLine = incomplete, isFirstChunk = false;
+  }
+  function parseLine(line) {
+    if (line === "") {
+      dispatchEvent();
+      return;
+    }
+    if (line.startsWith(":")) {
+      onComment && onComment(line.slice(line.startsWith(": ") ? 2 : 1));
+      return;
+    }
+    const fieldSeparatorIndex = line.indexOf(":");
+    if (fieldSeparatorIndex !== -1) {
+      const field = line.slice(0, fieldSeparatorIndex), offset = line[fieldSeparatorIndex + 1] === " " ? 2 : 1, value = line.slice(fieldSeparatorIndex + offset);
+      processField(field, value, line);
+      return;
+    }
+    processField(line, "", line);
+  }
+  function processField(field, value, line) {
+    switch (field) {
+      case "event":
+        eventType = value;
+        break;
+      case "data":
+        data = `${data}${value}
+`;
+        break;
+      case "id":
+        id = value.includes("\0") ? void 0 : value;
+        break;
+      case "retry":
+        /^\d+$/.test(value) ? onRetry(parseInt(value, 10)) : onError(
+          new ParseError(`Invalid \`retry\` value: "${value}"`, {
+            type: "invalid-retry",
+            value,
+            line
+          })
+        );
+        break;
+      default:
+        onError(
+          new ParseError(
+            `Unknown field "${field.length > 20 ? `${field.slice(0, 20)}\u2026` : field}"`,
+            { type: "unknown-field", field, value, line }
+          )
+        );
+        break;
+    }
+  }
+  function dispatchEvent() {
+    data.length > 0 && onEvent({
+      id,
+      event: eventType || void 0,
+      // If the data buffer's last character is a U+000A LINE FEED (LF) character,
+      // then remove the last character from the data buffer.
+      data: data.endsWith(`
+`) ? data.slice(0, -1) : data
+    }), id = void 0, data = "", eventType = "";
+  }
+  function reset(options = {}) {
+    incompleteLine && options.consume && parseLine(incompleteLine), isFirstChunk = true, id = void 0, data = "", eventType = "", incompleteLine = "";
+  }
+  return { feed, reset };
+}
+function splitLines(chunk) {
+  const lines = [];
+  let incompleteLine = "", searchIndex = 0;
+  for (; searchIndex < chunk.length; ) {
+    const crIndex = chunk.indexOf("\r", searchIndex), lfIndex = chunk.indexOf(`
+`, searchIndex);
+    let lineEnd = -1;
+    if (crIndex !== -1 && lfIndex !== -1 ? lineEnd = Math.min(crIndex, lfIndex) : crIndex !== -1 ? lineEnd = crIndex : lfIndex !== -1 && (lineEnd = lfIndex), lineEnd === -1) {
+      incompleteLine = chunk.slice(searchIndex);
+      break;
+    } else {
+      const line = chunk.slice(searchIndex, lineEnd);
+      lines.push(line), searchIndex = lineEnd + 1, chunk[searchIndex - 1] === "\r" && chunk[searchIndex] === `
+` && searchIndex++;
+    }
+  }
+  return [lines, incompleteLine];
+}
+
 // node_modules/zod/lib/index.mjs
 var util;
 (function(util2) {
@@ -35153,10 +35256,9 @@ import crypto3 from "crypto";
 import path from "path";
 import fs from "fs/promises";
 import crypto2 from "crypto";
-var VERSION = MCP_WORDPRESS_REMOTE_VERSION;
 function getConfigDir() {
   const baseConfigDir = CONFIG.WP_MCP_CONFIG_DIR;
-  return path.join(baseConfigDir, `wordpress-remote-${VERSION}`);
+  return path.join(baseConfigDir, `wordpress-remote-${MCP_WORDPRESS_REMOTE_VERSION}`);
 }
 async function ensureConfigDir() {
   try {
@@ -35346,7 +35448,7 @@ function calculateDefaultPort(serverUrlHash) {
 }
 async function findExistingClientPort(serverUrlHash) {
   const clientInfo = await readJsonFile(serverUrlHash, "client_info.json");
-  if (!clientInfo) {
+  if (!clientInfo || !clientInfo.redirect_uris) {
     return void 0;
   }
   const localhostRedirectUri = clientInfo.redirect_uris.map((uri) => {
@@ -35382,7 +35484,7 @@ async function selectCallbackPort(serverUrl, specifiedPort, _unused) {
 }
 
 // src/lib/config.ts
-var MCP_WORDPRESS_REMOTE_VERSION = "0.2.19";
+var MCP_WORDPRESS_REMOTE_VERSION = "0.3.0";
 var CONFIG = {
   // API Configuration
   WP_API_URL: process.env.WP_API_URL || "https://example.com",
@@ -36889,17 +36991,14 @@ var OAuthCallbackServer = class {
     });
   }
   async stop() {
-    return new Promise((resolve) => {
-      if (this.server) {
-        this.server.close(() => {
-          logger.oauth("OAuth callback server stopped");
-          this.server = null;
-          resolve();
-        });
-      } else {
-        resolve();
-      }
+    if (!this.server) return;
+    const server = this.server;
+    this.server = null;
+    server.close((err) => {
+      if (err) logger.error("OAuth callback server close error", "OAUTH", err);
+      else logger.oauth("OAuth callback server stopped");
     });
+    server.closeAllConnections?.();
   }
   getCallbackUrl() {
     return `http://${this.options.host}:${this.options.port}/oauth/callback`;
@@ -37904,6 +38003,12 @@ var mcpOAuthProvider = null;
 var authCoordinator = null;
 var globalEvents = null;
 var globalSessionId = null;
+var lastInitializeRequest = null;
+var sessionRefreshPromise = null;
+var WP_MCP_ENDPOINT = "/wp/v2/wpmcp";
+var INVALID_SESSION_ERROR_CODES = /* @__PURE__ */ new Set([-32602, -32005]);
+var INVALID_SESSION_ERROR_MESSAGE = "Invalid or expired session";
+var SESSION_NOT_FOUND_ERROR_MESSAGE = "Session not found";
 function validateEnvironment() {
   const validation = validateConfig();
   if (!validation.isValid) {
@@ -37916,6 +38021,24 @@ function validateEnvironment() {
 function removeTrailingSlash(url) {
   return url.replace(/\/+$/, "");
 }
+function parseSSEMessage(text) {
+  let result;
+  let found = false;
+  const parser = createParser({
+    onEvent(event) {
+      if (found) return;
+      if (!event.event || event.event === "message") {
+        result = JSON.parse(event.data);
+        found = true;
+      }
+    }
+  });
+  parser.feed(text);
+  if (!found) {
+    throw new Error('No "message" event with data found in SSE response');
+  }
+  return result;
+}
 function constructApiUrl(baseUrl, defaultEndpoint) {
   const cleanUrl = removeTrailingSlash(baseUrl);
   try {
@@ -38002,9 +38125,53 @@ async function getOAuthTokens() {
     return null;
   }
 }
-async function wpRequest(requestData, useJsonRpc = true) {
-  validateEnvironment();
-  const endpoint = "/wp/v2/wpmcp";
+function getCurrentApiUrl() {
+  return process.env.WP_API_URL || CONFIG.WP_API_URL;
+}
+function getRequestUrl() {
+  return constructApiUrl(getCurrentApiUrl(), WP_MCP_ENDPOINT);
+}
+function cloneRequestData(requestData) {
+  return JSON.parse(JSON.stringify(requestData));
+}
+function isInitializeRequest(requestData) {
+  return requestData?.method === "initialize";
+}
+function cacheInitializeRequest(requestData, useJsonRpc) {
+  lastInitializeRequest = {
+    requestData: cloneRequestData(requestData),
+    useJsonRpc
+  };
+}
+function parseApiErrorResponse(error) {
+  if (!error.response) {
+    return null;
+  }
+  if (typeof error.response === "string") {
+    try {
+      return JSON.parse(error.response);
+    } catch {
+      return null;
+    }
+  }
+  return error.response;
+}
+function isInvalidSessionError(error) {
+  const errorResponse = parseApiErrorResponse(error);
+  const jsonRpcError = errorResponse?.error && typeof errorResponse.error === "object" ? errorResponse.error : errorResponse;
+  const code = typeof jsonRpcError?.code === "number" ? jsonRpcError.code : null;
+  const message = typeof jsonRpcError?.message === "string" ? jsonRpcError.message : "";
+  return code !== null && INVALID_SESSION_ERROR_CODES.has(code) && (message === INVALID_SESSION_ERROR_MESSAGE || message.includes(SESSION_NOT_FOUND_ERROR_MESSAGE) || message.includes(INVALID_SESSION_ERROR_MESSAGE));
+}
+function updateSessionId(sessionId) {
+  if (globalSessionId === sessionId) {
+    return;
+  }
+  globalSessionId = sessionId;
+  logger.info(`Session ID received from WordPress: ${globalSessionId}`, "SESSION");
+}
+async function executeWordPressRequest(requestData, useJsonRpc, sessionIdUsed) {
+  const url = getRequestUrl();
   const method = "POST";
   if (useJsonRpc) {
     logger.api(`Request method: ${requestData.method || "unknown"} (JSON-RPC)`);
@@ -38063,13 +38230,12 @@ async function wpRequest(requestData, useJsonRpc = true) {
       "NO_AUTH_METHOD"
     );
   }
-  const currentApiUrl = process.env.WP_API_URL || CONFIG.WP_API_URL;
   logger.debug(`Environment: ${CONFIG.NODE_ENV}`, "API");
-  logger.debug(`Base API URL: ${currentApiUrl}`, "API");
-  const url = constructApiUrl(currentApiUrl, endpoint);
+  logger.debug(`Base API URL: ${getCurrentApiUrl()}`, "API");
   logger.debug(`Final requesting URL: ${url}`, "API");
   const headers = {
     "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
     "MCP-Protocol-Version": "2025-06-18",
     // MCP protocol version
     ...customHeaders
@@ -38078,8 +38244,8 @@ async function wpRequest(requestData, useJsonRpc = true) {
   if (authHeader) {
     headers.Authorization = authHeader;
   }
-  if (globalSessionId) {
-    headers["Mcp-Session-Id"] = globalSessionId;
+  if (sessionIdUsed) {
+    headers["Mcp-Session-Id"] = sessionIdUsed;
   }
   if (authHeader) {
     logger.debug("Using Authorization header for authentication", "API");
@@ -38103,21 +38269,27 @@ async function wpRequest(requestData, useJsonRpc = true) {
     logger.debug(`Request method: ${method}`, "API");
     const response = await proxyFetch(url, fetchOptions);
     logger.debug(`Response status: ${response.status}`, "API");
+    const rawBody = await response.text();
     if (!response.ok) {
-      const errorText = await response.text();
-      logger.error(`API error response: ${errorText}`, "API");
+      logger.error(`API error response: ${rawBody}`, "API");
       throw new APIError(
-        `WordPress API error (${response.status}): ${errorText}`,
+        `WordPress API error (${response.status}): ${rawBody}`,
         response.status,
         url,
-        errorText
+        rawBody
       );
     }
-    const responseData = await response.json();
+    const contentType = response.headers.get("content-type") ?? "";
+    let responseData;
+    if (contentType.includes("text/event-stream")) {
+      responseData = parseSSEMessage(rawBody);
+      logger.debug("Parsed text/event-stream response body", "API");
+    } else {
+      responseData = JSON.parse(rawBody);
+    }
     const sessionIdHeader = response.headers.get("Mcp-Session-Id");
-    if (sessionIdHeader && !globalSessionId) {
-      globalSessionId = sessionIdHeader;
-      logger.info(`Session ID received from WordPress: ${globalSessionId}`, "SESSION");
+    if (sessionIdHeader) {
+      updateSessionId(sessionIdHeader);
     }
     logger.api("Response received successfully");
     logger.debug(`Response data: ${JSON.stringify(responseData)}`, "API");
@@ -38130,14 +38302,20 @@ async function wpRequest(requestData, useJsonRpc = true) {
             `WordPress JSON-RPC error: ${jsonrpcResponse.error.message}`,
             jsonrpcResponse.error.code || 500,
             url,
-            JSON.stringify(jsonrpcResponse.error)
+            jsonrpcResponse.error
           );
         } else if (jsonrpcResponse.result !== void 0) {
-          return jsonrpcResponse.result;
+          return {
+            responseData: jsonrpcResponse.result,
+            sessionIdUsed
+          };
         }
       }
     }
-    return responseData;
+    return {
+      responseData,
+      sessionIdUsed
+    };
   } catch (error) {
     if (error instanceof APIError) {
       throw error;
@@ -38147,6 +38325,77 @@ async function wpRequest(requestData, useJsonRpc = true) {
     throw new APIError(errorMessage, 0, url);
   }
 }
+async function refreshSession(failedSessionId) {
+  if (failedSessionId && globalSessionId && globalSessionId !== failedSessionId) {
+    logger.info("Detected newer session while handling invalid-session error; skipping refresh", "SESSION");
+    return;
+  }
+  if (sessionRefreshPromise) {
+    logger.info("Waiting for in-flight WordPress session refresh", "SESSION");
+    await sessionRefreshPromise;
+    return;
+  }
+  if (!lastInitializeRequest) {
+    throw new APIError(
+      "Cannot refresh WordPress session before initialize has completed",
+      0,
+      getRequestUrl()
+    );
+  }
+  sessionRefreshPromise = (async () => {
+    logger.warn("WordPress session rejected; refreshing session via initialize", "SESSION");
+    globalSessionId = null;
+    await executeWordPressRequest(
+      lastInitializeRequest.requestData,
+      lastInitializeRequest.useJsonRpc,
+      null
+    );
+    if (!globalSessionId) {
+      throw new APIError(
+        "WordPress initialize did not return a session ID during refresh",
+        0,
+        getRequestUrl()
+      );
+    }
+  })();
+  try {
+    await sessionRefreshPromise;
+  } finally {
+    sessionRefreshPromise = null;
+  }
+}
+async function wpRequest(requestData, useJsonRpc = true, options = {}) {
+  validateEnvironment();
+  const allowSessionRecovery = options.allowSessionRecovery !== false;
+  if (isInitializeRequest(requestData)) {
+    cacheInitializeRequest(requestData, useJsonRpc);
+  }
+  const sessionIdUsed = globalSessionId;
+  try {
+    const result = await executeWordPressRequest(requestData, useJsonRpc, sessionIdUsed);
+    return result.responseData;
+  } catch (error) {
+    if (error instanceof APIError && allowSessionRecovery && !isInitializeRequest(requestData) && isInvalidSessionError(error)) {
+      logger.warn("WordPress session expired; attempting one-time recovery", "SESSION", {
+        method: requestData?.method || "unknown",
+        sessionIdUsed: sessionIdUsed || "none"
+      });
+      await refreshSession(sessionIdUsed);
+      const retriedResult = await executeWordPressRequest(
+        requestData,
+        useJsonRpc,
+        globalSessionId
+      );
+      return retriedResult.responseData;
+    }
+    if (error instanceof APIError) {
+      throw error;
+    }
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error(`Error in wpRequest: ${errorMessage}`, "API");
+    throw new APIError(errorMessage, 0, getRequestUrl());
+  }
+}
 export {
   APIError,
   AuthError,

package/dist/proxy.js

@@ -92,13 +92,13 @@ var require_ponyfill_es2018 = __commonJS({
       typeof exports === "object" && typeof module !== "undefined" ? factory(exports) : typeof define === "function" && define.amd ? define(["exports"], factory) : (global2 = typeof globalThis !== "undefined" ? globalThis : global2 || self, factory(global2.WebStreamsPolyfill = {}));
     })(exports, function(exports2) {
       "use strict";
-      function noop2() {
+      function noop3() {
         return void 0;
       }
       function typeIsObject(x2) {
         return typeof x2 === "object" && x2 !== null || typeof x2 === "function";
       }
-      const rethrowAssertionErrorRejection = noop2;
+      const rethrowAssertionErrorRejection = noop3;
       function setFunctionName(fn, name) {
         try {
           Object.defineProperty(fn, "name", {
@@ -2727,7 +2727,7 @@ var require_ponyfill_es2018 = __commonJS({
               return newPromise((resolveRead, rejectRead) => {
                 ReadableStreamDefaultReaderRead(reader, {
                   _chunkSteps: (chunk) => {
-                    currentWrite = PerformPromiseThen(WritableStreamDefaultWriterWrite(writer, chunk), void 0, noop2);
+                    currentWrite = PerformPromiseThen(WritableStreamDefaultWriterWrite(writer, chunk), void 0, noop3);
                     resolveRead(false);
                   },
                   _closeSteps: () => resolveRead(true),
@@ -3408,7 +3408,7 @@ var require_ponyfill_es2018 = __commonJS({
       function ReadableStreamFromIterable(asyncIterable) {
         let stream;
         const iteratorRecord = GetIterator(asyncIterable, "async");
-        const startAlgorithm = noop2;
+        const startAlgorithm = noop3;
         function pullAlgorithm() {
           let nextResult;
           try {
@@ -3460,7 +3460,7 @@ var require_ponyfill_es2018 = __commonJS({
       }
       function ReadableStreamFromDefaultReader(reader) {
         let stream;
-        const startAlgorithm = noop2;
+        const startAlgorithm = noop3;
         function pullAlgorithm() {
           let readPromise;
           try {
@@ -3779,7 +3779,7 @@ var require_ponyfill_es2018 = __commonJS({
           });
         }
         const sourceCancelPromise = stream._readableStreamController[CancelSteps](reason);
-        return transformPromiseWith(sourceCancelPromise, noop2);
+        return transformPromiseWith(sourceCancelPromise, noop3);
       }
       function ReadableStreamClose(stream) {
         stream._state = "closed";
@@ -5000,7 +5000,7 @@ async function toFormData(Body2, ct) {
   parser.end();
   return formData;
 }
-var s, S, f2, F, LF, CR, SPACE, HYPHEN, COLON, A, Z, lower, noop, MultipartParser;
+var s, S, f2, F, LF, CR, SPACE, HYPHEN, COLON, A, Z, lower, noop2, MultipartParser;
 var init_multipart_parser = __esm({
   "node_modules/node-fetch/src/utils/multipart-parser.js"() {
     "use strict";
@@ -5032,7 +5032,7 @@ var init_multipart_parser = __esm({
     A = 97;
     Z = 122;
     lower = (c) => c | 32;
-    noop = () => {
+    noop2 = () => {
     };
     MultipartParser = class {
       /**
@@ -5041,13 +5041,13 @@ var init_multipart_parser = __esm({
       constructor(boundary) {
         this.index = 0;
         this.flags = 0;
-        this.onHeaderEnd = noop;
-        this.onHeaderField = noop;
-        this.onHeadersEnd = noop;
-        this.onHeaderValue = noop;
-        this.onPartBegin = noop;
-        this.onPartData = noop;
-        this.onPartEnd = noop;
+        this.onHeaderEnd = noop2;
+        this.onHeaderField = noop2;
+        this.onHeadersEnd = noop2;
+        this.onHeaderValue = noop2;
+        this.onPartBegin = noop2;
+        this.onPartData = noop2;
+        this.onPartEnd = noop2;
         this.boundaryChars = {};
         boundary = "\r\n--" + boundary;
         const ui8a = new Uint8Array(boundary.length);
@@ -7882,7 +7882,7 @@ var require_destroy = __commonJS({
       }
       if (isEventEmitter(stream) && suppress) {
         stream.removeAllListeners("error");
-        stream.addListener("error", noop2);
+        stream.addListener("error", noop3);
       }
       return stream;
     }
@@ -7937,7 +7937,7 @@ var require_destroy = __commonJS({
     function isZlibStream(stream) {
       return stream instanceof Zlib.Gzip || stream instanceof Zlib.Gunzip || stream instanceof Zlib.Deflate || stream instanceof Zlib.DeflateRaw || stream instanceof Zlib.Inflate || stream instanceof Zlib.InflateRaw || stream instanceof Zlib.Unzip;
     }
-    function noop2() {
+    function noop3() {
     }
     function onDrainClearBinding() {
       this._binding.clear();
@@ -35686,6 +35686,109 @@ var StdioServerTransport = class {
   }
 };
 
+// node_modules/eventsource-parser/dist/index.js
+var ParseError = class extends Error {
+  constructor(message, options) {
+    super(message), this.name = "ParseError", this.type = options.type, this.field = options.field, this.value = options.value, this.line = options.line;
+  }
+};
+function noop(_arg) {
+}
+function createParser(callbacks) {
+  if (typeof callbacks == "function")
+    throw new TypeError(
+      "`callbacks` must be an object, got a function instead. Did you mean `{onEvent: fn}`?"
+    );
+  const { onEvent = noop, onError = noop, onRetry = noop, onComment } = callbacks;
+  let incompleteLine = "", isFirstChunk = true, id, data = "", eventType = "";
+  function feed(newChunk) {
+    const chunk = isFirstChunk ? newChunk.replace(/^\xEF\xBB\xBF/, "") : newChunk, [complete, incomplete] = splitLines(`${incompleteLine}${chunk}`);
+    for (const line of complete)
+      parseLine(line);
+    incompleteLine = incomplete, isFirstChunk = false;
+  }
+  function parseLine(line) {
+    if (line === "") {
+      dispatchEvent();
+      return;
+    }
+    if (line.startsWith(":")) {
+      onComment && onComment(line.slice(line.startsWith(": ") ? 2 : 1));
+      return;
+    }
+    const fieldSeparatorIndex = line.indexOf(":");
+    if (fieldSeparatorIndex !== -1) {
+      const field = line.slice(0, fieldSeparatorIndex), offset = line[fieldSeparatorIndex + 1] === " " ? 2 : 1, value = line.slice(fieldSeparatorIndex + offset);
+      processField(field, value, line);
+      return;
+    }
+    processField(line, "", line);
+  }
+  function processField(field, value, line) {
+    switch (field) {
+      case "event":
+        eventType = value;
+        break;
+      case "data":
+        data = `${data}${value}
+`;
+        break;
+      case "id":
+        id = value.includes("\0") ? void 0 : value;
+        break;
+      case "retry":
+        /^\d+$/.test(value) ? onRetry(parseInt(value, 10)) : onError(
+          new ParseError(`Invalid \`retry\` value: "${value}"`, {
+            type: "invalid-retry",
+            value,
+            line
+          })
+        );
+        break;
+      default:
+        onError(
+          new ParseError(
+            `Unknown field "${field.length > 20 ? `${field.slice(0, 20)}\u2026` : field}"`,
+            { type: "unknown-field", field, value, line }
+          )
+        );
+        break;
+    }
+  }
+  function dispatchEvent() {
+    data.length > 0 && onEvent({
+      id,
+      event: eventType || void 0,
+      // If the data buffer's last character is a U+000A LINE FEED (LF) character,
+      // then remove the last character from the data buffer.
+      data: data.endsWith(`
+`) ? data.slice(0, -1) : data
+    }), id = void 0, data = "", eventType = "";
+  }
+  function reset(options = {}) {
+    incompleteLine && options.consume && parseLine(incompleteLine), isFirstChunk = true, id = void 0, data = "", eventType = "", incompleteLine = "";
+  }
+  return { feed, reset };
+}
+function splitLines(chunk) {
+  const lines = [];
+  let incompleteLine = "", searchIndex = 0;
+  for (; searchIndex < chunk.length; ) {
+    const crIndex = chunk.indexOf("\r", searchIndex), lfIndex = chunk.indexOf(`
+`, searchIndex);
+    let lineEnd = -1;
+    if (crIndex !== -1 && lfIndex !== -1 ? lineEnd = Math.min(crIndex, lfIndex) : crIndex !== -1 ? lineEnd = crIndex : lfIndex !== -1 && (lineEnd = lfIndex), lineEnd === -1) {
+      incompleteLine = chunk.slice(searchIndex);
+      break;
+    } else {
+      const line = chunk.slice(searchIndex, lineEnd);
+      lines.push(line), searchIndex = lineEnd + 1, chunk[searchIndex - 1] === "\r" && chunk[searchIndex] === `
+` && searchIndex++;
+    }
+  }
+  return [lines, incompleteLine];
+}
+
 // node_modules/pkce-challenge/dist/index.node.js
 var crypto;
 crypto = globalThis.crypto?.webcrypto ?? // Node.js [18-16] REPL
@@ -35775,10 +35878,9 @@ import path from "path";
 import fs from "fs/promises";
 import fsSync from "fs";
 import crypto2 from "crypto";
-var VERSION = MCP_WORDPRESS_REMOTE_VERSION;
 function getConfigDir() {
   const baseConfigDir = CONFIG.WP_MCP_CONFIG_DIR;
-  return path.join(baseConfigDir, `wordpress-remote-${VERSION}`);
+  return path.join(baseConfigDir, `wordpress-remote-${MCP_WORDPRESS_REMOTE_VERSION}`);
 }
 async function ensureConfigDir() {
   try {
@@ -36000,7 +36102,7 @@ function calculateDefaultPort(serverUrlHash) {
 }
 async function findExistingClientPort(serverUrlHash) {
   const clientInfo = await readJsonFile(serverUrlHash, "client_info.json");
-  if (!clientInfo) {
+  if (!clientInfo || !clientInfo.redirect_uris) {
     return void 0;
   }
   const localhostRedirectUri = clientInfo.redirect_uris.map((uri) => {
@@ -36036,7 +36138,7 @@ async function selectCallbackPort(serverUrl, specifiedPort, _unused) {
 }
 
 // src/lib/config.ts
-var MCP_WORDPRESS_REMOTE_VERSION = "0.2.19";
+var MCP_WORDPRESS_REMOTE_VERSION = "0.3.0";
 var CONFIG = {
   // API Configuration
   WP_API_URL: process.env.WP_API_URL || "https://example.com",
@@ -37514,17 +37616,14 @@ var OAuthCallbackServer = class {
     });
   }
   async stop() {
-    return new Promise((resolve) => {
-      if (this.server) {
-        this.server.close(() => {
-          logger.oauth("OAuth callback server stopped");
-          this.server = null;
-          resolve();
-        });
-      } else {
-        resolve();
-      }
+    if (!this.server) return;
+    const server = this.server;
+    this.server = null;
+    server.close((err) => {
+      if (err) logger.error("OAuth callback server close error", "OAUTH", err);
+      else logger.oauth("OAuth callback server stopped");
     });
+    server.closeAllConnections?.();
   }
   getCallbackUrl() {
     return `http://${this.options.host}:${this.options.port}/oauth/callback`;
@@ -38529,6 +38628,12 @@ var mcpOAuthProvider = null;
 var authCoordinator = null;
 var globalEvents = null;
 var globalSessionId = null;
+var lastInitializeRequest = null;
+var sessionRefreshPromise = null;
+var WP_MCP_ENDPOINT = "/wp/v2/wpmcp";
+var INVALID_SESSION_ERROR_CODES = /* @__PURE__ */ new Set([-32602, -32005]);
+var INVALID_SESSION_ERROR_MESSAGE = "Invalid or expired session";
+var SESSION_NOT_FOUND_ERROR_MESSAGE = "Session not found";
 function validateEnvironment() {
   const validation = validateConfig();
   if (!validation.isValid) {
@@ -38541,6 +38646,24 @@ function validateEnvironment() {
 function removeTrailingSlash(url) {
   return url.replace(/\/+$/, "");
 }
+function parseSSEMessage(text) {
+  let result;
+  let found = false;
+  const parser = createParser({
+    onEvent(event) {
+      if (found) return;
+      if (!event.event || event.event === "message") {
+        result = JSON.parse(event.data);
+        found = true;
+      }
+    }
+  });
+  parser.feed(text);
+  if (!found) {
+    throw new Error('No "message" event with data found in SSE response');
+  }
+  return result;
+}
 function constructApiUrl(baseUrl, defaultEndpoint) {
   const cleanUrl = removeTrailingSlash(baseUrl);
   try {
@@ -38630,9 +38753,53 @@ async function getOAuthTokens() {
 function getSessionId() {
   return globalSessionId;
 }
-async function wpRequest(requestData, useJsonRpc = true) {
-  validateEnvironment();
-  const endpoint = "/wp/v2/wpmcp";
+function getCurrentApiUrl() {
+  return process.env.WP_API_URL || CONFIG.WP_API_URL;
+}
+function getRequestUrl() {
+  return constructApiUrl(getCurrentApiUrl(), WP_MCP_ENDPOINT);
+}
+function cloneRequestData(requestData) {
+  return JSON.parse(JSON.stringify(requestData));
+}
+function isInitializeRequest(requestData) {
+  return requestData?.method === "initialize";
+}
+function cacheInitializeRequest(requestData, useJsonRpc) {
+  lastInitializeRequest = {
+    requestData: cloneRequestData(requestData),
+    useJsonRpc
+  };
+}
+function parseApiErrorResponse(error) {
+  if (!error.response) {
+    return null;
+  }
+  if (typeof error.response === "string") {
+    try {
+      return JSON.parse(error.response);
+    } catch {
+      return null;
+    }
+  }
+  return error.response;
+}
+function isInvalidSessionError(error) {
+  const errorResponse = parseApiErrorResponse(error);
+  const jsonRpcError = errorResponse?.error && typeof errorResponse.error === "object" ? errorResponse.error : errorResponse;
+  const code = typeof jsonRpcError?.code === "number" ? jsonRpcError.code : null;
+  const message = typeof jsonRpcError?.message === "string" ? jsonRpcError.message : "";
+  return code !== null && INVALID_SESSION_ERROR_CODES.has(code) && (message === INVALID_SESSION_ERROR_MESSAGE || message.includes(SESSION_NOT_FOUND_ERROR_MESSAGE) || message.includes(INVALID_SESSION_ERROR_MESSAGE));
+}
+function updateSessionId(sessionId) {
+  if (globalSessionId === sessionId) {
+    return;
+  }
+  globalSessionId = sessionId;
+  logger.info(`Session ID received from WordPress: ${globalSessionId}`, "SESSION");
+}
+async function executeWordPressRequest(requestData, useJsonRpc, sessionIdUsed) {
+  const url = getRequestUrl();
   const method = "POST";
   if (useJsonRpc) {
     logger.api(`Request method: ${requestData.method || "unknown"} (JSON-RPC)`);
@@ -38691,13 +38858,12 @@ async function wpRequest(requestData, useJsonRpc = true) {
       "NO_AUTH_METHOD"
     );
   }
-  const currentApiUrl = process.env.WP_API_URL || CONFIG.WP_API_URL;
   logger.debug(`Environment: ${CONFIG.NODE_ENV}`, "API");
-  logger.debug(`Base API URL: ${currentApiUrl}`, "API");
-  const url = constructApiUrl(currentApiUrl, endpoint);
+  logger.debug(`Base API URL: ${getCurrentApiUrl()}`, "API");
   logger.debug(`Final requesting URL: ${url}`, "API");
   const headers = {
     "Content-Type": "application/json",
+    Accept: "application/json, text/event-stream",
     "MCP-Protocol-Version": "2025-06-18",
     // MCP protocol version
     ...customHeaders
@@ -38706,8 +38872,8 @@ async function wpRequest(requestData, useJsonRpc = true) {
   if (authHeader) {
     headers.Authorization = authHeader;
   }
-  if (globalSessionId) {
-    headers["Mcp-Session-Id"] = globalSessionId;
+  if (sessionIdUsed) {
+    headers["Mcp-Session-Id"] = sessionIdUsed;
   }
   if (authHeader) {
     logger.debug("Using Authorization header for authentication", "API");
@@ -38731,21 +38897,27 @@ async function wpRequest(requestData, useJsonRpc = true) {
     logger.debug(`Request method: ${method}`, "API");
     const response = await proxyFetch(url, fetchOptions);
     logger.debug(`Response status: ${response.status}`, "API");
+    const rawBody = await response.text();
     if (!response.ok) {
-      const errorText = await response.text();
-      logger.error(`API error response: ${errorText}`, "API");
+      logger.error(`API error response: ${rawBody}`, "API");
       throw new APIError(
-        `WordPress API error (${response.status}): ${errorText}`,
+        `WordPress API error (${response.status}): ${rawBody}`,
         response.status,
         url,
-        errorText
+        rawBody
       );
     }
-    const responseData = await response.json();
+    const contentType = response.headers.get("content-type") ?? "";
+    let responseData;
+    if (contentType.includes("text/event-stream")) {
+      responseData = parseSSEMessage(rawBody);
+      logger.debug("Parsed text/event-stream response body", "API");
+    } else {
+      responseData = JSON.parse(rawBody);
+    }
     const sessionIdHeader = response.headers.get("Mcp-Session-Id");
-    if (sessionIdHeader && !globalSessionId) {
-      globalSessionId = sessionIdHeader;
-      logger.info(`Session ID received from WordPress: ${globalSessionId}`, "SESSION");
+    if (sessionIdHeader) {
+      updateSessionId(sessionIdHeader);
     }
     logger.api("Response received successfully");
     logger.debug(`Response data: ${JSON.stringify(responseData)}`, "API");
@@ -38758,14 +38930,20 @@ async function wpRequest(requestData, useJsonRpc = true) {
             `WordPress JSON-RPC error: ${jsonrpcResponse.error.message}`,
             jsonrpcResponse.error.code || 500,
             url,
-            JSON.stringify(jsonrpcResponse.error)
+            jsonrpcResponse.error
           );
         } else if (jsonrpcResponse.result !== void 0) {
-          return jsonrpcResponse.result;
+          return {
+            responseData: jsonrpcResponse.result,
+            sessionIdUsed
+          };
         }
       }
     }
-    return responseData;
+    return {
+      responseData,
+      sessionIdUsed
+    };
   } catch (error) {
     if (error instanceof APIError) {
       throw error;
@@ -38775,6 +38953,77 @@ async function wpRequest(requestData, useJsonRpc = true) {
     throw new APIError(errorMessage, 0, url);
   }
 }
+async function refreshSession(failedSessionId) {
+  if (failedSessionId && globalSessionId && globalSessionId !== failedSessionId) {
+    logger.info("Detected newer session while handling invalid-session error; skipping refresh", "SESSION");
+    return;
+  }
+  if (sessionRefreshPromise) {
+    logger.info("Waiting for in-flight WordPress session refresh", "SESSION");
+    await sessionRefreshPromise;
+    return;
+  }
+  if (!lastInitializeRequest) {
+    throw new APIError(
+      "Cannot refresh WordPress session before initialize has completed",
+      0,
+      getRequestUrl()
+    );
+  }
+  sessionRefreshPromise = (async () => {
+    logger.warn("WordPress session rejected; refreshing session via initialize", "SESSION");
+    globalSessionId = null;
+    await executeWordPressRequest(
+      lastInitializeRequest.requestData,
+      lastInitializeRequest.useJsonRpc,
+      null
+    );
+    if (!globalSessionId) {
+      throw new APIError(
+        "WordPress initialize did not return a session ID during refresh",
+        0,
+        getRequestUrl()
+      );
+    }
+  })();
+  try {
+    await sessionRefreshPromise;
+  } finally {
+    sessionRefreshPromise = null;
+  }
+}
+async function wpRequest(requestData, useJsonRpc = true, options = {}) {
+  validateEnvironment();
+  const allowSessionRecovery = options.allowSessionRecovery !== false;
+  if (isInitializeRequest(requestData)) {
+    cacheInitializeRequest(requestData, useJsonRpc);
+  }
+  const sessionIdUsed = globalSessionId;
+  try {
+    const result = await executeWordPressRequest(requestData, useJsonRpc, sessionIdUsed);
+    return result.responseData;
+  } catch (error) {
+    if (error instanceof APIError && allowSessionRecovery && !isInitializeRequest(requestData) && isInvalidSessionError(error)) {
+      logger.warn("WordPress session expired; attempting one-time recovery", "SESSION", {
+        method: requestData?.method || "unknown",
+        sessionIdUsed: sessionIdUsed || "none"
+      });
+      await refreshSession(sessionIdUsed);
+      const retriedResult = await executeWordPressRequest(
+        requestData,
+        useJsonRpc,
+        globalSessionId
+      );
+      return retriedResult.responseData;
+    }
+    if (error instanceof APIError) {
+      throw error;
+    }
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    logger.error(`Error in wpRequest: ${errorMessage}`, "API");
+    throw new APIError(errorMessage, 0, getRequestUrl());
+  }
+}
 
 // src/lib/session-utils.ts
 function addSessionInfo(wpRequestParams, mcpRequest, context) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@automattic/mcp-wordpress-remote",
-  "version": "0.2.21",
+  "version": "0.3.1",
   "description": "MCP WordPress Remote proxy server",
   "engines": {
     "node": ">=18.0.0"
@@ -34,7 +34,7 @@
     }
   },
   "bin": {
-    "@automattic/mcp-wordpress-remote": "dist/proxy.js"
+    "mcp-wordpress-remote": "./dist/proxy.js"
   },
   "scripts": {
     "build": "tsup",
@@ -60,6 +60,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.8.0",
     "@tootallnate/quickjs-emscripten": "^0.23.0",
+    "eventsource-parser": "^3.0.1",
     "express": "^4.18.2",
     "https-proxy-agent": "^7.0.6",
     "node-fetch": "^3.3.2",
@@ -100,6 +101,7 @@
     "splitting": false,
     "noExternal": [
       "@modelcontextprotocol/sdk",
+      "eventsource-parser",
       "express",
       "node-fetch",
       "open"