@manabuy/mcp-server

v0.1.2

Published

23 days ago

ManaBuy MCP server for product search, order quote, and AI-assisted ordering.

0High
0Medium
0Low

wangzichu

mcp model-context-protocol manabuy ai-agent shopping orders

ManaBuy MCP Server

ManaBuy MCP Server 是一个 Model Context Protocol (MCP) 网关，供 AI 客户端搜索 ManaBuy 商品、查看商品详情、订单报价、创建已确认订单，以及查询订单状态。

该服务不会重新实现 ManaBuy 业务逻辑。它只把 MCP 工具调用转换为现有 ManaBuy API 请求，并把结构化 JSON 响应返回给 AI 客户端。

功能

搜索 ManaBuy 商品和游戏。
获取商品详情、SKU 列表、下单字段和充值说明。
在支付前进行订单报价。
在用户明确确认后创建订单。
查询订单状态和订单详情。
通过浏览器登录，或通过环境变量配置 API 环境、货币、语言、渠道和用户 token。

可用工具

| 工具 | 用途 | | --- | --- | | login_manabuy | 启动 ManaBuy 浏览器登录并返回登录链接。 | | logout_manabuy | 删除本地保存的 ManaBuy token。 | | get_login_status | 查看当前 MCP 是否已经登录。 | | search_products | 按关键词、商品编码、分类或游戏 hub URL 名称搜索商品或游戏。 | | get_product_detail | 获取商品详情、SKU、必填下单字段和充值说明。 | | quote_order | 创建订单前预览最终价格、折扣、优惠券和应付金额。 | | create_order | 创建 ManaBuy 订单并返回支付信息。这是高风险操作。 | | get_order_status | 根据订单号获取当前订单状态。 | | get_order_detail | 根据订单号获取订单详情。 |

安全说明

create_order 可以创建真实的 ManaBuy 订单。AI 客户端必须在用户明确确认商品、SKU、数量、账号字段、价格、货币和支付方式后，才能调用该工具。

生产环境建议使用更安全的流程：

create_order_draft
向用户展示完整订单摘要。
confirm_order({ draftOrderId, confirmationToken })

要求

Node.js >=20.10.0
npm
通过 login_manabuy 浏览器登录，或提供用于认证订单操作的有效 ManaBuy 用户 token

安装

npm install

配置

cp .env.example .env

MANABUY_API_BASE_URL=https://manabuy.com/api
MANABUY_ENVIRONMENT=yz
MANABUY_CURRENCY=USD
MANABUY_LANG=en
MANABUY_BIZ_CHANNEL=THIS
MANABUY_AUTH_TOKEN=your_user_login_token

开发

npm run dev

如果要启动远程 Streamable HTTP MCP 入口：

npm run dev:http

构建和运行

npm run build
npm start

构建后启动 HTTP MCP：

npm run start:http

默认监听 0.0.0.0:3000，并暴露：

| 路径 | 用途 | | --- | --- | | /mcp | Streamable HTTP MCP endpoint。 | | /health | 健康检查。 | | / | 面向开发者的落地页，包含 agent 配置命令。使用 Accept: application/json 可获取 JSON 服务描述。 |

HTTP 服务可通过这些环境变量配置：

| 变量 | 默认值 | 说明 | | --- | --- | --- | | PORT | 3000 | HTTP 端口。 | | HOST | 0.0.0.0 | HTTP 监听地址。 | | MCP_PATH | /mcp | MCP endpoint 路径。 | | CORS_ORIGIN | * | 允许的浏览器来源。 |

本地登录工具

服务提供 3 个认证工具，适合本地 stdio MCP 场景：

| 工具 | 用途 | | --- | --- | | login_manabuy | 启动 ManaBuy 浏览器登录并返回登录链接。 | | logout_manabuy | 删除本地保存的 ManaBuy token。 | | get_login_status | 查看当前 MCP 是否已经登录。 |

login_manabuy 默认复用 Web 登录页。Hosted HTTP MCP 场景下，它会立即返回登录链接，并尝试让运行环境打开浏览器。如果 Codex 没有自动打开浏览器，用户可以手动打开返回的 loginUrl。

https://manabuy.com/mcp-auth?redirect_uri=https://agents.manabuy.com/auth/callback&state=xxx

