<div align="center">

# NetSuite MCP

### 让 AI 助手直接操作你的 NetSuite ERP

[![GitHub Release](https://img.shields.io/github/v/release/letian940-prog/ns-mcp-china?style=flat-square)](https://github.com/letian940-prog/ns-mcp-china/releases)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
[![Node.js >= 18](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg?style=flat-square)](https://nodejs.org)

**[中文](#中文) · [English](#english)**

</div>

---

# 中文

## 这是什么？

**NetSuite MCP** 是一个连接器工具，让你的 AI 助手（各类 AI 助理，如 Kimi work、workbuddy、豆包工作、deepseek等）能够直接查询和操作 NetSuite ERP 系统——创建客户、跑报表、查数据，全部用自然语言完成。

**你只需要做三件事：**
1. 在 NetSuite 后台做一次集成配置（约 10 分钟）
2. 下载本工具并运行一条命令（约 1 分钟）
3. 在浏览器里填 3 个框、点一下授权（约 30 秒）

之后就可以对 AI 说"查询所有 subsidiary"、"跑一下试算平衡表"等，AI 会自动调用 NetSuite 的 17 个工具完成任务。

### 它是怎么工作的？

```
你 → AI 助理
         │
         ▼
    本连接器（自动管理 Token）
         │
         ▼
    NetSuite 官方 MCP 服务
    （17 个工具：记录操作、SuiteQL、报表等）
```

**核心优势：**
- **零依赖**：纯 Node.js 内置模块，不需要 `npm install`
- **自动刷新 Token**：Token 过期自动续期，无需人工干预
- **安全**：凭据存储在本地文件（权限 600），不泄露到配置文件
- **一键配置**：浏览器填 3 个框，OAuth 授权全自动

---

## 完整安装指南（手把手，按顺序操作）

### 第一步：在 NetSuite 后台配置集成授权

> 这一步在你的 NetSuite 网页后台操作，需要管理员权限。
> **预计耗时：10 分钟**

#### 1.1 启用 OAuth 2.0 功能

1. 登录 NetSuite → 顶部菜单 `Setup > Company > Enable Features`
2. 点击 **SuiteCloud** 标签页
3. 找到 **OAuth 2.0**，勾选它
4. 点击 **Save**

> 如果已经勾选了，跳过这步。

#### 1.2 创建集成（Integration）

1. 顶部菜单 `Setup > Integration > Manage Integrations > New`
2. 按下表填写：

| 字段 | 填什么 | 说明 |
|---|---|---|
| Name | `AI Assistant MCP` | 随便起名，自己认得就行 |
| **Authorization Code Grant** | ✅ 勾选 | **必须勾，不能漏** |
| **Public Client** | ✅ 勾选 | **必须勾，不勾会报错** |
| Audience | ✅ `NetSuite Service Endpoint Runtime` | 勾选 |
| Scopes | ✅ `NetSuite AI Connector Service` | 勾选 |
| Redirect URI | `http://127.0.0.1:38271/callback` | 复制粘贴这一行 |
| Token Lifetime | `3600` | 默认即可，想长一点可以改大 |

3. 点击 **Save**
4. **立刻复制** Client ID 和 Client Secret（关闭页面后看不到了！）

> ⚠️ **两个必须勾的选项**：`Authorization Code Grant` 和 `Public Client`，缺任何一个都会导致连接失败。

#### 1.3 安装 MCP Standard Tools 套件

1. 顶部菜单 `Customization > SuiteBundler > Search & Install Bundles`
2. 搜索 `MCP Standard Tools`
3. 点击 **Install**，等待安装完成

> 不装这个套件，连接成功但 0 个工具可用。

#### 1.4 创建专用角色（不能用管理员！）

> Oracle 官方文档明确说明：**管理员角色不能用于 AI Connector Service**。

1. 顶部菜单 `Setup > Users/Roles > Manage Roles > New`
2. 角色名称填 `MCP User`（或任意名称）
3. 在 Permissions 标签页添加以下权限：

| 权限分类 | 权限名称 | 级别 |
|---|---|---|
| Setup | **MCP Server Connection** | Full |
| Setup | **Log in using OAuth 2.0 Access Tokens** | Full |
| Setup | **REST Web Services** | Full |

4. 点击 **Save**
5. 把这个角色分配给一个用户：`Setup > Users/Roles > Assign Access Roles`
6. **记住这个用户的登录名和密码**——后面授权时要用它登录

> ✅ 第一步完成！你现在有了：Client ID、Client Secret、一个有权限的非管理员用户。

---

### 第二步：下载并安装本工具

> **预计耗时：1 分钟**
> **前提：电脑上已安装 Node.js 18 或以上版本**

#### 2.1 检查 Node.js

打开终端（macOS: `Cmd+空格` 搜 Terminal），输入：

```bash
node --version
```

如果版本号 >= 18，继续。如果没装或版本太低，去 https://nodejs.org 下载安装。

#### 2.2 下载项目

```bash
git clone https://github.com/letian940-prog/ns-mcp-china.git
cd ns-mcp-china
```

> 不需要 `npm install`！这个工具零外部依赖，下载即用。

> ✅ 第二步完成！项目已经下载到本地。

---

### 第三步：运行配置向导，连接 NetSuite

> **预计耗时：30 秒**

在刚才的终端里运行：

```bash
node bin/ns-mcp-connector.js --setup
```

浏览器会自动打开一个配置页面。按以下步骤操作：

1. 在表单中填写 3 个字段：

| 字段 | 填什么 | 示例 |
|---|---|---|
| **服务端点 URL** | 你的 NetSuite MCP 地址 | `https://td3065115.suitetalk.api.netsuite.com/services/mcp/v1/all` |
| **客户端 ID** | 第一步复制的 Client ID | `3cdf5429...` |
| **客户端密钥** | 第一步复制的 Client Secret | `91df2789...` |

> URL 中的 `td3065115` 换成你的 NetSuite Account ID。

2. 点击 **"连接"** 按钮
3. 浏览器跳转到 NetSuite 授权页面
4. **用第一步 1.4 创建的非管理员用户登录**
5. 点击 **Authorize**（授权）
6. 页面跳回本地，显示"连接成功！"

**连接器自动完成了以下工作：**
- OAuth 2.0 授权流程
- Token 保存到 `~/.ns-mcp/tokens.json`（权限 600）
- 更新 `~/.workbuddy/mcp.json` 配置文件

> ✅ 第三步完成！Token 已保存，配置已写入。

---

### 第四步：重启 AI 助手并验证

#### 4.1 完全退出 AI 助手

- **AI 助理**：完全退出应用（不是关窗口！），然后重新打开
- **Claude Desktop**：完全退出后重新打开
- **Cursor**：重启应用

#### 4.2 信任连接器

进入 **设置 → 连接器 → 自定义连接器**，找到 `netsuite-mcp`，点击 **Trust**。

#### 4.3 测试连接

在 AI 对话里输入：

> "查询 NetSuite 的所有 subsidiary"

如果 AI 返回了 NetSuite 的子公司列表，说明连接成功！

> ✅ 全部完成！以后可以随时用自然语言操作 NetSuite。

---

## 常见问题

### 浏览器打开后显示 `page_not_found`

**原因**：OAuth 2.0 功能未启用，或集成类型选错了。

**解决**：
1. 确认 `Setup > Company > Enable Features > SuiteCloud` 里已勾选 OAuth 2.0
2. 确认集成里勾选了 `Authorization Code Grant`（不是 Client Credentials）
3. 确认勾选了 `Public Client`

### 报错 `redirect_uri_mismatch`

**原因**：集成里的 Redirect URI 和实际不一致。

**解决**：确认集成里的 Redirect URI 是 `http://127.0.0.1:38271/callback`，一字不差。

### 端口 38271 被占用

```bash
# 查看谁在占用
lsof -i :38271
# 杀掉占用进程
kill -9 <PID>
```

然后重新运行 setup。

### 连接成功但 0 个工具

**原因**：MCP Standard Tools 套件未安装。

**解决**：`Customization > SuiteBundler > Search & Install Bundles` → 搜 `MCP Standard Tools` → 安装。

### 授权成功但 API 调用返回 401

**原因**：用了管理员角色授权。

**解决**：创建一个非管理员角色（权限：MCP Server Connection + OAuth 2.0 Access Tokens + REST Web Services），用该用户重新运行 `--setup`。

### Token 过期了怎么办？

**不用管！** 连接器会用 refresh_token 自动刷新。如果 refresh_token 也过期了，连接器会自动打开浏览器重新授权。

如果实在连不上，可以手动重置：

```bash
rm ~/.ns-mcp/tokens.json
node bin/ns-mcp-connector.js --setup
```

---

## 可用的 17 个工具

连接成功后，AI 助手可以调用以下工具：

| 分类 | 工具名 | 功能 |
|---|---|---|
| **记录操作** | `ns_createRecord` | 创建记录（客户、订单、发票等） |
| | `ns_getRecord` | 按 ID 获取记录 |
| | `ns_updateRecord` | 更新记录字段 |
| **SuiteQL** | `ns_runCustomSuiteQL` | 执行自定义 SuiteQL 查询 |
| | `ns_getSuiteQLMetadata` | 查看可用表和字段 |
| **保存搜索** | `ns_listSavedSearches` | 列出保存的搜索 |
| | `ns_runSavedSearch` | 执行保存的搜索 |
| **报表** | `ns_listAllReports` | 列出所有报表 |
| | `ns_runReport` | 运行报表（试算平衡、损益等） |
| | `ns_report_filters_app` | 获取报表筛选选项 |
| **元数据** | `ns_getRecordTypeMetadata` | 获取记录类型字段定义 |
| | `ns_getSubsidiaries` | 列出所有子公司 |
| | `ns_getAccountingBooks` | 列出会计账簿 |
| | `ns_getAccountingContexts` | 列出会计上下文 |
| | `ns_getNexusIds` | 列出税务关联 |
| **交互辅助** | `ns_prompt_library_app` | 浏览预置提示模板 |
| | `ns_selector_app` | 发现记录类型及关键字段 |

---

## 其他 AI 助手配置

### Claude Desktop

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "netsuite-mcp": {
      "command": "node",
      "args": ["/你的路径/ns-mcp-china/bin/ns-mcp-connector.js"],
      "env": {
        "NETSUITE_MCP_URL": "https://你的Account_ID.suitetalk.api.netsuite.com/services/mcp/v1/all",
        "NETSUITE_CLIENT_ID": "你的Client_ID",
        "NETSUITE_CLIENT_SECRET": "你的Client_Secret"
      }
    }
  }
}
```

### Cursor

编辑 `.cursor/mcp.json`，格式同上。

> 设置了 env 变量后，连接器会在首次运行时自动触发 OAuth（无需手动跑 `--setup`）。

### Kimi Work（月之暗面桌面智能体）✨ 一条命令

已完成 `--setup` 授权后，只需：

```bash
node bin/ns-mcp-connector.js --kimi
```

它会自动把连接器写进 Kimi Work 的 MCP 配置：

```
~/Library/Application Support/kimi-desktop/daimon-share/daimon/runtime/kimi-code/home/mcp.json
```

然后**完全退出 Kimi Work 并重启**，新开会话即可用。Token 与各 AI 客户端共用（`~/.ns-mcp/tokens.json`），任一客户端刷新后另一边自动生效。

也可以手动写该文件（Windows 路径为 `%APPDATA%\kimi-desktop\daimon-share\daimon\runtime\kimi-code\home\mcp.json`，或用环境变量 `KIMI_WORK_HOME` 指定自定义路径）：

```json
{
  "mcpServers": {
    "netsuite": {
      "command": "node",
      "args": ["/你的路径/ns-mcp-china/bin/ns-mcp-connector.js"],
      "env": {}
    }
  }
}
```

> 提示：如果 Kimi Work 更新后配置丢失，重跑一次 `--kimi` 即可恢复。

---

## 技术原理

### 三种模式，一个文件

| 模式 | 命令 | 作用 |
|---|---|---|
| **配置向导** | `node bin/ns-mcp-connector.js --setup` | 打开浏览器，填 3 个框完成 OAuth 授权 |
| **Kimi Work 安装** | `node bin/ns-mcp-connector.js --kimi` | 一条命令安装到 Kimi Work |
| **MCP 代理** | `node bin/ns-mcp-connector.js`（由 AI 助手自动调用） | 转发 MCP 消息 + 自动管理 Token |

### Token 生命周期

```
access_token（60分钟）──到期──> refresh_token ──自动──> 新的 access_token
                                         │
                                    也到期了
                                         │
                                         ▼
                               连接器自动打开浏览器
                               重新授权（你点一下就行）
```

### 安全设计

- Token 存在 `~/.ns-mcp/tokens.json`，文件权限 600（仅本人可读写）
- `mcp.json` 里**不含任何凭据**——只有连接器脚本的路径
- 所有 OAuth 流量走本地 `localhost:38271` 回调
- 零外部依赖，无供应链风险

---

## 项目结构

```
ns-mcp-china/
├── bin/
│   ├── ns-mcp-connector.js    # 核心连接器（零依赖）
│   └── ns-mcp-setup.js        # 早期 CLI 版本（兼容保留）
├── src/                        # Legacy TypeScript MCP 服务器
│   ├── index.ts
│   ├── netsuite-client.ts
│   └── tools/
├── server.json                 # MCP Registry 描述文件
├── package.json
└── README.md
```

---

<br>

---

# English

## What is this?

**NetSuite MCP** is a connector tool that lets your AI assistant directly query and operate your NetSuite ERP system — create customers, run reports, query data, all in natural language.

**You only need to do three things:**
1. Configure an integration in your NetSuite backend (~10 min)
2. Download this tool and run one command (~1 min)
3. Fill in 3 fields in a browser and authorize (~30 sec)

After that, you can say to your AI: "List all subsidiaries", "Run the trial balance report", and the AI will automatically call NetSuite's 17 tools.

### How does it work?

```
You → AI Assistant
         │
         ▼
    This Connector (auto-manages Token)
         │
         ▼
    NetSuite Official MCP Service
    (17 tools: record CRUD, SuiteQL, reports, etc.)
```

**Key advantages:**
- **Zero dependencies**: Pure Node.js built-in modules, no `npm install` needed
- **Auto-refreshing tokens**: Tokens are renewed automatically, no manual intervention
- **Secure**: Credentials stored in local file (permission 600), not leaked to config files
- **One-click setup**: Fill 3 fields in a browser, OAuth authorization is fully automatic

---

## Complete Installation Guide (Step by Step)

### Step 1: Configure Integration in NetSuite Backend

> This step is done in your NetSuite web backend and requires admin access.
> **Estimated time: 10 minutes**

#### 1.1 Enable OAuth 2.0

1. Log in to NetSuite → top menu `Setup > Company > Enable Features`
2. Click the **SuiteCloud** tab
3. Find **OAuth 2.0** and check it
4. Click **Save**

> Skip this step if already enabled.

#### 1.2 Create an Integration

1. Top menu `Setup > Integration > Manage Integrations > New`
2. Fill in the form:

| Field | What to enter | Notes |
|---|---|---|
| Name | `AI Assistant MCP` | Any name you'll recognize |
| **Authorization Code Grant** | ✅ Check | **Must be checked** |
| **Public Client** | ✅ Check | **Must be checked** |
| Audience | ✅ `NetSuite Service Endpoint Runtime` | Check this |
| Scopes | ✅ `NetSuite AI Connector Service` | Check this |
| Redirect URI | `http://127.0.0.1:38271/callback` | Copy-paste exactly |
| Token Lifetime | `3600` | Default is fine, can increase |

3. Click **Save**
4. **Copy the Client ID and Client Secret immediately** (they won't be shown again!)

> ⚠️ **Two must-check boxes**: `Authorization Code Grant` and `Public Client`. Missing either one will cause connection failure.

#### 1.3 Install MCP Standard Tools SuiteApp

1. Top menu `Customization > SuiteBundler > Search & Install Bundles`
2. Search for `MCP Standard Tools`
3. Click **Install** and wait for completion

> Without this bundle, the connection succeeds but returns 0 tools.

#### 1.4 Create a Dedicated Role (Cannot use Administrator!)

> Oracle's official documentation explicitly states: **"Administrator role does not work for AI Connector Service."**

1. Top menu `Setup > Users/Roles > Manage Roles > New`
2. Role name: `MCP User` (or any name)
3. In the Permissions tab, add:

| Permission Category | Permission Name | Level |
|---|---|---|
| Setup | **MCP Server Connection** | Full |
| Setup | **Log in using OAuth 2.0 Access Tokens** | Full |
| Setup | **REST Web Services** | Full |

4. Click **Save**
5. Assign this role to a user: `Setup > Users/Roles > Assign Access Roles`
6. **Remember this user's login and password** — you'll use it for authorization

> ✅ Step 1 complete! You now have: Client ID, Client Secret, and a non-admin user with proper permissions.

---

### Step 2: Download and Install This Tool

> **Estimated time: 1 minute**
> **Prerequisite: Node.js 18+ installed on your computer**

#### 2.1 Check Node.js

Open Terminal (macOS: `Cmd+Space`, search "Terminal"), type:

```bash
node --version
```

If the version is >= 18, continue. If not installed or too old, download from https://nodejs.org.

#### 2.2 Clone the project

```bash
git clone https://github.com/letian940-prog/ns-mcp-china.git
cd ns-mcp-china
```

> No `npm install` needed! This tool has zero external dependencies — clone and run.

> ✅ Step 2 complete! The project is downloaded to your computer.

---

### Step 3: Run the Setup Wizard and Connect to NetSuite

> **Estimated time: 30 seconds**

In the terminal, run:

```bash
node bin/ns-mcp-connector.js --setup
```

Your browser will automatically open a configuration page. Follow these steps:

1. Fill in the 3 fields in the form:

| Field | What to enter | Example |
|---|---|---|
| **服务端点 URL** (Endpoint URL) | Your NetSuite MCP endpoint | `https://td3065115.suitetalk.api.netsuite.com/services/mcp/v1/all` |
| **客户端 ID** (Client ID) | The Client ID from Step 1 | `3cdf5429...` |
| **客户端密钥** (Client Secret) | The Client Secret from Step 1 | `91df2789...` |

> Replace `td3065115` in the URL with your NetSuite Account ID.

2. Click the **"连接" (Connect)** button
3. Browser redirects to NetSuite's authorization page
4. **Log in with the non-admin user** you created in Step 1.4
5. Click **Authorize**
6. Page redirects back to localhost, showing "连接成功！" (Connection successful!)

**The connector automatically:**
- Completes the OAuth 2.0 authorization flow
- Saves tokens to `~/.ns-mcp/tokens.json` (permission 600)
- Updates `~/.workbuddy/mcp.json` configuration file

> ✅ Step 3 complete! Tokens saved, configuration written.

---

### Step 4: Restart Your AI Assistant and Verify

#### 4.1 Fully Quit Your AI Assistant

- **Your AI assistant**: fully quit (not just close the window!), then reopen
- **Claude Desktop**: Fully quit and reopen
- **Cursor**: Restart the app

#### 4.2 Trust the Connector

Go to **Settings → Connectors → Custom Connectors**, find `netsuite-mcp`, click **Trust**.

#### 4.3 Test the Connection

Type in your AI chat:

> "查询 NetSuite 的所有 subsidiary" (List all NetSuite subsidiaries)

If the AI returns a list of subsidiaries from NetSuite, the connection is successful!

> ✅ All done! You can now operate NetSuite using natural language anytime.

---

## Troubleshooting

### Browser shows `page_not_found`

**Cause**: OAuth 2.0 not enabled, or wrong Integration type.

**Fix**:
1. Verify `Setup > Company > Enable Features > SuiteCloud` has OAuth 2.0 checked
2. Verify the Integration has `Authorization Code Grant` checked (not just Client Credentials)
3. Verify `Public Client` is checked

### `redirect_uri_mismatch` error

**Cause**: Redirect URI in NetSuite doesn't match.

**Fix**: Ensure the Redirect URI is exactly `http://127.0.0.1:38271/callback`.

### Port 38271 already in use

```bash
# Find what's using the port
lsof -i :38271
# Kill the process
kill -9 <PID>
```

Then re-run setup.

### Connection succeeds but 0 tools

**Cause**: MCP Standard Tools SuiteApp not installed.

**Fix**: `Customization > SuiteBundler > Search & Install Bundles` → Search `MCP Standard Tools` → Install.

### Authorization succeeds but API calls return 401

**Cause**: Used Administrator role for authorization.

**Fix**: Create a non-admin role (permissions: MCP Server Connection + OAuth 2.0 Access Tokens + REST Web Services), re-run `--setup` and authorize as that user.

### Token expired?

**Don't worry!** The connector automatically refreshes tokens using refresh_token. If the refresh token also expires, the connector automatically opens the browser for re-authorization.

If all else fails, reset manually:

```bash
rm ~/.ns-mcp/tokens.json
node bin/ns-mcp-connector.js --setup
```

---

## Available Tools (17)

After connecting, your AI assistant can call these tools:

| Category | Tool | Description |
|---|---|---|
| **Records** | `ns_createRecord` | Create a record (customer, order, invoice, etc.) |
| | `ns_getRecord` | Retrieve a record by internal ID |
| | `ns_updateRecord` | Update fields on an existing record |
| **SuiteQL** | `ns_runCustomSuiteQL` | Execute a custom SuiteQL query with pagination |
| | `ns_getSuiteQLMetadata` | Discover available tables and column definitions |
| **Saved Searches** | `ns_listSavedSearches` | List saved searches, optionally filtered |
| | `ns_runSavedSearch` | Execute a saved search by ID |
| **Reports** | `ns_listAllReports` | List all available financial and operational reports |
| | `ns_runReport` | Run a report (trial balance, P&L, AR/AP aging, etc.) |
| | `ns_report_filters_app` | Get available filter options for reports |
| **Metadata** | `ns_getRecordTypeMetadata` | Get field definitions and sublists for a record type |
| | `ns_getSubsidiaries` | List all subsidiaries with currencies and hierarchy |
| | `ns_getAccountingBooks` | List accounting books (primary and secondary) |
| | `ns_getAccountingContexts` | List accounting contexts for multi-currency |
| | `ns_getNexusIds` | List tax nexus records by country |
| **Interactive** | `ns_prompt_library_app` | Browse pre-built prompt templates |
| | `ns_selector_app` | Discover valid record types and their key fields |

---

## Other AI Assistants

### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "netsuite-mcp": {
      "command": "node",
      "args": ["/your/path/to/ns-mcp-china/bin/ns-mcp-connector.js"],
      "env": {
        "NETSUITE_MCP_URL": "https://YOUR_ACCOUNT_ID.suitetalk.api.netsuite.com/services/mcp/v1/all",
        "NETSUITE_CLIENT_ID": "YOUR_CLIENT_ID",
        "NETSUITE_CLIENT_SECRET": "YOUR_CLIENT_SECRET"
      }
    }
  }
}
```

### Cursor

Edit `.cursor/mcp.json` with the same format.

> When env variables are set, the connector can auto-trigger OAuth on first run without `--setup`.

### Kimi Work (Moonshot desktop agent) ✨ One command

After completing `--setup` once, just run:

```bash
node bin/ns-mcp-connector.js --kimi
```

It writes the connector into Kimi Work's MCP config:

```
~/Library/Application Support/kimi-desktop/daimon-share/daimon/runtime/kimi-code/home/mcp.json
```

Then **fully quit and restart Kimi Work** and start a new session. Tokens are shared across AI clients (`~/.ns-mcp/tokens.json`) — a refresh from either client works for both.

You can also write the file manually (Windows: `%APPDATA%\kimi-desktop\daimon-share\daimon\runtime\kimi-code\home\mcp.json`, or set the `KIMI_WORK_HOME` environment variable for a custom path):

```json
{
  "mcpServers": {
    "netsuite": {
      "command": "node",
      "args": ["/your/path/ns-mcp-china/bin/ns-mcp-connector.js"],
      "env": {}
    }
  }
}
```

> Tip: if a Kimi Work update wipes the config, just run `--kimi` again.

---

## How It Works

### Three Modes, One File

| Mode | Command | Purpose |
|---|---|---|
| **Setup** | `node bin/ns-mcp-connector.js --setup` | Web UI for first-time configuration |
| **Kimi Work install** | `node bin/ns-mcp-connector.js --kimi` | Install into Kimi Work |
| **Proxy** | `node bin/ns-mcp-connector.js` (called by AI assistant) | Forwards MCP messages + manages tokens |

### Token Lifecycle

```
access_token (60min) ──expires──> refresh_token ──auto──> new access_token
                                         │
                                    also expires
                                         │
                                         ▼
                               Connector opens browser
                               for re-authorization
```

### Security

- Tokens stored in `~/.ns-mcp/tokens.json` with permission `600`
- `mcp.json` contains **no credentials** — only a path to the connector script
- All OAuth traffic goes through `localhost:38271` callback
- Zero external dependencies — no supply chain risk

---

## Development

```bash
npm install      # Install TypeScript deps (for src/ legacy server)
npm run build    # Compile TypeScript
npm run dev      # Watch mode
```

The connector (`bin/ns-mcp-connector.js`) is plain JavaScript with zero dependencies — it can be edited and run directly without compilation.

## Project Structure

```
ns-mcp-china/
├── bin/
│   ├── ns-mcp-connector.js    # Main connector (zero deps)
│   └── ns-mcp-setup.js        # Legacy CLI version (kept for compat)
├── src/                        # Legacy TypeScript MCP server
│   ├── index.ts
│   ├── netsuite-client.ts
│   └── tools/
├── server.json                 # MCP Registry description
├── package.json
└── README.md
```

## License

MIT