使用说明

ProcessWire MCP服务器

用于ProcessWire CMS的可扩展MCP（模型上下文协议）服务器，使Claude等AI助手能够与您的ProcessWire安装进行交互。

特性

完整的ProcessWire API访问 -查询、创建、更新和删除页面
模板和字段管理 -检查和修改您网站的数据结构
用户和角色管理 -创建用户、管理角色和权限
模块管理 -列出、安装和配置模块
文件管理 -访问页面文件和图像
可扩展架构 -第三方模块可以注册自定义工具
注重安全 -管理员页面被阻止，可配置限制

需求

PHP 8.1+
ProcessWire 3.0.200+
作曲家

安装

# Using Composer (recommended)
composer require elabx/processwire-mcp

# With DDEV
ddev composer require elabx/processwire-mcp

用法

运行服务器

通过Composer安装时，服务器会自动检测您的ProcessWire根目录——不需要路径标志：

# Auto-detects PW root (recommended)
vendor/bin/pw-mcp-server

# With DDEV
ddev exec php vendor/bin/pw-mcp-server

# Explicit path (if auto-detect doesn't work)
php vendor/bin/pw-mcp-server --pw-path=/path/to/processwire

# Using environment variable
PW_PATH=/path/to/processwire php vendor/bin/pw-mcp-server

Claude代码配置

添加到您的项目 .claude/settings.json 或 ~/.claude/settings.json:

{
  "mcpServers": {
    "processwire": {
      "command": "ddev",
      "args": ["exec", "php", "vendor/bin/pw-mcp-server"]
    }
  }
}

对于非DDEV设置：

{
  "mcpServers": {
    "processwire": {
      "command": "php",
      "args": ["vendor/bin/pw-mcp-server"]
    }
  }
}

可用工具

页面工具

工具	说明
`find_pages`	使用ProcessWire选择器查询页面
`get_page`	按ID或路径获取单页
`create_page`	创建新页面
`update_page`	更新页面字段值
`delete_page`	回收或永久删除页面
`get_children`	获取父级的子页面
`clone_page`	克隆页面，可选择带有子页面
`sort_pages`	相对于同级页面对页面进行排序
`restore_page`	从回收站还原页面

模板工具

工具	说明
`find_templates`	使用ProcessWire选择器语法查找模板
`list_templates`	列出所有可用模板
`get_template_fields`	获取模板字段和配置
`get_template_file`	获取模板文件路径
`create_template`	创建新模板
`update_template`	更新模板设置（标签、限制、缓存等）
`delete_template`	删除模板（必须没有页面）
`clone_template`	克隆一个包含所有字段和设置的模板
`add_field_to_template`	将字段添加到具有定位功能的模板中
`remove_field_from_template`	从模板中删除字段

现场工具

工具	说明
`find_fields`	使用ProcessWire选择器语法查找字段
`list_fields`	列出所有字段，可选择按类型筛选
`get_field`	获取字段详细信息和配置
`list_field_types`	列出可用字段类型
`create_field`	使用类型和设置创建新字段
`update_field`	更新字段属性
`delete_field`	删除字段（不得使用）
`clone_field`	使用所有设置克隆字段

用户工具

工具	说明
`list_users`	列出用户（可选按角色）
`get_user`	获取用户详细信息
`create_user`	使用电子邮件、密码和角色创建用户
`update_user`	更新用户电子邮件、密码或角色
`delete_user`	删除用户
`list_roles`	列出所有角色

角色工具

工具	说明
`create_role`	创建具有可选权限的新角色
`update_role`	添加或删除角色的权限
`delete_role`	删除角色（不得分配给用户）
`list_permissions`	列出所有可用权限
`create_permission`	创建新权限
`set_template_access`	在模板上设置基于角色的访问控制

模块工具

工具	说明
`list_modules`	列出所有模块（仅可选安装）
`get_module_info`	获取模块详细信息和要求
`install_module`	安装模块（需要确认）
`uninstall_module`	卸载模块（需要确认）
`get_module_config`	获取模块配置（敏感值已编辑）
`save_module_config`	保存模块配置值

文件工具

工具	说明
`get_page_files`	获取附加到页面的文件/图像
`get_image_variations`	获取图像大小变化
`get_page_files_path`	获取页面文件目录路径

可用资源

资源提供对ProcessWire数据的只读访问：

URI	描述
`templates://list`	所有模板及其字段
`fields://list`	所有字段定义
`users://list`	所有用户（仅基本信息）
`roles://list`	所有具有权限的角色

使用自定义工具进行扩展

第三方ProcessWire模块可以通过扩展来注册自定义MCP工具 ProcessWireMcpTool:

1.创建工具类

<?php

namespace YourVendor\YourModule;

use Elabx\ProcessWireMcp\Tool\ProcessWireMcpTool;
use Mcp\Capability\Attribute\McpTool;

class MyCustomTools extends ProcessWireMcpTool
{
    public static function getToolInfo(): array
    {
        return [
            'name' => 'my_custom_tools',
            'description' => 'Custom tools for my module',
            'priority' => 100, // Lower = loaded first
        ];
    }

    #[McpTool(
        name: 'my_custom_operation',
        description: 'Does something custom with pages'
    )]
    public function myCustomOperation(string $selector): array
    {
        // Use ProcessWire APIs via inherited methods
        $count = $this->pages()->count($selector);

        return $this->success([
            'count' => $count,
        ]);
    }
}

2.通过Hook注册

在ProcessWire模块中：

<?php

namespace ProcessWire;

