VoDmAl Composer Scripts MCP Server

VoDmAl Composer Scripts MCP Server

一个 PHP 库，可将项目的 Composer 脚本作为 MCP（Model Context Protocol）工具提供。安装后，AI 助手（或任何 MCP 客户端）即可自动发现并执行 Composer 脚本，无需每次都解释命令。

本库适用于任何 PHP 项目，并且可以连接任意数量的项目。每个项目的 MCP 工具名称都会根据其 composer.json 自动生成（例如 "name" 字段）。

为什么使用 Composer 脚本？

Composer 脚本让你无需添加额外依赖，即可规范并自动执行常见任务（测试、代码检查、代码生成等）。主要优势包括：

• 零额外依赖：运行 composer install 后即可使用脚本。
• 统一的接口：无论操作系统或本地配置如何，所有团队成员都使用相同的命令。
• 工作流自带说明：你的 composer.json 也可以作为可用命令的文档。
• 跨平台：脚本在 macOS、Linux 和 Windows 上都能一致运行。

这种方式虽然有很多优势，但也存在一些局限：

• 你需要记住每个项目的具体脚本名称
• 与独立工具相比，复杂的脚本链可能更难调试
• 性能可能略低于原生二进制程序

尽管存在这些小缺点，运行 composer install 后无需额外的外部依赖即可立即使用命令，这一便利性仍是显著优势。这正是本工具的用武之地——它让 AI 助手能够发现并执行 Composer 脚本，而你无需每次都解释命令。

实际示例

下面是一个示例，展示了 Composer 脚本在真实项目中的强大之处：

"scripts": {
    "check:before:commit": [
        "@test",
        "@check:code:style",
        "@check:code:static",
        "@check:code:dependency"
    ],
    "check:before:push": [
        "@check:config",
        "@check:before:commit",
        "@check:code:security"
    ],
    "check:code:static": [
        "@check:code:lint",
        "@rector",
        "@psalm",
        "@phpstan",
        "@classleak",
        "@check:code:comments"
    ],
    "test": [
        "@test:unit:phpunit"
    ],
    "test:unit:phpunit": [
        "@phpunit --testsuite Unit"
    ],
    "phpunit": "./vendor/bin/phpunit"
}

借助这些脚本，开发者可以在提交或推送代码前，通过 composer check:before:commit 这样的简单命令运行全面检查。MCP 服务会将这些脚本提供给 AI 助手，使其能够理解并执行合适的命令，无需你每次都解释项目的具体测试或验证流程。

这种方式最大的优势之一，是你不必反复向每个大模型解释如何运行测试、检查代码风格或执行其他常见开发任务。大模型可以通过 MCP 服务发现可用命令，并为当前任务推荐合适的命令。这样可以节省时间，减少在 PHP 项目中使用 AI 助手时的阻碍。

功能

安装 VoDmAl Composer Scripts MCP Server 后，你将获得两大优势：

1. 自动发现项目中的所有 Composer 脚本，并将其作为 MCP 工具。
2. 一步集成 AI 助手（例如 Claude Desktop），让它们无需手动配置即可列出并运行任何脚本。

• 自动从 composer.json 读取 Composer 脚本
• 将脚本公开为可发现和执行的 MCP 工具
• 支持 stdio 和 HTTP 传输方式
• 轻松集成到任何 PHP 项目
• 安装时自动将脚本添加到项目的 composer.json

要求

• PHP 8.1 或更高版本
• Composer
• php-mcp/server ^2.1

简单安装与自动设置

要开始使用，请运行：

composer require vodmal/composer-scripts-mcp-server
composer install

Composer 完成后，项目的 composer.json 中会新增两个脚本：

"scripts": {
    "mcp:server:start": "vendor/bin/mcp-server-start",
    "mcp:server:install": "vendor/bin/mcp-server-install"
}

现在所需的一切都已就绪。你无需立即运行 composer mcp:server:start。相反，如果你想与 Claude Desktop（或任何兼容 MCP 的大模型）集成，请运行：

composer mcp:server:install

如果已安装 Claude Desktop，且检测到了其配置文件，此命令会自动合并 MCP 配置。

如果找不到 Claude 的配置文件，它会输出一段 JSON 代码片段。将其粘贴到 claude_config.json 的 "tools" 下，然后重启 Claude。

