@patronage/mcp-wordpress 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patronage
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @patronage/mcp-wordpress
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The WordPress connector for [`@patronage/mcp-core`](../mcp-core). In the gateway's sandbox it is `wp`:
+
+- `wp.graphql({ query, variables? })` runs WPGraphQL queries, never mutations.
+- `wp.get({ path, query? })` reads the REST API under `/wp-json/`, and refuses method overrides.
+- `wp.apply({ intent, operations })` stages `update_post` operations (core and ACF fields, with an optional `expected_modified_gmt` check) for approval.
+
+It also gives `describe_site` the site's post types and GraphQL types.
+
+Requests go out as the signed-in person: the gateway forwards the Access JWT with a proof signed by `WORDPRESS_ACCESS_PROOF_SECRET`, which the `patronage-access` mu-plugin checks before it maps the JWT to a WordPress user. Bindings are in `WordPressEnv` (`src/env.ts`); the connector is on when `WORDPRESS_API_URL` is set.
+
+```ts
+import { wordpressConnector } from "@patronage/mcp-wordpress";
+```

package/dist/index.d.ts

@@ -0,0 +1,147 @@
+import { AccessResult, ApplyPreflight, BatchReceipt, ConnectorDeps, GatewayConnector, JsonObject, JsonValue, UpstreamClient, UpstreamFetchResult, UpstreamResponseInfo, UpstreamTelemetry } from "@patronage/mcp-core";
+import { z } from "zod";
+interface PostTypeSummary {
+  name: string;
+  rest_base: string;
+  supports: string[];
+  taxonomies: string[];
+}
+interface GraphqlTypeSummary {
+  fields: string[];
+  name: string;
+}
+interface WordPressDescription {
+  acfTypes: GraphqlTypeSummary[];
+  contentTypes: GraphqlTypeSummary[];
+  postTypes: PostTypeSummary[];
+  site: {
+    name: string;
+    url: string;
+  };
+}
+export declare const buildSiteDescription: (client: UpstreamClient, telemetry: UpstreamTelemetry) => Promise<WordPressDescription>;
+interface WordPressEnv {
+  WORDPRESS_ACCESS_CLIENT_ID?: string;
+  WORDPRESS_ACCESS_CLIENT_SECRET?: string;
+  WORDPRESS_ACCESS_PROOF_SECRET?: string;
+  WORDPRESS_API_URL?: string;
+}
+export declare const inspectWordPressResponse: (response: Response, json: JsonValue) => UpstreamResponseInfo;
+type VerifiedAccessResult = Extract<AccessResult, {
+  ok: true;
+}>;
+export declare const createWordPressClient: (env: WordPressEnv, access: VerifiedAccessResult) => UpstreamClient;
+export declare const wpFetch: (client: UpstreamClient, path: string, telemetry: UpstreamTelemetry, init?: RequestInit) => Promise<UpstreamFetchResult>;
+export declare const wpGraphql: (client: UpstreamClient, query: string, variables: JsonObject | undefined, telemetry: UpstreamTelemetry) => Promise<JsonValue>;
+declare const updatePostOperationSchema: z.ZodObject<{
+  acf: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+  expected_modified_gmt: z.ZodOptional<z.ZodString>;
+  fields: z.ZodOptional<z.ZodObject<{
+    content: z.ZodOptional<z.ZodString>;
+    excerpt: z.ZodOptional<z.ZodString>;
+    slug: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodEnum<{
+      draft: "draft";
+      pending: "pending";
+      private: "private";
+      publish: "publish";
+    }>>;
+    title: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  id: z.ZodNumber;
+  kind: z.ZodLiteral<"update_post">;
+  rest_base: z.ZodString;
+}, z.core.$strict>;
+type UpdatePostOperation = z.infer<typeof updatePostOperationSchema>;
+type WriteOperation = UpdatePostOperation;
+export declare const applyInputSchema: z.ZodObject<{
+  intent: z.ZodString;
+  operations: z.ZodArray<z.ZodObject<{
+    acf: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodJSONSchema>>;
+    expected_modified_gmt: z.ZodOptional<z.ZodString>;
+    fields: z.ZodOptional<z.ZodObject<{
+      content: z.ZodOptional<z.ZodString>;
+      excerpt: z.ZodOptional<z.ZodString>;
+      slug: z.ZodOptional<z.ZodString>;
+      status: z.ZodOptional<z.ZodEnum<{
+        draft: "draft";
+        pending: "pending";
+        private: "private";
+        publish: "publish";
+      }>>;
+      title: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    id: z.ZodNumber;
+    kind: z.ZodLiteral<"update_post">;
+    rest_base: z.ZodString;
+  }, z.core.$strict>>;
+}, z.core.$strip>;
+type ApplyInput = z.infer<typeof applyInputSchema>;
+export declare const parseApplyInput: <T>(input: T) => ApplyInput;
+export declare const preflightOperations: (client: UpstreamClient, intent: string, operations: WriteOperation[], telemetry: UpstreamTelemetry) => Promise<ApplyPreflight>;
+export declare const applyOperations: (options: {
+  approverOpaque: string;
+  client: UpstreamClient;
+  executionId: string;
+  operations: WriteOperation[];
+  preflight: ApplyPreflight;
+  requesterOpaque: string;
+  telemetry: UpstreamTelemetry;
+}) => Promise<BatchReceipt>;
+export declare const wordpressConnector: GatewayConnector<WordPressEnv>;
+export declare const WP_CONNECTOR_INSTRUCTIONS: string;
+export declare const createWordPressTools: (deps: ConnectorDeps<WordPressEnv>) => {
+  apply: {
+    description: string;
+    execute: <T>(args: T, ctx: import("@patronage/mcp-core").ToolCallContext | undefined) => Promise<import("@patronage/mcp-core").BatchReceipt>;
+    inputSchema: {
+      properties: {
+        intent: {
+          type: "string";
+        };
+        operations: {
+          items: {
+            type: "object";
+          };
+          type: "array";
+        };
+      };
+      required: string[];
+      type: "object";
+    };
+    requiresApproval: true;
+  };
+  get: {
+    description: string;
+    execute: <T>(args: T) => Promise<z.JSONType>;
+    inputSchema: {
+      properties: {
+        path: {
+          type: "string";
+        };
+        query: {
+          type: "object";
+        };
+      };
+      required: string[];
+      type: "object";
+    };
+  };
+  graphql: {
+    description: string;
+    execute: <T>(args: T) => Promise<z.JSONType>;
+    inputSchema: {
+      properties: {
+        query: {
+          type: "string";
+        };
+        variables: {
+          type: "object";
+        };
+      };
+      required: string[];
+      type: "object";
+    };
+  };
+};
+export type { ApplyInput, WordPressDescription, WordPressEnv, WriteOperation };

package/dist/index.js

@@ -0,0 +1,689 @@
+import { ApplyConflictError, ApplyValidationError, MAX_OPERATIONS, UpstreamRequestError, assertSafeApiUrl, batchStatus, deepEqual, joinPhrase, numericHeader, previewValue, upstreamActorSchema, upstreamFetch } from "@patronage/mcp-core";
+import { z } from "zod";
+import { Kind, OperationTypeNode, parse } from "graphql";
+// src/wordpress.ts
+const MAX_WORDPRESS_ERROR_CODE_LENGTH = 64;
+const WORDPRESS_USER_ID_HEADER = "X-Access-WordPress-User-ID";
+const WORDPRESS_USER_SLUG_HEADER = "X-Access-WordPress-User-Slug";
+const jsonObjectSchema = z.record(z.string(), z.json());
+const stringSchema$1 = z.string();
+const resolveWpUrl = (apiUrl, path) => {
+	if (/^[a-zA-Z][a-zA-Z0-9+.-]*:/u.test(path) || path.startsWith("//")) throw new UpstreamRequestError("WordPress path must be a site-relative /wp-json/ path");
+	if (!path.startsWith("/wp-json/")) throw new UpstreamRequestError("WordPress path must start with /wp-json/");
+	const base = assertSafeApiUrl(apiUrl);
+	const url = new URL(path, base);
+	if (url.origin !== base.origin) throw new UpstreamRequestError("WordPress path escaped origin");
+	if (!url.pathname.startsWith("/wp-json/")) throw new UpstreamRequestError("WordPress path escaped /wp-json/");
+	return url;
+};
+const boundedWordPressErrorCode = (value) => {
+	if (!/^[a-z0-9_]+$/u.test(value)) return;
+	return value.slice(0, MAX_WORDPRESS_ERROR_CODE_LENGTH);
+};
+const wordPressErrorCode = (json) => {
+	const object = jsonObjectSchema.safeParse(json);
+	if (!object.success) return;
+	const code = stringSchema$1.safeParse(object.data.code);
+	return code.success ? boundedWordPressErrorCode(code.data) : void 0;
+};
+const wordPressErrorMessage = (status, errorCode) => {
+	switch (errorCode) {
+		case "patronage_access_invalid_token": return "WordPress rejected the Access token. Reconnect the MCP client and retry.";
+		case "patronage_access_no_email": return "Service tokens cannot act as a WordPress user.";
+		case "patronage_access_missing_proof":
+		case "patronage_access_invalid_proof": return "WordPress rejected the gateway proof. The Worker and WordPress proof secrets are out of sync.";
+		case "patronage_access_no_user": return "No WordPress account matches your Access login. Ask a site administrator to create one with the same email.";
+		case "patronage_access_not_configured": return "The WordPress site's Access authentication plugin is not configured.";
+		case "rest_cannot_view":
+		case "rest_forbidden":
+		case "rest_forbidden_context":
+		case "rest_forbidden_status": return "Your WordPress account does not have permission for this content.";
+	}
+	if (status === 401 || status === 403) return "WordPress did not accept the request's authentication.";
+};
+const wordpressActor = (headers) => {
+	const id = numericHeader(headers, WORDPRESS_USER_ID_HEADER);
+	const encodedSlug = headers.get(WORDPRESS_USER_SLUG_HEADER);
+	if (!(id && encodedSlug)) return;
+	let slug;
+	try {
+		slug = decodeURIComponent(encodedSlug);
+	} catch {
+		return;
+	}
+	const parsed = upstreamActorSchema.safeParse({
+		id,
+		slug
+	});
+	return parsed.success ? parsed.data : void 0;
+};
+const inspectWordPressResponse = (response, json) => ({
+	actor: wordpressActor(response.headers),
+	errorCode: wordPressErrorCode(json),
+	totalItems: numericHeader(response.headers, "X-WP-Total"),
+	totalPages: numericHeader(response.headers, "X-WP-TotalPages")
+});
+const createWordPressClient = (env, access) => {
+	const apiUrl = env.WORDPRESS_API_URL?.trim();
+	if (!apiUrl) throw new UpstreamRequestError("WORDPRESS_API_URL is not configured");
+	assertSafeApiUrl(apiUrl);
+	const auth = {
+		kind: "access-jwt",
+		token: access.token
+	};
+	const proofSecret = env.WORDPRESS_ACCESS_PROOF_SECRET?.trim();
+	if (proofSecret) auth.proofSecret = proofSecret;
+	const clientId = env.WORDPRESS_ACCESS_CLIENT_ID?.trim();
+	const clientSecret = env.WORDPRESS_ACCESS_CLIENT_SECRET?.trim();
+	if (clientId && clientSecret) auth.serviceToken = {
+		clientId,
+		clientSecret
+	};
+	return {
+		apiUrl,
+		auth,
+		inspect: inspectWordPressResponse,
+		label: "WordPress"
+	};
+};
+const wpFetch = async (client, path, telemetry, init = {}) => await upstreamFetch(client, resolveWpUrl(client.apiUrl, path), telemetry, init);
+const graphqlUrl = (apiUrl) => new URL("/graphql", assertSafeApiUrl(apiUrl));
+const wpGraphql = async (client, query, variables, telemetry) => {
+	const body = variables ? {
+		query,
+		variables
+	} : { query };
+	const result = await upstreamFetch(client, graphqlUrl(client.apiUrl), telemetry, {
+		body: JSON.stringify(body),
+		headers: { "Content-Type": "application/json" },
+		method: "POST"
+	});
+	if (result.status < 200 || result.status >= 300) throw new UpstreamRequestError(wordPressErrorMessage(result.status, result.errorCode) ?? "WPGraphQL request failed");
+	return result.json;
+};
+// src/describe.ts
+const MAX_CONTENT_TYPES = 40;
+const MAX_FIELDS = 60;
+const CONTENT_NODE_INTERFACE = "ContentNode";
+const ACF_GROUP_INTERFACE = "AcfFieldGroup";
+const SCHEMA_INTROSPECTION_ERROR_MESSAGE = "WordPress GraphQL schema introspection failed.";
+const SCHEMA_QUERY = `query LaunchMcpSchema {
+  __schema {
+    types {
+      kind
+      name
+      interfaces { name }
+      fields {
+        name
+        type { kind name ofType { kind name ofType { kind name } } }
+      }
+    }
+  }
+}`;
+const postTypeSchema = z.object({
+	name: z.string(),
+	rest_base: z.string().min(1),
+	supports: z.record(z.string(), z.boolean()).optional(),
+	taxonomies: z.array(z.string()).optional()
+});
+const namedTypeSchema = z.object({
+	kind: z.string().optional(),
+	name: z.string().nullable().optional(),
+	ofType: z.lazy(() => namedTypeSchema).nullable().optional()
+});
+const schemaTypeSchema = z.object({
+	fields: z.array(z.object({
+		name: z.string(),
+		type: namedTypeSchema
+	})).nullable().optional(),
+	interfaces: z.array(z.object({ name: z.string().nullable() })).nullable().optional(),
+	kind: z.string(),
+	name: z.string()
+});
+const introspectionSchema = z.object({ data: z.object({ __schema: z.object({ types: z.array(schemaTypeSchema) }) }) });
+const graphqlErrorsSchema = z.object({ errors: z.array(z.json()).min(1) });
+const siteRootSchema = z.object({
+	name: z.string(),
+	url: z.string()
+});
+const parsePostTypes = (value) => {
+	const record = z.record(z.string(), z.json()).safeParse(value);
+	if (!record.success) return [];
+	const summaries = [];
+	for (const entry of Object.values(record.data)) {
+		const parsed = postTypeSchema.safeParse(entry);
+		if (!parsed.success) continue;
+		summaries.push({
+			name: parsed.data.name,
+			rest_base: parsed.data.rest_base,
+			supports: Object.entries(parsed.data.supports ?? {}).filter(([, enabled]) => enabled).map(([key]) => key).toSorted(),
+			taxonomies: parsed.data.taxonomies ?? []
+		});
+	}
+	return summaries;
+};
+const unwrapKind = (type) => type.ofType ? unwrapKind(type.ofType) : type.kind ?? "";
+const hasInterface = (interfaces, target) => (interfaces ?? []).some((entry) => entry.name === target);
+const hasGraphqlErrors = (value) => graphqlErrorsSchema.safeParse(value).success;
+const summarizeSchema = (value) => {
+	const parsed = introspectionSchema.safeParse(value);
+	if (!parsed.success) return {
+		acfTypes: [],
+		contentTypes: []
+	};
+	const acfTypes = [];
+	const contentTypes = [];
+	for (const type of parsed.data.data.__schema.types) {
+		if (type.kind !== "OBJECT") continue;
+		const fields = type.fields ?? [];
+		if (hasInterface(type.interfaces, ACF_GROUP_INTERFACE)) {
+			acfTypes.push({
+				fields: fields.map((field) => field.name).toSorted().slice(0, MAX_FIELDS),
+				name: type.name
+			});
+			continue;
+		}
+		if (!hasInterface(type.interfaces, CONTENT_NODE_INTERFACE)) continue;
+		contentTypes.push({
+			fields: fields.filter((field) => {
+				const kind = unwrapKind(field.type);
+				return kind === "SCALAR" || kind === "ENUM";
+			}).map((field) => field.name).toSorted().slice(0, MAX_FIELDS),
+			name: type.name
+		});
+	}
+	return {
+		acfTypes,
+		contentTypes: contentTypes.slice(0, MAX_CONTENT_TYPES)
+	};
+};
+const buildSiteDescription = async (client, telemetry) => {
+	const root = await wpFetch(client, "/wp-json/", telemetry);
+	const types = await wpFetch(client, "/wp-json/wp/v2/types?context=edit", telemetry);
+	for (const response of [root, types]) if (response.status < 200 || response.status >= 300) throw new UpstreamRequestError(wordPressErrorMessage(response.status, response.errorCode) ?? `WordPress returned HTTP ${response.status}`);
+	const schema = await wpGraphql(client, SCHEMA_QUERY, void 0, telemetry);
+	if (hasGraphqlErrors(schema)) throw new UpstreamRequestError(SCHEMA_INTROSPECTION_ERROR_MESSAGE);
+	const site = siteRootSchema.safeParse(root.json);
+	return {
+		...summarizeSchema(schema),
+		postTypes: parsePostTypes(types.json),
+		site: site.success ? {
+			name: site.data.name,
+			url: site.data.url
+		} : {
+			name: "unknown",
+			url: client.apiUrl
+		}
+	};
+};
+// src/wp-operations.ts
+const FIELD_ORDER = [
+	"title",
+	"content",
+	"excerpt",
+	"slug",
+	"status"
+];
+const restBaseSchema = z.string().trim().min(1).max(64).regex(/^[a-z0-9_-]+$/u);
+const updatePostFieldsSchema = z.strictObject({
+	content: z.string().max(5e5).optional(),
+	excerpt: z.string().max(5e4).optional(),
+	slug: z.string().trim().min(1).max(200).optional(),
+	status: z.enum([
+		"draft",
+		"pending",
+		"private",
+		"publish"
+	]).optional(),
+	title: z.string().max(500).optional()
+});
+const changedFieldKeys = (fields) => FIELD_ORDER.filter((key) => fields?.[key] !== void 0);
+const updatePostOperationSchema = z.strictObject({
+	acf: z.record(z.string().min(1).max(64), z.json()).optional(),
+	expected_modified_gmt: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/u).optional(),
+	fields: updatePostFieldsSchema.optional(),
+	id: z.number().int().positive(),
+	kind: z.literal("update_post"),
+	rest_base: restBaseSchema
+}).refine((operation) => changedFieldKeys(operation.fields).length > 0 || Object.keys(operation.acf ?? {}).length > 0, { message: "operation must change at least one field or acf key" });
+const operationTarget = (operation) => `${operation.rest_base}/${operation.id}`;
+const DUPLICATE_TARGET_CODE = "duplicate_target";
+const duplicateTargetIssueSchema = z.object({ params: z.object({ code: z.literal(DUPLICATE_TARGET_CODE) }) });
+const applyInputSchema = z.object({
+	intent: z.string().trim().min(1).max(500),
+	operations: z.array(updatePostOperationSchema).min(1).max(MAX_OPERATIONS)
+}).superRefine((input, ctx) => {
+	const seen = /* @__PURE__ */ new Set();
+	for (const [index, operation] of input.operations.entries()) {
+		const target = operationTarget(operation);
+		if (seen.has(target)) ctx.addIssue({
+			code: "custom",
+			message: `batch addresses ${target} more than once`,
+			params: { code: DUPLICATE_TARGET_CODE },
+			path: ["operations", index]
+		});
+		seen.add(target);
+	}
+});
+const parseApplyInput = (input) => {
+	const parsed = applyInputSchema.safeParse(input);
+	if (parsed.success) return parsed.data;
+	const detail = parsed.error.issues.map((issue) => `${issue.path.join(".")}: ${issue.message}`).join("; ");
+	const duplicate = parsed.error.issues.some((issue) => duplicateTargetIssueSchema.safeParse(issue).success);
+	throw new ApplyValidationError(duplicate ? DUPLICATE_TARGET_CODE : "invalid_operations", detail);
+};
+const changedPaths = (operation) => {
+	const paths = changedFieldKeys(operation.fields);
+	for (const key of Object.keys(operation.acf ?? {}).toSorted()) paths.push(`acf.${key}`);
+	return paths;
+};
+const operationSentence = (operation) => {
+	return `Update ${joinPhrase(changedPaths(operation))} on ${operation.rest_base} ${operation.id}`;
+};
+// src/wp-apply.ts
+const MISSED_PATH_LIMIT = 5;
+const ACF_PREFIX = "acf.";
+const UNREADABLE_MODIFIED_GMT_CODE = "unreadable_modified_gmt";
+const UNREADABLE_MODIFIED_GMT_MESSAGE = "WordPress did not report when this post was last modified, so the change cannot be checked against the approval preview";
+const recordSchema = z.record(z.string(), z.json());
+const stringSchema = z.string();
+const editableFieldSchema = z.object({ raw: z.json() });
+const readPath = (record, path) => {
+	if (path.startsWith(ACF_PREFIX)) {
+		const acf = recordSchema.safeParse(record.acf);
+		return acf.success ? acf.data[path.slice(4)] : void 0;
+	}
+	const value = record[path];
+	const editable = editableFieldSchema.safeParse(value);
+	return editable.success ? editable.data.raw : value;
+};
+const requestedValue = (operation, path) => {
+	if (path.startsWith(ACF_PREFIX)) return operation.acf?.[path.slice(4)];
+	const { fields } = operation;
+	if (fields === void 0) return;
+	return Object.entries(fields).find(([key]) => key === path)?.[1];
+};
+const adminEditUrl = (apiUrl, id) => new URL(`/wp-admin/post.php?post=${id}&action=edit`, apiUrl).toString();
+const modifiedGmt = (record) => {
+	const value = stringSchema.safeParse(record.modified_gmt);
+	return value.success ? value.data : void 0;
+};
+const postSlug = (record) => {
+	const value = stringSchema.safeParse(record.slug);
+	return value.success ? value.data : "";
+};
+const resourcePath = (operation) => `/wp-json/wp/v2/${operation.rest_base}/${operation.id}`;
+const readRecord = async (client, operation, telemetry) => {
+	const result = await wpFetch(client, `${resourcePath(operation)}?context=edit`, telemetry);
+	const parsed = recordSchema.safeParse(result.json);
+	if (result.status < 200 || result.status >= 300 || !parsed.success) throw new ApplyConflictError(result.errorCode ?? "read_failed", wordPressErrorMessage(result.status, result.errorCode) ?? `Could not read ${operationTarget(operation)}`);
+	return parsed.data;
+};
+const toReceiptError = (error) => {
+	if (error instanceof ApplyConflictError) return {
+		code: error.code,
+		message: error.message
+	};
+	if (error instanceof UpstreamRequestError) return {
+		code: "wordpress_request_failed",
+		message: error.message
+	};
+	return {
+		code: "unexpected_error",
+		message: "The operation failed"
+	};
+};
+const preflightRemaining = async (client, operations, telemetry, index, collected) => {
+	const operation = operations.at(index);
+	if (operation === void 0) return collected;
+	const record = await readRecord(client, operation, telemetry);
+	const current = modifiedGmt(record);
+	if (current === void 0) throw new ApplyConflictError(UNREADABLE_MODIFIED_GMT_CODE, UNREADABLE_MODIFIED_GMT_MESSAGE);
+	if (operation.expected_modified_gmt !== void 0 && operation.expected_modified_gmt !== current) throw new ApplyConflictError("stale_expected_modified_gmt", `${operationTarget(operation)} was last modified at ${current}`);
+	const fields = changedPaths(operation).map((path) => {
+		const before = readPath(record, path);
+		const after = requestedValue(operation, path);
+		return {
+			after: previewValue(after),
+			before: previewValue(before),
+			changed: !deepEqual(before, after),
+			path
+		};
+	});
+	collected.push({
+		editUrl: adminEditUrl(client.apiUrl, operation.id),
+		fields,
+		modifiedGmt: current,
+		operationIndex: index,
+		sentence: operationSentence(operation),
+		slug: postSlug(record),
+		target: operationTarget(operation)
+	});
+	return preflightRemaining(client, operations, telemetry, index + 1, collected);
+};
+const preflightOperations = async (client, intent, operations, telemetry) => {
+	return {
+		intent,
+		operations: await preflightRemaining(client, operations, telemetry, 0, [])
+	};
+};
+const writeBody = (operation) => {
+	const body = {};
+	const { fields } = operation;
+	if (fields !== void 0) {
+		for (const [key, value] of Object.entries(fields)) if (value !== void 0) body[key] = value;
+	}
+	if (operation.acf !== void 0) body.acf = operation.acf;
+	return body;
+};
+const classifyReadback = (operation, before, after) => {
+	const changed = [];
+	const missed = [];
+	const normalized = [];
+	for (const path of changedPaths(operation)) {
+		const requested = requestedValue(operation, path);
+		const previous = readPath(before, path);
+		if (deepEqual(previous, requested)) continue;
+		const stored = readPath(after, path);
+		if (deepEqual(stored, requested)) changed.push(path);
+		else if (deepEqual(stored, previous)) missed.push(path);
+		else {
+			changed.push(path);
+			normalized.push(path);
+		}
+	}
+	return {
+		changed,
+		missed,
+		normalized
+	};
+};
+const missedPathsMessage = (missed) => {
+	const listed = missed.slice(0, MISSED_PATH_LIMIT);
+	const extra = missed.length - listed.length;
+	const suffix = extra > 0 ? ` and ${extra} more` : "";
+	return `WordPress did not store ${listed.join(", ")}${suffix}`;
+};
+const applyOne = async (client, operation, snapshot, telemetry) => {
+	const base = {
+		kind: "update_post",
+		operation_index: snapshot.operationIndex,
+		target: snapshot.target
+	};
+	if (snapshot.target !== operationTarget(operation)) return {
+		...base,
+		changed_paths: [],
+		error: {
+			code: "preflight_mismatch",
+			message: "The approval preview describes a different target"
+		},
+		normalized_paths: [],
+		status: "failed",
+		target: operationTarget(operation)
+	};
+	let before;
+	try {
+		before = await readRecord(client, operation, telemetry);
+	} catch (error) {
+		return {
+			...base,
+			changed_paths: [],
+			error: toReceiptError(error),
+			normalized_paths: [],
+			status: "failed"
+		};
+	}
+	const currentModifiedGmt = modifiedGmt(before);
+	if (currentModifiedGmt === void 0) return {
+		...base,
+		changed_paths: [],
+		error: {
+			code: UNREADABLE_MODIFIED_GMT_CODE,
+			message: UNREADABLE_MODIFIED_GMT_MESSAGE
+		},
+		normalized_paths: [],
+		status: "conflict"
+	};
+	if (currentModifiedGmt !== snapshot.modifiedGmt) return {
+		...base,
+		changed_paths: [],
+		error: {
+			code: "modified_since_preflight",
+			message: `${snapshot.target} changed after the approval preview`
+		},
+		normalized_paths: [],
+		status: "conflict"
+	};
+	let write;
+	try {
+		write = await wpFetch(client, resourcePath(operation), telemetry, {
+			body: JSON.stringify(writeBody(operation)),
+			headers: { "Content-Type": "application/json" },
+			method: "POST"
+		});
+	} catch (error) {
+		return {
+			...base,
+			changed_paths: [],
+			error: toReceiptError(error),
+			normalized_paths: [],
+			status: "failed"
+		};
+	}
+	if (write.status < 200 || write.status >= 300) return {
+		...base,
+		changed_paths: [],
+		error: {
+			code: write.errorCode ?? "write_failed",
+			message: wordPressErrorMessage(write.status, write.errorCode) ?? `WordPress rejected the write to ${snapshot.target}`
+		},
+		normalized_paths: [],
+		status: "failed"
+	};
+	let after;
+	try {
+		after = await readRecord(client, operation, telemetry);
+	} catch (error) {
+		return {
+			...base,
+			changed_paths: [],
+			error: toReceiptError(error),
+			normalized_paths: [],
+			status: "failed"
+		};
+	}
+	const readback = classifyReadback(operation, before, after);
+	if (readback.missed.length > 0) return {
+		...base,
+		changed_paths: readback.changed,
+		error: {
+			code: "readback_mismatch",
+			message: missedPathsMessage(readback.missed)
+		},
+		normalized_paths: readback.normalized,
+		status: "failed"
+	};
+	return {
+		...base,
+		changed_paths: readback.changed,
+		normalized_paths: readback.normalized,
+		status: readback.changed.length > 0 ? "changed" : "unchanged"
+	};
+};
+const applyRemaining = async (client, operations, preflight, telemetry, index, collected) => {
+	const operation = operations.at(index);
+	if (operation === void 0) return collected;
+	const snapshot = preflight.operations.at(index);
+	if (snapshot === void 0) collected.push({
+		changed_paths: [],
+		error: {
+			code: "missing_preflight",
+			message: "No approval preview exists for this operation"
+		},
+		kind: "update_post",
+		normalized_paths: [],
+		operation_index: index,
+		status: "failed",
+		target: operationTarget(operation)
+	});
+	else collected.push(await applyOne(client, operation, snapshot, telemetry));
+	return applyRemaining(client, operations, preflight, telemetry, index + 1, collected);
+};
+const applyOperations = async (options) => {
+	const receipts = await applyRemaining(options.client, options.operations, options.preflight, options.telemetry, 0, []);
+	return {
+		approverOpaque: options.approverOpaque,
+		executionId: options.executionId,
+		operations: receipts,
+		requesterOpaque: options.requesterOpaque,
+		status: batchStatus(receipts)
+	};
+};
+// src/wp-tools.ts
+const WP_CONNECTOR_INSTRUCTIONS = [
+	"WordPress site reached as the signed-in Cloudflare Access user.",
+	"Reads: wp.graphql({query, variables?}) runs WPGraphQL (introspection allowed);",
+	"wp.get({path, query?}) GETs any /wp-json/ path and throws on a non-2xx response.",
+	"Writes: wp.apply({intent, operations}) is the only write path and pauses for human approval.",
+	`Send 1-${MAX_OPERATIONS} update_post operations per call and set expected_modified_gmt when you read the post first.`
+].join(" ");
+const assertQueryOnly = (query) => {
+	let document;
+	try {
+		document = parse(query);
+	} catch {
+		throw new UpstreamRequestError("wp.graphql could not parse the query; send one valid GraphQL document");
+	}
+	if (document.definitions.some((definition) => definition.kind === Kind.OPERATION_DEFINITION && definition.operation !== OperationTypeNode.QUERY)) throw new UpstreamRequestError("wp.graphql runs queries only; make changes with wp.apply, which pauses for approval");
+};
+const METHOD_OVERRIDE_KEY = /method/iu;
+const graphqlArgsSchema = z.object({
+	query: z.string().trim().min(1),
+	variables: z.record(z.string(), z.json()).optional()
+});
+const restQuerySchema = z.record(z.string(), z.union([
+	z.boolean(),
+	z.number(),
+	z.string()
+]));
+const getArgsSchema = z.object({
+	path: z.string().min(1),
+	query: restQuerySchema.optional()
+});
+const callerClient = (env, caller) => createWordPressClient(env, {
+	ok: true,
+	subjectOpaque: caller.subjectOpaque,
+	token: caller.token
+});
+const queryString = (query) => {
+	if (query === void 0) return "";
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) params.set(key, String(value));
+	const encoded = params.toString();
+	return encoded ? `?${encoded}` : "";
+};
+const createWordPressTools = (deps) => ({
+	apply: {
+		description: `Apply 1-${MAX_OPERATIONS} update_post operations to WordPress. Give the work a concise, one-sentence intent for the human approval card. Pauses for human approval; returns one receipt per operation.`,
+		execute: async (args, ctx) => {
+			const input = parseApplyInput(args);
+			const caller = deps.scope.require();
+			const executionId = ctx?.executionId ?? caller.executionId;
+			if (executionId === void 0) throw new UpstreamRequestError("wp.apply requires an execution id from the codemode runtime");
+			const preflight = caller.preflight ?? await deps.store.readPreflight(executionId) ?? {
+				intent: input.intent,
+				operations: []
+			};
+			return await applyOperations({
+				approverOpaque: caller.subjectOpaque,
+				client: callerClient(deps.env, caller),
+				executionId,
+				operations: input.operations,
+				preflight,
+				requesterOpaque: await deps.store.readRequester(executionId) ?? "unknown",
+				telemetry: deps.telemetry()
+			});
+		},
+		inputSchema: {
+			properties: {
+				intent: { type: "string" },
+				operations: {
+					items: { type: "object" },
+					type: "array"
+				}
+			},
+			required: ["intent", "operations"],
+			type: "object"
+		},
+		requiresApproval: true
+	},
+	get: {
+		description: "GET a WordPress REST path. The path must start with /wp-json/. Returns parsed JSON, or throws if WordPress responds with a non-2xx status.",
+		execute: async (args) => {
+			const parsed = getArgsSchema.safeParse(args);
+			if (!parsed.success) throw new UpstreamRequestError("wp.get requires a string path and scalar query values");
+			if (parsed.data.path.includes("?")) throw new UpstreamRequestError("wp.get path must not contain a query string; pass parameters in the query argument");
+			if (Object.keys(parsed.data.query ?? {}).some((key) => METHOD_OVERRIDE_KEY.test(key))) throw new UpstreamRequestError("wp.get is a read and takes no method override; make changes with wp.apply");
+			const result = await wpFetch(callerClient(deps.env, deps.scope.require()), `${parsed.data.path}${queryString(parsed.data.query)}`, deps.telemetry());
+			if (result.status < 200 || result.status >= 300) throw new UpstreamRequestError(wordPressErrorMessage(result.status, result.errorCode) ?? `WordPress returned HTTP ${result.status}`);
+			return result.json;
+		},
+		inputSchema: {
+			properties: {
+				path: { type: "string" },
+				query: { type: "object" }
+			},
+			required: ["path"],
+			type: "object"
+		}
+	},
+	graphql: {
+		description: "Run a WPGraphQL query against the site. Introspection works. Returns the full {data, errors?} response.",
+		execute: async (args) => {
+			const parsed = graphqlArgsSchema.safeParse(args);
+			if (!parsed.success) throw new UpstreamRequestError("wp.graphql requires a string query");
+			assertQueryOnly(parsed.data.query);
+			return await wpGraphql(callerClient(deps.env, deps.scope.require()), parsed.data.query, parsed.data.variables, deps.telemetry());
+		},
+		inputSchema: {
+			properties: {
+				query: { type: "string" },
+				variables: { type: "object" }
+			},
+			required: ["query"],
+			type: "object"
+		}
+	}
+});
+const wordpressConnector = {
+	configured: (env) => Boolean(env.WORDPRESS_API_URL?.trim()),
+	describe: (env, caller, telemetry) => buildSiteDescription(createWordPressClient(env, {
+		ok: true,
+		...caller
+	}), telemetry),
+	executeDescription: [
+		"The wp global reaches WordPress.",
+		"Reads: await wp.graphql({ query, variables? }); or await wp.get({ path, query? }), where path starts /wp-json/, contains no ?, and query values are scalars.",
+		"Writes: await wp.apply({ intent, operations }), with 1-20 operations shaped { kind: \"update_post\", rest_base, id, expected_modified_gmt?, fields?, acf? }; fields may contain title, content, excerpt, slug, or status. Put all changes for one post in one operation. Read with context: \"edit\" first and copy modified_gmt to expected_modified_gmt.",
+		"Read example: async () => await wp.get({ path: \"/wp-json/wp/v2/posts/123\", query: { context: \"edit\" } }).",
+		"Write example: async () => { const post = await wp.get({ path: \"/wp-json/wp/v2/posts/123\", query: { context: \"edit\" } }); return await wp.apply({ intent: \"Fix the title.\", operations: [{ kind: \"update_post\", rest_base: \"posts\", id: post.id, expected_modified_gmt: post.modified_gmt, fields: { title: \"Correct title\" } }] }); }"
+	].join(" "),
+	instructions: WP_CONNECTOR_INSTRUCTIONS,
+	name: "wp",
+	parseApply: (args) => {
+		const input = parseApplyInput(args);
+		return {
+			intent: input.intent,
+			sentences: input.operations.map((operation) => operationSentence(operation))
+		};
+	},
+	preflight: (env, caller, args, telemetry) => {
+		const input = parseApplyInput(args);
+		return preflightOperations(createWordPressClient(env, {
+			ok: true,
+			...caller
+		}), input.intent, input.operations, telemetry);
+	},
+	tools: createWordPressTools
+};
+export { WP_CONNECTOR_INSTRUCTIONS, applyInputSchema, applyOperations, buildSiteDescription, createWordPressClient, createWordPressTools, inspectWordPressResponse, parseApplyInput, preflightOperations, wordpressConnector, wpFetch, wpGraphql };

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@patronage/mcp-wordpress",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "The WordPress connector for @patronage/mcp-core: WPGraphQL and REST reads, and post updates through the approval step.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/patronage/launch.git",
+    "directory": "packages/mcp-wordpress"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@patronage/mcp-core": "0.1.0",
+    "graphql": "17.0.2",
+    "zod": "4.6.7"
+  },
+  "devDependencies": {
+    "@cloudflare/workers-types": "5.20261031.1",
+    "@patronage/access": "0.1.0",
+    "@types/node": "24.19.2",
+    "evlog": "2.26.0",
+    "tsdown": "0.23.4",
+    "vitest": "5.0.5"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "scripts": {
+    "build": "pnpm --filter @patronage/mcp-core generate && tsdown",
+    "test": "pnpm --filter @patronage/mcp-core generate && vitest run",
+    "typecheck": "pnpm --filter @patronage/mcp-core generate && tsc --noEmit"
+  }
 }