KnowDevPro

KnowDevPro is a WordPress-to-WordPress sync and AI connector plugin for teams that maintain local, staging, and production environments.

It is designed for this operating model:

1. Build and edit on local/dev.
2. Push to staging.
3. Let an AI connector inspect staging.
4. Ask the user before production changes.
5. Push from staging to production only after explicit approval.
6. Pull production changes back into staging/dev when needed.

Current sync support includes:

• Posts.
• Pages.
• Enabled custom post types.
• Post meta, with filtered exclusions.
• Public or UI-visible taxonomies.
• Push from a site the target cannot reach (a local dev site): media is uploaded as files, never fetched from the sender.
• Media identified by content hash: each file is uploaded once and reused on every later push or pull, including files the target already had.
• Previews a person can check: every push or compare item says in words what it would change on the target (unpublishing a live page, title renames, URL moves, which components are replaced), and which menus or pages still link to a page being unpublished or moved.
• kdp_sync_diff: field-by-field differences of one page between two sites (text, block settings, custom fields, terms).
• Undo: every push snapshots the target first; kdp_sync_revert_job puts it back. kdp_sync_verify re-checks what a push sent.
• Classic menu sync (kdp_sync_push_menus), with items whose page is missing or unpublished on the target left out instead of becoming 404s.
• Production pushes requested by an AI connector wait for an administrator's approval in wp-admin.
• Attachment IDs translated on the receiving site: image, cover, gallery, media-text, file, video and audio blocks, Kadence image, gallery, row, column, info box and video popup blocks, wp-image-N classes, data-id, [gallery ids], and image-ID meta such as Rank Math social images. Every size URL is mapped to the receiver's matching size.
• References to synced patterns, navigation menus, and Kadence headers and forms translated to the receiver's copies, matched by sync UUID then by path.
• Posts matched on the receiver by sync UUID, then by post type and full path, then by unique slug.
• A KnowDevPro box in the post editor sidebar (classic and block editor) to preview or push the current post, and "Push to " bulk actions in post lists.
• Multi-site connection records with one-click connection tests.
• Site manifests and content hashes.
• Compare, pull, prepare-push, and execute-push jobs.
• Manual compare/pull/push from the WP Admin Sync tab.
• Local-to-remote object ID mapping records.
• Production approval phrase for guarded pushes.
• Audit logging with configurable retention.
• Daily cleanup of expired OTP challenges, tokens, and old jobs.

• Namespaced OAuth authorization endpoint.
• Dynamic Client Registration for compatible MCP clients.
• Static OAuth clients for Custom GPT Actions.
• Email allowlist.
• Guest OTP verification.
• Logged-in admin approval without OTP.
• Logged-in allowlisted user approval without OTP.
• 1-hour access tokens.
• 14-day refresh-token connection window by default.
• Namespaced MCP JSON-RPC endpoint.
• Custom GPT OpenAPI schema endpoint.
• Dynamic Custom GPT name, description, instructions, conversation starters, and action setup fields.
• OpenAPI schema in JSON and YAML.
• Admin-settable MCP connection name, used by every generated config, the bundle manifest and filename, and the server name reported to clients.
• Downloadable `.mcpb` desktop bundle carrying a Node stdio relay for MCP clients that install local servers.
• Labelled, revocable, default-scoped bundle access tokens with configurable lifetime.
• Ready-to-paste client config for remote HTTP MCP clients and for a local stdio fallback.

Install KnowDevPro on every WordPress site that participates in sync.

Recommended production-safe topology:

` Dev -> Staging -> Production Production -> Staging -> Dev `

Recommended AI connector topology:

` Claude / Custom GPT -> Staging KnowDevPro MCP/GPT endpoint Staging KnowDevPro -> Production WordPress site `

Do not expose a local-only WordPress URL directly to hosted AI clients. Hosted clients need a reachable HTTPS URL. Use staging as the AI-facing control point.

Example staging-to-production setup:

1. Install KnowDevPro on production.
2. In production, set environment to `production`.
3. In production, rotate a Site API Key and copy it.
4. Install KnowDevPro on staging.
5. In staging, set environment to `staging`.
6. In staging, add production as a connected site.
7. Paste the production URL and production Site API Key.

Open `KnowDevPro -> AI Connectors`.

First enter the GPT name, for example:

` Halim GPT `

KnowDevPro then generates copy-ready GPT Builder fields using that name:

• Name
• Description
• Instructions
• Conversation starters
• OAuth authorization URL
• OAuth token URL
• OAuth scope string
• Token exchange method
• OpenAPI JSON URL
• OpenAPI YAML URL
• Privacy policy URL
• OAuth Client ID guidance
• OAuth Client Secret / Key guidance

KnowDevPro does not require an allowed AI user to have a WordPress account.

Configure users in `KnowDevPro -> Access Control`.

Allowed list format (only the email is required):

` email | scopes | push environments | expires | notes `

Examples:

` james@example.com sara@example.com | kdp_sync:read kdp_sync:compare kdp_sync:pull lee@example.com | kdp_sync:read kdp_sync:push_staging | staging | 2026-12-31 | contractor `

Push environments restrict which environments the identity may push to (dev, staging, production; comma-separated; empty means all). Expires is a YYYY-MM-DD date after which the identity can no longer authorize or use connectors.

OAuth behavior:

• If the visitor is not logged in, KnowDevPro asks for email.
• If the email is not on the allowlist, authorization is rejected.
• If the email is allowed, KnowDevPro sends a one-time password.
• The visitor enters the OTP.
• KnowDevPro shows an Allow / No consent screen.
• If approved, OAuth completes.
• Access tokens last 1 hour by default.
• Refresh tokens keep the connection alive for 14 days by default.

• Logged-in admins may skip OTP if admin bypass is enabled.
• Logged-in users whose account email is allowlisted may skip OTP.
• Logged-in users whose email is not allowlisted are rejected unless they are admins and admin bypass is enabled.

Find these in `KnowDevPro -> AI Connectors`.

Claude / MCP Server URL:

` https://staging.example.com/wp-json/knowdevpro/v1/mcp `

Custom GPT OpenAPI Schema URL:

` https://staging.example.com/wp-json/knowdevpro/v1/gpt/openapi.json `

Custom GPT OpenAPI YAML Schema URL:

` https://staging.example.com/wp-json/knowdevpro/v1/gpt/openapi.yaml `

OAuth Authorization URL:

` https://staging.example.com/knowdevpro/oauth/authorize `

OAuth Token URL:

` https://staging.example.com/wp-json/knowdevpro/v1/oauth/token `

Dynamic Client Registration URL:

` https://staging.example.com/wp-json/knowdevpro/v1/oauth/register `

1. Use a publicly reachable HTTPS staging site.
2. Open Claude connector settings.
3. Add a custom connector.
4. Paste the KnowDevPro MCP Server URL from staging.
5. Complete OAuth.
6. Enable only the tools needed for the current workflow.

Some MCP clients install a local server instead of connecting to a remote one. For those, `KnowDevPro -> AI Connectors` builds a `.mcpb` bundle on demand.

The bundle contains a manifest and a small dependency-free Node relay. The relay forwards MCP calls from the client's stdio transport to this site's MCP endpoint over HTTPS. Node 18 or newer must be installed on the machine that installs the bundle.

If your client supports remote MCP servers, use the MCP Server URL and OAuth instead. The bundle exists for clients that cannot.

Downloading the bundle:

1. Open `KnowDevPro -> AI Connectors`.
2. Set the MCP Connection Name if the default is not what you want this connection called.
3. Optionally tick `Include the production push scope`. It is off by default.
4. Click `Download .mcpb` and install the file in your desktop client.

