# @flexprice/mcp-server 中文文档

规范地址：https://npmcn.com/package/%40flexprice/mcp-server/

版本：2\.1\.48
npm 元数据更新时间：2026-11-05T14:58:55.181Z
中文译文更新时间：2026-11-14T22:42:07.423Z
软件包许可：未声明

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40flexprice/mcp-server
原文对照：https://npmcn.com/package/%40flexprice/mcp-server/?lang=original

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：12.2 MB，3559 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：4 个
- 首次发布：2026-02-17T09:23:07.710Z
- 最新版本发布：2026-11-05T14:58:54.994Z
- 近 30 天下载量：3125（2026-10-15 至 2026-11-13，npm 官方下载统计）
- 已发布版本数：56（近 12 个月 56 个）

## 中文简介

一个模式上下文协议(MCP)服务器,将弹性价格API暴露为AI助手(如克洛德,Cursor,VS代码,Windsurf)的工具. 使用它来管理客户,计划,价格,订阅,发票,支付,事件,以及更多来自您的IDE或CLI.

## 安装

```sh
npm install @flexprice/mcp-server
```

也可以使用：`pnpm add @flexprice/mcp-server`、`yarn add @flexprice/mcp-server`、`bun add @flexprice/mcp-server`

## README

# 弹性价格 MCP 服务器

一个模式上下文协议(MCP)服务器,将弹性价格API暴露为AI助手(如克洛德,Cursor,VS代码,Windsurf)的工具. 使用它来管理客户,计划,价格,订阅,发票,支付,事件,以及更多来自您的IDE或CLI.

## 目录

