# ACF MCP Server

Production-ready Model Context Protocol server for safely reading and changing WordPress + ACF Pro structure through ACF Local JSON and explicit WP-CLI synchronization.

The server is built for AI agents that need to inspect or propose changes to ACF field groups, custom post types, taxonomies, and options pages without direct database access.

ACF 6.8 also exposes ACF schema and content through the WordPress Abilities API when paired with the MCP Adapter plugin or another MCP server implementation. This project complements that runtime path with a repo-first workflow: Local JSON remains the source of truth, changes are reviewable in git, and WordPress synchronization is explicit.

## Features

- TypeScript, Node.js, Zod, Vitest, and `@modelcontextprotocol/sdk`.
- JSON-first ACF Local JSON repository.
- No direct SQL, no arbitrary PHP, no shell interpolation.
- Automatic backups before mutations.
- `dryRun` support for write workflows.
- Explicit WP-CLI sync/import/export tools.
- ACF 6.8 runtime-readiness audits for AI access, REST visibility, and location references.
- Simplified creation tools using ACF Abilities-style inputs.
- Read-only Schema.org mapping audits for ACF field metadata.
- `stdio` transport by default, optional Streamable HTTP for development.
- DDEV WordPress fixture configuration.

## Install

```bash
npm install
npm run build
```

For local development:

```bash
export ACF_MCP_ACF_JSON_DIR="/absolute/path/to/wp-content/themes/my-theme/acf-json"
export ACF_MCP_WP_ROOT="/absolute/path/to/wordpress"
npm run dev
```

## MCP Client Configuration

Example stdio configuration:

```json
{
  "mcpServers": {
    "acf": {
      "command": "node",
      "args": ["/absolute/path/to/acf_mcp/dist/server/stdio.js"],
      "env": {
        "ACF_MCP_ACF_JSON_DIR": "/absolute/path/to/wp-content/themes/my-theme/acf-json",
        "ACF_MCP_WP_ROOT": "/absolute/path/to/wordpress"
      }
    }
  }
}
```

During development, use `tsx`:

```json
{
  "command": "npx",
  "args": ["tsx", "/absolute/path/to/acf_mcp/src/server/stdio.ts"]
}
```

## Safety Model

Local JSON is the primary source of truth. Tools that create, update, delete, or apply content models write JSON files only. They do not sync the WordPress database automatically.

Recommended workflow:

1. Call a write tool with `dryRun: true`.
2. Review the planned `changes`.
3. Call the same tool with `dryRun: false`.
4. Review git diff for `acf-json`.
5. Call `acf_sync_json` with `dryRun: true`.
6. Call `acf_sync_json` with `dryRun: false` only when ready.

## Tools

- `acf_ping`
- `acf_list_field_groups`
- `acf_get_field_group`
- `acf_create_field_group`
- `acf_create_field_group_simple`
- `acf_update_field_group`
- `acf_delete_field_group`
- `acf_validate_field_group`
- `acf_audit_ai_access`
- `acf_validate_runtime_compatibility`
- `acf_audit_schema_mappings`
- `acf_runtime_status`
- `acf_export_json`
- `acf_import_json`
- `acf_sync_json`
- `acf_list_post_types`
- `acf_create_post_type`
- `acf_create_post_type_simple`
- `acf_list_taxonomies`
- `acf_create_taxonomy`
- `acf_create_taxonomy_simple`
- `acf_list_options_pages`
- `acf_create_options_page`
- `acf_apply_content_model`

See [docs/tools.md](docs/tools.md) for schemas and examples.
See [docs/runtime-compatibility.md](docs/runtime-compatibility.md) for ACF 6.8 Abilities API, MCP Adapter, and Schema.org guidance.

## Example: Apply a Content Model

```json
{
  "dryRun": true,
  "backup": true,
  "model": {
    "postTypes": [
      {
        "key": "post_type_product",
        "post_type": "product",
        "labels": { "name": "Products", "singular_name": "Product" },
        "public": true,
        "show_in_rest": true
      }
    ],
    "taxonomies": [
      {
        "key": "taxonomy_brand",
        "taxonomy": "brand",
        "object_type": ["product"],
        "labels": { "name": "Brands", "singular_name": "Brand" }
      }
    ],
    "optionsPages": [
      {
        "key": "ui_options_page_theme_settings",
        "menu_slug": "theme-settings",
        "page_title": "Theme Settings"
      }
    ],
    "fieldGroups": [
      {
        "key": "group_product_details",
        "title": "Product Details",
        "fields": [
          {
            "key": "field_product_subtitle",
            "label": "Subtitle",
            "name": "subtitle",
            "type": "text"
          }
        ],
        "location": [
          [{ "param": "post_type", "operator": "==", "value": "product" }]
        ]
      }
    ]
  }
}
```

## DDEV

This repository includes `.ddev/config.yaml` for a WordPress fixture in `wp/`.

ACF Pro is not bundled or redistributed. Install your licensed ACF Pro copy in the fixture when running WordPress integration checks.

See [docs/ddev.md](docs/ddev.md).

## Development

```bash
npm run typecheck
npm run lint
npm test
npm run build
```

Optional integration tests can be added under `tests/integration` and gated with:

```bash
RUN_DDEV_INTEGRATION=1 npm run test:integration
```

## Project Structure

```text
src/
  adapters/
  config/
  errors/
  prompts/
  repositories/
  resources/
  schemas/
  server/
  services/
  tools/
  types/
  utils/
```

## Explore ACF Pro skill for AI agents
https://github.com/symonbaikov/acf-pro-skill


## Contributing

Keep changes small, tested, and backward-compatible. New tools must include:

- Zod input schema.
- Typed structured result.
- Error handling through the shared tool wrapper.
- Tests for success, validation failure, and dry-run behavior when mutating.

## License

MIT