Web 端用户登录成功后，把现有 cookie 中的 ManaBuy token 通过 POST 回 MCP callback：

{
  "state": "xxx",
  "token": "user-login-token",
  "user": {
    "userId": 123,
    "email": "[email protected]"
  }
}

MCP 会保存 token，之后请求 ManaBuy API 时按现有 Web 约定直接放进 Authorization 请求头。本地 stdio MCP 仍可通过 waitForCallback: true 使用 127.0.0.1 callback 等待登录完成。

Claude Desktop 配置

{
  "mcpServers": {
    "manabuy": {
      "command": "node",
      "args": ["/absolute/path/to/ManaBuy-mcp/dist/index.js"],
      "env": {
        "MANABUY_API_BASE_URL": "https://manabuy.com/api",
        "MANABUY_ENVIRONMENT": "yz",
        "MANABUY_CURRENCY": "USD",
        "MANABUY_LANG": "en",
        "MANABUY_BIZ_CHANNEL": "THIS",
        "MANABUY_AUTH_BASE_URL": "https://manabuy.com"
      }
    }
  }
}

远程 MCP 配置

如果你想做到 Morpho 那种“用户不需要从 GitHub 或 npm 下载 MCP”，就把 HTTP 入口部署到公网，然后让客户端连接你的公开 URL。

Codex：

codex mcp add manabuy --url https://your-domain.example/mcp

或写入 codex.toml：

[mcp_servers.manabuy]
url = "https://your-domain.example/mcp"

Cursor：

{
  "mcpServers": {
    "manabuy": {
      "url": "https://your-domain.example/mcp"
    }
  }
}

Claude Code：

claude mcp add manabuy --transport http https://your-domain.example/mcp

这种模式下，用户本地只保存 MCP URL。真正的工具代码、依赖和 ManaBuy API 调用都运行在你部署的服务器上。

不要在公开服务上配置共享的 MANABUY_AUTH_TOKEN。生产环境创建订单时，建议改成用户级 OAuth、短期 token broker，或者后端 draft/confirm 流程，确保每个用户只授权自己的订单。

GitHub Actions 自动部署

仓库包含 .github/workflows/deploy.yml。当代码 push 到 main 分支时，GitHub 会自动：

安装依赖。
执行类型检查。
构建 dist/。
通过 SSH 上传到服务器目录 /app/manaBuy-cmp。
在服务器执行 npm ci --omit=dev。
用 PM2 启动或重启 node dist/http.js。

先在服务器执行一次基础准备：

sudo mkdir -p /app/manaBuy-cmp
sudo chown -R ubuntu:ubuntu /app/manaBuy-cmp
sudo npm install -g pm2

如果服务器还没有 Node.js 20，先安装 Node.js 20。可以用 nvm、NodeSource 或你现有的服务器管理方式安装。

然后在 GitHub 仓库里进入 Settings -> Secrets and variables -> Actions，添加这些 Repository secrets：

| Secret | 示例 | 说明 | | --- | --- | --- | | SSH_HOST | 43.130.68.70 | 服务器 IP 或域名。 | | SSH_USER | ubuntu | SSH 用户；不填 workflow 默认使用 ubuntu。 | | SSH_PORT | 22 | SSH 端口；不填 workflow 默认使用 22。 | | SSH_PRIVATE_KEY | 私钥内容 | 可登录服务器的 SSH 私钥。 | | MANABUY_ENV_FILE | .env 内容 | 可选。部署时写入服务器 /app/manaBuy-cmp/.env。 |

MANABUY_ENV_FILE 示例：

MANABUY_API_BASE_URL=https://manabuy.com/api
MANABUY_ENVIRONMENT=yz
MANABUY_CURRENCY=USD
MANABUY_LANG=en
MANABUY_BIZ_CHANNEL=THIS
MANABUY_AUTH_TOKEN=

部署成功后，GitHub Actions 默认让 MCP 服务监听服务器本机 3100 端口：

http://43.130.68.70:3100/mcp

生产环境建议在 Nginx 里把域名 HTTPS 反代到 127.0.0.1:3100，然后让用户连接：

codex mcp add manabuy --url https://your-domain.example/mcp

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme