内容
# ACF MCP 服务器
为安全读写 WordPress + ACF Pro 结构而准备的生产就绪型模型上下文协议服务器，通过 ACF 本地 JSON 和明确的 WP-CLI 同步实现。
该服务器适用于需要检查或提出对 ACF 字段组、自定义帖子类型、分类法和选项页面的更改的 AI 代理，而无需直接访问数据库。
## 功能
- TypeScript、Node.js、Zod、Vitest 和 `@modelcontextprotocol/sdk`。
- 以 JSON 为优先的 ACF 本地 JSON 仓库。
- 无直接 SQL，无任意 PHP，无 shell 插值。
- 突变前自动备份。
- `dryRun` 支持写入工作流。
- 明确的 WP-CLI 同步/导入/导出工具。
- 默认 `stdio` 传输，可选 Streamable HTTP 用于开发。
- DDEV WordPress 固定装置配置。
## 安装
```bash
npm install
npm run build
```
用于本地开发：
```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 客户端配置
示例stdio配置：
```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"
}
}
}
}
```
在开发过程中，请使用 `tsx`：
```json
{
"command": "npx",
"args": ["tsx", "/absolute/path/to/acf_mcp/src/server/stdio.ts"]
}
```
## 安全模型
本地 JSON 是主要的真实来源。创建、更新、删除或应用内容模型的工具仅写入 JSON 文件。它们不会自动同步 WordPress 数据库。
推荐的工作流程：
1. 调用写入工具时使用 `dryRun: true`。
2. 查看计划的 `changes`。
3. 调用相同的工具，`dryRun: false`。
4. 查看 `acf-json` 的 git diff。
5. 调用 `acf_sync_json` 时使用 `dryRun: true`。
6. 仅在准备好时调用 `acf_sync_json`，`dryRun: false`。
## 工具
- `acf_ping`
- `acf_list_field_groups`
- `acf_get_field_group`
- `acf_create_field_group`
- `acf_update_field_group`
- `acf_delete_field_group`
- `acf_validate_field_group`
- `acf_export_json`
- `acf_import_json`
- `acf_sync_json`
- `acf_list_post_types`
- `acf_create_post_type`
- `acf_list_taxonomies`
- `acf_create_taxonomy`
- `acf_list_options_pages`
- `acf_create_options_page`
- `acf_apply_content_model`
参见 [docs/tools.md](docs/tools.md) 获取模式和示例。
## 示例：应用内容模型
```json
{
"dryRun": true,
"backup": true,
"model": {
"postTypes": [
{
"key": "post_type_product",
"post_type": "product",
"labels": { "name": "产品", "singular_name": "产品" },
"public": true,
"show_in_rest": true
}
],
"taxonomies": [
{
"key": "taxonomy_brand",
"taxonomy": "brand",
"object_type": ["product"],
"labels": { "name": "品牌", "singular_name": "品牌" }
}
],
"optionsPages": [
{
"key": "ui_options_page_theme_settings",
"menu_slug": "theme-settings",
"page_title": "主题设置"
}
],
"fieldGroups": [
{
"key": "group_product_details",
"title": "产品详情",
"fields": [
{
"key": "field_product_subtitle",
"label": "副标题",
"name": "subtitle",
"type": "text"
}
],
"location": [
[{ "param": "post_type", "operator": "==", "value": "product" }]
]
}
]
}
}
```
## DDEV
此仓库包含 `wp/` 中的 WordPress 固定装置的 `.ddev/config.yaml`。
ACF Pro 不捆绑或重新分发。在运行 WordPress 集成检查时，请在固定装置中安装您许可的 ACF Pro 副本。
参见 [docs/ddev.md](docs/ddev.md)。
## 开发
```bash
npm run typecheck
npm run lint
npm test
npm run build
```
可选的集成测试可以添加到 `tests/integration` 下，并使用以下命令控制：
```bash
RUN_DDEV_INTEGRATION=1 npm run test:integration
```
## 项目结构
```text
src/
adapters/
config/
errors/
prompts/
repositories/
resources/
schemas/
server/
services/
tools/
types/
utils/
```
## 贡献
保持更改小，测试完善，向后兼容。新工具必须包括：
- Zod 输入模式。
- 类型化的结构化结果。
- 通过共享工具包装器的错误处理。
- 成功、验证失败和突变时的 dry-run 行为的测试。
## 许可证
MIT