class MyModule extends WireData implements Module
{
    public static function getModuleInfo(): array
    {
        return [
            'title' => 'My Module',
            'requires' => ['ProcessWireMcp'],
            // ...
        ];
    }

    public function ready(): void
    {
        $this->addHookAfter('ProcessWireMcp::getToolClasses', function($event) {
            $classes = $event->return;
            $classes[] = \YourVendor\YourModule\MyCustomTools::class;
            $event->return = $classes;
        });
    }
}

基类方法

ProcessWireMcpTool 提供了以下辅助方法：

// ProcessWire API access
$this->pages()      // Pages API
$this->templates()  // Templates API
$this->fields()     // Fields API
$this->users()      // Users API
$this->sanitizer()  // Sanitizer API
$this->get($name)   // Any wire service

// Security helpers
$this->isAdminPage($page)          // Check if page is admin
$this->assertNotAdminPage($page)   // Throw if admin page
$this->excludeAdminFromSelector($selector)  // Add admin exclusion

// Response helpers
$this->success($data, $message)    // Success response
$this->error($message, $code)      // Error response
$this->pageToArray($page, $fields) // Convert page to array

安全

MCP服务器包括几种安全措施：

管理员页面保护 -以下页面 /processwire/ （ID 2）被阻止
无密码泄露 -用户工具从不返回密码数据
选择器筛选 -可配置的阻塞选择器（通过模块配置）
系统页面保护 -无法删除系统页面（ID<=7）
文件限制 -只有ProcessWire管理的文件可访问
模块安全 -安装/卸载需要明确确认
配置编校 -敏感模块配置值（密码、密钥）被编辑

可选ProcessWire模块

安装可选 ProcessWireMcp 模块用于：

ProcessWire管理中的配置UI
自定义阻止选择器配置
挂钩支持第三方扩展

复制 ProcessWireMcp.module.php 到 site/modules/ProcessWireMcp/ 并通过ProcessWire管理员进行安装。

测试

测试针对实时ProcessWire安装运行。您可以使用Docker（自包含）或DDEV（现有开发环境）。

Docker（推荐用于CI）

Docker设置提供了一个新的ProcessWire安装，并使用一个命令运行完整的测试套件：

# Run all tests
docker compose -f docker-compose.test.yml run --rm tests

# Run a specific test class (use --filter, not file paths)
docker compose -f docker-compose.test.yml run --rm tests --filter=PageToolsTest

# Run multiple test classes
docker compose -f docker-compose.test.yml run --rm tests --filter='FieldToolsTest|TemplateToolsTest'

# Run with verbose output
docker compose -f docker-compose.test.yml run --rm tests --testdox

# Tear down containers
docker compose -f docker-compose.test.yml down --volumes

# Rebuild after Dockerfile changes
docker compose -f docker-compose.test.yml build --no-cache tests

注：使用 --filter 选择测试，而不是文件路径。通过路径如 tests/Tool/PageToolsTest.php 将失败，并显示“未找到测试文件”，因为该包在容器内的不同位置被符号链接(/package 通过Composer路径仓库）访问PHPUnit工作目录(/var/www/html).

DDEV

如果您已经有一个带ProcessWire的DDEV项目：

先决条件

安装了ProcessWire并填充了数据库的工作DDEV项目
安装到DDEV容器中的包（例如，通过docker compose卷 /packages/ProcessWireMcp)
该包作为Composer依赖项安装，因此其类会自动加载
PHPUnit在项目供应商处可用（例如。 phpunit/phpunit 在 require-dev)
在项目中注册的测试命名空间 autoload-dev:

{
  "autoload-dev": {
    "psr-4": {
      "Elabx\\ProcessWireMcp\\Tests\\": "/packages/ProcessWireMcp/tests/"
    }
  }
}

更改自动加载配置后，重新生成自动加载器：

ddev composer dump-autoload

运行测试

ddev exec vendor/bin/phpunit --configuration /packages/ProcessWireMcp/phpunit.xml

具有可读输出：

ddev exec vendor/bin/phpunit --configuration /packages/ProcessWireMcp/phpunit.xml --testdox

运行特定的测试类：

ddev exec vendor/bin/phpunit --configuration /packages/ProcessWireMcp/phpunit.xml --filter PageTools

运作原理

测试引导程序(tests/bootstrap.php)加载宿主项目的Composer自动加载器，然后通过包含其 index.php。这使测试可以通过真实的数据库连接访问完整的ProcessWireneneneba API-与MCP服务器运行的环境相同 PW_PATH 环境变量控制ProcessWire根目录（默认为 /var/www/html).

tests/ProcessWireTestCase.php 是所有测试的基类。它暴露了 $this->wire() 它返回自举的 ProcessWire 例子

写作测试

扩展 ProcessWireTestCase 并直接实例化工具类：

<?php

namespace Elabx\ProcessWireMcp\Tests\Tool;

use Elabx\ProcessWireMcp\Tests\ProcessWireTestCase;
use Elabx\ProcessWireMcp\Tool\Core\PageTools;

class PageToolsTest extends ProcessWireTestCase
{
    private PageTools $tools;

    protected function setUp(): void
    {
        parent::setUp();
        $this->tools = new PageTools();
        $this->tools->setWire($this->wire());
    }

    public function testFindPagesReturnsResults(): void
    {
        $result = $this->tools->findPages('limit=3');

        $this->assertTrue($result['success']);
        $this->assertArrayHasKey('pages', $result['data']);
    }
}

许可证

MIT许可证

贡献

欢迎投稿！请打开问题或提交拉取请求。

学分

与 MCP-PHP-SDK.