@respira/wordpress-mcp-server 7.5.1 → 7.5.2

package/README.md

@@ -35,6 +35,22 @@ Other WordPress MCP servers wrap the REST API. They can create posts and pages,
 
 Respira includes a WordPress plugin that gives AI **native access** to 16 page builders, plus element-level precision, full page creation from structure, HTML-to-builder conversion, storefront design intelligence, stock image search, and bulk operations across hundreds of pages.
 
+### New in v7.5.2: reconnect-safe writes and drop diagnostics
+
+- **Writes carry a stable idempotency key.** The connector automatically retries transient reads. It retries a write only when WordPress explicitly confirms replay support; an ambiguous timeout/reset is reported as `respira_write_outcome_unknown` so the agent verifies the target before trying again.
+- **Telemetry queues and retries independently of tool execution.** A dashboard or network interruption cannot block a WordPress call, and failed metadata batches are retained with bounded exponential backoff.
+- **Local API keys stay local.** With Respira for WordPress 7.5.46+, a local `respira_*` key is exchanged inside WordPress for a revocable, site-scoped telemetry bearer. The central service never receives that local key.
+- **The quality dashboard can separate exact retries from editing sweeps.** It records stable session/call identity, transport, incomplete calls, connector/plugin versions, total vs tool time, and privacy-safe stage durations. Target comparison uses a secret HMAC; arguments, results, prompts, and WordPress content are never sent.
+- **Native URL-connected clients gain timeout-safe writes.** Plugin 7.5.46 adds `_respira_async: true`, `respira_get_job_status`, stable `Mcp-Session-Id` responses, replay-safe `_respira_call_id`, and a native `respira_diagnose_connection` tool. The native endpoint is stateless HTTP—independent POST requests, not a persistent “write channel.”
+
+### Also shipped since the README's previous v7.1 refresh
+
+- **v7.2:** cascade session rollback; dropped-styling/no-op guidance; page-parent schemas; Oxygen 6 build guidance; completed live-edit confirmation parameters; bounded heavy-write/docs timeouts; and route-aware capability negotiation that hides tools an older plugin cannot execute.
+- **v7.3:** the WooCommerce add-on expanded from 21 to 56 tools across catalog, pricing, stock, storefront, brands, variations/attributes, coupons, customers, refunds, and AI-readiness.
+- **v7.4:** Agent-Ready Commerce expanded WooCommerce to 79 tools with feeds + store `llms.txt`, readiness fixes, signed cart links/attribution, and Subscriptions, Bookings, and Memberships writes. v7.4.1 then made newly connected dashboard sites self-heal into a running connector session.
+- **v7.5.0:** eight STAGGS configurator tools brought the WooCommerce total to 87.
+- **v7.5.1:** fixed normalized ACF tool routing and preserved dashboard-token 401 machine codes—the two fixes shipped immediately before this reliability release.
+
 ### New in v7.1 "Roots"
 
 The biggest release since launch.
@@ -43,7 +59,7 @@ The biggest release since launch.
 - **Make a page responsive in one call** on Bricks, Elementor, Divi 4, Beaver Builder, and WPBakery.
 - **Playbooks.** Teach an agent a multi-step workflow once and rerun it as a single callable WordPress Ability. Five tools (create / list / get / update / delete), with static cycle detection and a runtime depth cap.
 - **Agent-creatable Custom Post Types, taxonomies, and ACF field groups** (twelve tools), stored in options and registered on `init`. No PHP files, server-side slug allowlist, conservative deletes that report orphans.
-- **Native in-WP MCP endpoint.** Point a client straight at `your-site/?respira=mcp` (Streamable HTTP, JSON-RPC) with an API key, no npx process required. One-click connect-by-link mints and installs the key for you.
+- **Native in-WP MCP endpoint.** Point a client straight at `your-site/wp-json/respira/v1/mcp` (Streamable HTTP JSON-RPC; `?rest_route=` fallback supported) with an API key, no npx process required. One-click connect-by-link mints and installs the key for you.
 - **System certificate-store trust.** The connector trusts the OS certificate store at startup (verification stays on) with a bundled Mozilla CA fallback, so valid public certs stop being rejected on Claude Desktop's bundled Node.
 - **Bricks design-token import + section presets**, the **Elementor 4 atomic write path** (partial: 20 atomic element types with `$$type` envelopes, per-breakpoint + per-state styling, and a clear 422 on unsupported types instead of a silent drop), and **`respira_generate_activity_report`** for client-ready reports.
 
