NexBank MCP Server

独立的 NexBank API v2 MCP Server。提供 Stateless Streamable HTTP、Bearer Token、可选 OAuth 授权码接入、MySQL Connection 解析和六个业务工具。

准备

1. 使用 Node.js 20 或更高版本安装依赖：npm install。
2. 数据库执行唯一脚本 sql/001_init.sql。脚本第一部分会删除旧表及其全部数据，第二部分创建统一使用 nxb_mcp_ 前缀的新表；执行前必须确认旧数据无需保留或已完成备份。
3. 复制 config/application.example.yaml 为部署配置，并填写 MySQL 与两个环境的 API Base URL。
4. 通过 --config <文件> 或 NEXBANK_MCP_CONFIG_FILE 指定配置文件。

不要把真实 AppSecret、Bearer Token 或生产配置提交到仓库。

Token 有效期使用可读 Duration 配置，支持 s（秒）、m（分钟）、h（小时）、d（天）。Access Token 默认 1 小时，Refresh Token 默认 365 天：

auth:
  accessTokenTtl: "1h"
  refreshTokenTtl: "365d"

OAuth /token 响应中的 expires_in 始终按秒返回。验证自动刷新时，可在重新授权前暂时设置 accessTokenTtl: "30s" 和 refreshTokenTtl: "10m"。

运行

npm run build
npm start -- --config ./config/application.yaml

开发模式：

npm run dev -- --config ./config/application.yaml

日志默认同时输出到控制台和 ./logs，并按照服务所在时区的自然日写入 nexbank-mcp-server-YYYY-MM-DD.log。可以通过部署配置调整文件日志：

logging:
  level: "info"
  file:
    enabled: true
    directory: "./logs"
    prefix: "nexbank-mcp-server"

设置 file.enabled: false 可以只保留控制台日志。日志滚动不会改变既有敏感字段脱敏规则。

MCP 入口默认为 POST /mcp，请求必须包含：

Authorization: Bearer <26-character-ULID>.<22-character-random-secret>

完整 Token 固定为 49 个字符。第一部分是 26 字符 ULID，第二部分是 16 字节密码学安全随机数的 Base64URL 编码。

Stateless 模式不提供 GET/SSE 会话，GET /mcp 和 DELETE /mcp 返回 405。

OAuth 简易绑定

在配置中增加 oauth 后，Server 同时支持原有 Bearer Token 和 OAuth 2.1 授权码流程：

oauth:
  issuerUrl: "https://mcp.example.com"
  bindingEnvironment: "sandbox"

• issuerUrl 必须是对外可访问的 HTTPS Origin；仅本机开发允许 localhost、127.0.0.1 或 [::1] 使用 HTTP。
• bindingEnvironment 决定授权页凭证绑定到沙盒还是正式环境。页面本身只填写 App ID、AppSecret、customerCode，不要求用户登录。
• 服务端保留 PKCE、OAuth state、redirect URI 和 resource 校验。授权成功后在同一个数据库事务中创建 Bearer Token 与 nxb_mcp_connection，OAuth /token 返回的 expires_in 与数据库 expires_at 的剩余有效期一致。
• OAuth 公共客户端注册信息持久化在 nxb_mcp_oauth_client；未完成授权请求和授权码仍只在进程内短期保存。
• 授权码交换同时返回 Access Token、expires_in 和 Refresh Token。Refresh Token 只保存 SHA-256 哈希，并绑定 client_id、scope 和 resource；每次刷新都会同时轮换 Access Token 与 Refresh Token。
• 已使用 Refresh Token 被再次提交时，服务端会撤销整个 Token Family 及当前 Access Token，客户端必须重新授权。
• OAuth 请求参数会写入结构化日志。AppSecret、授权码、PKCE verifier、token 不记录原值，appId、customerCode 只记录脱敏值。

启用 OAuth 的部署必须通过 HTTPS 暴露授权端点。删除整个 oauth 配置块即可继续只使用手工生成的 Bearer Token。

Token 与 Connection

生成 Token：

npm run token:generate -- --name "调用方名称" --config ./config/application.yaml

完整 Token 只显示一次，同时会显示过期时间。随后在 nxb_mcp_connection 中按生成记录的数据库主键维护 Sandbox Connection；付费并取得正式配置后，为同一 access_token_id 增加 Production Connection。

只有未过期、enabled=1 且 status='active' 的 Connection 能调用 NexBank。停用 Token 可直接把 nxb_mcp_access_token.enabled 更新为 0。

测试

npm test
npm run test:e2e

MySQL 集成测试只允许连接专用测试库：

NEXBANK_MCP_TEST_CONFIG_FILE=./config/application.test.yaml
NEXBANK_MCP_ALLOW_DB_TESTS=true
npm run test:integration

集成测试不会创建或删除数据库。真实 Sandbox 联调仅执行只读工具；签约链接生成不属于默认自动化测试。