连接任意数量的项目 你可以在每个 PHP 项目文件夹中运行 composer mcp:server:install，数量不限。每个项目的工具名称都取自其自身 composer.json 中的 "name" 字段，因此多个项目会在 Claude 的工具列表中分别显示。

如果你不使用 Claude 运行：

composer mcp:server:install

会输出一个 JSON 代码块，准确显示如何启动 MCP 服务。将其复制到所需的大模型或 MCP 客户端配置中。完成配置后，你的 AI 助手便可调用 composer_list 和 composer_run MCP 方法，无需其他设置。

高级手动配置与启动

使用 stdio 传输

要通过 stdio 传输启动服务（以便与 AI 助手集成）：

vendor/bin/mcp-server-start

使用 HTTP 传输

要通过 HTTP 传输启动服务（以便使用客户端进行测试）：

vendor/bin/mcp-server-start --http [--host=<host>] [--port=<port>]

默认情况下，服务会监听 127.0.0.1:8088。

与 Claude Desktop 集成

若要将此 MCP 服务与 Claude Desktop 集成，可以使用提供的 mcp-server-install 命令：

vendor/bin/mcp-server-install

此命令会自动检测你的操作系统，并查找 Claude Desktop 配置文件。如果找到，它会更新该文件以加入 MCP 服务配置。如果未找到，它会输出需要手动合并到 Claude Desktop 配置文件中的配置。该服务会自动将项目中的所有 Composer 脚本公开为 MCP 工具。

命令选项

• --output=<file>：指定自定义输出文件（默认情况下，命令会尝试查找适用于你的操作系统的 Claude Desktop 配置文件）
• --name=<name>：指定服务名称（默认值：composer.json 中的项目名称）

多个服务

如果你安装了此库的多个 PHP 项目，可以将它们都添加到同一个配置文件中：

# In project1
vendor/bin/mcp-server-install --name=project1

# In project2
vendor/bin/mcp-server-install --name=project2 --output=/path/to/claude_desktop_config.json

使用配置

1. 完全重启 Claude Desktop
2. 重启后，你应该会在输入框左下角看到一个滑块图标
3. 点击滑块图标，查看可用工具（你的 Composer 脚本）
4. 现在，你可以让 Claude 运行任意 Composer 脚本

故障排除

如果 Claude Desktop 未检测到该服务：

1. 确保 Claude Desktop 已更新到最新版本
2. 检查配置文件语法是否正确
3. 确认配置中的文件路径有效且为绝对路径（而非相对路径）
4. 查看日志，了解服务无法连接的原因：
   • macOS：~/Library/Logs/Claude
   • Windows：%APPDATA%\Claude\logs
5. 尝试手动运行服务，看看是否出现错误：

   vendor/bin/mcp-server-start
   

**注意：**在使用 stdio 传输与大模型应用交互时，所有日志消息都会写入 stderr，而不是 stdout。这样可以避免日志消息干扰服务与大模型应用之间的 JSON 通信，否则可能导致 JSON 解析错误。

可用的 MCP 工具

该库提供以下 MCP 工具：

composer_list

列出所有可用的 Composer 脚本。

**参数：**无

返回值：

• scripts：脚本信息数组（名称和命令）
• count：可用脚本的数量

composer_run

运行 Composer 脚本。

参数：

• script（字符串，必填）：要运行的脚本名称
• arguments（数组，可选）：传递给脚本的其他参数

返回：

• script：已运行的脚本名称
• command：已执行的命令
• output：命令的输出
• return_code：命令的返回代码
• success：命令是否成功（返回代码为 0）

许可证

本项目采用双重许可：

开源许可证

本项目根据 GNU 通用公共许可证 v3.0（GPL-3.0）授权，可用于开源用途。详情请参阅 LICENSE-GPL 文件。

商业许可证

如需在专有软件中进行商业用途，可另行获取商业许可证。有关商业许可条款，请联系 [ваш email]。

许可证摘要

• GPL-3.0：免费适用于同样采用 GPL-3.0 许可的开源项目
• 商业许可证：适用于不受 GPL 限制的专有／商业用途，需付费

如果不确定哪种许可证适用于你的使用场景，请联系我们。