Docker Techstack Rolldev Mcp Server

RollDev MCP 服务

一个用于 RollDev + Magento 2 开发环境的模型上下文协议（MCP）服务。此服务支持 Claude 和其他大模型与 RollDev 项目交互、管理环境、执行命令，并轻松初始化新的 Magento 2 项目。

功能

环境管理

• 环境控制：列出、启动和停止 RollDev 项目环境
• 服务管理：控制 RollDev 系统服务（数据库、Redis、OpenSearch 等）
• 项目初始化：创建带有自动配置的新 Magento 2 项目

开发工具

• 数据库操作：直接在项目数据库中执行 SQL 查询
• PHP 脚本执行：在项目容器中运行 PHP 脚本
• Magento CLI 访问：通过 roll magento 执行 Magento 命令
• Composer 集成：在项目环境中运行 Composer 命令

可靠性功能

• 命令超时：所有命令均设有适当的超时时间，以防止执行挂起（根据操作不同，为 5-15 分钟）
• 输出文件重定向：可将命令输出保存到日志文件，以便之后查看

前提条件

• 已安装并配置 RollDev
• Node.js 18+
• 有可用的 RollDev 项目环境（部分操作需要）

安装

选项 1：使用 NPM（推荐）

{
  "mcpServers": {
    "rolldev": {
      "command": "npx",
      "args": [
        "-y",
        "@disrex/rolldev-mcp-server"
      ]
    }
  }
}

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

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%\Claude\claude_desktop_config.json

选项 2：手动设置

1. 克隆此仓库：

git clone https://github.com/dockergiant/rolldev-mcp-server.git
cd rolldev-mcp-server

2. 安装依赖：

npm install

3. 添加到 Claude 配置：

{
  "mcpServers": {
    "rolldev": {
      "command": "node",
      "args": ["/path/to/rolldev-mcp-server/server.js"]
    }
  }
}

可用工具

rolldev_list_environments

列出所有正在运行的 RollDev 环境，并提供结构化信息，包括项目名称、路径、URL、Docker 网络和容器数量。

rolldev_start_project

启动 RollDev 项目环境。

• project_path：项目目录路径

rolldev_stop_project

停止 RollDev 项目环境。

• project_path：项目目录路径

rolldev_start_svc

启动 RollDev 系统服务。

• project_path：项目目录路径

rolldev_stop_svc

停止 RollDev 系统服务。

• project_path：项目目录路径

rolldev_db_query

在项目数据库中执行 SQL 查询。

• project_path：项目目录路径
• query：要执行的 SQL 查询
• database：数据库名称（可选，默认为 "magento"）

rolldev_php_script

在项目容器中运行 PHP 脚本。

• project_path：项目目录路径
• script_path：相对于项目根目录的 PHP 脚本路径
• args：附加参数（可选）

rolldev_magento_cli

执行 Magento CLI 命令（超时 5 分钟）。

• project_path：项目目录的路径
• command：Magento 命令（不含 bin/magento 前缀）
• args：其他参数（可选）
• save_output_to_file：将完整输出保存到日志文件（可选，默认：false）

rolldev_composer

在项目环境中运行 Composer 命令（超时 10 分钟）。

• project_path：项目目录的路径
• command：Composer 命令（例如，"install"、"update"、"require symfony/console"）
• save_output_to_file：将完整输出保存到日志文件（可选，默认：false）

rolldev_magento2_init

使用自动配置初始化新的 Magento 2 项目（超时 15 分钟）。

• project_name：项目名称（仅限小写字母、数字和连字符）
• magento_version：Magento 版本（可选，默认值为 "2.4.x"）
• target_directory：目标目录（可选，默认值为当前目录）

Roll Inspector 工具（只读）

这些工具从 Roll Inspector（https://inspector.<TRAEFIK_DOMAIN>）读取信息，不会更改环境。每个工具都需要 project_path，并像 roll 一样读取 ROLL_ENV_NAME、TRAEFIK_DOMAIN 和 ROLL_INSPECTOR（依次读取 ${ROLL_HOME_DIR:-~/.roll}/.env.roll、其中的 .env，再读取最近的项目 .env.roll，每个文件的设置都会覆盖前一个文件中的设置），并支持与上述工具相同的 save_output_to_file 参数。输出为精简文本加一个 JSON 块。超过 60,000 个字符的内容会被截断，并提示使用 save_output_to_file。

