@respira/wordpress-mcp-server 7.1.0 → 7.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +17 -5
- package/dist/__tests__/startup-guard.test.d.ts +2 -0
- package/dist/__tests__/startup-guard.test.d.ts.map +1 -0
- package/dist/__tests__/startup-guard.test.js +49 -0
- package/dist/__tests__/startup-guard.test.js.map +1 -0
- package/dist/index.js +11 -0
- package/dist/index.js.map +1 -1
- package/dist/startup-guard.d.ts +73 -0
- package/dist/startup-guard.d.ts.map +1 -0
- package/dist/startup-guard.js +169 -0
- package/dist/startup-guard.js.map +1 -0
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
<p align="center">
|
|
2
2
|
<a href="https://respira.press">
|
|
3
|
-
<img src="https://respira.press/hero/
|
|
3
|
+
<img src="https://respira.press/hero/respira-mcp-kv.jpg" alt="Respira for WordPress, the AI infrastructure layer for WordPress" width="100%">
|
|
4
4
|
</a>
|
|
5
5
|
</p>
|
|
6
6
|
|
|
7
7
|
<h1 align="center">Respira WordPress MCP Server</h1>
|
|
8
8
|
|
|
9
9
|
<p align="center">
|
|
10
|
-
<strong>180+ MCP tools.
|
|
10
|
+
<strong>180+ MCP tools. 16 page builders. Context-aware tool filtering. The AI infrastructure layer for WordPress.</strong><br>
|
|
11
11
|
Element-level editing, full page creation, HTML-to-builder conversion with rendering fidelity validation, per-site tool governance, storefront design intelligence, stock images, bulk operations — all through one MCP server.
|
|
12
12
|
</p>
|
|
13
13
|
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
<a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/v/@respira/wordpress-mcp-server.svg?style=flat-square&color=10b981" alt="npm version"></a>
|
|
16
16
|
<a href="https://www.npmjs.com/package/@respira/wordpress-mcp-server"><img src="https://img.shields.io/npm/dm/@respira/wordpress-mcp-server.svg?style=flat-square" alt="npm downloads"></a>
|
|
17
17
|
<img src="https://img.shields.io/badge/tools-172+-10b981?style=flat-square" alt="172+ Tools">
|
|
18
|
-
<img src="https://img.shields.io/badge/builders-
|
|
18
|
+
<img src="https://img.shields.io/badge/builders-16-10b981?style=flat-square" alt="16 Page Builders">
|
|
19
19
|
<img src="https://img.shields.io/badge/TypeScript-100%25-blue?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript">
|
|
20
20
|
</p>
|
|
21
21
|
|
|
@@ -33,7 +33,19 @@
|
|
|
33
33
|
|
|
34
34
|
Other WordPress MCP servers wrap the REST API. They can create posts and pages, but **they can't touch your page builder content**.
|
|
35
35
|
|
|
36
|
-
Respira includes a WordPress plugin that gives AI **native access** to
|
|
36
|
+
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.
|
|
37
|
+
|
|
38
|
+
### New in v7.1 "Roots"
|
|
39
|
+
|
|
40
|
+
The biggest release since launch.
|
|
41
|
+
|
|
42
|
+
- **Four new page builders.** Spectra, Kadence Blocks, and GenerateBlocks join with full read + write; SeedProd ships read + audit. Supported builders go from 12 to 16.
|
|
43
|
+
- **Make any builder responsive in one call** across Bricks, Elementor, Divi 4, Beaver Builder, and WPBakery.
|
|
44
|
+
- **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.
|
|
45
|
+
- **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.
|
|
46
|
+
- **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.
|
|
47
|
+
- **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.
|
|
48
|
+
- **Bricks design-token import + section presets**, the **Elementor 4 atomic write path**, and **`respira_generate_activity_report`** for client-ready reports.
|
|
37
49
|
|
|
38
50
|
### New in v6.17.0: an MCP that knows how to behave
|
|
39
51
|
|
|
@@ -61,7 +73,7 @@ The MCP server automatically filters the tool list based on your site's detected
|
|
|
61
73
|
|
|
62
74
|
| Capability | Respira | Other MCP Servers |
|
|
63
75
|
|---|---|---|
|
|
64
|
-
| Page builder support | **
|
|
76
|
+
| Page builder support | **16 builders** (incl. Spectra, Kadence, GenerateBlocks) | None |
|
|
65
77
|
| Element-level find/update/move/remove | **Yes** | No |
|
|
66
78
|
| Build full pages from structure | **Yes** | No |
|
|
67
79
|
| Convert HTML to native builder | **Yes** | No |
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"startup-guard.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/startup-guard.test.ts"],"names":[],"mappings":""}
|
|
@@ -0,0 +1,49 @@
|
|
|
1
|
+
import { test } from 'node:test';
|
|
2
|
+
import assert from 'node:assert/strict';
|
|
3
|
+
import { compareVersions, getConfiguredMinConnectorVersion, assertConnectorMeetsConfig, OutdatedConnectorError, } from '../startup-guard.js';
|
|
4
|
+
test('compareVersions orders semver correctly', () => {
|
|
5
|
+
assert.equal(compareVersions('7.1.4', '7.1.4'), 0);
|
|
6
|
+
assert.equal(compareVersions('6.11.4', '7.1.0'), -1);
|
|
7
|
+
assert.equal(compareVersions('7.2.0', '7.1.9'), 1);
|
|
8
|
+
assert.equal(compareVersions('7.0.10', '7.0.9'), 1);
|
|
9
|
+
assert.equal(compareVersions('6.9.0', '7.0.0'), -1);
|
|
10
|
+
});
|
|
11
|
+
test('compareVersions treats unparseable versions as equal (never blocks)', () => {
|
|
12
|
+
assert.equal(compareVersions('unknown', '7.1.0'), 0);
|
|
13
|
+
assert.equal(compareVersions('7.1.0', 'not-a-version'), 0);
|
|
14
|
+
});
|
|
15
|
+
test('getConfiguredMinConnectorVersion reads metadata.minConnectorVersion', () => {
|
|
16
|
+
assert.equal(getConfiguredMinConnectorVersion({ metadata: { minConnectorVersion: '7.1.0' } }), '7.1.0');
|
|
17
|
+
assert.equal(getConfiguredMinConnectorVersion({ metadata: {} }), null);
|
|
18
|
+
assert.equal(getConfiguredMinConnectorVersion({}), null);
|
|
19
|
+
assert.equal(getConfiguredMinConnectorVersion(null), null);
|
|
20
|
+
assert.equal(getConfiguredMinConnectorVersion({ metadata: { minConnectorVersion: ' ' } }), null);
|
|
21
|
+
});
|
|
22
|
+
test('assertConnectorMeetsConfig is a no-op when no floor is declared', () => {
|
|
23
|
+
assert.doesNotThrow(() => assertConnectorMeetsConfig({ metadata: {} }, '6.0.0'));
|
|
24
|
+
assert.doesNotThrow(() => assertConnectorMeetsConfig({ sites: [] }, '1.0.0'));
|
|
25
|
+
});
|
|
26
|
+
test('assertConnectorMeetsConfig passes when the build meets or exceeds the floor', () => {
|
|
27
|
+
const cfg = { metadata: { minConnectorVersion: '7.1.0' } };
|
|
28
|
+
assert.doesNotThrow(() => assertConnectorMeetsConfig(cfg, '7.1.0'));
|
|
29
|
+
assert.doesNotThrow(() => assertConnectorMeetsConfig(cfg, '7.2.0'));
|
|
30
|
+
});
|
|
31
|
+
test('assertConnectorMeetsConfig throws an actionable error when the build is too old', () => {
|
|
32
|
+
const cfg = { metadata: { minConnectorVersion: '7.1.0' } };
|
|
33
|
+
assert.throws(() => assertConnectorMeetsConfig(cfg, '6.11.4'), (err) => {
|
|
34
|
+
assert.ok(err instanceof OutdatedConnectorError);
|
|
35
|
+
assert.equal(err.code, 'respira_outdated_connector');
|
|
36
|
+
assert.equal(err.requiredVersion, '7.1.0');
|
|
37
|
+
assert.equal(err.currentVersion, '6.11.4');
|
|
38
|
+
// Message must point the user at the reinstall path.
|
|
39
|
+
assert.match(err.message, /reinstall the current connector/i);
|
|
40
|
+
assert.match(err.message, /dashboard\/mcp/);
|
|
41
|
+
return true;
|
|
42
|
+
});
|
|
43
|
+
});
|
|
44
|
+
test('assertConnectorMeetsConfig does not block when the running version is unknown', () => {
|
|
45
|
+
const cfg = { metadata: { minConnectorVersion: '7.1.0' } };
|
|
46
|
+
// Unknown compares equal, so an unreadable package.json never locks the user out.
|
|
47
|
+
assert.doesNotThrow(() => assertConnectorMeetsConfig(cfg, 'unknown'));
|
|
48
|
+
});
|
|
49
|
+
//# sourceMappingURL=startup-guard.test.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"startup-guard.test.js","sourceRoot":"","sources":["../../src/__tests__/startup-guard.test.ts"],"names":[],"mappings":"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"}
|
package/dist/index.js
CHANGED
|
@@ -4,6 +4,7 @@
|
|
|
4
4
|
* Entry point
|
|
5
5
|
*/
|
|
6
6
|
import { initializeSystemCertificateTrust } from './system-ca.js';
|
|
7
|
+
import { assertConnectorMeetsConfig, getConnectorVersion, installStartupWatchdog, } from './startup-guard.js';
|
|
7
8
|
/**
|
|
8
9
|
* Detect npm/npx cache corruption (ENOENT inside _npx or node_modules paths).
|
|
9
10
|
* Returns a friendly recovery message if the error matches, otherwise null.
|
|
@@ -149,6 +150,8 @@ async function startStdioMode() {
|
|
|
149
150
|
const { loadConfig } = await import('./config.js');
|
|
150
151
|
try {
|
|
151
152
|
const config = loadConfig();
|
|
153
|
+
// Refuse to limp along on a setup code that needs a newer build — say so.
|
|
154
|
+
assertConnectorMeetsConfig(config, getConnectorVersion());
|
|
152
155
|
const server = new RespiraWordPressServer(config.sites, config.preferences?.enabledTools);
|
|
153
156
|
// Start STDIO transport — reads JSON-RPC from stdin, writes to stdout
|
|
154
157
|
const options = parseStdioArgs(args);
|
|
@@ -214,14 +217,22 @@ async function startMcpServer() {
|
|
|
214
217
|
const { RespiraWordPressServer } = await import('./server.js');
|
|
215
218
|
const { loadConfig } = await import('./config.js');
|
|
216
219
|
setupEpipeHandler();
|
|
220
|
+
// Arm a watchdog so a stalled startup writes a diagnostic and exits with a
|
|
221
|
+
// clear message instead of hanging until the host kills it with no error.
|
|
222
|
+
const watchdog = installStartupWatchdog(getConnectorVersion());
|
|
217
223
|
try {
|
|
218
224
|
// Load configuration
|
|
219
225
|
const config = loadConfig();
|
|
226
|
+
// Refuse to limp along on a setup code that needs a newer build — say so.
|
|
227
|
+
assertConnectorMeetsConfig(config, getConnectorVersion());
|
|
220
228
|
// Create and run server
|
|
221
229
|
const server = new RespiraWordPressServer(config.sites, config.preferences?.enabledTools);
|
|
222
230
|
await server.run();
|
|
231
|
+
// Connected — stand the watchdog down so it can't fire mid-session.
|
|
232
|
+
watchdog.clear();
|
|
223
233
|
}
|
|
224
234
|
catch (error) {
|
|
235
|
+
watchdog.clear();
|
|
225
236
|
const errorMessage = error?.message || error?.toString() || String(error) || 'Unknown error';
|
|
226
237
|
const errorStack = error?.stack ? `\nStack: ${error.stack}` : '';
|
|
227
238
|
console.error('Fatal error:', errorMessage);
|
package/dist/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG;AAEH,OAAO,EAAE,gCAAgC,EAAE,MAAM,gBAAgB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Startup guard — fail loud, never wedge silently.
|
|
3
|
+
*
|
|
4
|
+
* Two protections, both aimed at the same failure class: an installed connector
|
|
5
|
+
* that is too old for the setup code it was handed, or one that stalls on
|
|
6
|
+
* startup for any reason. Before this guard, an outdated Claude Desktop bundle
|
|
7
|
+
* (e.g. a 6.x build fed a newer dashboard setup code) would start, accept the
|
|
8
|
+
* connect handshake, then hang until the host killed it ~7s later with no error
|
|
9
|
+
* shown to the user. Reported by a MaxAd customer 2026-06-04: "i cannot connect
|
|
10
|
+
* the 5th site you have changed everything" — the bundled build silently died on
|
|
11
|
+
* every retry. The fix on their side is to reinstall, but the connector should
|
|
12
|
+
* have said so instead of dying quietly.
|
|
13
|
+
*
|
|
14
|
+
* 1. assertConnectorMeetsConfig — if the setup code declares a minimum connector
|
|
15
|
+
* version newer than this build, throw a clear, actionable error (reinstall
|
|
16
|
+
* from the dashboard) instead of attempting to run with a config it can't
|
|
17
|
+
* fully understand.
|
|
18
|
+
* 2. installStartupWatchdog — a timer that, if the server has not finished
|
|
19
|
+
* connecting within a budget, writes a diagnostic file and exits with a clear
|
|
20
|
+
* message. Robust to ANY stall cause (config, network, certificate), since it
|
|
21
|
+
* does not depend on knowing why startup hung.
|
|
22
|
+
*
|
|
23
|
+
* Both paths write ~/.respira/last-startup-error.txt so Cowork, the doctor
|
|
24
|
+
* command, or the user can read what went wrong after the host swallows stderr.
|
|
25
|
+
*/
|
|
26
|
+
/**
|
|
27
|
+
* Read this connector's own version from package.json. Mirrors the read in
|
|
28
|
+
* server.ts but kept self-contained so the entry point can compare versions
|
|
29
|
+
* without importing the (large) server module.
|
|
30
|
+
*/
|
|
31
|
+
export declare function getConnectorVersion(): string;
|
|
32
|
+
/**
|
|
33
|
+
* Compare two semver-ish versions. Returns -1 if a < b, 1 if a > b, 0 if equal
|
|
34
|
+
* or either is unparseable (unknown versions compare equal so they never block).
|
|
35
|
+
*/
|
|
36
|
+
export declare function compareVersions(a: string, b: string): number;
|
|
37
|
+
/**
|
|
38
|
+
* Pull the declared minimum connector version out of a loaded config, if the
|
|
39
|
+
* dashboard stamped one. Stored under metadata.minConnectorVersion so older
|
|
40
|
+
* builds that don't know the field simply ignore it (forward compatible).
|
|
41
|
+
*/
|
|
42
|
+
export declare function getConfiguredMinConnectorVersion(config: unknown): string | null;
|
|
43
|
+
/** Error thrown when the installed connector is older than the config requires. */
|
|
44
|
+
export declare class OutdatedConnectorError extends Error {
|
|
45
|
+
readonly code = "respira_outdated_connector";
|
|
46
|
+
readonly requiredVersion: string;
|
|
47
|
+
readonly currentVersion: string;
|
|
48
|
+
constructor(requiredVersion: string, currentVersion: string);
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Throw a clear, actionable error if the config declares a minimum connector
|
|
52
|
+
* version newer than this build. No-op when the field is absent or this build
|
|
53
|
+
* is new enough. Call right after loadConfig(), before connecting.
|
|
54
|
+
*/
|
|
55
|
+
export declare function assertConnectorMeetsConfig(config: unknown, connectorVersion: string): void;
|
|
56
|
+
/**
|
|
57
|
+
* Best-effort write of a single diagnostic file the user / Cowork / doctor can
|
|
58
|
+
* read after the host swallows stderr. Never throws.
|
|
59
|
+
*/
|
|
60
|
+
export declare function writeStartupDiagnostic(message: string): void;
|
|
61
|
+
export type StartupWatchdog = {
|
|
62
|
+
clear: () => void;
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* Arm a watchdog that fires if startup has not signalled completion within the
|
|
66
|
+
* budget. On fire it writes a diagnostic and exits, turning a silent stall into
|
|
67
|
+
* a clear, recorded failure. Call clear() once the transport is connected.
|
|
68
|
+
*
|
|
69
|
+
* The timer is intentionally NOT unref()'d: during a stall some pending promise
|
|
70
|
+
* keeps the loop alive, and we want the watchdog to reliably win that race.
|
|
71
|
+
*/
|
|
72
|
+
export declare function installStartupWatchdog(connectorVersion: string): StartupWatchdog;
|
|
73
|
+
//# sourceMappingURL=startup-guard.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"startup-guard.d.ts","sourceRoot":"","sources":["../src/startup-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAkBH;;;;GAIG;AACH,wBAAgB,mBAAmB,IAAI,MAAM,CAY5C;AAWD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAY5D;AAED;;;;GAIG;AACH,wBAAgB,gCAAgC,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI/E;AAED,mFAAmF;AACnF,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,IAAI,gCAAgC;IAC7C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;gBAEpB,eAAe,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM;CAW5D;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,OAAO,EAAE,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAQ1F;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAU5D;AAED,MAAM,MAAM,eAAe,GAAG;IAAE,KAAK,EAAE,MAAM,IAAI,CAAA;CAAE,CAAC;AAEpD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,gBAAgB,EAAE,MAAM,GAAG,eAAe,CA0BhF"}
|
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Startup guard — fail loud, never wedge silently.
|
|
3
|
+
*
|
|
4
|
+
* Two protections, both aimed at the same failure class: an installed connector
|
|
5
|
+
* that is too old for the setup code it was handed, or one that stalls on
|
|
6
|
+
* startup for any reason. Before this guard, an outdated Claude Desktop bundle
|
|
7
|
+
* (e.g. a 6.x build fed a newer dashboard setup code) would start, accept the
|
|
8
|
+
* connect handshake, then hang until the host killed it ~7s later with no error
|
|
9
|
+
* shown to the user. Reported by a MaxAd customer 2026-06-04: "i cannot connect
|
|
10
|
+
* the 5th site you have changed everything" — the bundled build silently died on
|
|
11
|
+
* every retry. The fix on their side is to reinstall, but the connector should
|
|
12
|
+
* have said so instead of dying quietly.
|
|
13
|
+
*
|
|
14
|
+
* 1. assertConnectorMeetsConfig — if the setup code declares a minimum connector
|
|
15
|
+
* version newer than this build, throw a clear, actionable error (reinstall
|
|
16
|
+
* from the dashboard) instead of attempting to run with a config it can't
|
|
17
|
+
* fully understand.
|
|
18
|
+
* 2. installStartupWatchdog — a timer that, if the server has not finished
|
|
19
|
+
* connecting within a budget, writes a diagnostic file and exits with a clear
|
|
20
|
+
* message. Robust to ANY stall cause (config, network, certificate), since it
|
|
21
|
+
* does not depend on knowing why startup hung.
|
|
22
|
+
*
|
|
23
|
+
* Both paths write ~/.respira/last-startup-error.txt so Cowork, the doctor
|
|
24
|
+
* command, or the user can read what went wrong after the host swallows stderr.
|
|
25
|
+
*/
|
|
26
|
+
import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
|
|
27
|
+
import { join, dirname, resolve } from 'node:path';
|
|
28
|
+
import { homedir } from 'node:os';
|
|
29
|
+
import { fileURLToPath } from 'node:url';
|
|
30
|
+
const CONFIG_DIR = join(homedir(), '.respira');
|
|
31
|
+
const STARTUP_ERROR_FILE = join(CONFIG_DIR, 'last-startup-error.txt');
|
|
32
|
+
const DASHBOARD_URL = 'https://respira.press/dashboard/mcp';
|
|
33
|
+
/** Default startup budget. Healthy startup connects in well under a second; the
|
|
34
|
+
* host typically kills a stalled server around 7s, so a 6s budget leaves a
|
|
35
|
+
* diagnostic breadcrumb just before that happens without false-tripping on a
|
|
36
|
+
* cold start. Override with RESPIRA_STARTUP_BUDGET_MS. */
|
|
37
|
+
const DEFAULT_STARTUP_BUDGET_MS = 6000;
|
|
38
|
+
const MIN_STARTUP_BUDGET_MS = 2000;
|
|
39
|
+
/**
|
|
40
|
+
* Read this connector's own version from package.json. Mirrors the read in
|
|
41
|
+
* server.ts but kept self-contained so the entry point can compare versions
|
|
42
|
+
* without importing the (large) server module.
|
|
43
|
+
*/
|
|
44
|
+
export function getConnectorVersion() {
|
|
45
|
+
try {
|
|
46
|
+
const currentDir = dirname(fileURLToPath(import.meta.url));
|
|
47
|
+
const pkgPath = resolve(currentDir, '../package.json');
|
|
48
|
+
const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
|
|
49
|
+
if (typeof pkg.version === 'string' && pkg.version.trim()) {
|
|
50
|
+
return pkg.version.trim();
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
catch {
|
|
54
|
+
// Fall through.
|
|
55
|
+
}
|
|
56
|
+
return 'unknown';
|
|
57
|
+
}
|
|
58
|
+
/** Parse a semver-ish string to [major, minor, patch]; null if unparseable. */
|
|
59
|
+
function parseVersion(version) {
|
|
60
|
+
const match = String(version).match(/(\d+)\.(\d+)\.(\d+)/);
|
|
61
|
+
if (!match) {
|
|
62
|
+
return null;
|
|
63
|
+
}
|
|
64
|
+
return [Number(match[1]), Number(match[2]), Number(match[3])];
|
|
65
|
+
}
|
|
66
|
+
/**
|
|
67
|
+
* Compare two semver-ish versions. Returns -1 if a < b, 1 if a > b, 0 if equal
|
|
68
|
+
* or either is unparseable (unknown versions compare equal so they never block).
|
|
69
|
+
*/
|
|
70
|
+
export function compareVersions(a, b) {
|
|
71
|
+
const pa = parseVersion(a);
|
|
72
|
+
const pb = parseVersion(b);
|
|
73
|
+
if (!pa || !pb) {
|
|
74
|
+
return 0;
|
|
75
|
+
}
|
|
76
|
+
for (let i = 0; i < 3; i++) {
|
|
77
|
+
if (pa[i] !== pb[i]) {
|
|
78
|
+
return pa[i] < pb[i] ? -1 : 1;
|
|
79
|
+
}
|
|
80
|
+
}
|
|
81
|
+
return 0;
|
|
82
|
+
}
|
|
83
|
+
/**
|
|
84
|
+
* Pull the declared minimum connector version out of a loaded config, if the
|
|
85
|
+
* dashboard stamped one. Stored under metadata.minConnectorVersion so older
|
|
86
|
+
* builds that don't know the field simply ignore it (forward compatible).
|
|
87
|
+
*/
|
|
88
|
+
export function getConfiguredMinConnectorVersion(config) {
|
|
89
|
+
const meta = config?.metadata;
|
|
90
|
+
const raw = meta?.minConnectorVersion;
|
|
91
|
+
return typeof raw === 'string' && raw.trim() ? raw.trim() : null;
|
|
92
|
+
}
|
|
93
|
+
/** Error thrown when the installed connector is older than the config requires. */
|
|
94
|
+
export class OutdatedConnectorError extends Error {
|
|
95
|
+
code = 'respira_outdated_connector';
|
|
96
|
+
requiredVersion;
|
|
97
|
+
currentVersion;
|
|
98
|
+
constructor(requiredVersion, currentVersion) {
|
|
99
|
+
super(`This Respira setup code needs connector v${requiredVersion} or newer, but the ` +
|
|
100
|
+
`installed connector is v${currentVersion}. Reinstall the current connector from ` +
|
|
101
|
+
`${DASHBOARD_URL} . In Claude Desktop, remove the old "Respira for WordPress" item ` +
|
|
102
|
+
`that shows Failed first, then install the fresh download and restart Claude.`);
|
|
103
|
+
this.name = 'OutdatedConnectorError';
|
|
104
|
+
this.requiredVersion = requiredVersion;
|
|
105
|
+
this.currentVersion = currentVersion;
|
|
106
|
+
}
|
|
107
|
+
}
|
|
108
|
+
/**
|
|
109
|
+
* Throw a clear, actionable error if the config declares a minimum connector
|
|
110
|
+
* version newer than this build. No-op when the field is absent or this build
|
|
111
|
+
* is new enough. Call right after loadConfig(), before connecting.
|
|
112
|
+
*/
|
|
113
|
+
export function assertConnectorMeetsConfig(config, connectorVersion) {
|
|
114
|
+
const required = getConfiguredMinConnectorVersion(config);
|
|
115
|
+
if (!required) {
|
|
116
|
+
return;
|
|
117
|
+
}
|
|
118
|
+
if (compareVersions(connectorVersion, required) < 0) {
|
|
119
|
+
throw new OutdatedConnectorError(required, connectorVersion);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Best-effort write of a single diagnostic file the user / Cowork / doctor can
|
|
124
|
+
* read after the host swallows stderr. Never throws.
|
|
125
|
+
*/
|
|
126
|
+
export function writeStartupDiagnostic(message) {
|
|
127
|
+
try {
|
|
128
|
+
if (!existsSync(CONFIG_DIR)) {
|
|
129
|
+
mkdirSync(CONFIG_DIR, { recursive: true });
|
|
130
|
+
}
|
|
131
|
+
const ts = new Date().toISOString();
|
|
132
|
+
writeFileSync(STARTUP_ERROR_FILE, `[${ts}] ${message}\n`, 'utf8');
|
|
133
|
+
}
|
|
134
|
+
catch {
|
|
135
|
+
// Diagnostic write is best-effort.
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Arm a watchdog that fires if startup has not signalled completion within the
|
|
140
|
+
* budget. On fire it writes a diagnostic and exits, turning a silent stall into
|
|
141
|
+
* a clear, recorded failure. Call clear() once the transport is connected.
|
|
142
|
+
*
|
|
143
|
+
* The timer is intentionally NOT unref()'d: during a stall some pending promise
|
|
144
|
+
* keeps the loop alive, and we want the watchdog to reliably win that race.
|
|
145
|
+
*/
|
|
146
|
+
export function installStartupWatchdog(connectorVersion) {
|
|
147
|
+
if (process.env.RESPIRA_DISABLE_STARTUP_WATCHDOG === '1') {
|
|
148
|
+
return { clear: () => { } };
|
|
149
|
+
}
|
|
150
|
+
const parsed = Number.parseInt(process.env.RESPIRA_STARTUP_BUDGET_MS || '', 10);
|
|
151
|
+
const budgetMs = Number.isFinite(parsed) && parsed > 0
|
|
152
|
+
? Math.max(MIN_STARTUP_BUDGET_MS, parsed)
|
|
153
|
+
: DEFAULT_STARTUP_BUDGET_MS;
|
|
154
|
+
const timer = setTimeout(() => {
|
|
155
|
+
const message = `Respira connector v${connectorVersion} did not finish connecting within ${budgetMs}ms ` +
|
|
156
|
+
`and was stopped. The most common cause is an outdated installed build that cannot read a ` +
|
|
157
|
+
`newer setup code. Reinstall the current connector from ${DASHBOARD_URL} (in Claude Desktop, ` +
|
|
158
|
+
`remove the old "Respira for WordPress" item that shows Failed, then install the fresh ` +
|
|
159
|
+
`download and restart Claude). If it still stalls, reply to your Respira support thread and ` +
|
|
160
|
+
`attach this file.`;
|
|
161
|
+
writeStartupDiagnostic(message);
|
|
162
|
+
console.error(`[respira-mcp] startup-watchdog: ${message}`);
|
|
163
|
+
process.exit(1);
|
|
164
|
+
}, budgetMs);
|
|
165
|
+
return {
|
|
166
|
+
clear: () => clearTimeout(timer),
|
|
167
|
+
};
|
|
168
|
+
}
|
|
169
|
+
//# sourceMappingURL=startup-guard.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"startup-guard.js","sourceRoot":"","sources":["../src/startup-guard.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@respira/wordpress-mcp-server",
|
|
3
|
-
"version": "7.1.
|
|
3
|
+
"version": "7.1.1",
|
|
4
4
|
"mcpName": "io.github.webmyc/respira-wordpress",
|
|
5
5
|
"repository": {
|
|
6
6
|
"type": "git",
|
|
7
7
|
"url": "git+https://github.com/webmyc/respira-wordpress.git",
|
|
8
8
|
"directory": "mcp-server"
|
|
9
9
|
},
|
|
10
|
-
"description": "180+ MCP tools for WordPress
|
|
10
|
+
"description": "180+ MCP tools for WordPress across 16 page builders. The only MCP server with native page-builder access, context-aware tool filtering, and an agent persona loaded into every handshake. v7.1 'Roots': four new builders (Spectra, Kadence Blocks, GenerateBlocks, SeedProd), Playbooks (teach an agent a multi-step workflow once and rerun it as one callable WordPress Ability), agent-creatable custom post types + taxonomies + ACF field groups, a native in-WP MCP endpoint (Streamable HTTP at /?respira=mcp plus one-click connect-by-link), make-any-builder-responsive in one call, and an OS certificate-store trust layer so valid certs stop failing on Claude Desktop's bundled Node. v6.17.0: (1) SOUL.md, an agent persona file loaded into the handshake so every AI client reads identity, voice, values, and rules of engagement before its first tool call; mirrored at https://www.respira.press/soul.md for outside-MCP integrations (Cursor system prompts, Claude Projects, GPT custom instructions). (2) respira_search_docs, full-text search across the Respira documentation, mirrored nightly from the docs repo; agent calls this before offering to file a bug because most 'bugs' are documented known issues with workarounds. (3) respira_report_issue, files a structured bug report from inside the AI chat directly to https://www.respira.press/mcp/report-issue; auto-attaches site URL, builder + version, MCP version, OS, last tool, optional diagnose snapshot. Privacy hard line: no prompts, no tool args, no tool results, no WP content. (4) respira_diagnose_connection probe timeout default 30000ms (was 15000ms), new probe_timeout_ms arg clamped [5000, 60000]; sites behind Cloudflare custom rules routinely cross 15s on first-hit HEADs and the old default produced spurious 'MCP timed out but the site is fine' reports. (5) bootstrap stderr log now reads 'respira-mcp vX.Y.Z ready · N sites: host1, host2, ...' so the customer can tell at a glance whether the MCP came back after a Claude restart. (6) Agent triage rule baked into handshake instructions: tool error → apply hint + retry once → respira_search_docs → respira_diagnose_connection → ask the customer if they want to file a bug → respira_report_issue. Never auto-file. v6.16.0: usage telemetry ships by default for every customer, not only those who generated an OTEL bearer at /dashboard/settings/earn. New 3-tier auth on the usage emitter (OTEL bearer → per-site license api_token → off); /api/mcp-spend/track accepts both bearer shapes. v6.14.0: opt-in per-tool-call usage telemetry to power the per-site / per-tool cost breakdown on the Respira dashboard; each tool call is timed and batched (50 events or 5s, whichever first) to /mcp-spend/track. Privacy: only metadata is shipped, tool name, read-vs-write classification, site URL, duration, success flag. Opt out entirely with RESPIRA_USAGE_OPT_OUT=1. v6.13.0: respira_get_page_outline (row-level outline of any builder page, lighter than extract_builder_content), respira_get_builder_inline_schemas (per-shortcode attribute schemas for WPBakery + Uncode + TagDiv via vc_map() at runtime, cached 1h transient plugin-side), respira_find_builder_targets pagination upgrade (true total_matches, offset/has_more/next_offset, populated label/admin_label on WPBakery + Uncode targets), Divi 5 _nodeId fallback in find_builder_targets. v6.12.0: respira_extract_builder_content auto-detects the active site builder when the builder arg is omitted; respira_update_element exposes editTarget=live|duplicate with explicit target_id/original_id/edit_target/is_duplicate in the response; respira_inject_builder_content threads confirm_replace through (plugin returns 409 respira_replace_confirmation_required if the page already has content); server self-identifies as the actually installed version instead of a stale literal; respira_diagnose_connection now probes OPTIONS alongside GET and reports write_method_blocked: true when GET returns 2xx but OPTIONS returns 4xx/5xx, with the literal Cloudflare expression to append to the rule. v6.11.2: auto-fallback to ?rest_route= when WordPress rewrite rules shadow /wp-json/[anything] and trigger redirect_canonical(); transparent retry, per-session sticky flag, new forceRestRoute site-config flag. v6.11.1: snake_case sweep across the tool catalog (14 keys, 46 schema occurrences, 21 dispatcher reads) with one release of bidirectional camelCase back-compat. v6.11.0: respira_diagnose_connection runs a full self-check battery (extracts page <title> from HTML responses, detects edge-layer presence: Cloudflare cf-ray, Wordfence x-wordfence-*, Sucuri x-sucuri-*). v6.6.5: Oxygen 6 detection finally works on Soflyy builds without an /engine or /jenga subfolder. v6.6.4: upload-hang killer, per-call watchdog on every tool (default 120s, RESPIRA_MAX_TOOL_TIMEOUT_MS); respira_upload_media has a hard AbortController abort and 50 MB preflight. v6.3.0: structuredContent in all tool results (MCP 2025-06-18 spec compliance), improved error taxonomy with self-correction hints. v6.2.0: Elementor conversion validator (7 rendering fidelity rules + auto-fix), per-site tool allowlist (whitelist/blacklist/presets), approval-required on destructive tools. v6.0.0: context-aware tool filtering, the MCP server automatically filters the tool list based on detected builder and active plugins (a Divi site without WooCommerce sees ~130 tools instead of ~170, less noise, faster AI responses, lower token usage). 12 builders supported: Elementor, Divi 4+5, Bricks, Gutenberg, WPBakery, Oxygen, Beaver Builder, Brizy, Visual Composer, Thrive, Breakdance, Flatsome. Bricks Deep Intelligence (20 tools), Elementor Deep Intelligence (9 tools), WooCommerce Commerce (36 tools). Element-level editing, full page creation, HTML-to-builder conversion, WCAG accessibility, stock images, bulk operations. Setup: npx add-mcp for auto-config, --setup wizard, --doctor diagnostics. Duplicate-before-edit safety. Skills marketplace with 26 AI workflows.",
|
|
11
11
|
"main": "dist/index.js",
|
|
12
12
|
"bin": {
|
|
13
13
|
"wordpress-mcp-server": "./dist/index.js",
|