<p align="center">
  <img src="assets/icon.svg" width="128" height="128" alt="MainWP MCP Bridge icon">
</p>

# MainWP MCP Bridge

[![Quality and package](https://github.com/uniquekaiser/mainwp-mcp-bridge/actions/workflows/quality.yml/badge.svg)](https://github.com/uniquekaiser/mainwp-mcp-bridge/actions/workflows/quality.yml)
[![Latest release](https://img.shields.io/github/v/release/uniquekaiser/mainwp-mcp-bridge)](https://github.com/uniquekaiser/mainwp-mcp-bridge/releases/latest)
[![License: GPL v3+](https://img.shields.io/badge/License-GPL_v3%2B-blue.svg)](LICENSE.txt)

Give AI agents, coding assistants, and GitHub Actions policy-controlled access to your MainWP Dashboard—through the MCP connection you already use, a dedicated MainWP server, or both.

MainWP MCP Bridge is free and open source. It exposes the live WordPress Abilities registered by MainWP in two complementary ways:

- **Existing-server mode:** publishes MainWP abilities to the active Novamira or WordPress MCP Adapter server, so an AI client needs no second MCP configuration.
- **Dedicated-server mode:** registers `/wp-json/mcp/mainwp` with direct MainWP tool names, richer confirmation tokens, prompts, and resources.

[Download the latest release](https://github.com/uniquekaiser/mainwp-mcp-bridge/releases/latest)

> [!IMPORTANT]
> **Unofficial community project.** MainWP MCP Bridge is independently developed and maintained. It is not an official WordPress, Novamira, or MainWP product, and it is not maintained or supported by the WordPress, Novamira, or MainWP development teams. Please report feedback, bugs, and support requests through [GitHub Issues](https://github.com/uniquekaiser/mainwp-mcp-bridge/issues).

## Why use this plugin?

Novamira and WordPress MCP Adapter provide the MCP protocol, HTTP transport, authentication, and server framework. MainWP provides the site-management operations. This bridge connects those layers while letting each administrator choose the simplest useful exposure model.

Benefits include:

- **First-class MainWP tools when dedicated:** agents call `list_sites_v1`, `list_updates_v1`, and other MainWP operations directly instead of navigating a generic ability discovery/execution interface.
- **One connection when preferred:** publish MainWP abilities through the site's existing MCP server and keep the AI client configuration it already uses.
- **Always-current discovery:** tools come from the abilities registered by the installed MainWP Dashboard, so runtime behavior does not depend on a handwritten PHP inventory.
- **Safer automation:** destructive operations fail closed; dedicated mode can require a preview plus a user-bound, one-time confirmation token.
- **Optional isolation:** enable the dedicated `/wp-json/mcp/mainwp` endpoint alone or alongside existing-server ability access.
- **Agent guidance included:** eight workflow prompts cover troubleshooting, maintenance, updates, reporting, security, backups, and performance.
- **Automation-ready authentication:** remote clients use standard WordPress Application Passwords over HTTPS; the plugin stores no client credentials.
- **Controlled exposure:** administrators can configure namespaces, allowlists, blocklists, safe mode, schema verbosity, and per-user rate limits.
- **Dashboard updates:** future releases are discovered and installed through the normal WordPress Plugins screen using the exact packaged GitHub Release asset.
- **WordPress 7.1 ready:** dedicated tools use Core's client-safe JSON Schema preparation when available, while the bridge retains its WordPress 6.9 minimum.

## Architecture

The plugin is an integration layer, not a replacement for MainWP, Novamira, or WordPress MCP Adapter. It contains no MainWP site-management business logic and bundles no MCP Adapter source.

```mermaid
flowchart LR
    Agent["AI agent or GitHub Action"]
    Auth["HTTPS + WordPress Application Password"]
    Adapter["Novamira or WordPress MCP Adapter"]
    Mode{"Exposure mode"}
    Existing["Existing adapter server and generic ability tools"]
    Server["Dedicated mainwp MCP server"]
    Bridge["Discovery, schemas, naming, policy, confirmation"]
    Abilities["WordPress Abilities API"]
    MainWP["MainWP Dashboard"]

    Agent --> Auth --> Adapter --> Mode
    Mode --> Existing --> Abilities
    Mode --> Server --> Bridge --> Abilities --> MainWP
    Abilities --> MainWP
```

| Component | Responsibility |
| --- | --- |
| MainWP Dashboard | Registers and executes the real site-management abilities. |
| WordPress Abilities API | Supplies the live ability registry and delegates permission checks. |
| Novamira or WordPress MCP Adapter | Handles MCP JSON-RPC, HTTP transport, sessions, and WordPress authentication. |
| MainWP MCP Bridge | Publishes selected MainWP abilities to an existing server and/or builds the dedicated server with direct tools, prompts, resources, and confirmation tokens. |
| AI client | Connects with an authorized WordPress user and decides which exposed tools to call. |

For existing-server mode, the bridge uses WordPress's supported `wp_register_ability_args` filter to add `mcp.public` metadata only to policy-selected MainWP abilities. The adapter's own `discover-abilities`, `get-ability-info`, and `execute-ability` tools then expose them without another endpoint. For dedicated mode, the bridge detects the active provider and registers a separate server through that provider's compatible `McpAdapter::create_server()` API. Standalone and Novamira-scoped class namespaces and hook families are handled independently; the bridge does not alias or fork adapter code or replace existing Novamira routes.

## Requirements

- WordPress 6.9 or newer
- PHP 7.4 or newer
- MainWP Dashboard 6.0 or newer
- MCP Adapter 0.5 or newer supplied by either:
  - [WordPress MCP Adapter](https://github.com/WordPress/mcp-adapter), or
  - Novamira with its compatible scoped bundled MCP Adapter

WordPress cannot express an OR relationship in `Requires Plugins`. The plugin declares MainWP as a dependency and checks the adapter provider at runtime. If no compatible provider is active, MCP exposure remains inactive and administrators receive an actionable notice rather than a fatal error.

## Installation

1. Install and activate MainWP Dashboard.
2. Install WordPress MCP Adapter 0.5+ or activate a compatible Novamira installation.
3. Download the versioned `mainwp-mcp-bridge-X.Y.Z.zip` asset from the [latest GitHub release](https://github.com/uniquekaiser/mainwp-mcp-bridge/releases/latest).
4. In WordPress, open **Plugins > Add Plugin > Upload Plugin**, install the ZIP, and activate it.
5. Open **Settings > MainWP MCP Bridge** and confirm that every dependency is healthy.
6. Choose **Existing MCP server only**, **Dedicated MainWP server only**, or **Existing and dedicated servers**.
7. For existing-server mode, keep using the MCP client connection you already configured. For dedicated mode, create a WordPress Application Password and copy the generated client configuration.

Version `0.2.0` is the updater bootstrap release. Install it manually once if you are currently on `0.1.0`; releases after `0.2.0` will appear in the normal WordPress Dashboard update flow.

## WordPress Dashboard updates

The plugin checks this repository's public, non-prerelease GitHub Releases and integrates the result with WordPress's standard plugin update UI. No GitHub token or update credential is stored.

```mermaid
flowchart LR
    Release["Tagged GitHub Release"]
    Asset["mainwp-mcp-bridge-X.Y.Z.zip"]
    Checker["Bundled Dashboard updater"]
    WordPress["Plugins > Updates"]

    Release --> Asset --> Checker --> WordPress
```

The updater accepts only assets named `mainwp-mcp-bridge-X.Y.Z.zip`. If the expected asset is absent, it refuses to fall back to GitHub's automatically generated source archive, which does not have the distributable WordPress plugin layout.

WordPress normally checks for updates twice daily. Administrators can also use the **Check for updates** action on the Plugins screen. Release descriptions provide the details/changelog content, while the packaged icon supplies the update-row artwork.

## Existing MCP server mode

Choose **Existing MCP server only** when Novamira or the standalone WordPress MCP Adapter is already connected to the AI client. The bridge marks the selected MainWP abilities as MCP-public during their normal WordPress registration. They appear through the provider's generic ability discovery and execution tools; `/wp-json/mcp/mainwp` is not registered and no second client entry is needed.

Allow/block filters, safe mode, MainWP's native `confirm`/`dry_run` controls, underlying ability permissions, and the per-user rate limit remain enforced. The dedicated endpoint is still the better choice when an agent benefits from 62 direct tool definitions, one-time cross-request preview tokens, compact schemas, the eight workflow prompts, or the four bridge resources.

## Dedicated MCP client configuration

Keep credentials in a secret store or environment variables. Never commit an Application Password.

```json
{
  "mcpServers": {
    "mainwp": {
      "command": "npx",
      "args": ["-y", "@automattic/mcp-wordpress-remote@latest"],
      "env": {
        "WP_API_URL": "https://dashboard.example.com/wp-json/mcp/mainwp",
        "WP_API_USERNAME": "automation-user",
        "WP_API_PASSWORD": "APPLICATION_PASSWORD_FROM_A_SECRET_STORE"
      }
    }
  }
}
```

Application Passwords require HTTPS unless WordPress explicitly recognizes a local development environment.

## Live tool mapping

Every server build calls `wp_get_abilities()` and selects the configured namespaces. The default namespace is `mainwp`, with a compatibility baseline of 62 MainWP 6 tools.

Dashboard add-ons can append a live namespace through `mainwp_mcp_bridge_ability_namespaces`. Values still pass the bridge's namespace validation before discovery, so an add-on such as Novamira for MainWP can expose `novamira-mainwp/*` through both dedicated and shared-server modes without replacing the administrator's saved bridge settings.

- `mainwp/list-sites-v1` becomes `list_sites_v1`.
- A secondary namespace such as `vendor-extension/do-thing-v1` becomes `vendor_extension__do_thing_v1`.
- Blocked or non-allowlisted tools disappear from discovery, invocation, and generated help.
- Authorization remains delegated to each underlying MainWP ability after bridge-only control arguments are removed.

The generated contract records expected schemas and behavior for testing and drift detection. It never replaces live discovery. On WordPress 7.1+, the bridge passes live Ability schemas through `wp_prepare_json_schema_for_client()` before publishing dedicated MCP declarations, removing server-only schema details and normalizing required fields for AI clients. Older supported WordPress versions retain the established schema path.

## Safety model

Only an explicit `annotations.destructive === false` is treated as non-destructive. Missing or malformed annotations fail closed.

Policy order is fixed:

1. Apply the blocked-tools and allowlist policy.
2. Block destructive tools when safe mode is active.
3. Require the configured confirmation workflow.
4. Delegate execution to the live MainWP ability.

For destructive tools that declare confirmation support:

1. Call with `confirm:true` to request a preview.
2. Show the preview or exact operation to the user and obtain explicit approval.
3. Within five minutes, call again with `user_confirmed:true` and the returned `confirmation_token`.

Tokens persist across HTTP requests in WordPress transients. Each token is bound to the authenticated user, WordPress site, tool, and canonical non-control arguments. Tokens are single-use, expire after five minutes, reject replay and argument swapping, and are capped at 100 pending tokens per user.

Stable workflow result codes include `SAFE_MODE_BLOCKED`, `CONFIRMATION_REQUIRED`, `PREVIEW_REQUIRED`, `PREVIEW_EXPIRED`, `CONFIRMATION_UNSUPPORTED`, `DRY_RUN_NOT_SUPPORTED`, `CONFLICTING_PARAMETERS`, and `NO_CHANGE`.

## Prompts and resources

Eight guided prompts are included:

- `troubleshoot-site`
- `maintenance-check`
- `update-workflow`
- `site-report`
- `network-summary`
- `security-audit`
- `backup-status`
- `performance-check`

Four static resources help agents understand the live surface:

- `mainwp://abilities`
- `mainwp://categories`
- `mainwp://status`
- `mainwp://help`

MCP Adapter 0.5 does not expose resource-template registration. Use `get_site_v1` for an individual site and `mainwp://help` for per-tool guidance.

## Settings

Only administrators can modify the validated `mainwp_mcp_bridge_settings` option.

```php
array(
    'enabled'                => true,
    'exposure_mode'          => 'dedicated', // existing, dedicated, or both.
    'safe_mode'              => false,
    'require_confirmation'   => true,
    'schema_verbosity'       => 'standard',
    'ability_namespaces'     => array( 'mainwp' ),
    'allowed_tools'          => array(),
    'blocked_tools'          => array(),
    'rate_limit_per_minute'  => 60,
)
```

The settings screen discovers the currently registered tools and renders **Allowed tools** and **Blocked tools** as multi-select controls. Administrators no longer need to type or guess normalized tool names. Dashboard URL, credentials, SSL bypass, retry, request-timeout, response-size, and session-byte settings are intentionally absent because ability execution is local and in-process.

## Contract synchronization

The static synchronizer accepts a release ZIP, extracted directory, or GitHub tag and never executes the source package:

```powershell
node tools/sync-upstream.mjs C:\path\to\mainwp-mcp.zip --check
node tools/sync-upstream.mjs vNEXT --write
node tools/sync-upstream.mjs vNEXT --write --accept-critical # only after parity review and tests
```

Compatible data-only changes can regenerate the committed contract. Changes to policy, confirmation, naming, or schema behavior fail closed and produce a machine-readable report for human or AI-assisted review. After the required PHP parity work and tests, maintainers can explicitly accept the reviewed critical fingerprint; scheduled automation cannot do so. The repository checks releases every Monday and Friday. See [PORTING.md](PORTING.md).

## Development

```powershell
composer install
composer test
npm run build
python tools/inspect-dist.py dist/mainwp-mcp-bridge-0.4.2.zip
```

The release ZIP contains runtime PHP, the single production update dependency and its license, assets, the generated PHP contract, and end-user documentation. It excludes development dependencies, source archives, tests, CI configuration, and development tooling.

The project includes PHPUnit, PHPCS, PHPStan, contract drift checks, Plugin Check, package inspection, and disposable WordPress/MainWP integration workflows.

## Frequently asked questions

### Does this replace Novamira or WordPress MCP Adapter?

No. One of those providers is required. The adapter supplies MCP transport and authentication; this plugin publishes MainWP abilities into that provider, adds the optional dedicated MainWP server, and applies the selected safety contract.

### Do I need to configure a second MCP server in my AI client?

No. Select **Existing MCP server only** and continue using the site's current Novamira or WordPress MCP Adapter connection. Select **Dedicated** or **Both** only when you want the direct MainWP tools and the bridge's richer endpoint-specific features.

### Why would I still use the dedicated endpoint?

This bridge gives agents stable, directly discoverable MainWP tools plus purpose-built prompts, resources, policy controls, and confirmation behavior. That is easier to use and safer to automate than asking every client to rediscover and reconstruct the MainWP surface.

### Does it copy MainWP functionality?

No. The bridge delegates permission checks and execution to MainWP's live abilities.

### Does it store my MainWP or MCP credentials?

No. Remote clients authenticate through WordPress. Keep Application Passwords in the client's secret store.

### How do plugin updates work?

Version `0.2.0` and later query public GitHub Releases and use the versioned distributable ZIP attached to each release. Install `0.2.0` manually if upgrading from `0.1.0`; subsequent versions can be installed from the WordPress Plugins screen.

### Is it free?

Yes. MainWP MCP Bridge is licensed under GPL-3.0-or-later and can be used, audited, modified, and shared under that license.

## Contributing and security

This is an unofficial community project and is not maintained or supported by the WordPress, Novamira, or MainWP development teams. Please send all feedback, bug reports, and support requests to this repository's [GitHub Issues](https://github.com/uniquekaiser/mainwp-mcp-bridge/issues). Pull requests are welcome.

Please include reproducible steps and avoid posting Application Passwords, site URLs, or other secrets.

For security-sensitive reports, use GitHub's private vulnerability reporting for this repository rather than opening a public issue.

## License

GPL-3.0-or-later. See [LICENSE.txt](LICENSE.txt).