-   [先决条件](https://npmcn.com/package/%40flexprice/mcp-server/#readme-prerequisites)
-   [如何使用弹性价格 MCP 服务器](https://npmcn.com/package/%40flexprice/mcp-server/#readme-how-to-use-the-flexprice-mcp-server)
-   [添加到您的 MCP 客户端](https://npmcn.com/package/%40flexprice/mcp-server/#readme-add-to-your-mcp-client)
-   [工具](https://npmcn.com/package/%40flexprice/mcp-server/#readme-tools)
-   [逐步发现(动态模式)](https://npmcn.com/package/%40flexprice/mcp-server/#readme-progressive-discovery-dynamic-mode)
-   [范围](https://npmcn.com/package/%40flexprice/mcp-server/#readme-scopes)
-   [解决问题](https://npmcn.com/package/%40flexprice/mcp-server/#readme-troubleshooting)
-   [生成 MCP 服务器](https://npmcn.com/package/%40flexprice/mcp-server/#readme-generating-the-mcp-server)

## 先决条件

-   **节点.js** v20 级或以上
-   **无** 或者说 **线条**
-   **弹性价格 API 密钥** 从你的 [弹性价格账户](https://app.flexprice.io/)

## 如何使用弹性价格 MCP 服务器

您可以以两种方式运行服务器 : **npm 软件包** (一个命令)或 **本地还原** (循环和运行)。 那就选一个 [添加到您的 MCP 客户端](https://npmcn.com/package/%40flexprice/mcp-server/#readme-add-to-your-mcp-client)。 。 。 .

* * *

### 备选案文1:npm包

安装 : `npm i @flexprice/mcp-server`。或用一个命令运行(没有克隆或构建):

```bash
npx @flexprice/mcp-server start --server-url https://us.api.flexprice.io/v1 --api-key-auth YOUR_API_KEY
```

替换 `YOUR_API_KEY` 与您的弹性价格 API 键。 下一个 : [添加到您的 MCP 客户端](https://npmcn.com/package/%40flexprice/mcp-server/#readme-add-to-your-mcp-client)。 。 。 .

* * *

### 备选案文2:当地回购

如果您想要更改代码或不使用 npm 运行, 请使用此选项 :

1.  克隆寄存器并去MCP服务器目录(例如. `api/mcp` 或包含它的还款.
2.  安装依赖性 : `npm install`
3.  创建一个 `.env` 文件(从 `.env.example` (如果有的话)
    -   `BASE_URL=https://us.api.flexprice.io/v1` (必须包括 `/v1`. . 没有后行的空间,也没有后行的斜线
    -   `API_KEY_APIKEYAUTH=your_api_key_here`
4.  构建 : `npm run build`
5.  开始 : `npm start`

**多克( stdio) :** 您也可以使用 stdio 来构建和运行 :

```bash
docker build -t flexprice-mcp .
docker run -i -e API_KEY_APIKEYAUTH=your_api_key_here -e BASE_URL=https://us.api.flexprice.io/v1 flexprice-mcp node bin/mcp-server.js start
```

下一个 : [添加到您的 MCP 客户端](https://npmcn.com/package/%40flexprice/mcp-server/#readme-add-to-your-mcp-client) 并使用 **Repo 的节点** 或者说 **夹克** 下面的配置 .

## 添加到您的 MCP 客户端

在您的编辑器中添加弹性价格 MCP 服务器 。 替换 `YOUR_API_KEY` 在所有示例中使用您的弹性价格 API 键。 示例配置片段在 [实例/](https://npmcn.com/package/%40flexprice/mcp-server/examples/)。 。 。 .

**连接后 :** 在 Cursor 中,打开 MCP 面板,确认服务器已连接. 您可以从助手处列出工具并尝试操作(如列表客户). 在克洛德语中,使用 `/mcp` 以查看连接的服务器和可用的工具.

### 配置文件位置

| 东道主 | 配置位置 |
| --- | --- |
| **光标** | Cursor → 设置 → MCP (或 Cmd+Shift+P) → “ 设置 ” → MCP |
| **VS 代码** | 调色板命令 **MCP: 打开用户配置** (开口) `mcp.json`(中文(简体) ) |
| **克劳德桌面( MacOS)** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Claude 桌面 (窗口)** | `%APPDATA%\Claude\claude_desktop_config.json` |

* * *

### 光标

1.  打开 **光标 设置 光标设置** 进入 **MCP 磁共振** 选项卡.
2.  添加新的 MCP 服务器并使用此配置( 选项 1 - npx) :

```json
{
  "mcpServers": {
    "flexprice": {
      "command": "npx",
      "args": [
        "-y",
        "@flexprice/mcp-server",
        "start",
        "--server-url",
        "https://us.api.flexprice.io/v1",
        "--api-key-auth",
        "YOUR_API_KEY"
      ]
    }
  }
}
```

* * *

### VS 代码

1.  打开命令调色板( O)**缩写+ 移动+P** 编号 : **Cmd+Shift+P 软件**运行 **MCP: 打开用户配置** 或者说 **MCP: 添加服务器**。 。 。 .
2.  添加:

```json
{
  "servers": {
    "flexprice": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@flexprice/mcp-server",
        "start",
        "--server-url",
        "https://us.api.flexprice.io/v1",
        "--api-key-auth",
        "YOUR_API_KEY"
      ]
    }
  }
}
```

* * *

### 克劳德代码

```bash
claude mcp add flexprice -- npx -y @flexprice/mcp-server start --server-url https://us.api.flexprice.io/v1 --api-key-auth YOUR_API_KEY
```

然后运行 `claude` 和使用情况 `/mcp` 以确认服务器已连接.

* * *

### 克劳德桌面

添加到您的 Claude 桌面配置文件( 上表路径) :

```json
{
  "mcpServers": {
    "flexprice": {
      "command": "npx",
      "args": [
        "-y",
        "@flexprice/mcp-server",
        "start",
        "--server-url",
        "https://us.api.flexprice.io/v1",
        "--api-key-auth",
        "YOUR_API_KEY"
      ]
    }
  }
}
```

退出并重新打开克洛德桌面.

* * *

### 替代配置

**Repo 的节点** (备选2——从被克隆的回放中运行):

```json
{
  "mcpServers": {
    "flexprice": {
      "command": "node",
      "args": ["/path/to/mcp-server/bin/mcp-server.js", "start"],
      "env": {
        "API_KEY_APIKEYAUTH": "your_api_key_here",
        "BASE_URL": "https://us.api.flexprice.io/v1"
      }
    }
  }
}
```

**夹克** (备选案文2——stdio):

```json
{
  "mcpServers": {
    "flexprice": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "API_KEY_APIKEYAUTH", "-e", "BASE_URL", "flexprice-mcp"],
      "env": {
        "API_KEY_APIKEYAUTH": "your_api_key_here",
        "BASE_URL": "https://us.api.flexprice.io/v1"
      }
    }
  }
}
```

编辑后保存和 **重新启动光标或退出并重新打开 Claude 桌面** 因此 MCP 服务器已装入 .

## 工具

服务器将弹性价格API操作暴露为MCP工具. **只包含带有 OpenAPI 标记的操作** (如客户,发票,事件). 允许的标记在 repo 中配置; 过滤的 spec 是 `docs/swagger/swagger-3-0-mcp.json`。工具名称和参数遵循 OpenAPI 规格。 完整的列表,请查看您 MCP 客户端在连接后的工具列表,或 OpenAPI spec(例如. `docs/swagger/swagger-3-0.json`) 在还原.

## 逐步发现(动态模式)

拥有许多工具的服务器可以 bloat上下文和符号使用. **动态模式** 暴露出一组小的元工具,使助手可以发现并按要求调用操作:

-   **`list_tools`** - 列出有姓名和说明的现有工具
-   **`describe_tool`** - 获取一个或多个工具的输入方案
-   **`execute_tool`** - 以给定参数运行一个工具名称

要启用动态模式, 添加 `--mode dynamic` 启动服务器时:

```json
"args": ["-y", "@flexprice/mcp-server", "start", "--server-url", "https://us.api.flexprice.io/v1", "--api-key-auth", "YOUR_API_KEY", "--mode", "dynamic"]
```

这可以减少每个请求的令牌,并且在有很多操作时可以改进工具选择.

## 范围

FlexPrice MCP工具被归类为三个许可范围,以便进行精细的访问控制:

-   **`read`** - 只读操作(GET请求):列出客户列表,获取发票,查看使用,查询数据
-   **`write`** - 创建/更新操作(POST/PUT/PATCH):创建客户,更新订阅,修改资源
-   **`delete`** - 破坏性业务(DELETE,定稿):删除资源、敲定发票、作废交易

### 正在挂起特定范围

通过在服务器启动时指定范围来控制哪些工具可用 。 可以结合多个瞄准镜或者使用单一瞄准镜进行受限访问.

**仅读访问** (最安全勘探和报告):

```json
{
  "mcpServers": {
    "flexprice-readonly": {
      "command": "npx",
      "args": [
        "-y",
        "@flexprice/mcp-server",
        "start",
        "--server-url",
        "https://us.api.flexprice.io/v1",
        "--api-key-auth",
        "YOUR_API_KEY",
        "--scope",
        "read"
      ]
    }
  }
}
```

**读取和写取** (最常见于自动化):

```json
{
  "mcpServers": {
    "flexprice-full": {
      "command": "npx",
      "args": [
        "-y",
        "@flexprice/mcp-server",
        "start",
        "--server-url",
        "https://us.api.flexprice.io/v1",
        "--api-key-auth",
        "YOUR_API_KEY",
        "--scope",
        "read",
        "--scope",
        "write"
      ]
    }
  }
}
```

**完全进入** (包括破坏性行动):

```json
{
  "mcpServers": {
    "flexprice-admin": {
      "command": "npx",
      "args": [
        "-y",
        "@flexprice/mcp-server",
        "start",
        "--server-url",
        "https://us.api.flexprice.io/v1",
        "--api-key-auth",
        "YOUR_API_KEY",
        "--scope",
        "read",
        "--scope",
        "write",
        "--scope",
        "delete"
      ]
    }
  }
}
```

**说明:** 选择 `--scope` 将完全安装所有可用的工具(相当于指定所有范围).

## 解决问题

### “无效 URL” 或请求错误

-   服务器从 `BASE_URL` +路径. 若为 `BASE_URL` 未设置或错误,请求失败.
-   **修补 :** 设定 `BASE_URL=https://us.api.flexprice.io/v1` (后面没有空格或斜线) `v1`) (中文(简体) ). Npx, 通过 `--server-url https://us.api.flexprice.io/v1`。 。 。 .
-   如果你得到一个 **404 (韩语)** 在工具调用时,确保基准 URL 包含 `/v1`。 。 。 .

### API 连接问题

1.  **全权证书:** 检查您的 API 密钥和基址是否正确 。 以弹性价 API 测试密钥( 如 . `curl -H "x-api-key: your_key" https://us.api.flexprice.io/v1/customers`) (中文(简体) ).
2.  **网络 :** 确认主机可以到达弹性价格API(防火墙,代理).
3.  **限制费率 :** 如果看到速率限制错误,请减少请求频率或联系人弹性价格支持.

### 服务器问题

-   **正在使用的端口 :** 如果有其它东西使用端口(如3000),则改变服务器配置或停止其他进程.
-   **缺少依赖性 :** 运行 `npm install` 财务报告和审定财务报表 `npm run build` 在服务器目录中.
-   **权限 :** 确保切入点可以执行(例如:. `chmod +x bin/mcp-server.js`) (中文(简体) ).

### 夹克

-   **构建失败 :** 检查多克已安装, 守护进程正在运行; 尝试 `docker build --no-cache`。 。 。 .
-   **集装箱出口:** 检查日志 `docker logs <container_id>`。 。 。 .
-   **内文 vars:** 校验符通过 : `docker run -it --rm flexprice-mcp printenv`。 。 。 .

## 生成 MCP 服务器

服务器来自标签过滤的 OpenAPI spec(`docs/swagger/swagger-3-0-mcp.json`),不是全谱. 仅包含其标记被列出被允许的tag配置中的操作. 要在 API 或 覆蓋變更后再生成 :

1.  (可选) 编辑允许的标签配置以添加或删除标签; 然后运行 `make filter-mcp-spec` 以重建过滤的光谱.
2.  从还原根,运行 `make sdk-all` (这个运行) `filter-mcp-spec` 自动,然后生成MCP服务器.
3.  运行 `make merge-custom` 因此自定义文件(包括这个 README) 被合并到输出中.
4.  构建和运行 : `npm run build` 财务报告和审定财务报表 `npm start` 从 MCP 输出目录.

参见SDK/MCP生成和出版的主要repo README和AGENTS.md.

## 常见问题

### @flexprice/mcp-server 是什么？

一个模式上下文协议\(MCP\)服务器,将弹性价格API暴露为AI助手\(如克洛德,Cursor,VS代码,Windsurf\)的工具\. 使用它来管理客户,计划,价格,订阅,发票,支付,事件,以及更多来自您的IDE或CLI\.

### 如何安装 @flexprice/mcp-server？

在项目目录运行 npm install @flexprice/mcp-server，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 mcp、mcp-server，可以用 npx mcp 直接运行。

### @flexprice/mcp-server 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/flexprice\_\_mcp-server 是否存在。

### @flexprice/mcp-server 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @flexprice/mcp-server 可以商用吗？

@flexprice/mcp-server 使用 未声明 许可。package\.json 没有声明许可证。没有许可证的代码默认保留全部权利，商用前请联系作者或查看仓库中的 LICENSE 文件。以上为概括，不构成法律意见，请以许可原文为准。

### @flexprice/mcp-server 的下载量有多少？

根据 npm 官方下载统计，@flexprice/mcp-server 在 2026/10/15 – 2026/11/13 这 30 天内被下载 3,125 次，日均约 104 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @flexprice/mcp-server 还在维护吗？

最新版本 2\.1\.48 发布于 2026/11/05（10 天前）；至今共发布 56 个版本，其中过去 12 个月发布了 56 个；首次发布于 2026/02/17。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。