Clearon WordPress MCP

Local MCP server for controlled Clearon WordPress publishing through the WordPress REST API.

Safety model

• Read tools may run directly.

• Run upsert_post_from_payload in dry_run mode before every write.

• Dry runs surface pending source-integrity review items from payload.source_audit and warn when the live source-audit report is missing, mismatched, or still blocked; real writes require source_audit, re-hash the payload content, and re-check the live source-audit report before writing.

• Contradictory source-audit states are rejected. A payload or live report cannot be both ready_for_publish_or_update: true and still blocked by pending findings or publish_update_gate.blocked. Approved reports may still retain publish_update_review_required_findings as historical evidence.

• Only an exact slug, a valid wordpress_post_id, or an explicit_target_id can authorize an update, and stored or explicit IDs are rejected when exact-slug evidence points to a different post. Title and near-slug matches produce a conflict for human review.

• Publishing and scheduling require a featured image. Local media is uploaded and attached before the final public post update.

• New posts are created as drafts and promoted only after prerequisites succeed. Existing live posts are not modified until the final combined update.

• publish_now refuses already-published targets so it cannot silently reset publication dates on a live post.

• After the final write, the server re-fetches the post and verifies its slug, canonical link, status, featured image, share block, supplied publication date, and featured-image social metadata.

• On a later failure, newly created drafts are trashed, newly uploaded media is deleted, and a modified existing post is restored from its pre-write snapshot when verification proves the result is wrong.

• Payload and image paths must resolve inside the configured workspace root. Set CLEARON_WP_MCP_WORKSPACE when the process is not already started from that workspace; symlinks cannot escape the resolved root.

• Image uploads accept JPG, PNG, WebP, and GIF files up to 20 MB and verify the file signature.

• Writes are serialized within one MCP process by the payload slug plus any supplied post IDs so slug-based and ID-based writes against the same post do not race. This does not coordinate multiple independently running server processes.

• Duplicate cleanup verifies numeric WordPress slug suffixes. Permanent deletion requires confirm_permanent_delete: true.

Tools

Read-only:

• get_server_health

• get_auth_mode

• get_endpoint_config

• get_post

• find_posts

• audit_slug_state

Writes:

• upsert_post_from_payload

• upload_media

• publish_now

• resolve_duplicate_posts

publish_now is no longer a bare post-ID publish shortcut. It requires both post_id and payload_path, re-runs reviewed payload targeting, proves that the existing target already matches the reviewed payload content, re-checks the live source-audit gate, then publishes with the same verification and rollback path used by upsert_post_from_payload. When publish_at_local is omitted, the server stamps the current local time in WordPress YYYY-MM-DDTHH:mm:ss format.

The legacy direct mutation tools set_featured_image, upsert_share_block, and set_social_meta remain present only as disabled compatibility stubs. They return an error directing callers back to the reviewed payload workflow.

resolve_duplicate_posts supports:

• trash: move a duplicate to WordPress trash; recoverable

• draft: retain it as a draft

• private: retain it privately

• delete: permanently delete it; requires confirm_permanent_delete: true

Payload requirements

Payloads require non-empty title, slug, and content. Slugs must use lowercase letters, numbers, and hyphens. categories and tags, when supplied, must contain positive integer IDs.

Payload dry runs may proceed while source_audit.pending_publish_update_review_findings is non-empty, but non-dry-run writes require source_audit with a revision fingerprint that exactly matches the approved editorial revision when editorial_approval.sha256 is present, otherwise the current payload content fingerprint. They are blocked unless the latest live source-audit report for that slug also matches that same fingerprint, matches the payload title, is ready_for_human_approval, and is ready_for_publish_or_update.

Schedule mode requires a valid future date. Publish and schedule modes require one of:

• featured_media

• local_featured_image

• an existing featured image on the exact update target

Run and test

cd tools/clearon-wordpress-mcp
npm run syntax
npm test
node server.mjs

Safe live smoke test:

CLEARON_WP_MCP_WORKSPACE=/absolute/path/to/workspace \
npm run smoke -- /absolute/path/to/workspace/path/to/payload.json

The smoke test initializes the MCP, checks health, and performs only a payload dry run.

Recommended workflow

1. Call get_server_health and confirm auth_mode is not missing.

2. Call upsert_post_from_payload with mode: "dry_run". If the payload is still marked draft but you want dry-run checks for an eventual publish or schedule operation, pass intended_mode.

3. Resolve every conflict or warning, including any listed pending source-integrity approvals. Use explicit_target_id only after checking the candidate manually.

4. Publish as a draft first for editorial review when practical.

5. Use publish, draft, or schedule only when the dry run identifies the intended target and image and the live source-audit gate is clear.

6. Use publish_now only for an already prepared exact target post and pass the same reviewed payload path used for the dry run.

7. Review the returned verification result, then call audit_slug_state as an independent live-state check.

Authentication

The server checks:

1. WP_AUTH

2. WP_USER plus WP_APP_PASSWORD

3. clearonWordPress.wpAuth in OPENCLAW_LOCAL_SECRETS or ~/.openclaw/secrets/local.json

Credentials are sent only in the WordPress REST authorization header and are not returned by MCP tools or written to logs.

Failure and recovery

• A failed local image validation performs no WordPress write.

• A failed upload performs no post write.

• Cleanup after a failed later step is best-effort: newly uploaded media is deleted, new drafts are trashed, and verified mismatches on existing posts trigger rollback plus a rollback verification read.

• If WordPress accepts the final write but all three verification reads fail, the server does not guess or roll back an unknown state. It reports that a manual audit_slug_state is required before retrying.

• If the final write response is lost or times out, the server treats WordPress state as unknown, skips cleanup assumptions, and requires audit_slug_state before retrying.

• JSON logs go to stderr. Set CLEARON_WP_MCP_LOG_LEVEL=info or debug for troubleshooting.

The server does not modify payload JSON files. WordPress state remains the source of truth and should be verified through audit_slug_state or your own live-state audit path.