NetSuite MCP Tools

用于 Windows 本机 VS Code 的内部扩展：它通过 NetSuite OAuth 2.0 Authorization Code + PKCE 在系统浏览器中授权，在本机提供 Streamable HTTP MCP 代理，并为 VS Code Copilot、Claude Code 与 Codex CLI 生成无凭据的本地 MCP 配置。

当前版本：v0.3.3。版本变更详见 CHANGELOG.md。

这不是 M2M 或 mTLS 客户端证书代理。扩展使用 NetSuite Public Client Integration，授权码、PKCE verifier、state、access token 与 refresh token 只在当前 VS Code Extension Host 内存中存在。

支持范围

Windows Desktop 上的本地单文件夹工作区
当前稳定版 VS Code Copilot、Claude Code CLI 与 Codex CLI
官方 NetSuite AI Connector SuiteApp：com.netsuite.mcpstandardtools
NetSuite Public Client Integration 与非 Administrator Role

不支持 WSL、Remote SSH、Dev Container、Codespaces、macOS、Linux、局域网访问、任意 MCP URL、私钥迁移或其他 MCP 客户端。

安全模型

只监听 127.0.0.1；不监听局域网或 IPv6 地址。
每个工作区保存 /.netsuite-mcp/environment.json。其中只含可共享的非机密连接元数据、固定端口和端口排除清单；仅 /.netsuite-mcp/logs/ 及两份 MCP 配置自动加入 .gitignore。
environment.json 只保存非机密 profile 元数据、Public Client clientId 和受控的 loopback Redirect URI。
不生成或保存证书、私钥、Client Secret、授权码、PKCE verifier、state、access token 或 refresh token。
授权材料、认证头和 HTTP 正文不落盘、不写日志。
同一 Windows 用户下的恶意进程理论上可发现 loopback 端口，因此必须使用 NetSuite 最小权限 Role，且不要在不可信共享帐户上运行。

状态栏交互

扩展在状态栏左侧显示连接状态。点击状态栏按钮是所有操作的主入口，无需通过 Ctrl+Shift+P 搜索命令。

状态	文案	点击行为
未连接（无有效 clientId）	`NetSuite MCP：未连接`	打开 `environment.json` + 弹出操作下拉框
未连接（有有效 clientId）	`NetSuite MCP：未连接`	弹出操作下拉框
已连接	`NetSuite MCP：已连接`	弹出操作下拉框
需要修复	`NetSuite MCP：需要修复`	弹出代理启动失败提示

VS Code 重启后，即使 environment.json 中 profile 标记为 verified，若内存中无 OAuth token，状态栏仍显示"未连接"而非误报"已连接"。

安装 VSIX

从发布物取得 netsuite-mcp-tools-<version>.vsix。
在 VS Code 执行 Extensions: Install from VSIX…，选择该文件。
重新打开一个 Windows 本地文件夹工作区。
点击状态栏的 NetSuite MCP：未连接 按钮。

首次配置

点击状态栏的 NetSuite MCP：未连接 按钮。扩展会创建并打开 /.netsuite-mcp/environment.json，同时弹出操作下拉框；之后所有人工配置都在这个文件完成，不会逐字段弹窗询问。
在模板中编辑以下人工配置：
- 将 YOUR_NETSUITE_ACCOUNT_ID 同时替换为 environments 的键和其中的 accountId 值；两处必须完全一致。
- 将 environmentType 设为 sandbox 或 production。
- 填写 Public Client Integration 的 clientId。不要手工编辑 id、status、端口、allocatedPorts 或 workspaceId；这些是扩展维护的派生状态。打开配置命令会显示由该工作区持久化端口派生的 Redirect URI。
在 NetSuite 创建专用 Integration，并配置：
- 勾选 Public Client 与 Authorization Code Grant；
- 将"打开连接配置"操作显示的 Redirect URI 原样填入 Redirect URI；
- 启用 NetSuite AI Connector Service scope；
- 使用非 Administrator 的最小权限 Role。该 Role 必须有 MCP Server Connection、OAuth 2.0 Access Tokens，并在使用 MCP Standard Tools SuiteApp 时具有 REST Web Services 权限。
回到 environment.json 填写 clientId 并保存，然后点击状态栏按钮，从下拉框选择 启动连接。扩展会启动仅限 127.0.0.1 的临时回调、打开系统浏览器完成 NetSuite 登录/同意，再执行 MCP initialize 与 tools/list 健康检查，不读取业务数据；健康检查成功后会把档案标记为已验证，并将该工作区固定端口加入共享的 allocatedPorts 和当前主机的插件用户级排除清单。
验证后，点击状态栏按钮，从下拉框选择 生成 Agent 配置。弹出多选下拉框，选择需要配置的 Agent（VS Code Copilot、Claude Code、Codex CLI，允许多选），确认后写入对应的配置文件。

权限模型

每个工作区只有一个 MCP 连接和一份 profile。实际的读写权限完全由 NetSuite Role 控制，本地不再区分 read/write profile。只要 Role 具有相应权限，同一 MCP 连接既可读取也可写入。这简化了配置流程，同时将权限边界保持在 NetSuite 服务端。

