MCP 客户端使用指南（标准版）

本指南教你如何在任意支持 MCP（Model Context Protocol）的客户端中使用已发布的工具服务端包：coupon-mcp-server@0.1.0。

前置条件

• Node.js 18.17+
• 网络访问：你的后端 API 域名，例如 https://mcpcounpon.onrender.com
• 已发布的 MCP 服务器包：coupon-mcp-server（已发布）

一、在客户端中注册 MCP 服务器

• 将以下 JSON 配置加到你的 MCP 客户端的配置里（客户端支持 stdio 的 MCP 设置处）。
• 推荐直接使用 npx 包名启动：

{
  "mcpServers": {
    "coupon": {
      "command": "npx",
      "args": ["-y", "coupon-mcp-server"],
      "env": {
        "BASE_URL": "https://mcpcounpon.onrender.com"
      }
    }
  }
}

说明：

• command 使用 npx，会自动拉取并执行 coupon-mcp-server 包。
• env.BASE_URL 是你的后端 API 基地址，不要带末尾 /。

保存配置后，在客户端里执行“重载配置/重启 MCP”。

二、可用工具与契约

注册成功后，你将看到以下工具名：

• http.request
  • 用途：通用 HTTP 转发
  • 入参：
    • method 严格为 GET|POST|PUT|PATCH|DELETE
    • path 以 / 开头的路径，如 /coupons
    • query 可选，任意键值对象
    • headers 可选，任意键值对象
    • body 可选，任意 JSON/字符串/数组/数值/布尔/空
• coupon.create
  • 用途：POST /coupons
  • 入参：{ "body": { ... } }
• coupon.get
  • 用途：GET /coupons/{id}
  • 入参：{ "id": "字符串" }
• coupon.list
  • 用途：GET /coupons
  • 入参：{ "query"?: { ... } }
• jutuike.public_promo_list
  • 用途：GET /api/mcp/jutuike/public_promo_list
  • 入参：{ "query"?: { ... } }

所有请求都会拼接到 BASE_URL 后发送，无鉴权、无数据库，仅代理转发并原样返回响应。

三、调用示例

• 调用专用工具 jutuike.public_promo_list：

{
  "query": {
    "page": 1,
    "size": 20
  }
}

• 使用通用工具 http.request 访问相同接口：

{
  "method": "GET",
  "path": "/api/mcp/jutuike/public_promo_list",
  "query": {
    "page": 1,
    "size": 20
  }
}

• 创建优惠券（示例）：

{
  "body": {
    "title": "New Year Coupon",
    "discount": 10
  }
}

四、常见问题与排查

• 看不到新工具
  • 重启或刷新 MCP 客户端，以重新加载工具列表。
• BASE_URL 显示为 http://localhost:3000
  • 说明当前进程未带入环境变量。请确保客户端配置中的 env.BASE_URL 已设置并由客户端接入生效。
  • 或在命令行临时设置环境变量再执行：
    • PowerShell：

      $env:BASE_URL="https://mcpcounpon.onrender.com"; npx -y coupon-mcp-server
      

• npx 本地执行失败
  • npx 运行本地文件（如 npx -y .\server.js）在 Windows 上会被解析为包名，可能失败。请使用包名 coupon-mcp-server，或直接 node path\to\server.js。
• 网络请求报错
  • 使用 http.request 打印返回的 Status <code> 与文本，排查后端接口路径、方法、参数是否正确。
  • 确认后端允许跨域（如果客户端环境需要）以及无需鉴权。