Bundle tokens are listed under `Active Bundle Tokens` with a masked hint and can be revoked there. They carry the default scopes minus `kdp_sync:push_production` unless you asked for it, and expire after the lifetime set in `Settings` (90 days by default).

The name this connection is given belongs to you, not to the plugin: several MCP servers commonly sit side by side in one client config, and two KnowDevPro sites must not collide there.

Set it in `KnowDevPro -> AI Connectors`. One value drives all of:

• the `mcpServers` key in both generated client config snippets,
• the `name` and `display_name` in the `.mcpb` manifest,
• the `.mcpb` filename,
• the server name reported to MCP clients on `initialize`,
• `resource_name` in the OAuth protected-resource metadata.

The name is copied into configs and bundles, not read live. After changing it, re-copy the snippets and re-download the bundle; anything already pasted or installed keeps the old name.

The GPT Builder only shows its OAuth callback URL after you save a Client ID and Secret, so create the KnowDevPro client first and add the callback URL afterwards:

1. In `KnowDevPro -> AI Connectors`, create a static OAuth client. Only the client name is required; leave the redirect URIs empty for now.
2. Copy the Client ID and Client Secret shown once after creation.
3. Create or edit a Custom GPT with Actions.
4. In the GPT Builder, paste the generated Name, Description, Instructions, and Conversation Starters from `KnowDevPro -> AI Connectors`.
5. Create a new Action.
6. Import the OpenAPI JSON URL or OpenAPI YAML URL shown in KnowDevPro.
7. Select OAuth authentication and paste the Client ID and Client Secret.
8. Use the Authorization URL and Token URL shown in KnowDevPro.
9. Paste the Scope string shown in KnowDevPro.
10. Use the default POST token exchange method.
11. Save the GPT action, then copy the callback URL the GPT editor now displays.
12. Back in KnowDevPro, paste that callback URL into the client's Redirect URIs field in the OAuth Clients table and click Update URIs.
13. Keep production-push tools approval-gated.

Recommended Custom GPT instruction:

` You are connected only to the staging KnowDevPro site. Always compare staging and production before suggesting a production push. Never execute a production push until the user explicitly says it is ready and approves the exact prepared job. `

KnowDevPro exposes namespaced MCP tools:

• `kdp_sync_list_sites`, `kdp_sync_connector_config` (includes sync_scope: what is and is not synced)
• `kdp_sync_compare`, `kdp_sync_diff`
• `kdp_sync_prepare_push`, `kdp_sync_execute_push`, `kdp_push_posts`, `kdp_list_posts`
• `kdp_sync_verify`, `kdp_sync_revert_job`, `kdp_sync_list_jobs`, `kdp_sync_get_job`
• `kdp_sync_pull`
• `kdp_sync_push_menus`
• `kdp_get_page_settings`, `kdp_site_design_settings`, `kdp_compare_design_settings`
• `kdp_media_duplicates`

1. `kdp_sync_prepare_push` (or `kdp_push_posts` with dry_run) returns each item's changes in words, risky_items, the media plan, and what is held back.
2. `kdp_sync_execute_push` (or `kdp_push_posts`). A push that unpublishes or moves a live page needs `confirm_risky: true` from an AI connector, sent after the user agreed.
3. `kdp_sync_verify`; if needed, `kdp_sync_revert_job`.

MCP tool results leave out hash fields unless `args.compact` is false.

Push scopes are enforced per target environment:

• Pushes to dev or staging targets require `kdp_sync:push_staging`.
• Preparing a production push requires `kdp_sync:push_production_pending_approval`.
• Executing a production push requires `kdp_sync:push_production`.

All plugin endpoints are namespaced under `knowdevpro/v1`.

Site-to-site API:

• `GET /wp-json/knowdevpro/v1/site/ping`
• `GET /wp-json/knowdevpro/v1/site/manifest`
• `POST /wp-json/knowdevpro/v1/site/content/export`
• `POST /wp-json/knowdevpro/v1/site/content/apply`
• `POST /wp-json/knowdevpro/v1/site/content/trash` (undo of a push that created posts)
• `POST /wp-json/knowdevpro/v1/site/references` (menus, navigation and content linking to posts)
• `GET /wp-json/knowdevpro/v1/site/menus`, `POST /wp-json/knowdevpro/v1/site/menus/apply`

