mage-remote-run

关键词

MCP 服务JSON-RPC工具注册传输协议命令执行

使用说明（Markdown 格式）

  • 项目简介

    • 这是一个基于 MCP（Model Context Protocol）的后端服务器实现，目标是将 Mage Remote Run 的 CLI 命令注册为 MCP 工具，通过 JSON-RPC 的方式供 LLM 客户端调用。服务器端负责注册工具、管理会话与能力信息，并支持多种传输协议（stdio、HTTP/SSE），为后端上下文提供统一接口。

  • 主要功能点

    • 注册工具：自动遍历注册的 CLI 命令，将叶子命令注册为 MCP 工具，工具名称按命令路径转译为 underscore 风格，支持命令参数和选项的输入约束（通过 Zod 描述）。
    • 资源与工具访问：通过 MCP 客户端调用工具时，服务器在本地执行对应命令并将输出以 MCP 的响应格式返回给调用方。
    • 传输协议：支持标准输入输出（stdio）和基于 HTTP 的 SSE/进度传输，便于不同环境的集成。
    • 可运行的服务端：具备 startMcpServer() 入口，能够独立启动一个 MCP 服务器实例，并在启动时输出注册的工具数量等信息，便于运维与集成测试。
    • 与现有 CLI 的整合：服务器通过注册的工具执行本地 CLI 的命令，确保对 Magento 等后端系统的操作可被 LLM 客户端安全地调用。

  • 安装与运行

    • 依赖环境：Node.js（推荐版本与仓库的 package.json 保持一致）。
    • 安装步骤（简要）：获取代码后安装依赖（npm install），在支持的环境中执行服务器。
    • 启动 MCP 服务器示例（stdio）：node bin/mage-remote-run.js mcp --transport stdio
    • 启动 MCP 服务器示例（HTTP/SSE）：node bin/mage-remote-run.js mcp --transport http --host 127.0.0.1 --port 18098

  • 服务器配置（MCP 客户端所需配置，JSON 格式，描述性信息，非代码块展示）

    • serverName: mage-remote-run MCP 服务

    • command: node

    • args: ["bin/mage-remote-run.js", "mcp", "--transport", "stdio"] 注释：该配置用于指向服务器的启动命令及参数，客户端在建立连接时需要根据具体环境选择 stdio（本地进程管道）或 http 传输（需要 host、port）。配置信息仅用于 MCP 客户端的连接准备，不需要在运行时修改服务器行为。

    • 另一种常见配置（HTTP/SSE 传输）：

    • serverName: mage-remote-run MCP 服务

    • command: node

    • args: ["bin/mage-remote-run.js", "mcp", "--transport", "http", "--host", "127.0.0.1", "--port", "18098"] 注释：上述配置将通过 HTTP/SSE 传输，LLM 客户端需要通过该端点与 MCP 服务进行通信。

  • 基本使用方法

    • 启动服务器后，客户端通过 MCP JSON-RPC 向 Mage CLI 暴露的工具执行命令。
    • 客户端可请求获取可用工具、读取资源、调用工具、获取 Prompt 模板等，服务器将执行本地 CLI 命令并以统一格式返回结果。
    • 由于服务器会将 CLI 的输出作为工具执行结果返回，确保你的工作流和权限在本地 CLI 层面上是可控的。

  • 重要注意

    • 这是一个完整的服务器实现，包含工具注册、命令执行封装以及传输层支持，非单纯的客户端示例。
    • 在实际环境中，请确保对暴露的工具有严格的鉴权和访问控制，以避免对 Magento 后端的潜在误操作。

服务器信息

访问项目