@@ -61,7 +77,7 @@ The triage rule, baked into the handshake instructions: tool error → apply hin
 
 ### v6.16.0: usage telemetry ships by default
 
-Every customer's MCP now ships per-tool-call telemetry to the Respira dashboard without setup. Previously the emitter was gated on customers having generated an `rp_otel_*` OTEL bearer, a step almost nobody completed; the audit showed only one distinct user shipping data despite ~41 sites on v6.14.0+. The emitter now falls back to the per-site license api_token, so any customer on v6.16.0+ ships telemetry by default. Privacy hard line unchanged: metadata only, no prompts, no tool args, no tool results, no WP content. `RESPIRA_USAGE_OPT_OUT=1` disables the entire stream.
+v6.16 introduced default per-tool telemetry so customers did not have to configure an OTEL bearer. As of v7.5.2 with plugin 7.5.46+, local WordPress API keys are never sent to the central ingest: the connector asks WordPress for a revocable, site-scoped telemetry token instead. Privacy remains metadata-only—no prompts, raw tool arguments, tool results, or WordPress content. `RESPIRA_USAGE_OPT_OUT=1` disables the entire stream.
 
 ### v6.3 — MCP Protocol Compliance
 

package/dist/__tests__/usage-emitter-privacy.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=usage-emitter-privacy.test.d.ts.map

package/dist/__tests__/usage-emitter-privacy.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-emitter-privacy.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/usage-emitter-privacy.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/usage-emitter-privacy.test.js

@@ -0,0 +1,16 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { isDirectTelemetryBearer } from '../usage-emitter.js';
+describe('usage emitter credential privacy', () => {
+    it('never treats a local WordPress key as a central-ingest bearer', () => {
+        assert.equal(isDirectTelemetryBearer('respira_local-secret'), false);
+        assert.equal(isDirectTelemetryBearer('respira_0123456789abcdef'), false);
+    });
+    it('accepts only explicitly central-scoped bearer families', () => {
+        assert.equal(isDirectTelemetryBearer('respira_site_abc'), true);
+        assert.equal(isDirectTelemetryBearer('rsp_at_abc'), true);
+        assert.equal(isDirectTelemetryBearer('rp_mcp_abc'), true);
+        assert.equal(isDirectTelemetryBearer('rp_otel_abc'), false);
+    });
+});
+//# sourceMappingURL=usage-emitter-privacy.test.js.map

