Skip to content

PeterKnightDigital/PromptWire-MCP

BranchesTags

Repository files navigation

PromptWire

ProcessWire ↔ Cursor MCP Bridge for AI-assisted development.

Disclaimer: This is a development tool. It gives an AI agent direct access to create, edit, download, and delete pages, fields, templates, and files via the ProcessWire API. Always have backups in place. Do not use this on client-facing sites or any environment where you cannot accept the risk of data loss or corruption. This module is provided as-is, with no warranty. By using it you accept all associated risk.

Introduction

PromptWire connects your ProcessWire CMS to Cursor IDE via the Model Context Protocol, giving AI agents direct read/write access to your site's structure, content, and files. It ships with 47 specialised tools for site inspection, content sync, schema management, page creation, page slug renames, schema-aware fieldgroup edits, page-asset sync (catches MediaHub-managed files), database introspection, log analysis, site sync, backup, maintenance mode, and cross-environment deployment.

Just describe what you want in plain language:

"Build a blog section at /blog/ with an index page and three sample posts. Posts should have a title, body, summary, and publish date. Dry-run everything first."

"Pull our About page, rewrite the body to be more concise, and push the changes to both local and production."

"Compare our local schema against production and flag anything that could cause problems if we pushed."

"Sync everything to production with backup and maintenance mode. Dry-run first."

The agent reads your site's schema, selects the right tools, sequences the operations, and previews everything before applying. No tool names to memorise — see the Prompt recipes for more examples.

The module has two parts:

  • Cursor MCP integration — describe what you want and the AI agent builds it: creates templates, fields, pages, and content, pushes changes between environments, and compares schemas. All from Cursor chat.
  • Admin dashboard — a visual sync status UI inside the PW admin. See which pages are synced, view diffs, pull and push individual or bulk pages — all without leaving the browser.

Installation

1. Install the ProcessWire module

Clone or download this repo directly into your ProcessWire site/modules/ folder as PromptWire:

git clone https://github.com/PeterKnightDigital/PromptWire-MCP.git site/modules/PromptWire

Or download the zip, extract, and rename the folder to PromptWire inside site/modules/.

Then in ProcessWire admin: Modules → Refresh → Install PromptWire.

The admin dashboard (ProcessPromptWireAdmin) is installed automatically — you'll find it under Setup → PromptWire Admin.

Developing PromptWire itself? Symlink your local clone into site/modules/PromptWire so edits land in the git repo, not a vendored copy:

# From your ProcessWire site root — adjust the clone path to match your machine
ln -sfn /path/to/PromptWire-MCP site/modules/PromptWire

Point .cursor/mcp.json at site/modules/PromptWire/mcp-server/dist/index.js — symlinks resolve fine. Rebuild the MCP server after TypeScript changes (npm run build in mcp-server/).

2. Build the MCP server

cd site/modules/PromptWire/mcp-server
npm install
npm run build

3. Configure Cursor

Create or edit .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "PromptWire: My Site (Local)": {
      "command": "node",
      "args": ["/path/to/pw-site/site/modules/PromptWire/mcp-server/dist/index.js"],
      "env": {
        "PW_PATH": "/path/to/your/processwire/site",
        "PHP_PATH": "/path/to/php"
      }
    }
  }
}
Setting What it is
"PromptWire: My Site (Local)" A label of your choice — this name appears in Cursor's MCP panel
command The runtime that starts the MCP server. Always "node"
args Absolute path to the compiled MCP server entry point (mcp-server/dist/index.js) inside your PromptWire module directory
PW_PATH Absolute path to your ProcessWire install root (the directory containing site/ and wire/)
PHP_PATH Absolute path to your PHP binary. Optional if php is already on your system PATH

Finding your PHP path: Run which php in your terminal. Common locations:

  • MAMP: /Applications/MAMP/bin/php/php8.x.x/bin/php
  • Homebrew: /opt/homebrew/bin/php or /usr/local/bin/php
  • XAMPP: /Applications/XAMPP/bin/php
  • System (macOS): /usr/bin/php

If which php returns the correct version (8.0+), you can omit PHP_PATH entirely.

4. (Recommended) Cursor project rules

So every new AI chat knows to use PromptWire for CMS content (not direct DB access or guessing from templates), copy the rule into your ProcessWire project:

cp site/modules/PromptWire/install/cursor-rules/promptwire.mdc .cursor/rules/

The rule applies on every chat (alwaysApply: true). It separates CMS content (pull → edit site/assets/pw-mcp/ → push) from code (templates, modules, CSS).

For coverage across all ProcessWire projects without copying the file into each repo, install the personal skills from install/cursor-skills/ into ~/.cursor/skills/ (promptwire for the general workflow, promptwire-page-rename for slug changes).

5. (Optional) Remote site access

To push content to a production site, deploy the API endpoint file (api/promptwire-api.php) to your remote site root. Rename it to something non-obvious (e.g. pw-xyz8k3m.php) so the URL isn't guessable from the public documentation, then set PW_REMOTE_URL to match. The endpoint enforces HTTPS; requests over plain HTTP are rejected with a 403.

See the Remote setup guide for full instructions.

Keep the remote API in sync. The HTTP endpoint (api/promptwire-api.php) must match your installed module version. After upgrading PromptWire, redeploy the API file to your remote site root (rename it for security, then set PW_REMOTE_URL):

# From the PromptWire repo — pushes promptwire-api.php to production
PW_REMOTE_URL=https://www.example.com/your-endpoint.php \
PW_REMOTE_KEY=your-key \
node scripts/push-api-to-remote.mjs

Also push module PHP changes when upgrading:

PW_REMOTE_URL=... PW_REMOTE_KEY=... node scripts/push-self-to-remote.mjs