工具	返回内容
rolldev_inspector_overview	服务运行状况、警告及可复制的修复方案
rolldev_inspector_traces	跟踪列表，包含按类别划分的成本。筛选条件：route、min_ms、sort、limit
rolldev_inspector_trace	对某个跟踪 id 的分析：按类别划分的成本、热点跨度、重复调用（N+1）及最慢调用。只有设置 include_spans 才返回原始跨度，最多返回 200 个（按自身耗时计算）
rolldev_inspector_hotspots	所有已存储跟踪中最慢的路由、成本最高的操作及重复调用。limit 设置每个部分返回的行数
rolldev_inspector_request	某个 url（或 xid）的时间线条目：Varnish 结果以及 PHP、缓存和搜索各部分的记录。limit 会返回更多匹配项，按时间从新到旧排序
rolldev_inspector_service	kind 为 varnish、redis、search 或 rabbitmq 时的 section health（默认）或 info

连接详情：

• 工具使用 node:https 连接，并信任 Roll 的根 CA：${ROLL_SSL_DIR}/rootca/certs/ca.cert.pem。与 bin/roll 一样，ROLL_SSL_DIR 默认为 ${ROLL_HOME_DIR}/ssl，ROLL_HOME_DIR 默认为 ~/.roll。在 MCP 服务的环境中设置任一变量即可覆盖默认值。
• 请求在 10 秒后超时。
• 如果未设置 ROLL_INSPECTOR 或其值为 0，工具会给出修复方法：在 .env.roll 中设置 ROLL_INSPECTOR=1，然后运行 roll env up。
• 如果 Inspector 容器已停止（roll env up）、证书存在问题（roll sign-certificate <domain>）、主机名无法解析，或 gate 返回 403，工具会用通俗易懂的文字报告问题。
• rolldev_inspector_trace 和 rolldev_inspector_hotspots 需要使用带有 analysis 和 hotspots 端点的 Inspector 镜像。旧版镜像会提示更新。

跟踪和热点查询要求项目的 .env.roll 中设置 ROLL_INSPECTOR=1 和 ROLL_INSPECTOR_TRACE=1。Varnish HIT 没有跟踪，因此 rolldev_inspector_request 对这类请求不会找到结果。用户文档：roll-docker-stack/docs/inspector/api-and-extensions.md。

逻辑位于 inspector.cjs 中，test/inspector.test.js 会通过模拟传输运行这些逻辑。

示例

设置好 RollDev MCP 服务后，可以尝试与 Claude 进行以下示例交互：

基本环境管理

1. “可以列出我的所有 RollDev 环境吗？”
2. “启动 /path/to/my-magento-project 中的项目”
3. “停止当前项目的服务”

数据库操作

4. “在我的项目中运行查询 'SELECT * FROM admin_user LIMIT 5'”
5. “显示数据库中所有已启用的模块”
6. “检查我的商店当前的配置值”

Magento 开发

7. “在我的项目中执行 Magento 命令 'cache:flush'”
8. “在我的 Magento 安装中运行 'setup:upgrade'”
9. “列出所有可用的 Magento CLI 命令”

项目初始化

10. “初始化一个名为 'my-store' 的新 Magento 2.4.7 项目”
11. “在 /Users/dev/projects 中使用最新版本创建一个 Magento 项目”

Composer 操作

12. “在我的项目中使用 Composer 安装依赖项”
13. “在我的项目中引入 symfony/console 软件包”

输出文件重定向

14. “运行 setup:upgrade 并将输出保存到文件中以供排查”
15. “执行 composer install 并将输出保存到日志文件”

Roll Inspector

这些提示词只会读取；不会有 Inspector 工具清除缓存、刷新缓存或切换任何内容。 16. “/category-1.html 为什么很慢？检查 Inspector 跟踪记录” 17. “显示此项目的 Inspector 热点” 18. “此项目中哪些路由会重复执行相同的 SQL 查询（N+1）？” 19. “RabbitMQ 状态正常吗？请 Inspector 提供概览” 20. “上一次对 /checkout/cart 的请求是否命中 Varnish MISS？原因是什么？”

开发

# Start in development mode with debugging
npm run dev

# Run tests
npm test

测试

你可以使用 MCP Inspector 测试服务：

npx @modelcontextprotocol/inspector node server.js

贡献

1. 从 dockergiant/rolldev-mcp-server Fork 此仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add some amazing feature'）
4. 将分支推送到远程仓库（git push origin feature/amazing-feature）
5. 创建 Pull Request

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。

支持

如果你遇到任何问题或有疑问：

1. 查看 GitHub Issues 部分
2. 查阅 modelcontextprotocol.io 上的 MCP 文档
3. 创建新的 issue，并提供详细的复现步骤

---

赞助方