package/dist/__tests__/usage-emitter-privacy.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"usage-emitter-privacy.test.js","sourceRoot":"","sources":["../../src/__tests__/usage-emitter-privacy.test.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAEzC,OAAO,EAAE,uBAAuB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,QAAQ,CAAC,kCAAkC,EAAE,GAAG,EAAE;IAChD,EAAE,CAAC,+DAA+D,EAAE,GAAG,EAAE;QACvE,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,sBAAsB,CAAC,EAAE,KAAK,CAAC,CAAC;QACrE,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,0BAA0B,CAAC,EAAE,KAAK,CAAC,CAAC;IAC3E,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAC,CAAC;QAChE,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,CAAC;QAC1D,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,CAAC;QAC1D,MAAM,CAAC,KAAK,CAAC,uBAAuB,CAAC,aAAa,CAAC,EAAE,KAAK,CAAC,CAAC;IAC9D,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/__tests__/write-retry-safety.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=write-retry-safety.test.d.ts.map

package/dist/__tests__/write-retry-safety.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-retry-safety.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/write-retry-safety.test.ts"],"names":[],"mappings":""}

package/dist/__tests__/write-retry-safety.test.js

@@ -0,0 +1,36 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ensureWriteIdempotencyKey, isReplaySafeRetry, } from "../wordpress-client.js";
+test("mutations receive one stable idempotency key while reads do not", () => {
+    const write = { method: "post", headers: {} };
+    ensureWriteIdempotencyKey(write, () => "call_12345678");
+    ensureWriteIdempotencyKey(write, () => "should_not_replace");
+    assert.equal(write.headers["Idempotency-Key"], "call_12345678");
+    const read = { method: "get", headers: {} };
+    ensureWriteIdempotencyKey(read, () => "should_not_exist");
+    assert.equal(read.headers["Idempotency-Key"], undefined);
+});
+test("reads retry transient responses and connection failures", () => {
+    assert.equal(isReplaySafeRetry({ method: "GET", status: 500 }), true);
+    assert.equal(isReplaySafeRetry({ method: "GET", connectionCode: "ECONNRESET" }), true);
+    assert.equal(isReplaySafeRetry({ method: "GET", status: 404 }), false);
+});
+test("writes retry only explicit replay-safe gateway responses", () => {
+    assert.equal(isReplaySafeRetry({
+        method: "POST",
+        status: 503,
+        idempotencySupported: true,
+    }), true);
+    assert.equal(isReplaySafeRetry({
+        method: "POST",
+        status: 503,
+        idempotencySupported: false,
+    }), false);
+    assert.equal(isReplaySafeRetry({
+        method: "POST",
+        status: 500,
+        idempotencySupported: true,
+    }), false);
+    assert.equal(isReplaySafeRetry({ method: "POST", connectionCode: "ECONNRESET" }), false);
+});
+//# sourceMappingURL=write-retry-safety.test.js.map

package/dist/__tests__/write-retry-safety.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-retry-safety.test.js","sourceRoot":"","sources":["../../src/__tests__/write-retry-safety.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EACL,yBAAyB,EACzB,iBAAiB,GAClB,MAAM,wBAAwB,CAAC;AAEhC,IAAI,CAAC,iEAAiE,EAAE,GAAG,EAAE;IAC3E,MAAM,KAAK,GAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACnD,yBAAyB,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,eAAe,CAAC,CAAC;IACxD,yBAAyB,CAAC,KAAK,EAAE,GAAG,EAAE,CAAC,oBAAoB,CAAC,CAAC;IAC7D,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,eAAe,CAAC,CAAC;IAEhE,MAAM,IAAI,GAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC;IACjD,yBAAyB,CAAC,IAAI,EAAE,GAAG,EAAE,CAAC,kBAAkB,CAAC,CAAC;IAC1D,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,iBAAiB,CAAC,EAAE,SAAS,CAAC,CAAC;AAC3D,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,yDAAyD,EAAE,GAAG,EAAE;IACnE,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;IACtE,MAAM,CAAC,KAAK,CACV,iBAAiB,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,EAClE,IAAI,CACL,CAAC;IACF,MAAM,CAAC,KAAK,CAAC,iBAAiB,CAAC,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,EAAE,KAAK,CAAC,CAAC;AACzE,CAAC,CAAC,CAAC;AAEH,IAAI,CAAC,0DAA0D,EAAE,GAAG,EAAE;IACpE,MAAM,CAAC,KAAK,CACV,iBAAiB,CAAC;QAChB,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,GAAG;QACX,oBAAoB,EAAE,IAAI;KAC3B,CAAC,EACF,IAAI,CACL,CAAC;IACF,MAAM,CAAC,KAAK,CACV,iBAAiB,CAAC;QAChB,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,GAAG;QACX,oBAAoB,EAAE,KAAK;KAC5B,CAAC,EACF,KAAK,CACN,CAAC;IACF,MAAM,CAAC,KAAK,CACV,iBAAiB,CAAC;QAChB,MAAM,EAAE,MAAM;QACd,MAAM,EAAE,GAAG;QACX,oBAAoB,EAAE,IAAI;KAC3B,CAAC,EACF,KAAK,CACN,CAAC;IACF,MAAM,CAAC,KAAK,CACV,iBAAiB,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,cAAc,EAAE,YAAY,EAAE,CAAC,EACnE,KAAK,CACN,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/server.d.ts

