PageFly 退款 MCP 服务器

用于 Crisp Hugo AI Agent 的 MCP (Model Context Protocol) 服务器，旨在端到端处理 PageFly 退款请求。

它提供了九个工具，分为三个层级：

查询（模拟数据）

• check_subscription → 获取商店或邮箱的当前套餐

• get_billing_history → 列出商店的所有账单/即将到来的扣款

纯逻辑

• classify_refund_case → 将上下文映射到 7 种剧本案例（TH1–TH7）之一

• calculate_refund → 计算 30 天按比例分配或多周期退款，并包含扣除额

• collect_refund_info → 决定下一个要询问的问题并识别阻碍因素

• generate_refund_message → 根据 PageFly 模板起草客户回复

状态（Turso / libSQL）

• get_case_state → 通过商店 URL 恢复案例

• save_case_state → 在每个关键步骤持久化进度

• list_pending_cases → 查看等待经理、客户或账单支付的案例

基于 @modelcontextprotocol Typescript SDK 构建。

环境

将 .env.example 复制为 .env 并填入你的 Turso 凭据：

TURSO_DATABASE_URL=libsql://<your-db>.turso.io
TURSO_AUTH_TOKEN=<token>
PORT=3000

迁移会在服务器启动时自动运行——可安全重新运行。

Related MCP server: Spaceship MCP

I. 安装与运行

要开始使用此 MCP 服务器，你可以选择在本地运行或使用托管版本。

使用托管版本

此 MCP 服务器已托管并准备好连接到你的 Crisp 工作区（如果你想快速测试）。 你可以通过以下地址访问：https://crisp-mcp-demo.fly.dev/mcp

本地运行

前置要求：

• 已安装 Node.js 24.x

• 键盘（可选，但建议使用）

第 1 步 — 克隆仓库

在所需文件夹中打开终端并运行：

git clone https://github.com/NTHieu002/refund-crisp-mcp.git
cd refund-crisp-mcp

第 2 步 — 运行服务器

你可以构建并启动服务器，或者直接在开发模式下运行。

要构建并运行服务器，请使用：

npm ci
npm run build
npm run start

或者使用 tsx 在开发模式（监视模式）下运行：

npm ci
npm run dev

第 3 步 — 暴露服务器（如果本地运行）

如果你希望在本地运行服务器，则需要通过隧道将其暴露出来，以便 Crisp 可以访问它。 此包已预配置为使用 Cloudflared，不过你可以使用任何你喜欢的隧道解决方案。

如果你的机器上尚未安装 Cloudflared，请点击此链接查找适用于你操作系统的安装说明：

安装完成后，打开一个新终端并运行：

npm run tunnel

你可以访问隧道的 URL 以确认其是否正常工作。你应该会看到一条问候消息。

可用脚本

• npm run dev → 开发服务器（监视）

• npm run build → 编译 TypeScript

• npm run start → 运行已编译的服务器

• npm run tunnel → 通过 Cloudflare Tunnel 暴露 localhost

• npm run inspect → 运行 @modelcontextprotocol 检查器

II. 连接到 Crisp

本节是将此 MCP 服务器连接到你的 Crisp 工作区的快速入门指南。 我们建议同时查看我们的官方文档以获取更详细的说明。

前置要求：

• 一个 Crisp 账户

• 一个 Essentials 或 Plus 套餐的 Crisp 工作区

第 1 步 — 导航至 app.crisp.chat

第 2 步 — 在 AI Agent 菜单中，前往 AI Agent → Automate → Integrations & MCP → External MCP servers，然后点击 Add MCP server 区域。

第 3 步 — 输入你的 MCP 服务器 URL（托管/隧道 URL 或我们的托管版本），然后点击 Add MCP Server。

第 4 步 — 配置 MCP 服务器：

1. 命名它

2. 如果工具没有自动获取，点击 Refresh tools from server

3. 启用 MCP 服务器

4. 点击 Save changes 按钮

第 5 步 — 你的 MCP 服务器现在应该已注册并可以使用了！

III. 测试 MCP 服务器

仍在 Automations 菜单中，你可以前往 Playground 测试你的 MCP 服务器和不同的 AI 模型。问它一个问题！

Playground 示例

一次性问题：

你能检查一下我的订单 OID_002 的退款是否已处理吗？

你好，我的账户 baptiste@acme.com 是否启用了通知？

AI 可以串联多个工具调用（例如：查找账户、列出最近订单并获取产品详情）：

我的订单 OID_001 中的商品还在保修期内吗？

我最近的订单什么时候送达？我是 chris@acme.com

也可以尝试部分问题，让 AI 向你请求额外信息：

我上一笔订单的金额是多少？

我找不到我的追踪号码，你能帮我吗？

可用账户与订单

• chris@acme.com

  • OID_003

  • OID_006

• baptiste@acme.com

  • OID_001

  • OID_004

• dinis@acme.com

  • OID_002

  • OID_005

  • OID_007

MCP 最佳实践

MCP 设计

• 服务器描述： 描述 MCP 服务器的通用目的

• 工具命名： 使用清晰且明确的名称（例如 get_order，而不是 orderLookup）

• 工具描述： 简洁地描述工具的功能、何时调用它，并可选择提供用例示例

• 模式： 为工具输入提供精确的模式，以确保正确使用

用户验证

在 MCP 服务器配置中，你还可以选择要求用户在 AI 调用 MCP 工具之前进行身份验证。这加强了对敏感操作的安全性。

如果用户尚未通过身份验证，Crisp 将通过电子邮件或短信向他们发送 OTP 代码，然后才允许 AI 调用你的 MCP 工具。

为此，只需导航到你的 MCP 服务器并点击 Manage。 在每个工具上，你可以切换 Require user identification verification 选项。

服务器身份验证

在生产环境中，你可能希望限制对 MCP 服务器的访问并防止未经授权的使用。 有两种身份验证方法可用：

• Bearer Token： 在每个请求的 Authorization 标头中发送的静态令牌

• Basic Auth： 在每个请求的 Authorization 标头中发送的用户名和密码