@marvalt/digivalt-mcp 0.0.0-stage → 0.5.0

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.
Files changed (51) hide show
  1. package/CHANGELOG.md +56 -0
  2. package/LICENSE +674 -0
  3. package/README.md +69 -2
  4. package/dist/audit.d.ts +24 -0
  5. package/dist/audit.js +34 -0
  6. package/dist/audit.js.map +1 -0
  7. package/dist/blocks/serialize.d.ts +15 -0
  8. package/dist/blocks/serialize.js +231 -0
  9. package/dist/blocks/serialize.js.map +1 -0
  10. package/dist/catalogue/blocks.d.ts +17 -0
  11. package/dist/catalogue/blocks.js +37 -0
  12. package/dist/catalogue/blocks.js.map +1 -0
  13. package/dist/catalogue/shortcodes.d.ts +49 -0
  14. package/dist/catalogue/shortcodes.js +384 -0
  15. package/dist/catalogue/shortcodes.js.map +1 -0
  16. package/dist/cli.d.ts +2 -0
  17. package/dist/cli.js +58 -0
  18. package/dist/cli.js.map +1 -0
  19. package/dist/config.d.ts +48 -0
  20. package/dist/config.js +139 -0
  21. package/dist/config.js.map +1 -0
  22. package/dist/index.d.ts +9 -0
  23. package/dist/index.js +8 -0
  24. package/dist/index.js.map +1 -0
  25. package/dist/media.d.ts +26 -0
  26. package/dist/media.js +118 -0
  27. package/dist/media.js.map +1 -0
  28. package/dist/publish.d.ts +32 -0
  29. package/dist/publish.js +74 -0
  30. package/dist/publish.js.map +1 -0
  31. package/dist/refresh.d.ts +30 -0
  32. package/dist/refresh.js +93 -0
  33. package/dist/refresh.js.map +1 -0
  34. package/dist/resources/guides.d.ts +2 -0
  35. package/dist/resources/guides.js +51 -0
  36. package/dist/resources/guides.js.map +1 -0
  37. package/dist/server.d.ts +19 -0
  38. package/dist/server.js +522 -0
  39. package/dist/server.js.map +1 -0
  40. package/dist/validate/local.d.ts +17 -0
  41. package/dist/validate/local.js +75 -0
  42. package/dist/validate/local.js.map +1 -0
  43. package/dist/version.d.ts +3 -0
  44. package/dist/version.js +4 -0
  45. package/dist/version.js.map +1 -0
  46. package/dist/wp-client.d.ts +31 -0
  47. package/dist/wp-client.js +94 -0
  48. package/dist/wp-client.js.map +1 -0
  49. package/docs/README.md +114 -0
  50. package/docs/SECURITY.md +44 -0
  51. package/package.json +51 -4