@@ -203,6 +203,8 @@ export declare class RespiraWordPressServer {
      */
     private normalizeArgsForBackCompat;
     private handleToolCall;
+    /** Privacy-safe target HMAC: arguments never leave this process. */
+    private telemetryArgsHash;
     /**
      * v6.18.2: enforce a response-size cap on tool results.
      *

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAoBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAkQzE,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,mBAAmB,CAAS;IACpC,iFAAiF;IACjF,OAAO,CAAC,iBAAiB,CAAK;IAC9B,iFAAiF;IACjF,OAAO,CAAC,mBAAmB,CAAgC;IAE3D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAsB;IAEhE;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;gBA4Bb,WAAW,EAAE,mBAAmB,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE;IAiVvE,OAAO,CAAC,cAAc;IAItB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IA4BrB,gEAAgE;IAChE,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,UAAU;IA2CxB;;;;;;;;;;;;;;OAcG;YACW,WAAW;IAiJzB;;;;;;;;;OASG;YACW,kBAAkB;IAiHhC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;YACW,qBAAqB;YAiBrB,kBAAkB;IA6FhC,yFAAyF;IACzF,OAAO,CAAC,gBAAgB;IASxB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,6BAA6B;IA0BrC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IA+BjC,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;YAmQP,kBAAkB;YA6BlB,yBAAyB;IASvC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAyBd,QAAQ;IA+vFtB;;;;;;OAMG;IACH,yEAAyE;IACzE,OAAO,CAAC,mBAAmB,CAAoD;IAC/E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;YAEpC,oBAAoB;YAqDpB,2BAA2B;IAazC;;;;OAIG;YACW,cAAc;IAY5B,OAAO,CAAC,mBAAmB;IA2uC3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAe3C;IAEF;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;YAmCpB,cAAc;IAqG5B;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;YAuCT,gBAAgB;IAimC9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwUzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6UxB,GAAG;CAyCV"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAqBH,OAAO,KAAK,EAAE,mBAAmB,EAAe,MAAM,kBAAkB,CAAC;AAsQzE,qBAAa,sBAAsB;IACjC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,WAAW,CAAgC;IACnD,OAAO,CAAC,KAAK,CAA2C;IACxD,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,cAAc,CAAwB;IAC9C,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,YAAY,CAA4B;IAChD,8EAA8E;IAC9E,OAAO,CAAC,mBAAmB,CAAS;IACpC,iFAAiF;IACjF,OAAO,CAAC,iBAAiB,CAAK;IAC9B,iFAAiF;IACjF,OAAO,CAAC,mBAAmB,CAAgC;IAE3D,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAsB;IAEhE;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAWzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;gBA4Bb,WAAW,EAAE,mBAAmB,EAAE,EAAE,YAAY,CAAC,EAAE,MAAM,EAAE;IAiVvE,OAAO,CAAC,cAAc;IAItB;;;;;;;;;OASG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,aAAa;IA4BrB,gEAAgE;IAChE,OAAO,CAAC,aAAa;IAUrB;;;;;;OAMG;YACW,UAAU;IA2CxB;;;;;;;;;;;;;;OAcG;YACW,WAAW;IAiJzB;;;;;;;;;OASG;YACW,kBAAkB;IAiHhC;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;YACW,qBAAqB;YAiBrB,kBAAkB;IA6FhC,yFAAyF;IACzF,OAAO,CAAC,gBAAgB;IASxB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,6BAA6B;IA0BrC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,yBAAyB;IA+BjC,OAAO,CAAC,eAAe;IAmBvB,OAAO,CAAC,aAAa;YAmQP,kBAAkB;YA6BlB,yBAAyB;IASvC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;YAyBd,QAAQ;IA+vFtB;;;;;;OAMG;IACH,yEAAyE;IACzE,OAAO,CAAC,mBAAmB,CAAoD;IAC/E,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,gBAAgB,CAAU;YAEpC,oBAAoB;YAqDpB,2BAA2B;IAazC;;;;OAIG;YACW,cAAc;IAY5B,OAAO,CAAC,mBAAmB;IA2uC3B;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,qBAAqB,CAe3C;IAEF;;;;OAIG;IACH,OAAO,CAAC,0BAA0B;YAmCpB,cAAc;IA4G5B,oEAAoE;IACpE,OAAO,CAAC,iBAAiB;IAoBzB;;;;;;;;;;;;;;;;;;;OAmBG;IACH,OAAO,CAAC,eAAe;YAuCT,gBAAgB;IAimC9B;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAwUzB;;OAEG;IACH,OAAO,CAAC,sBAAsB;IA6UxB,GAAG;CAyCV"}

package/dist/server.js

@@ -11,12 +11,16 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
 import { dirname, join, resolve } from 'path';
 import { fileURLToPath } from 'url';
+import { createHmac, randomUUID } from 'node:crypto';
 import { WordPressClient } from './wordpress-client.js';
 import { RespiraVersionChecker } from './version-checker.js';
 import { getBricksTools, dispatchBricksTool } from './bricks-tools.js';
 import { getElementorTools, dispatchElementorTool } from './elementor-tools.js';
 import { getAcfTools, resolveAcfToolName } from './acf-tools.js';
 import { getUsageEmitter, deriveToolKind } from './usage-emitter.js';
+// Process-local secret keeps target hashes useful for same-session retry
+// detection without making low-entropy WordPress ids reversible centrally.
+const TELEMETRY_HASH_SECRET = randomUUID();
 /**
  * Read the server version from package.json at module load time so the
  * MCP handshake, the `instructions` block, and the version-checker all
@@ -617,7 +621,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
             // gracefully when neither is.
             if (config.apiKey && config.url) {
                 try {
-                    getUsageEmitter().registerSiteToken(config.url, config.apiKey);
+                    getUsageEmitter().registerSiteToken(config.url, config.apiKey, () => client.getTelemetryToken());
                 }
                 catch {
                     // Best-effort; usage telemetry never blocks server startup.
@@ -1161,7 +1165,7 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     this.defaultSiteId = s.id;
                 }
                 try {
-                    getUsageEmitter().registerSiteToken(s.url, s.apiKey);
+                    getUsageEmitter().registerSiteToken(s.url, s.apiKey, () => client.getTelemetryToken());
                 }
                 catch {
                     // usage telemetry never blocks
@@ -5784,13 +5788,16 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         finally {
             if (emitter.isEnabled()) {
                 let siteUrl = null;
+                let pluginVersion = null;
                 try {
                     if (!SITE_AGNOSTIC_TOOLS.has(canonical)) {
                         const client = this.resolveClient(args);
                         siteUrl = client.getSiteUrl();
+                        pluginVersion = client.pluginVersion;
                     }
                     else if (this.currentSite) {
                         siteUrl = this.currentSite.getSiteUrl();
+                        pluginVersion = this.currentSite.pluginVersion;
                     }
                 }
                 catch {
@@ -5845,6 +5852,10 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
                     durationMs: Date.now() - startedAt,
                     success: dispatchError === null,
                     errorCode,
+                    targetArgsHash: this.telemetryArgsHash(canonical, args),
+                    stageTimings: result?.write_diag?.stage_timings || result?.stage_timings || null,
+                    pluginVersion,
+                    mcpVersion: MCP_SERVER_VERSION,
                 });
             }
         }
@@ -5857,6 +5868,28 @@ Allowlist: css, scss, less, json. PHP / JS theme writes are intentionally out of
         }
         return this.capResponseSize(canonical, result);
     }
+    /** Privacy-safe target HMAC: arguments never leave this process. */
+    telemetryArgsHash(toolName, args) {
+        try {
+            const canonicalize = (value) => {
+                if (Array.isArray(value))
+                    return value.map(canonicalize);
+                if (value && typeof value === 'object') {
+                    return Object.keys(value).sort().reduce((out, key) => {
+                        out[key] = canonicalize(value[key]);
+                        return out;
+                    }, {});
+                }
+                return value;
+            };
+            return createHmac('sha256', TELEMETRY_HASH_SECRET)
+                .update(`${toolName}|${JSON.stringify(canonicalize(args))}`)
+                .digest('hex');
+        }
+        catch {
+            return null;
+        }
+    }
     /**
      * v6.18.2: enforce a response-size cap on tool results.
      *