PortOne MCP 服务器

PortOne 用户的 MCP (模型上下文协议) 服务器。它提供 PortOne 开发者中心、帮助中心等官方文档内容给大型语言模型（LLM），以准确的信息为基础，帮助用户进行集成和查询。

此外，该服务器还可以执行部分由 PortOne 控制台提供的功能：

• 查询频道列表
• 添加测试频道
• 查询子商店
• 查询支付记录

使用控制台功能时，需要通过浏览器登录控制台。

使用 DXT 进行安装

可以通过 DXT (桌面扩展) 一键安装 MCP 服务器。

1. 从 GitHub 发布页面 下载最新版本的 portone-mcp-server.dxt 文件。
2. 在支持的 AI 工具（如 Claude Desktop）中，通过拖放或打开下载的 .dxt 文件来安装。
3. 安装后，请重新启动工具，确认 MCP 服务器已正确注册。

[!WARNING] 在 Claude Desktop 中使用 DXT 文件时的注意事项

由于当前的 已知问题，在 Claude Desktop 中安装 DXT 后，MCP 服务器可能无法正常工作。

如果遇到这种情况，请安装 Node.js 22.6.0 或更高版本，并在 Claude Desktop 设置中禁用 “为 MCP 使用内置 Node.js” 选项，然后重新启动。

注册 MCP 服务器

1. 需要安装 Node.js 22.6.0 或更高版本。

2. 在使用的 AI 工具的 MCP 设置中添加以下内容。（例如：Cursor, Windsurf, Claude Desktop 等）

   "mcpServers": {
   
     // 原有设置
   
     "portone-mcp-server": {
       "command": "npx",
       "args": [
         "-y",
         "@portone/mcp-server@latest"
       ]
     }
   }
   

3. 重新启动工具，确认 portone-mcp-server 及其提供的工具已正确注册。

[!CAUTION] 使用第三方 AI 服务时的注意事项

当使用第三方 AI 服务时，API 响应（包括查询的数据等）可能会被传递到 AI 服务并存储，或者根据该服务的政策用于模型训练。

MCP 服务器优先采取措施识别并移除 API 响应中包含的个人身份信息，防止其泄露。但其他信息可能会根据 AI 服务的操作政策暂时存储或处理，请注意这一点。

开发指南

要求

• Node.js 22.6. 0 或更高版本
• pnpm（推荐）或 npm

1. 克隆仓库并安装所需包

   pnpm install
   

2. 运行 MCP 服务器（开发模式）

   pnpm dev
   

3. 代码检查与格式化

   pnpm lint
   pnpm format
   

4. 类型检查

   pnpm typecheck
   

5. 构建与发布

   # 首先更改 package.json 中的版本
   rm -rf dist
   pnpm install
   pnpm build
   pnpm publish
   

6. 注册本地环境中的 MCP 服务器

   "mcpServers": {
      "portone-mcp-server": {
        "command": "node",
        "args": [
          "/your/absolute/path/to/portone-mcp-server/dist/index.js"
        ]
      }
   }
   

7. 更新文档

   要求：

   • 本地克隆了 developers.portone.io 和 help.portone.io 仓库。
   • 安装了 nvm（Node 版本管理器）及 Node.js 20 和 23 版本。
   • 安装了 corepack。

   若要更新 MCP 服务器中的文档，请执行以下操作：

   # 使用环境变量的方法
   export DEVELOPERS_PORTONE_IO_PATH="/path/to/developers.portone.io"
   export HELP_PORTONE_IO_PATH="/path/to/help.portone.io"
   pnpm update-docs
   
   # 或者交互式执行
   p
   npm update-docs
   # 根据提示输入 developers.portone.io 和 help.portone.io 仓库的路径
   

   该脚本执行以下操作：

   1. 在 developers.portone.io 和 help.portone.io 仓库中运行 pnpm docs-for-llms 命令（基于本地设置的分支生成文档）。
   2. 将 MCP 服务器的 docs 目录替换为新生成的内容。
   3. 下载并替换开发者中心、帮助中心及其他一些文档。

从 Python 版本迁移

如果您之前使用的是 Python 版本（<0.13.0）的 MCP 服务器，建议迁移到 TypeScript 版本。

迁移方法

1. 修改 MCP 设置

   原有 Python 版本设置：

   "mcpServers": {
     "portone-mcp-server": {
       "command": "uvx",
       "args": ["portone-mcp-server@latest"]
     }
   }
   

   新的 TypeScript 版本设置：

   "mcpServers": {
     "portone-mcp-server": {
       "command": "npx",
       "args": ["-y", "@portone/mcp-server@latest"]
     }
   }
   

2. 环境变量及 API 密钥设置保持不变。

3. 安装 Node.js：需要 Node.js 22.6.0 或更高版本。

4. 重启 AI 工具：设置更改后，请重新启动正在使用的 AI 工具。

许可证

Apache License 2.0 OR MIT License