内容
# JoomEngine MCP for Joomla
一款可嵌入的库和自主托管的模型上下文协议（MCP）服务器，用于通过有界、可审计的语义操作管理Joomla 6.x。
服务器具有两种Joomla集成路径：
- **Joomla Web 服务 API：** 使用专用的Joomla API标识进行远程HTTPS访问。
- **Joomla本地伴侣：** 通过可安装的控制台插件、Joomla依赖注入、ACL检查和核心模型进行本地访问。
本地Joomla功能是权威的。伴侣适配原生Joomla服务和模型到结构化的JSON合约；它不替换或重新实现Joomla功能。没有通用HTTP、CLI、shell、PHP、SQL、文件系统、模型、方法或URL直通。
Joomla 6.1是实现基准，Joomla 6.2是兼容性目标，Joomla 7作为预警测试。
> **生产状态：** 所有236个Joomla 6.1核心Web服务路由模板都已源编目，但有五个明确为源代码专有，尚未完成所需的实时Joomla 6.1/6.2成功、拒绝、后置条件和恢复矩阵。生产认证仍受限于该证据、更深层次的价值/输出合约、特权恢复测试和多副本写入的共享协调。参见[覆盖率和发布状态](docs/COVERAGE.md)。
## 为什么选择这个堆栈
TypeScript是一级MCP SDK，而PHP是三级。为方便起见，使用TypeScript和可能的情况下使用PHP。
## 功能
- 所有236个Joomla 6.1核心Web服务路由模板的源代码支持的语义目录。
- 36个核心资源库的CRUD操作，包括文章、横幅、用户、联系人、类别、菜单、模块、标签、重定向、字段、模板、语言、消息和新闻源。
- 每个CRUD变体家族的字段允许列表已审查，固定形状的媒体、隐私、插件、语言覆盖、应用程序配置和Joomla更新变体的确切模式。
- 对于Joomla 6.1中存在缺陷或需要未实现的运行时秘密/模式发现的路由，明确的源代码专有门控。
- 通过固定伴侣允许列表进行本地Joomla操作。
- 只读发现、安全配置过滤和不可变的多站点别名。
- 使用明确的主体绑定操作员授予（`once`、`30-minutes`或`indefinite`）、预览、签名一次性计划、幂等性、锁、审计事件和支持的验证。
- 通过stdio或身份验证的Streamable HTTP进行MCP。
- 版本化的ESM包，带有类型化的根和子路径导出，供主机应用程序使用。
- OCI镜像、Docker Compose和systemd部署基础。
- 具有确定性Joomla夹具、安全确认和编辑的Markdown/JSON/JUnit失败证据的交互式和无人值守的目录完整性实时验证。
生成的[API操作参考](docs/API_ACTIONS.md)列出了每个路由、语义ID、接受的字段集、传输、风险和源代码专有门控。发布真相表在[docs/COVERAGE.md](docs/COVERAGE.md)中。实施的操作在通过相应的实时Joomla矩阵验证之前，不被描述为生产验证。
## 要求
- Node.js 22.12或更新版本。
- Joomla 6.1或更新版本用于伴侣；用于API的Joomla 6.x站点。
- 主机使用伴侣时，PHP 8.3或更新版本。
- HTTPS和专用的最低权限Joomla API用户，用于远程API访问。
- 具有HTTPS JWKS端点的OAuth/OIDC授权服务器，用于远程MCP访问。
## 作为库依赖使用
安装公共的版本化包：
```bash
npm install @joomengine/joomla-mcp@^0.7.0
```
在不启动进程或绑定端口的情况下创建传输中立的应用程序：
```js
import {
createJoomlaMcp,
loadConfiguration,
} from '@joomengine/joomla-mcp';
const configuration = await loadConfiguration('/etc/joomla-mcp/sites.json');
const application = createJoomlaMcp({ configuration });
const mcpServer = application.createServer();
```
该包保留完整的目录、读取、保护写入、管理操作、授予工作流、Joomla API和伴侣传输、stdio和身份验证的HTTP支持。主机应用程序可以注入秘密解析、审计、API和CLI适配器，同时操作和安全边界由该包控制。
参见[库集成](docs/LIBRARY.md)，了解每个公共入口点、配置和秘密管理器集成、stdio/HTTP生命周期、适配器合约、隔离规则、可执行示例和兼容性策略。
## 安装和验证
```bash
git clone https://github.com/joomengine/joomla-mcp.git
cd joomla-mcp
npm ci
cp config/sites.example.json config/sites.json
npm run validate
```
编辑`config/sites.json`，然后导出`tokenEnv`、`updateTokenEnv`和`approval.secretEnv`中命名的每个秘密。令牌和批准秘密永远不会存储在站点文件中。
对于启用写入的站点，生成至少32个随机字符的批准秘密：
```bash
export JOOMLA_MCP_APPROVAL_SECRET="$(openssl rand -hex 32)"
```
不要将生产秘密放入shell历史、源代码控制、客户端配置或命令参数中。使用操作系统服务管理器或秘密存储。
要构建伴侣并证明新的安装和完整的实时MCP矩阵针对存储库的可处置Joomla 6.1/JoomEngine夹具：
```bash
php companion/build.php
npm run test:fixture:joomengine
```
这需要带有Compose v2的Docker。夹具使用新鲜的隔离卷，仅在随机环回端口上发布Joomla，生成一次性凭证和临时API令牌，清单安装的CLI合约，然后通过API/伴侣和stdio/Streamable HTTP练习完整的动作目录，然后删除站点和数据库。失败会上传编辑的Markdown、JSON、JUnit、每个动作的证据和运行时日志，然后拆除。参见[实时验证](docs/LIVE_TESTING.md)。
打包的声明性场景是`config/live-test.default.json`。它创建并独立验证几个类别、文章、用户组、用户、横幅类别、横幅、菜单、文章菜单项和自定义HTML模块。关系在JSON中使用命名引用；仅在创建并独立观察引用记录后才解析Joomla ID。
要保留Joomla中创建的每个记录以便检查，而不发出任何删除或垃圾邮件操作：
```bash
npm run test:live -- \
--scenario ./config/live-test.default.json \
--config /absolute/path/to/config/sites.json \
--site demo \
--profile crud \
--non-interactive \
--confirm-mutations \
--cleanup never
```
运行器将`START`、`WAIT`和终端状态行写入标准输出，同时保留完整的Markdown、JSON、JUnit、每个动作和夹具日志工件。
要交互式地选择实时演示站点：
```bash
npm run build
npx joomla-mcp-live-test
```
变体配置文件打印确切的目标，需要键入主机名/运行种子确认。无人值守的变体运行需要明确的`--confirm-mutations`；完整的特权配置文件还需要`--disposable`。
## 通过stdio使用
构建并启动服务器：
```bash
npm run build
JOOMLA_MCP_CONFIG=/absolute/path/to/config/sites.json npm start
```
MCP客户端入口示例：
```json
{
"mcpServers": {
"joomla": {
"command": "node",
"args": ["/opt/joomla-mcp/dist/bin/joomla-mcp.js"],
"env": {
"JOOMLA_MCP_CONFIG": "/etc/joomla-mcp/sites.json"
}
}
}
}
```
进程环境还必须包含站点文件引用的令牌和批准秘密变量。stdio继承本地MCP客户端的权限，因此为生产使用专用操作系统帐户。
## 通过Streamable HTTP使用
添加`config/sites.example.json`中显示的`http`块，然后运行：
```bash
npm run build
JOOMLA_MCP_CONFIG=/etc/joomla-mcp/sites.json npm run start:http
```
HTTP入口点需要加密验证的JWT，并验证发行者、受众、范围、确切的`Host`、可选的`Origin`、请求限制和主体绑定会话。`/healthz`是浅层进程活跃度；`/readyz`在实例接收MCP流量之前预热并验证配置的JWKS依赖项。关闭新录取，关闭空闲连接，等待活动连接最多`shutdownGraceMs`，然后强制关闭它们。在受信任的反向代理处终止TLS，并将Node监听器保留在私有接口上。参见[远程HTTP](docs/REMOTE_HTTP.md)和[部署](docs/DEPLOYMENT.md)。
## 使用Joomla伴侣
构建和测试可安装的包：
```bash
php companion/tests/run.php
php companion/build.php
```
使用Joomla的扩展安装器安装生成的`companion/dist/pkg_joomlamcp-*.zip`。首次安装通过Joomla的原生安装程序生命周期启用**控制台 - JoomEngine MCP for Joomla Companion**；包更新保留操作员的启用/禁用状态。选择专用的最低权限**MCP操作员用户**，并在`config/sites.json`中配置站点的固定Joomla根目录和PHP可执行文件。
从Joomla根目录验证：
```bash
php cli/joomla.php joomla:mcp:describe --format=json --no-interaction --no-ansi
```
边缘仅通过JSON标准输入调用伴侣的命名、模式验证的操作。参见[PHP伴侣](docs/PHP_COMPANION.md)。
## Joomla API设置
对于每个站点：
1. 启用**API身份验证 - Web服务Joomla令牌**。
2. 启用**用户 - Joomla API令牌**，并允许专用自动化组。
3. 为自动化组授予`core.login.api`和仅限于其启用的工具集所需的组件权限。
4. 仅启用那些工具集所需的Web服务插件。
5. 创建用户的Joomla API令牌，并将其放入`tokenEnv`命名的环境变量中。
6. 确认`https://your-site.example/api/index.php/v1/content/articles`使用该令牌响应。
Joomla更新使用`updateTokenEnv`引用的单独令牌。不要重用或公开任一令牌到MCP客户端。
## 写入
除非启用相关的站点工具集和批准配置，否则写入被禁用。正常流程是：
1. 搜索目录并选择一个固定的语义操作。
2. 调用`joomla_action_describe`检查其完整的模式、源、配置的传输可用性和认证状态。
3. 调用`joomla_action_write_plan`并使用UUID幂等键和`dryRun: true`检查操作。伴侣计划执行Joomla的原生非变异预飞行，并将其编辑的结果绑定到计划中。
4. 为确切的站点、写入/管理工具集、原因和持续时间调用`joomla_permission_request`。
5. 显示返回的确认短语给操作员。仅在操作员准确提供它后，将其提交给`joomla_permission_approve`。
6. 用`dryRun: false`重复写入计划；需要一个活动的匹配授予，返回的令牌绑定到该授予。
7. 调用`joomla_write_apply`并使用令牌。应用重新检查认证主体、站点/工具集范围、授予、存储的计划和Joomla前提条件，然后执行。
一次性授予由一次应用尝试消耗。 30分钟授予期满后恰好30分钟。无限期授予默认情况下禁用，需要一个完整性保护的持久存储，并仅在明确撤销之前保持活动。授予永远不会覆盖站点配置、OAuth范围、Joomla令牌权限或Joomla ACL。
在您的环境中通过[docs/COVERAGE.md](docs/COVERAGE.md)中的实时和恢复门控之前，请勿启用破坏性或特权工具集。
## 文档
- [架构和原生优先规则](docs/ARCHITECTURE.md)
- [库和主机应用程序集成](docs/LIBRARY.md)
- [版本控制和协调的包发布](docs/RELEASING.md)
- [单公司、单站点部署](docs/SINGLE_SITE.md)
- [ChatGPT、Codex、Claude、Gemini和Grok连接](docs/CLIENTS.md)
- [生成的Joomla API操作参考](docs/API_ACTIONS.md)
- [操作覆盖率和发布状态](docs/COVERAGE.md)
- [部署、升级和回滚](docs/DEPLOYMENT.md)
- [夹具设置和实时验证](docs/FIXTURES.md)
- [交互式、无人值守和CI实时验证](docs/LIVE_TESTING.md)
- [操作和监控](docs/OPERATIONS.md)
- [PHP伴侣](docs/PHP_COMPANION.md)
- [远程Streamable HTTP](docs/REMOTE_HTTP.md)
- [安全模型](docs/SECURITY.md)
- [测试](docs/TESTING.md)
- [故障排除](docs/TROUBLESHOOTING.md)
- [MCP工具和使用案例](docs/USAGE.md)
- [Joomla CLI库存和集成映射](docs/CLI.md)
## 开发和贡献
```bash
npm run check
npm test
npm run build
php companion/tests/run.php
php companion/build.php
```
`npm run validate`运行TypeScript检查、离线测试套件和生产构建。参见[CONTRIBUTING.md](CONTRIBUTING.md)贡献要求和[SECURITY.md](SECURITY.md)私有漏洞报告。
## 许可证
Copyright (C) 2026 Vast Development Method.
JoomEngine MCP for Joomla是根据**GNU通用公共许可证，版本2或后续版本**（`GPL-2.0-or-later`）许可的免费软件。您可以在这些条款下使用、修改和重新分发它。完整的许可证文本在[LICENSE](LICENSE)中。