The MCP server (mcp-server/) runs locally only and does not need to be deployed to production.

Product release pages (ZIP downloads)

For pages with a release_file field (e.g. /downloads/mediahub/v1-17-0/):

  1. Place the ZIP in the local page files directory (site/assets/files/{localPageId}/)
  2. Set release_file in page.yaml with filename and description (e.g. MediaHub 1.17.0)
  3. pw_page_push — page content and file descriptions (local and/or remote)
  4. pw_file_sync — upload the ZIP binary to remote (deleteRemoteOrphans: true when replacing)
  5. Republish if needed (publish: true on push)

pw_page_push does not replace binaries. Use pw_file_sync for the ZIP itself.

Available tools

Site inspection

Tool Description
pw_health Check ProcessWire connection, version, and counts
pw_list_templates List all templates
pw_get_template Get template details (fields, settings)
pw_inspect_template Like pw_get_template but each field comes back as {name, type, label}, sized for fieldgroup-diff workflows across environments
pw_list_fields List all fields
pw_get_field Get field details (type, settings)
pw_get_page Get a page by ID or path with full field content
pw_query_pages Query pages with ProcessWire selectors
pw_search Search page content by keyword
pw_search_files Search PHP/template files in the site directory
pw_modules_list List installed modules with version, file path, and install state. Pass site: "both" to compare
pw_users_list List users with id, name, email, roles, and any member_* fields. Password hashes are excluded
pw_resolve Bulk-resolve names to ProcessWire ids on the chosen site (fields, templates, pages, roles, users)
pw_export_schema Export the full site schema (templates + fields) as JSON

Content sync

Content is synced to site/assets/pw-mcp/ — editable YAML files that you can open in any editor or hand to an AI agent.

Tool Description
pw_page_pull Pull a page into a local sync directory as editable YAML
pw_page_push Push local YAML changes back to ProcessWire (local, remote, or both)
pw_pages_pull Bulk pull pages by selector, parent, or template
pw_pages_push Bulk push all changes in a sync directory tree
pw_sync_status Check sync status of all pulled pages (clean, dirty, conflict)
pw_sync_reconcile Fix path drift, detect orphans, reconcile sync directories
pw_validate_refs Validate page references across synced content

Page management

Tool Description
pw_page_new Scaffold a new page locally (creates page.yaml + page.meta.json)
pw_page_init Initialise or repair page.meta.json for a sync directory
pw_page_publish Publish a scaffolded page to ProcessWire (local, remote, or both)
pw_pages_publish Bulk publish all new page scaffolds in a directory
pw_page_rename Rename a page slug (local, remote, or both); reconciles pw-mcp folder

Schema sync

Tool Description
pw_schema_pull Pull field and template schema from a PW site into local files
pw_schema_push Push local schema files to a PW site (creates/updates fields and templates)
pw_schema_diff Diff local schema files against the live site
pw_schema_compare Compare schemas between two sites (e.g. local vs production)
pw_template_fields_push Add, remove, or reorder fields on a template's fieldgroup, with per-field context overrides. Includes a three-tier conflict classifier (safe / warning / danger), module-ownership awareness, and a frontend-usage scan on remove ops.
pw_list_sites List configured remote sites from .pw-sync/sites/

File sync

Tool Description
pw_page_assets Preferred path. Syncs the on-disk asset directory for a page (site/assets/files/{pageId}/) by walking the directory directly, so module-managed files (notably MediaHub) are picked up alongside standard file/image field uploads. Supports both directions, dry-run by default.
pw_file_sync Field-aware file sync for standard file/image fields. Uploads changed binaries, syncs description from page.yaml, resolves the correct local page id after remote pulls (ids.local.id), and supports deleteRemoteOrphans when replacing release ZIPs. Use pw_page_assets when modules store files outside the normal field flow.

Repeater Matrix

Tool Description
pw_matrix_info Get matrix field structure (types, fields, labels)
pw_matrix_add Add a new item to a repeater matrix field

Database

Tool Description
pw_db_schema Inspect database tables — list all or describe a single table
pw_db_query Execute read-only SELECT queries (mutations are blocked)
pw_db_explain Run EXPLAIN on a SELECT query for performance analysis
pw_db_counts Row counts for core tables and the 20 largest field-data tables

Logs

Tool Description
pw_logs List log files, or read/filter entries from a specific log
pw_last_error Retrieve the most recent error from the error and exception logs

Cache

Tool Description
pw_clear_cache Clear ProcessWire caches (all, modules, templates, compiled, wire)

Site sync

Tool Description
pw_site_compare Compare local and remote sites across pages, schema, and template/module files
pw_site_sync Orchestrated deployment: compare, backup, maintenance, push, verify
pw_maintenance Toggle maintenance mode on local, remote, or both sites
pw_backup Create, list, restore, or delete site backups (database + files)

For detailed parameters and examples, see the Tools reference.

Admin dashboard

PromptWire includes a visual dashboard in the ProcessWire admin under Setup → PromptWire Admin. It installs automatically alongside the main module.

The dashboard shows your full page tree with sync status badges (Clean, File Newer, Wire Newer, Conflict, Untracked), per-row actions (Wire to File, File to Wire, View YAML), template and status filters, and bulk operations for multi-page sync.

For a full walkthrough, see the Admin dashboard guide.

Documentation

Requirements

  • ProcessWire 3.0+
  • PHP 8.0+
  • Node.js 18+
  • Cursor IDE with MCP support

Credits

Created and maintained by Peter Knight.

License

MIT — see CHANGELOG.md for version history.

About

Query ProcessWire sites from Cursor IDE via MCP

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 21

v1.12.2 — NEW* placeholder support for repeater matrix item creation Latest
May 25, 2026
+ 20 releases

Packages

 
 
 

Contributors

Languages