使用说明

项目简介

'polar-js' 仓库提供的 Polar SDK 不仅是一个方便开发者使用的 Typescript SDK，它还可以作为一个 Model Context Protocol (MCP) 服务器 运行。这意味着您可以利用这个 SDK，将 Polar API 的各项功能以标准化的 MCP 协议形式暴露出来，供支持 MCP 协议的 LLM 客户端（如 Claude、Cursor 等）调用。

主要功能点

资源 (Resources) 访问: 虽然仓库文档主要关注工具 (Tools)，但 MCP 服务器本身具备资源管理能力。通过 SDK 提供的工具，可以间接访问和操作 Polar 平台上的各种资源，例如客户 (Customers)、产品 (Products)、订阅 (Subscriptions)、订单 (Orders) 和指标 (Metrics) 等。
工具 (Tools) 注册和执行: 仓库将 Polar API 的各种操作封装成 MCP 工具，例如：
- 订阅管理工具: 'subscriptions_list', 'subscriptions_get', 'subscriptions_update', 'subscriptions_revoke', 'subscriptions_export'
- 产品管理工具: 'products_list', 'products_create', 'products_get', 'products_update', 'products_update-benefits'
- 订单管理工具: 'orders_list', 'orders_get', 'orders_invoice'
- 客户管理工具: 'customers_list', 'customers_create', 'customers_get', 'customers_update', 'customers_delete', 'customers_get-external', 'customers_update-external', 'customers_delete-external', 'customers_get-state', 'customers_get-state-external'
- 指标 (Metrics) 工具: 'metrics_get', 'metrics_limits'
Prompt 模板 (Prompts): 仓库本身未直接提供 Prompt 模板功能，但 MCP 服务器的工具可以用于构建动态 Prompt，从而支持可定制的 LLM 交互模式。
会话管理和能力声明: MCP 服务器由 '@modelcontextprotocol/sdk/server/mcp.js' 实现，具备 MCP 服务器应有的会话管理和能力声明功能。
多种传输协议: 支持 Stdio 和 SSE 传输协议，满足不同 LLM 客户端的连接需求。

总而言之，该 MCP 服务器允许 LLM 客户端通过调用预定义的工具，安全、便捷地访问和操作 Polar 平台提供的订阅管理、支付处理等核心业务能力。

安装步骤

使用以下命令之一安装 '@polar-sh/sdk' 包：

npm add @polar-sh/sdk

pnpm add @polar-sh/sdk

bun add @polar-sh/sdk

yarn add @polar-sh/sdk zod

注意: 使用 'yarn' 时，需要手动安装 'zod' 依赖。

服务器配置

为了让 MCP 客户端（例如 Claude 或 Cursor）连接到 Polar MCP 服务器，您需要配置客户端的 MCP 服务器设置。以下是针对 Claude 和 Cursor 的配置示例。请注意，您只需要配置客户端，无需手动启动服务器，SDK 会在客户端连接时自动启动。

Claude 配置 (添加到 'claude_desktop_config.json')

{
  "mcpServers": {
    "Polar": {
      "command": "npx",
      "args": [
        "-y",
        "--package",
        "@polar-sh/sdk",
        "--",
        "mcp",
        "start",
        "--access-token",
        "YOUR_ACCESS_TOKEN" // 请替换为您的 Polar API 访问令牌
      ]
    }
  }
}

'server name': Polar (服务器名称，可自定义)
'command': npx (Node.js 包执行器)
'args': 启动服务器的参数列表
- '-y': 自动确认安装包
- '--package': 指定要安装和运行的 npm 包为 '@polar-sh/sdk'
- '--': 分隔 npx 参数和包参数
- 'mcp': 执行 '@polar-sh/sdk' 包中的 'mcp' 命令 (指向 'src/mcp-server/mcp-server.ts')
- 'start': 'mcp' 命令的子命令，启动 MCP 服务器 (指向 'src/mcp-server/cli/start/command.ts')
- '--access-token': Polar API 的访问令牌，请替换为您的真实 Access Token。您可以在 Polar 平台获取。

Cursor 配置 (在 Cursor 设置中添加 MCP 服务器)

Name: 'Polar' (服务器名称，可自定义)
Type: 'command'
Command:

npx -y --package @polar-sh/sdk -- mcp start --access-token YOUR_ACCESS_TOKEN  # 请替换为您的 Polar API 访问令牌

'Name': Polar (服务器名称，可自定义)
'Type': command (命令类型)
'Command': 启动服务器的完整命令，与 Claude 配置中的 'command' 和 'args' 组合相同。
- 'npx -y --package @polar-sh/sdk -- mcp start --access-token YOUR_ACCESS_TOKEN': 与 Claude 配置的 'command' 和 'args' 含义一致，请务必替换 'YOUR_ACCESS_TOKEN' 为您的真实 Access Token。

基本使用方法

安装 SDK: 按照上述安装步骤安装 '@polar-sh/sdk'。
配置 MCP 客户端: 根据您使用的 LLM 客户端 (Claude 或 Cursor)，按照上述服务器配置示例进行配置，务必替换 'YOUR_ACCESS_TOKEN' 为您在 Polar 平台获取的有效 API 访问令牌。
在 LLM 客户端中使用工具: 配置完成后，您的 LLM 客户端应该能够识别并调用 Polar MCP 服务器提供的工具。您可以通过自然语言指令，指示 LLM 客户端调用相应的工具来完成各种操作，例如查询客户信息、创建产品、管理订阅等。具体的工具调用方式和参数，请参考 Polar SDK 的文档或工具的描述信息。

注意: 运行 MCP 服务器需要 Node.js v20 或更高版本。

关键词