• `GET /wp-json/knowdevpro/v1/gpt/openapi.json`
• `GET /wp-json/knowdevpro/v1/gpt/openapi.yaml`
• `GET /wp-json/knowdevpro/v1/gpt/sites`
• `POST /wp-json/knowdevpro/v1/gpt/compare`
• `POST /wp-json/knowdevpro/v1/gpt/push/prepare`
• `POST /wp-json/knowdevpro/v1/gpt/push/execute`
• `POST /wp-json/knowdevpro/v1/gpt/pull`
• `GET /wp-json/knowdevpro/v1/gpt/jobs`

• `GET /knowdevpro/oauth/authorize`
• `POST /wp-json/knowdevpro/v1/oauth/token`
• `POST /wp-json/knowdevpro/v1/oauth/register`
• `POST /wp-json/knowdevpro/v1/oauth/revoke`
• `GET /wp-json/knowdevpro/v1/oauth/authorization-server`
• `GET /wp-json/knowdevpro/v1/oauth/protected-resource`

Always active (KnowDevPro-specific, cannot collide with other plugins):

• `/.well-known/oauth-authorization-server/knowdevpro/oauth`
• `/.well-known/openid-configuration/knowdevpro/oauth`
• `/knowdevpro/oauth/.well-known/oauth-authorization-server`
• `/knowdevpro/oauth/.well-known/openid-configuration`
• `/.well-known/oauth-protected-resource/wp-json/knowdevpro/v1/mcp`

• `/.well-known/oauth-authorization-server`
• `/.well-known/openid-configuration`
• `/.well-known/oauth-protected-resource`

` add_filter('knowdevpro_register_well_known_oauth_routes', '__return_false'); `

KnowDevPro is designed for addons.

Content and sync filters:

` apply_filters('knowdevpro_sync_supported_post_types', $post_types); apply_filters('knowdevpro_sync_excluded_meta_keys', $meta_keys, $post_id); apply_filters('knowdevpro_sync_preserve_meta_keys', $preserved_keys, $post_id); apply_filters('knowdevpro_sync_query_args', $query_args, $args); apply_filters('knowdevpro_sync_prepare_payload', $payload, $post, $target_site); apply_filters('knowdevpro_sync_apply_remote_payload', $result, $payload, $source_site); apply_filters('knowdevpro_sync_environment_policy_allowed', $allowed, $local_environment, $target_environment, $direction, $connection); `

Content and sync actions:

` do_action('knowdevpro_sync_before_apply_item', $item, $source_site); do_action('knowdevpro_sync_after_apply_item', $result, $item, $source_site); `

Well-known OAuth route filter:

` apply_filters('knowdevpro_register_well_known_oauth_routes', true); `

Suggested future addon hook names:

` do_action('knowdevpro_sync_before_push', $job, $source, $target); do_action('knowdevpro_sync_after_push', $result, $job); do_action('knowdevpro_sync_before_pull', $job, $source, $target); do_action('knowdevpro_sync_after_pull', $result, $job); apply_filters('knowdevpro_sync_payload_for_acf', $payload, $post_id); apply_filters('knowdevpro_sync_payload_for_woocommerce', $payload, $object_id); `

KnowDevPro is powerful. Treat it like deployment infrastructure.

Recommended:

• Expose AI connectors from staging, not production.
• Use HTTPS.
• Keep Site API Keys private.
• Rotate keys when a developer leaves.
• Keep OAuth scopes narrow.
• Keep production approval enabled.
• Keep direct dev-to-production disabled.
• Review audit logs after each production sync.
• Back up production before major pushes.