@@ -0,0 +1,75 @@
1
+ import { parse } from '@wordpress/block-serialization-default-parser';
2
+ import { renderedBlockNames, UNRENDERED_HINTS } from '../catalogue/blocks.js';
3
+ import { checkShortcode, findShortcodes } from '../catalogue/shortcodes.js';
4
+ const HEADING_LEVEL = /<h([1-6])\b/i;
5
+ /** Checks whether the DigiValt frontend will render the content as intended. Pure function, no network. */
6
+ export function validateLocal(content, opts = {}) {
7
+ const issues = [];
8
+ const add = (severity, code, path, block, message) => issues.push({ severity, code, path, block, message });
9
+ if (!content || !content.trim()) {
10
+ add('error', 'EMPTY_CONTENT', '', null, 'Content is empty.');
11
+ return { valid: false, errors: [...issues], warnings: [] };
12
+ }
13
+ if (/<script\b/i.test(content)) {
14
+ add('error', 'SCRIPT_TAG', '', null, 'Script tags are not allowed in page content.');
15
+ }
16
+ if (/\[\s*gravityforms?\b/i.test(content)) {
17
+ add('error', 'GRAVITY_SHORTCODE', '', null, 'Use [gf_embed id="N"] instead of the Gravity Forms shortcode; the app renders its own form.');
18
+ }
19
+ const rendered = renderedBlockNames(opts.extraBlocks);
20
+ const blocks = parse(content);
21
+ const real = blocks.filter((b) => b.blockName || b.innerHTML.trim());
22
+ if (real.length === 0) {
23
+ add('error', 'EMPTY_CONTENT', '', null, 'Content has no blocks.');
24
+ }
25
+ let h1Count = 0;
26
+ let lastLevel = 0;
27
+ const visit = (block, path, topLevel) => {
28
+ const name = block.blockName;
29
+ if (!name) {
30
+ if (block.innerHTML.trim()) {
31
+ add('warning', 'LOOSE_HTML', path, null, 'Content outside any block (classic editor markup) is not rendered reliably. Wrap it in blocks.');
32
+ }
33
+ return;
34
+ }
35
+ if (!rendered.has(name)) {
36
+ const hint = UNRENDERED_HINTS[name];
37
+ add('error', 'BLOCK_NOT_RENDERED', path, name, `${name} is not rendered by the frontend.${hint ? ` ${hint}` : ' Use a supported block (list_blocks).'}`);
38
+ }
39
+ if (topLevel && name !== 'core/group' && name !== 'core/cover') {
40
+ add('warning', 'TOP_LEVEL_NOT_GROUP', path, name, 'Top-level blocks should be core/group sections so the layout stays consistent.');
41
+ }
42
+ if (name === 'core/heading') {
43
+ const level = Number(block.attrs?.level ?? HEADING_LEVEL.exec(block.innerHTML)?.[1] ?? 2);
44
+ if (level === 1) {
45
+ h1Count += 1;
46
+ if (h1Count === 2)
47
+ add('warning', 'MULTIPLE_H1', path, name, 'More than one H1 on the page.');
48
+ }
49
+ if (lastLevel && level > lastLevel + 1) {
50
+ add('warning', 'HEADING_SKIP', path, name, `Heading level jumps from H${lastLevel} to H${level}.`);
51
+ }
52
+ lastLevel = level;
53
+ }
54
+ if (name === 'core/image') {
55
+ const alt = /\balt="([^"]*)"/i.exec(block.innerHTML)?.[1] ?? '';
56
+ if (!alt.trim())
57
+ add('warning', 'IMAGE_NO_ALT', path, name, 'Image has no alt text.');
58
+ }
59
+ const shortcodes = findShortcodes(block.innerHTML);
60
+ for (const sc of shortcodes) {
61
+ if (name !== 'core/paragraph') {
62
+ add('warning', 'SHORTCODE_WRONG_BLOCK', path, name, `[${sc.name}] only renders inside a core/paragraph block.`);
63
+ }
64
+ for (const issue of checkShortcode(sc)) {
65
+ add(issue.severity, issue.code, path, name, issue.message);
66
+ }
67
+ }
68
+ block.innerBlocks.forEach((inner, i) => visit(inner, `${path}.${i}`, false));
69
+ };
70
+ blocks.forEach((b, i) => visit(b, String(i), true));
71
+ const errors = issues.filter((i) => i.severity === 'error');
72
+ const warnings = issues.filter((i) => i.severity === 'warning');
73
+ return { valid: errors.length === 0, errors, warnings };
74
+ }
75
+ //# sourceMappingURL=local.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"local.js","sourceRoot":"","sources":["../../src/validate/local.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,+CAA+C,CAAC;AACtE,OAAO,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC9E,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAC;AAwB5E,MAAM,aAAa,GAAG,cAAc,CAAC;AAErC,2GAA2G;AAC3G,MAAM,UAAU,aAAa,CAAC,OAAe,EAAE,IAAI,GAA+B,EAAE;IAClF,MAAM,MAAM,GAAiB,EAAE,CAAC;IAChC,MAAM,GAAG,GAAG,CAAC,QAAgC,EAAE,IAAY,EAAE,IAAY,EAAE,KAAoB,EAAE,OAAe,EAAE,EAAE,CAClH,MAAM,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,CAAC;IAExD,IAAI,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QAChC,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,IAAI,EAAE,mBAAmB,CAAC,CAAC;QAC7D,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,GAAG,MAAM,CAAC,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC;IAC7D,CAAC;IAED,IAAI,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC/B,GAAG,CAAC,OAAO,EAAE,YAAY,EAAE,EAAE,EAAE,IAAI,EAAE,8CAA8C,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,uBAAuB,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1C,GAAG,CAAC,OAAO,EAAE,mBAAmB,EAAE,EAAE,EAAE,IAAI,EAAE,6FAA6F,CAAC,CAAC;IAC7I,CAAC;IAED,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;IACtD,MAAM,MAAM,GAAG,KAAK,CAAC,OAAO,CAA6B,CAAC;IAC1D,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;IAErE,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACtB,GAAG,CAAC,OAAO,EAAE,eAAe,EAAE,EAAE,EAAE,IAAI,EAAE,wBAAwB,CAAC,CAAC;IACpE,CAAC;IAED,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,IAAI,SAAS,GAAG,CAAC,CAAC;IAElB,MAAM,KAAK,GAAG,CAAC,KAAkB,EAAE,IAAY,EAAE,QAAiB,EAAE,EAAE;QACpE,MAAM,IAAI,GAAG,KAAK,CAAC,SAAS,CAAC;QAC7B,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;gBAC3B,GAAG,CAAC,SAAS,EAAE,YAAY,EAAE,IAAI,EAAE,IAAI,EAAE,gGAAgG,CAAC,CAAC;YAC7I,CAAC;YACD,OAAO;QACT,CAAC;QAED,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;YACpC,GAAG,CAAC,OAAO,EAAE,oBAAoB,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,oCAAoC,IAAI,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,uCAAuC,EAAE,CAAC,CAAC;QAC3J,CAAC;QAED,IAAI,QAAQ,IAAI,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;YAC/D,GAAG,CAAC,SAAS,EAAE,qBAAqB,EAAE,IAAI,EAAE,IAAI,EAAE,gFAAgF,CAAC,CAAC;QACtI,CAAC;QAED,IAAI,IAAI,KAAK,cAAc,EAAE,CAAC;YAC5B,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,KAAK,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;YAC1F,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;gBAChB,OAAO,IAAI,CAAC,CAAC;gBACb,IAAI,OAAO,KAAK,CAAC;oBAAE,GAAG,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,EAAE,IAAI,EAAE,+BAA+B,CAAC,CAAC;YAChG,CAAC;YACD,IAAI,SAAS,IAAI,KAAK,GAAG,SAAS,GAAG,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,6BAA6B,SAAS,QAAQ,KAAK,GAAG,CAAC,CAAC;YACrG,CAAC;YACD,SAAS,GAAG,KAAK,CAAC;QACpB,CAAC;QAED,IAAI,IAAI,KAAK,YAAY,EAAE,CAAC;YAC1B,MAAM,GAAG,GAAG,kBAAkB,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;YAChE,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE;gBAAE,GAAG,CAAC,SAAS,EAAE,cAAc,EAAE,IAAI,EAAE,IAAI,EAAE,wBAAwB,CAAC,CAAC;QACxF,CAAC;QAED,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QACnD,KAAK,MAAM,EAAE,IAAI,UAAU,EAAE,CAAC;YAC5B,IAAI,IAAI,KAAK,gBAAgB,EAAE,CAAC;gBAC9B,GAAG,CAAC,SAAS,EAAE,uBAAuB,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,IAAI,+CAA+C,CAAC,CAAC;YAClH,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,cAAc,CAAC,EAAE,CAAC,EAAE,CAAC;gBACvC,GAAG,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;YAC7D,CAAC;QACH,CAAC;QAED,KAAK,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,IAAI,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC,CAAC;IAC/E,CAAC,CAAC;IAEF,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC,CAAC;IAEpD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC;IAChE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;AAC1D,CAAC"}
@@ -0,0 +1,3 @@
1
+ /** Keep in sync with package.json (a test checks it). */
2
+ export declare const VERSION = "0.5.0";
3
+ export declare const PACKAGE_NAME = "@marvalt/digivalt-mcp";
@@ -0,0 +1,4 @@
1
+ /** Keep in sync with package.json (a test checks it). */
2
+ export const VERSION = '0.5.0';
3
+ export const PACKAGE_NAME = '@marvalt/digivalt-mcp';
4
+ //# sourceMappingURL=version.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC;AAC/B,MAAM,CAAC,MAAM,YAAY,GAAG,uBAAuB,CAAC"}
@@ -0,0 +1,31 @@
1
+ import type { Config } from './config.js';
2
+ export declare class WpError extends Error {
3
+ readonly status: number;
4
+ readonly code: string;
5
+ readonly data?: unknown;
6
+ constructor(status: number, code: string, message: string, data?: unknown);
7
+ }
8
+ export interface WpResponse<T> {
9
+ status: number;
10
+ data: T;
11
+ headers: Headers;
12
+ }
13
+ type Query = Record<string, string | number | boolean | undefined>;
14
+ /** Minimal WordPress REST client: Basic auth (application password) plus optional Cloudflare Access service token. */
15
+ export declare class WpClient {
16
+ private readonly config;
17
+ private readonly fetchImpl;
18
+ private readonly timeoutMs;
19
+ constructor(config: Config, fetchImpl?: typeof fetch, timeoutMs?: number);
20
+ get configured(): boolean;
21
+ private headers;
22
+ send<T>(method: string, path: string, opts?: {
23
+ query?: Query;
24
+ body?: unknown;
25
+ }): Promise<WpResponse<T>>;
26
+ request<T>(method: string, path: string, opts?: {
27
+ query?: Query;
28
+ body?: unknown;
29
+ }): Promise<T>;
30
+ }
31
+ export {};
@@ -0,0 +1,94 @@
1
+ import { PACKAGE_NAME, VERSION } from './version.js';
2
+ export class WpError extends Error {
3
+ status;
4
+ code;
5
+ data;
6
+ constructor(status, code, message, data) {
7
+ super(message);
8
+ this.status = status;
9
+ this.code = code;
10
+ this.data = data;
11
+ this.name = 'WpError';
12
+ }
13
+ }
14
+ /** Minimal WordPress REST client: Basic auth (application password) plus optional Cloudflare Access service token. */
15
+ export class WpClient {
16
+ config;
17
+ fetchImpl;
18
+ timeoutMs;
19
+ constructor(config, fetchImpl = fetch, timeoutMs = 30_000) {
20
+ this.config = config;
21
+ this.fetchImpl = fetchImpl;
22
+ this.timeoutMs = timeoutMs;
23
+ }
24
+ get configured() {
25
+ return Boolean(this.config.wpUrl && this.config.wpUser && this.config.wpPassword) && this.config.problems.length === 0;
26
+ }
27
+ headers(hasBody) {
28
+ const headers = {
29
+ Accept: 'application/json',
30
+ 'User-Agent': `${PACKAGE_NAME}/${VERSION}`,
31
+ Authorization: `Basic ${Buffer.from(`${this.config.wpUser}:${this.config.wpPassword}`).toString('base64')}`,
32
+ };
33
+ if (this.config.accessMode === 'service-token') {
34
+ headers['CF-Access-Client-Id'] = this.config.cfClientId ?? '';
35
+ headers['CF-Access-Client-Secret'] = this.config.cfClientSecret ?? '';
36
+ }
37
+ if (hasBody)
38
+ headers['Content-Type'] = 'application/json';
39
+ return headers;
40
+ }
41
+ async send(method, path, opts = {}) {
42
+ if (!this.configured) {
43
+ throw new WpError(0, 'NOT_CONFIGURED', `MCP is not configured: ${this.config.problems.join(' ') || 'missing settings'}`);
44
+ }
45
+ const url = new URL(`${this.config.wpUrl}/wp-json${path}`);
46
+ for (const [key, value] of Object.entries(opts.query ?? {})) {
47
+ if (value !== undefined)
48
+ url.searchParams.set(key, String(value));
49
+ }
50
+ let res;
51
+ try {
52
+ res = await this.fetchImpl(url, {
53
+ method,
54
+ headers: this.headers(opts.body !== undefined),
55
+ body: opts.body === undefined ? undefined : JSON.stringify(opts.body),
56
+ redirect: 'manual',
57
+ signal: AbortSignal.timeout(this.timeoutMs),
58
+ });
59
+ }
60
+ catch (e) {
61
+ const reason = e instanceof Error ? e.message : String(e);
62
+ throw new WpError(0, 'NETWORK', `Could not reach WordPress: ${reason}`);
63
+ }
64
+ if (res.status >= 300 && res.status < 400) {
65
+ const location = res.headers.get('location') ?? '';
66
+ const access = /cloudflareaccess\.com|cdn-cgi\/access/.test(location);
67
+ throw new WpError(res.status, access ? 'ACCESS_BLOCKED' : 'REDIRECT', access
68
+ ? 'Cloudflare Access blocked the request. Use a service token (CF_ACCESS_CLIENT_ID/SECRET) or connect from an allowed network (static IP bypass or WARP).'
69
+ : `WordPress redirected the request to ${location || 'another URL'}. Check the WordPress URL (https, no redirect, permalinks enabled).`);
70
+ }
71
+ const text = await res.text();
72
+ let data = null;
73
+ if (text) {
74
+ try {
75
+ data = JSON.parse(text);
76
+ }
77
+ catch {
78
+ const access = /cloudflare access|cloudflareaccess/i.test(text);
79
+ throw new WpError(res.status, access ? 'ACCESS_BLOCKED' : 'NOT_JSON', access
80
+ ? 'Cloudflare Access returned its login page. Use a service token or an allowed network.'
81
+ : `WordPress returned a non-JSON response (HTTP ${res.status}). Is the URL a WordPress site with the REST API enabled?`);
82
+ }
83
+ }
84
+ if (!res.ok) {
85
+ const body = (data ?? {});
86
+ throw new WpError(res.status, body.code ?? `HTTP_${res.status}`, body.message ?? `HTTP ${res.status}`, body.data ?? data);
87
+ }
88
+ return { status: res.status, data: data, headers: res.headers };
89
+ }
90
+ async request(method, path, opts = {}) {
91
+ return (await this.send(method, path, opts)).data;
92
+ }
93
+ }
94
+ //# sourceMappingURL=wp-client.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"wp-client.js","sourceRoot":"","sources":["../src/wp-client.ts"],"names":[],"mappings":"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"}
package/docs/README.md ADDED
@@ -0,0 +1,114 @@
1
+ # @marvalt/digivalt-mcp: configuration and operation
2
+
3
+ ## Environment variables
4
+
5
+ Loaded from the shell, then `.env.local`, then `.env` in the working directory (or `--cwd`). The shell wins.
6
+
7
+ | Variable | Required | Notes |
8
+ |----------|----------|-------|
9
+ | `VITE_WORDPRESS_API_URL` | yes | Site root or `/wp-json` URL. Alias `DIGIVALT_MCP_WP_URL`. HTTPS required except localhost. |
10
+ | `DIGIVALT_MCP_WP_USER` / `DIGIVALT_MCP_WP_APP_PASSWORD` | yes | Dedicated agent user. Falls back to `WP_API_USERNAME` / `WP_APP_PASSWORD` with a notice. |
11
+ | `CF_ACCESS_CLIENT_ID` / `CF_ACCESS_CLIENT_SECRET` | no | Cloudflare Access service token. Both or neither. |
12
+ | `VITE_ENABLED_POST_TYPES` | no | Post types the agent may edit. `page` is always included; `google_reviews` is ignored. |
13
+ | `VITE_STAGING_FRONTEND` | no | Frontend slug that drafts are pinned to. |
14
+ | `DIGIVALT_MCP_EXTRA_BLOCKS` | no | Comma-separated block names the app's own registry renders beyond the defaults. |
15
+ | `DIGIVALT_MCP_PUBLISH_USER` / `DIGIVALT_MCP_PUBLISH_APP_PASSWORD` | no | A separate WordPress user who can publish (for example an Editor). Enables `promote_page`, `publish_page`, `rollback_page` only. Both or neither. |
16
+ | `DIGIVALT_MCP_REQUIRE_ELICITATION` | no | `true`: publishing needs a client that can prompt the person; the approval-code fallback is disabled. |
17
+ | `DIGIVALT_MCP_WRITE_LIMIT` | no | Writes allowed per 10 minutes (default 60). Reads are not counted. |
18
+ | `DIGIVALT_MCP_DATA_DIR` | no | Folder for `.env.local`, the audit log and the app's static data when `--cwd` is not given. The desktop extension sets it from its "Working folder" field. |
19
+
20
+ ## Claude Desktop extension (.mcpb)
21
+
22
+ For people who do not work in the app repository (content managers). One file, no Node, no `.env`.
23
+
24
+ 1. Get `digivalt-mcp-<version>.mcpb` (GitHub release, or `npm run pack:mcpb` in the package).
25
+ 2. Claude Desktop: Settings, Extensions, install the file (or open it).
26
+ 3. Fill the form: WordPress URL, agent user and application password, staging frontend. Add the Cloudflare Access client ID and secret only if the site is behind Access, and the publisher user and password only if this person may publish (each publish still needs their approval). Leave unused fields empty.
27
+ 4. Ask Claude to call `site_info`.
28
+
29
+ Notes:
30
+ - Password and secret fields are entered once and kept by Claude Desktop, not in a project folder.
31
+ - "Working folder" holds the audit log. Choose an app repository to also allow `refresh_static_data`; its `.env.local` fills anything not entered in the form.
32
+ - To update, install the new `.mcpb` over the old one. To revoke access, delete the application passwords in WordPress.
33
+ - The same bundle (`server/index.mjs` inside the file) runs in any client that starts a stdio command: `node server/index.mjs` with the variables above in the client's `env`.
34
+
35
+ ## WordPress requirements
36
+
37
+ - Plugin `wp-pagesync` 2.1.0 or later, active (2.0.1 cannot upload media; before 2.1.0 there is no preview overlay).
38
+ - Agent user with `edit_pages`, `edit_others_pages`, `upload_files`; without `publish_pages` and `edit_published_pages`.
39
+ - Application passwords enabled (HTTPS in production).
40
+
41
+ ## Writing pages
42
+
43
+ `create_page` and `update_page` take either `content` (block markup) or `blocks` (a JSON tree). The tree is serialized into canonical markup for blocks the frontend renders: group, heading, paragraph, shortcode, image, list, columns, buttons, quote, separator, spacer, cover, code, html. Text allows only `a`, `strong`, `em`, `b`, `i`, `br`, `span`, `code`, `sup`, `sub`, `mark`; URLs must be https, relative, `#`, `mailto:` or `tel:`.
44
+
45
+ Rules enforced before any request:
46
+
47
+ - `VITE_STAGING_FRONTEND` must be set. Drafts are pinned to it and the server refuses other frontends.
48
+ - `post_type` must be in `VITE_ENABLED_POST_TYPES` (`page` always).
49
+ - Content must pass local validation (no errors). Warnings are returned but do not block.
50
+
51
+ Published pages are never edited in place: `update_page` writes to a shadow draft (`source_id` is the live page) and leaves the live page untouched. The agent user has no publish rights, so promote, publish and rollback return 403 for it.
52
+
53
+ `upload_media` reads a local file, checks type (by content, not extension), size and dimensions (limits come from the server, defaults 12 MB and 3840x2160), requires alt text, and uploads as base64. SVG is refused. Identical files are reused (`deduplicated: true`).
54
+
55
+ `set_seo` accepts `title`, `description`, `canonical`, `og_image_id`, `robots_index`, `robots_follow`, `og_type`, `schema_type`, `faq`.
56
+
57
+ ### Audit log
58
+
59
+ `.digivalt-mcp/audit.jsonl` in the working directory: one JSON line per write attempt (including rejected ones) with time, WordPress user, tool, post id, outcome and a SHA-256 of the content.
60
+
61
+ ## Publishing
62
+
63
+ Offered only when a publisher credential is set (`site_info.can_publish`). The agent user keeps its own credential for everything else and still gets 403 on the publish routes.
64
+
65
+ | Tool | Does |
66
+ |------|------|
67
+ | `promote_page` | Shadow draft becomes the live content. Refuses if the live page changed after the draft was made (`E_SOURCE_CHANGED`; `force` overrides), or if there is nothing to promote. `allow_slug_change` permits a URL change. A revision is kept. |
68
+ | `publish_page` | Publishes a never-published draft. `add_frontends` must be in the site's publishable list. |
69
+ | `rollback_page` | Restores the revision saved by the last promote, or `revision_id`. |
70
+
71
+ Approval, in order of preference:
72
+
73
+ 1. **Prompt.** If the client supports MCP elicitation, the person sees the plan (diff, options) and approves or declines in their client. The agent cannot answer it.
74
+ 2. **Approval code.** Otherwise the first call returns the plan and a single-use code (5 minutes, bound to that exact plan). After the person says yes in chat, the agent repeats the call with `approval_code`. An agent could pass the code without asking, so this guards against mistakes, not a hostile agent. Set `DIGIVALT_MCP_REQUIRE_ELICITATION=true` to disable it.
75
+
76
+ Audit lines for these tools add `publisher`, `approval` (`elicitation` or `code`), `plan_sha256` and `revision_id`.
77
+
78
+ ### Limits
79
+
80
+ Writes are budgeted per session (default 60 per 10 minutes, `RATE_LIMITED` beyond). Content over 500 KB, or blocks nested deeper than 12 levels, is rejected before any request. Credentials are redacted from returned errors and audit details.
81
+
82
+ ## Previewing drafts locally
83
+
84
+ `refresh_static_data` (developers only; offered when the MCP runs in an app repo) runs `npm run generate` with `VITE_PREVIEW_DRAFTS=true`. `@marvalt/digivalt-core` 0.2.50+ then overlays shadow drafts and new drafts (pages and posts) onto `public/wordpress-data.json`. Reload the dev server afterwards.
85
+
86
+ Guards: `VITE_STAGING_FRONTEND` must be set and `VITE_FRONTEND_ID` must equal it (set it in `.env.local` for local previews); WordPress also refuses draft listings for any frontend not configured as staging. The run has a 3-minute timeout, secrets are redacted from the returned output, and the run is audited. See `@marvalt/digivalt-core` `docs/PREVIEW-DRAFTS.md`.
87
+
88
+ The staging site shows drafts after its own build; `wp-pagesync` requests a debounced staging build after each write.
89
+
90
+ ## Validation
91
+
92
+ `validate_page` runs two layers:
93
+
94
+ 1. Local: will the frontend render this? Unrendered blocks, shortcodes outside paragraphs, unknown or wp-only shortcodes, missing or invalid shortcode attributes, structure warnings (top-level groups, one H1, heading order, image alt), scripts and the Gravity Forms shortcode.
95
+ 2. WordPress (`POST /digivalt-mcp/v1/validate`): allowlist, external media hosts, loose HTML and round-trip stability.
96
+
97
+ Errors block writing; warnings are advice.
98
+
99
+ ## Troubleshooting
100
+
101
+ | Code | Meaning |
102
+ |------|---------|
103
+ | `NOT_CONFIGURED` | URL or credentials missing. See `site_info.problems`. |
104
+ | `ACCESS_BLOCKED` | Cloudflare Access refused the request. Use a service token or an allowed network. |
105
+ | 401 | Wrong user or application password. |
106
+ | 403 | User lacks the capability. Ask a publisher or administrator. |
107
+ | `E_SOURCE_CHANGED` | Live page edited after the draft; diff, merge, retry (or `force`). |
108
+ | `E_REVISIONS_DISABLED` | Enable WordPress revisions; promote needs them for rollback. |
109
+ | `APPROVAL_DECLINED` / `APPROVAL_INVALID` / `ELICITATION_REQUIRED` | The person declined; the code is wrong, used or expired; or the client cannot prompt and strict mode is on. |
110
+ | `rest_no_route` | `wp-pagesync` 2.x is not active. |
111
+
112
+ ## Catalogues
113
+
114
+ The block and shortcode catalogues are built into the package (`src/catalogue`) and versioned by date. Update them when `@marvalt/wparser` or the shortcode packages change.
@@ -0,0 +1,44 @@
1
+ # Security model
2
+
3
+ ## Principles
4
+
5
+ 1. WordPress decides what is allowed. The agent user has no publish rights, so a compromised or confused agent cannot publish with its own credential. The MCP's checks add early, friendly failures; they are not the last line.
6
+ 2. Drafts only, staging only. Writes are pinned to `VITE_STAGING_FRONTEND`. Published pages are never edited in place; changes go to a shadow draft.
7
+ 3. Publishing needs two separate things: a publisher credential the operator chose to add, and the person's approval of each action.
8
+ 4. Everything that writes is audited locally, without content or credentials.
9
+
10
+ ## Credentials
11
+
12
+ | Credential | Used by | Rights |
13
+ |------------|---------|--------|
14
+ | Agent user (`DIGIVALT_MCP_WP_*`) | all tools except publish ones | `edit_pages`, `edit_others_pages`, `upload_files`; no `publish_pages`, no `edit_published_pages` |
15
+ | Publisher (`DIGIVALT_MCP_PUBLISH_*`) | `promote_page`, `publish_page`, `rollback_page` | Publish rights, for example an Editor |
16
+
17
+ Keep the publisher credential out of `.env.local` by default and add it for a session where publishing is wanted. Use application passwords, revoke them after the session, and never reuse the agent user as the publisher (the MCP warns if they are the same).
18
+
19
+ ## Approval
20
+
21
+ - With a client that supports MCP elicitation, the person answers a native prompt showing the diff. The agent cannot answer it.
22
+ - Without it, a single-use code bound to the exact plan, valid 5 minutes, is returned. A hostile agent can relay it without asking; this mode guards against mistakes. `DIGIVALT_MCP_REQUIRE_ELICITATION=true` removes it.
23
+ - `force` (overwrite newer live edits) and `allow_slug_change` appear in the approval text. A promote is refused up front if the live page changed after the draft was made.
24
+ - Rollback restores a WordPress revision created at promote time; the live page can be restored again.
25
+
26
+ ## Threats
27
+
28
+ | Threat | Mitigation |
29
+ |--------|------------|
30
+ | Prompt injection in a brief, a page or fetched content tells the agent to publish | No publisher credential by default; with one, each action still needs the person's approval; content is validated and sanitized (no scripts, allowlisted blocks and HTML, https/relative URLs only) |
31
+ | Agent loops and floods WordPress | Write budget (60 per 10 minutes), size cap 500 KB, nesting cap 12 |
32
+ | Agent overwrites someone's live edit | Stale-source check; revisions; rollback |
33
+ | Secrets leak through errors or logs | Redaction of all configured secrets in returned errors and audit detail; audit never stores content; stderr-only logging |
34
+ | Draft reaches production | Drafts are pinned to staging; the preview overlay refuses without a matching staging frontend; WordPress refuses draft listings to non-staging frontends |
35
+ | Malicious image upload | Type read from bytes, size and dimension limits, SVG refused, alt required, server re-checks |
36
+ | Cloudflare Access bypass | Service token only; redirects to Access are reported, never followed |
37
+
38
+ ## Desktop extension
39
+
40
+ The `.mcpb` form marks passwords and secrets as sensitive, so Claude Desktop masks them and keeps them outside any project folder. The server receives them as environment variables, like any stdio client. The same residual risk applies (below): software running as the same user can read what the desktop app can read. The publisher fields are optional; leave them empty on machines whose users should not publish.
41
+
42
+ ## Residual risk
43
+
44
+ A local stdio MCP runs with the developer's privileges and reads `.env.local`. Anyone who can run commands as that developer can read the credentials directly; the approval gate does not protect against that. Use short-lived, revocable application passwords.
package/package.json CHANGED
@@ -1,6 +1,53 @@
1
1
  {
2
2
  "name": "@marvalt/digivalt-mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.5.0",
4
+ "description": "MCP server for building and editing DigiValt WordPress pages with AI agents",
5
+ "license": "GPL-3.0-or-later",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/MarVAlt-Project/digivalt-mcp.git"
9
+ },
10
+ "type": "module",
11
+ "main": "dist/index.js",
12
+ "types": "dist/index.d.ts",
13
+ "bin": {
14
+ "digivalt-mcp": "dist/cli.js"
15
+ },
16
+ "exports": {
17
+ ".": {
18
+ "types": "./dist/index.d.ts",
19
+ "import": "./dist/index.js"
20
+ }
21
+ },
22
+ "files": [
23
+ "dist",
24
+ "docs",
25
+ "README.md",
26
+ "CHANGELOG.md",
27
+ "LICENSE"
28
+ ],
29
+ "engines": {
30
+ "node": ">=20.12.0"
31
+ },
32
+ "scripts": {
33
+ "build": "tsc -p tsconfig.build.json",
34
+ "typecheck": "tsc --noEmit",
35
+ "test": "vitest run",
36
+ "clean": "rimraf dist",
37
+ "prepublishOnly": "npm run clean && npm run build && node ../scripts/verify-pack.cjs",
38
+ "pack:mcpb": "node scripts/build-mcpb.mjs"
39
+ },
40
+ "dependencies": {
41
+ "@modelcontextprotocol/sdk": "^1.32.2",
42
+ "@wordpress/block-serialization-default-parser": "^6.1.0",
43
+ "zod": "^4.6.7"
44
+ },
45
+ "devDependencies": {
46
+ "@anthropic-ai/mcpb": "^2.1.2",
47
+ "@types/node": "^26.6.6",
48
+ "esbuild": "^0.28.2",
49
+ "rimraf": "^6.1.4",
50
+ "typescript": "^7.0.2",
51
+ "vitest": "^5.1.0"
52
+ }
53
+ }