Joomla MCP Suite

Joomla MCP套件

一个模型上下文协议（MCP）服务器，使AI代理能够安全地与在Docker中运行的Joomla站点进行交互。

这是什么？

该项目在AI助手（如Claude Desktop）和本地Joomla实例之间提供了一座桥梁，使AI能够：

• 从数据库中读取并列出Joomla文章
• 通过Joomla的REST API创建和修改文章
• 在Joomla安装中读写文件
• 执行安全的数据库查询
• 通过受控的MCP工具管理Joomla内容

建筑

该项目由三个Docker服务组成：

• 数据库：Joomla的MySQL 8.0数据库
• 模板：官方Joomla容器（可访问http://localhost:8080)
• mcp服务器：Node.js MCP服务器，连接到数据库和Joomla API

先决条件

• 已安装Docker和Docker Compose
• Node.js 18+（用于本地测试）
• 兼容的MCP客户端（例如Claude Desktop）

安装说明

1.克隆存储库

git clone 
cd joomla-mcp-suite

2.创建环境文件

创建一个 .env 项目根目录中的文件：

echo "JOOMLA_API_TOKEN=your_token_here" > .env

（安装Joomla后，您将使用真实令牌更新此内容）

3.启动Docker堆栈

docker compose up -d

这将开始：

• 内部网络上的MySQL数据库
• Joomla网站http://localhost:8080
• MCP服务器容器

4.安装Joomla

1. 打开浏览器http://localhost:8080
2. 完成Joomla安装向导：

- 设置站点名称、管理员用户名和密码 - 数据库配置（应自动填充）： - 主持人： db - 数据库： joomla_db - 用户名： joomla_user - 密码： joomla_password

1. 完成安装

5.生成Joomla API代币

1. 登录Joomla管理员：http://localhost:8080/administrator
2. 引导到 系统→ 管理→ API令牌 （或用户配置文件→ API代币）
3. 创建新的API令牌
4. 复制生成的令牌

6.更新环境文件

编辑 .env 使用您的真实API代币：

JOOMLA_API_TOKEN=your_actual_token_here

重新启动MCP服务器以加载新令牌：

docker-compose up -d --force-recreate mcp-server

可用的MCP工具

服务器公开了以下工具：

数据库工具

• db_阅读_文章：从数据库中读取文章

- 参数： limit （数字，默认值：5）

• db_create_文章：通过直接插入数据库创建文章

- 参数： title （字符串）， introtext （字符串）， alias （可选）， catid （数字，默认值：2）

文件系统工具

• 文件_读取：从Joomla安装中读取文件

- 参数： relative_path （字符串）

• 文件_写入：在Joomla安装中写入/覆盖文件

- 参数： relative_path （字符串）， content （字符串）

API工具

• api_列表_文章：列出使用Joomla REST API的文章

- 参数：无

• api_create_文章：通过Joomla REST API创建文章

- 参数： title （字符串）， articletext （字符串）， catid （数字，默认值：2）， language （字符串，默认值：“\*”）

• api_edit_文章：更新现有文章

- 参数： id （字符串）， title （字符串）， articletext （字符串）

测试MCP服务器

运行所有测试

docker exec -it joomla_mcp node test-all-tools.js

这将测试所有可用工具并显示摘要报告。

测试单个组件

测试数据库连接：

docker exec -it joomla_mcp node test-db.js

测试API连接：

docker exec -it joomla_mcp node test-api.js

测试MCP客户端：

docker exec -it joomla_mcp node test-mcp-client.js

连接到克劳德桌面

将此配置添加到您的Claude Desktop配置文件中：

Linux/macOS: ~/.config/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "joomla-master": {
      "command": "docker",
      "args": ["exec", "-i", "joomla_mcp", "node", "index.js"]
    }
  }
}

重新启动Claude Desktop以加载MCP服务器。

与GitHub代码空间一起使用

该项目包括 .devcontainer GitHub代码空间的配置：

1. 在Codespace中打开存储库
2. 环境将自动设置
3. 通过转发端口8080访问Joomla
4. 按照设置说明中的步骤4-6进行操作

项目结构

joomla-mcp-suite/
├── .devcontainer/          # Codespaces configuration
│   ├── devcontainer.json
│   └── docker-compose.yaml
├── mcp-server/             # MCP server implementation
│   ├── Dockerfile
│   ├── index.js            # Main MCP server
│   ├── package.json
│   ├── test-all-tools.js   # Comprehensive test suite
│   ├── test-api.js         # API connectivity test
│   ├── test-db.js          # Database connectivity test
│   └── test-mcp-client.js  # MCP client test
├── scripts/
│   └── auto_install.sh     # Joomla auto-install script
├── docker-compose.yml      # Main Docker configuration
├── .env                    # Environment variables (create this)
├── .gitignore
└── README.md

环境变量

MCP服务器使用以下环境变量：

• DB_HOST：数据库主机（默认值： db)
• DB_USER：数据库用户（默认值： joomla_user)
• DB_PASSWORD：数据库密码（默认值： joomla_password)
• DB_NAME：数据库名称（默认值： joomla_db)
• DB_PREFIX：表前缀（默认值： joos_)
• JOOMLA_API_TOKEN：您的Joomla API代币
• JOOMLA_API_BASE：API基本URL（默认值： http://joomla/api/index.php/v1)

故障排除

端口8080已在使用中

更改中的端口映射 docker-compose.yml:

ports:
  - "8081:80"  # Use 8081 instead

MCP服务器无法连接到数据库

检查所有容器是否正在运行：

docker ps

重新启动堆栈：

docker compose down
docker compose up -d

API调用失败

1. 验证API令牌是否在中正确设置 .env
2. 检查Joomla API是否在Joomla管理中启用
3. 更新令牌后重新启动MCP服务器

测试失败

查看详细日志：

docker logs joomla_mcp
docker logs joomla_site
docker logs joomla_db

发展

重建MCP服务器

更改MCP服务器代码后：

docker compose up -d --build mcp-server

访问容器外壳

docker exec -it joomla_mcp sh

查看日志

docker compose logs -f mcp-server

安全说明

• 这 .env 文件包含敏感信息，已从git中排除
• API代币应保持安全并定期轮换
• MCP服务器可以完全访问Joomla数据库和文件
• 仅在开发环境中使用此设置

许可证

\[您的许可证在这里\]

贡献

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