生成的 MCP 配置

生成的配置仅包含 http://127.0.0.1:<port>/<profile-id>/mcp，没有 Client ID、Client Secret、授权码、PKCE verifier、JWT 或 access token。

VS Code Copilot（工作区级）：配置写入 .vscode/mcp.json，server 名称为 netsuite-mcp-<workspaceId>。

Claude Code（工作区级）：配置写入 .mcp.json，server 名称为 netsuite-mcp-<workspaceId>。

Codex CLI（工作区级）：配置写入 .codex/config.toml 的 [mcp_servers.netsuite-mcp-<workspaceId>] 表，仅包含 url 字段，不会读取或修改用户级 ~/.codex/config.toml。与其他 Agent 一样，生成时仅新增或更新当前工作区的受托管条目；需要移除历史受托管条目时，请使用 清理 MCP 配置 操作。

environment.json 只能保存非机密配置和扩展派生的文件元数据，可由管理员随项目共享给其他用户。allocatedPorts 会传递已验证工作区使用过的端口，帮助其他用户初始化新工作区时避让。若文件包含 private key、Client Secret、Certificate ID、JWT、token、认证头或其他未知字段，扩展会拒绝加载它。

若该文件不存在、为空或仅包含空白字符，打开命令会重新初始化完整的草稿模板。对于只缺少扩展维护字段的合法 JSON，扩展会安全补全并提示"已补全"，同时保留已有 accountId、环境和 Client ID。JSON 损坏、字段类型错误或包含未知字段时不会覆盖文件，需先手动修复。

断开连接与重新授权

断开连接：在已连接状态下，从下拉框选择 断开连接。扩展会清除当前工作区的内存 token、停止本机代理服务器，并将 profile 状态回退为 registered。已生成的 MCP 配置不会被自动清理，用户可在后续重新启动连接。
重新授权：在已连接状态下，从下拉框选择 重新授权。扩展会打开浏览器完成新一轮 OAuth 授权；在新的授权完成之前，旧的 token 仍然有效，不会提前清除。
扩展不会自动撤销 NetSuite 远端 Integration 或其已授予的访问权限。
清理 MCP 配置操作会弹出多选下拉框，选择需要清理的 Agent 后，扫描对应配置文件，删除所有由本扩展托管（名称以 netsuite-mcp- 开头）的 server 条目，保留无关配置。
若复制项目到另一个 Windows 用户/设备，必须使用该设备的浏览器重新授权。

故障处理

症状	处理方式
浏览器授权失败或回调超时	核对 Public Client、Redirect URI（必须与模板完全一致）、Authorization Code Grant、AI Connector Service scope 与 OAuth 2.0 feature。
MCP 初始化失败	确认 SuiteApp 已安装、使用 MCP `2025-06-18`、Role 为非 Administrator 且具有 MCP Server Connection / OAuth 2.0 Access Tokens / REST Web Services 所需权限，并仅在 sandbox 运行 Phase 0。
MCP 健康检查成功，但 Agent 未显示任何工具	确认目标 NetSuite 账号已安装并启用 Oracle NetSuite 发布的 MCP Standard Tools SuiteApp。仅具备 AI Connector Service scope 可以完成 OAuth 和 MCP 握手；若该 SuiteApp 未安装或未生效，`tools/list` 仍可能成功返回空列表。安装或更新后，重新授权，并重启本地代理与 Agent 的 MCP 会话。
本地端口冲突	扩展会自动分配新的回调端口并更新 `environment.json`，同时同步刷新已生成的 MCP 配置（`.vscode/mcp.json`、`.mcp.json`、`.codex/config.toml`）中的 URL。由于 NetSuite 对 loopback Redirect URI 不校验端口（RFC 8252），无需在 Integration 中更新 Redirect URI。仅在多次自动分配均失败时，需关闭占用高位端口的程序后重试。
本机代理提示需要授权	点击状态栏，从下拉框选择启动连接或重新授权，在系统浏览器中完成当前会话的授权。
Agent 未连接	检查 VS Code 是否打开该工作区、profile 是否已验证，以及 `.vscode/mcp.json`、`.mcp.json` 或 `.codex/config.toml` 是否被 Git 跟踪或损坏。

日志位于 /.netsuite-mcp/logs/，仅保存脱敏事件、状态码和 MCP 方法名，最多保留 7 天或 10 MB。

从 v0.2.x 升级

v0.3.0 移除了 read/write profile 区分。升级后，已有的 environment.json（schema v2）会自动迁移到 v3：

每个 environment 的 read 和 write profile 合并为一个（优先保留已验证的，其次保留有 clientId 的）。
access 字段被移除。
MCP 配置中的旧命名 netsuite-mcp-<accountId>-<access> 不再被自动清理，请手动执行 清理 MCP 配置 后重新生成。

本地开发与打包

npm install
npm run typecheck
npm run lint
npm test
npm run package

最后一条命令会生成可通过 VS Code 安装的 .vsix 文件。真实 NetSuite 验证只允许最小权限 sandbox，且只执行浏览器授权、initialize 和 tools/list；不要把 production 当作测试环境。