Theme and builder page settings — Kadence's Page Settings panel (transparent header, page title, page layout, content style, vertical spacing), the page template dropdown, and their equivalents in other themes — are stored as post meta, so content sync has always carried them. What was missing was any way to read or verify them.

`KnowDevPro -> Design` now reports:

• the active theme, its version, stylesheet, template, and parent,
• every page template the theme offers,
• colour palettes found in theme mods and design options, with swatches,
• theme mods and design options as stored,
• a per-page inspector showing the page's template and each page setting with a human label.

Site-level design settings (palettes, theme mods, global builder options) are reported and compared, not pushed. They are site-wide and overwriting them from a sync would change every page at once.

If a page arrives carrying a template the receiving theme does not offer, the template name is stored anyway and the apply result reports it under `unavailable_templates` — the page renders with the default template until the theme provides that file.

Discovery is prefix-based, so themes other than the ones named above are covered as far as their naming allows. Four filters extend it: `knowdevpro_page_setting_keys`, `knowdevpro_design_option_prefixes`, `knowdevpro_design_theme_mods`, and `knowdevpro_site_design_settings`.

Pages are matched between sites by sync UUID first, then by their full hierarchical path (`parent-slug/child-slug`), then by a slug that is unique for the post type. Bare-slug matching is not used, because a slug alone cannot identify a child page.

`post_parent` is synced. A new child page is created under its parent, a page moved between parents follows, and a page that became top-level on the source is moved back to top level on the target.

Parents are applied before their children within a payload. If a page's parent does not exist on the receiving site at all, the page is still applied, its existing position is left untouched, and the apply result reports it under `unresolved_parents`. Push the parent page and the child settles on the next sync.

Both sites must run the same plugin version. A push is applied by the RECEIVING site, so the target of a push needs the update as much as the source does.

This first version focuses on safe content-object sync. It is not a full database migration tool.

Not included by default:

• Full database cloning.
• Theme/plugin file deployment.
• WooCommerce order synchronization.
• User account synchronization.
• Form entry synchronization.
• Bidirectional automatic conflict merging.
• Widgets, Customizer settings, theme mods, palettes and Kadence global settings (compared by kdp_compare_design_settings, never pushed).
• Deletions: deleting a post on one site never deletes it on the other.

Media notes:

• Pushes upload every file a post uses to the target, so a local site the target cannot reach can push. Pulls download files from the site being pulled.
• If an image download fails, the content is still synced and the image keeps its original source URL as a fallback — so it still displays, but is loaded from the source site. This is reported: `media_failed` on the item, `failed_media` in the apply summary, and a warning panel on the Sync tab.
• An image is only copied when this site does not already have it. A copy is reused when the source URL was synced before, or when a local file at the same uploads-relative path has identical contents — which is the usual case for staging and production sites cloned from each other. A file with the same name but different contents is treated as a different image and copied.
• Attachment IDs in core and Kadence blocks, wp-image-N classes, gallery shortcodes and known attachment-ID meta keys are translated to the receiver's own IDs.
• Since 0.7, an image URL counts by the file's content, not its name, so a reused photo.jpg and the sender's photo-1.jpg compare as identical. Sites on 0.6 still compare correctly against 0.7 (legacy hashes are kept for them), but update every site to get menu sync, references, diff and undo on the receiving side.
• Menu sync replaces each sent menu on the target and carries every item's own meta (Kadence mega-menu/icon settings, theme or plugin options) generically. Meta that stores another post's ID is only meaningful per site: declare such keys with the `knowdevpro_menu_item_meta_post_keys` filter and they travel as that post's sync UUID. Exclude keys with `knowdevpro_menu_item_meta_excluded`.

Does an allowed connector user need a WordPress account?

Can admins skip OTP?

Why is the access token only 1 hour if I asked for 14 days?

Can Claude connect by URL?

Can a Custom GPT connect?

My client cannot add a remote MCP server. What now?

Can I choose what this connection is called in my AI client?

Can I add ACF support later?