FlexPrice MCP Server 使用说明

项目简介

FlexPrice MCP Server 是一个基于 Model Context Protocol (MCP) 构建的应用后端，旨在为 AI Agent 提供访问 FlexPrice 平台发票、客户等数据的能力。通过标准化的 MCP 协议，AI Agent 可以安全、高效地与 FlexPrice 数据进行交互，从而实现更智能的应用场景，例如：

帮助用户理解和分析 FlexPrice 账单数据
为客户提供个性化的订阅和计费信息
基于 FlexPrice 数据构建智能客服或销售助手

主要功能点

资源 (Resources) 管理: 提供 FlexPrice API 文档等资源，帮助 AI Agent 理解可用的数据接口。
工具 (Tools) 注册与执行: 注册了丰富的工具，允许 AI Agent 查询和操作 FlexPrice 的核心数据，例如：
- 获取客户信息 (Customers)
- 获取订阅信息 (Subscriptions)
- 获取发票信息 (Invoices)
- 获取支付信息 (Payments)
- 获取钱包信息 (Wallets)
- 获取事件信息 (Events)
- 获取计划信息 (Plans)
- 获取价格信息 (Prices)
Prompt 模板 (Prompts) 定义与渲染: 预置了 Prompt 模板，支持 AI Agent 基于 FlexPrice 数据生成定制化的内容，例如：
- 解释发票费用 (Explain Charges)
- 分析账单趋势 (Billing Trends)
- 总结订阅信息 (Subscription Summary)

安装步骤

本地安装 (Option 1: Local Setup)

克隆仓库:

git clone <仓库URL>
cd mcp-server

安装依赖:
```
npm install
```
配置环境变量: 在项目根目录下创建 '.env' 文件，并填入您的 FlexPrice API 密钥和 API Base URL：
```
API_KEY=your_api_key_here
BASE_URL=https://api.cloud.flexprice.io
```
请替换 'your_api_key_here' 为您实际的 FlexPrice API 密钥。'BASE_URL' 默认为 'https://api.cloud.flexprice.io'，通常无需修改。
构建项目:
```
npm run build
```
启动服务器:
```
npm start
```
或者使用开发模式启动，支持代码热重载：
```
npm run dev
```

Docker 安装 (Option 2: Docker Setup)

克隆仓库:

git clone <仓库URL>
cd mcp-server

构建 Docker 镜像:

docker build -t flexprice-mcp .

运行 Docker 容器:

docker run -i -e API_KEY=your_api_key_here -e BASE_URL=https://api.cloud.flexprice.io flexprice-mcp

请替换 'your_api_key_here' 为您实际的 FlexPrice API 密钥。'BASE_URL' 默认为 'https://api.cloud.flexprice.io'，通常无需修改。

服务器配置 (MCP 客户端配置)

要将 FlexPrice MCP Server 连接到 MCP 客户端（例如 Claude Desktop），您需要在客户端的配置文件中添加 MCP 服务器的配置信息。以下是针对 Node.js 本地启动和 Docker 两种方式的配置示例，请根据您的实际部署方式选择其一添加到客户端的配置文件（例如 'claude_desktop_config.json'）中。

Node.js 本地启动配置:

{
  "mcpServers": {
    "flexprice": {  // 服务器名称，可以自定义
      "command": "node",  // 启动命令，使用 Node.js 运行时
      "args": ["/absolute/path/to/cloned/mcp-server/dist/server.js"], // 启动参数，指向编译后的 server.js 文件绝对路径，请替换为您的实际路径
      "env": {  // 环境变量
        "API_KEY": "your_api_key_here",  // FlexPrice API 密钥，请替换为您的实际密钥
        "BASE_URL": "https://api.cloud.flexprice.io" // FlexPrice API Base URL，通常无需修改
      }
    }
  }
}

请注意: '/absolute/path/to/cloned/mcp-server/dist/server.js' 需要替换为您克隆的 'mcp-server' 仓库中 'dist/server.js' 文件的绝对路径。

Docker 启动配置:

{
  "mcpServers": {
    "flexprice": {  // 服务器名称，可以自定义
      "command": "docker",  // 启动命令，使用 Docker 运行时
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "API_KEY",
        "-e",
        "BASE_URL",
        "flexprice-mcp" // Docker 镜像名称
      ],
      "env": {  // 环境变量
        "API_KEY": "your_api_key_here",  // FlexPrice API 密钥，请替换为您的实际密钥
        "BASE_URL": "https://api.cloud.flexprice.io" // FlexPrice API Base URL，通常无需修改
      }
    }
  }
}

请注意: 'flexprice-mcp' 为 Docker 镜像名称，与 Docker 构建命令 'docker build -t flexprice-mcp .' 中的 '-t' 参数保持一致。 'API_KEY' 和 'BASE_URL' 环境变量将传递给 Docker 容器。

基本使用方法

确保 FlexPrice MCP Server 成功启动并运行。
配置 MCP 客户端（例如 Claude Desktop），添加上述相应的服务器配置信息。
在 MCP 客户端中，您应该能够看到 'flexprice' 服务器及其提供的 工具 (Tools) 和 Prompt 模板 (Prompts)。
您可以使用这些工具和 Prompt 模板，结合自然语言指令，让 AI Agent 访问和利用 FlexPrice 数据完成各种任务，例如：
- 询问客户的订阅状态
- 查询指定发票的详细信息
- 分析客户的账单趋势
- 等等

详细工具列表和 Prompt 模板描述请参考仓库的 README.md 文件。

关键词