# WordPress MCP Custom Server

WordPress MCP server with:
- capability-based versioned tools (`*.v1`)
- backward-compatible aliases (old tool names still work)
- unified error contract
- request-level observability (`requestId`, duration, status)
- retry/timeout HTTP client for WP + W3C requests
- text playbooks/checklists for repeatable execution
- A/B benchmark report generator (`benchmark-summary.md`)
- write-safety policy for generic REST writes (allowlist + approval + dry-run)

## Installation

```bash
cd /Users/yanka/dev/wp-mcp-custom
npm install
```

## Required env

- `WP_URL`
- `WP_USER`
- `WP_APP_PASS`

Optional:
- `WP_PROJECT_ROOT` for file tools
- `PROJECT_PROFILE_PATH` for custom profile location

## Project profile

Create `project.profile.json` in server working directory (or use `PROJECT_PROFILE_PATH`):

```json
{
  "projectType": "wordpress",
  "capabilities": ["seo", "content", "site", "validation", "files"],
  "limits": {
    "listFilesDefault": 200,
    "listFilesMax": 2000,
    "autofixDefaultMaxFiles": 500,
    "autofixMaxFiles": 5000
  },
  "autofix": {
    "defaultPaths": [
      "wp-content/themes",
      "wp-content/mu-plugins"
    ]
  },
  "http": {
    "timeoutMs": 15000,
    "retries": 2,
    "retryDelayMs": 250,
    "maxRetryDelayMs": 2000
  },
  "safety": {
    "enabled": true,
    "writeMethods": ["POST", "PUT", "DELETE"],
    "allowedWritePathPrefixes": [
      "/wp/v2/posts",
      "/wp/v2/pages",
      "/custom/v1/update-option",
      "/custom/v1/update-yoast"
    ],
    "requireApprovalPathPrefixes": [
      "/wp/v2/settings",
      "/wp/v2/users",
      "/wp/v2/themes",
      "/wp/v2/plugins"
    ]
  }
}
```

## Tool naming

Canonical versioned tools:
- `content.list.v1`
- `content.publish.v1`
- `content.update_fields.v1`
- `site.request.v1`
- `site.update_option.v1`
- `seo.set_meta.v1`
- `project.files.list.v1`
- `project.files.read.v1`
- `project.files.write.v1`
- `validation.w3c.validate_urls_raw.v1`
- `validation.w3c.validate_pages.v1`
- `validation.w3c.validate_and_recheck.v1`
- `validation.w3c.autofix_safe.v1`
- `playbook.list.v1`
- `playbook.read.v1`
- `checklist.seo_landing_audit.v1`
- `checklist.w3c_validate_and_fix_plan.v1`
- `checklist.multilang_publish.v1`
- `benchmark.compare_ab.v1`

Backward-compatible aliases still supported:
- `list_posts`, `create_post_multilang`, `update_acf_fields`
- `wp_request`, `update_option`, `update_yoast`
- `list_project_files`, `read_project_file`, `write_project_file`
- `w3c_validate_live_urls_raw`, `w3c_validate_pages`, `w3c_validate_and_recheck`, `w3c_autofix_safe`

## Playbooks

Stored in `/Users/yanka/dev/wp-mcp-custom/playbooks`:
- `seo-landing-checklist-v1.md`
- `w3c-fix-checklist-v1.md`
- `multilang-publish-v1.md`

Use:
- `playbook.list.v1`
- `playbook.read.v1`

## Safety behavior for `site.request.v1`

- `GET` requests are allowed.
- Write methods are checked against `safety.allowedWritePathPrefixes`.
- Paths in `safety.requireApprovalPathPrefixes` require `require_approval=true`.
- `dry_run=true` returns preview without sending request.

## Benchmark demo report

Use `benchmark.compare_ab.v1` with:
- `runs_prompt_only`
- `runs_mcp`
- optional `output_path`

Output:
- aggregate metrics
- per-case comparisons
- generated markdown report (`mcp-benchmarks/benchmark-summary.md` by default)

## Unified error contract

Every tool error returns:

```json
{
  "code": "INVALID_ARGUMENT",
  "message": "...",
  "details": {},
  "retryable": false,
  "requestId": "..."
}
```

## Tests

```bash
npm test
```

## Notes

- Logs go to stderr as JSON (`tool.start`, `tool.success`, `tool.error`, `server.started`).
- Tool schemas use stricter JSON Schema (`additionalProperties: false`) for stable contracts.