# rakuten-rms-mcp

楽天市場 RMS（RMS WEB SERVICE）の公式 API を、AI から使えるようにする [Model Context Protocol](https://modelcontextprotocol.io/)（MCP）サーバです。

- **言語**: TypeScript
- **SDK**: [MCP TypeScript SDK v2](https://github.com/modelcontextprotocol/typescript-sdk)（`@modelcontextprotocol/server`）
- **接続方式**: いまは **stdio**（Cursor / Claude Desktop 向け）
- **対象 API**: 受注・購入商品・商品・在庫・クーポン・問い合わせ（公式 IF をほぼ網羅）
- **ライブラリ利用**: `createServer()` などを export（Remote MCP ラッパーから再利用可）

> ChatGPT 本体から使う場合は、別途 **HTTPS の Remote MCP** が必要です（npm 公開だけでは足りません）。HTTP / OAuth 本体は別リポ（例: `rakuten-rms-mcp-remote`）に置き、本パッケージはツール実装の供給側にします。

---

## できること

| 領域 | 例 |
|------|----|
| 受注運用 | 注文検索、確認、発送報告、メモ／備考、キャンセル、決済情報 |
| 売上の把握 | 日別売上、商品ランキング、キャンセル率 |
| 商品 | 検索、取得、登録／更新、価格変更、削除 |
| 在庫 | バリアント単位の取得・更新・一括操作 |
| クーポン | 検索・発行・更新・削除、サンキュークーポン |
| 問い合わせ | 件数・一覧・詳細・返信・既読／完了、添付 |

認証は RMS の **ESA** 方式です（`Authorization: ESA Base64(serviceSecret:licenseKey)`）。

---

## 必要条件

- Node.js **20** 以上
- RMS WEB SERVICE で発行した
  - `serviceSecret`（アプリ）
  - `licenseKey`（店舗）
- 問い合わせ返信を使う場合は、あわせて **店舗 ID**（`RMS_SHOP_ID`）

キーの取得・アプリ登録は、RMS の「WEB SERVICE」メニュー（サービス一覧・アプリ登録）を参照してください。

---

## インストール

```bash
git clone https://github.com/moneyan9/rakuten-rms-mcp.git
cd rakuten-rms-mcp
npm install
npm run build
```

将来 npm に公開されたあとは、`npx -y rakuten-rms-mcp` でも起動できます（現状はローカルビルドを推奨）。

### ライブラリとして使う（Remote ラッパー向け）

stdio を起動せず、ツール登録済みの `McpServer` だけ欲しい場合:

```ts
import { createServer, hasCredentials } from 'rakuten-rms-mcp';

const server = createServer(); // HTTP transport は呼び出し側で接続
```

公開 API（`package.json` の `exports["."]`）:

| export | 説明 |
|--------|------|
| `createServer` | 全 `rms_*` ツールを登録した MCP サーバを生成 |
| `createApis` | RMS API クライアント一式 |
| `loadConfig` / `hasCredentials` | 環境変数から認証情報を読む |

ローカル開発で未公開の本リポを参照する場合の例: `"rakuten-rms-mcp": "file:../rakuten-rms-mcp"`。

---

## 環境変数

| 変数 | 必須 | 説明 |
|------|------|------|
| `RMS_SERVICE_SECRET` | はい | アプリの serviceSecret |
| `RMS_LICENSE_KEY` | はい | 店舗の licenseKey |
| `RMS_SHOP_ID` | 返信時 | 問い合わせ返信 API で使う数値の店舗 ID |

サンプルは `.env.example` にあります。**Secret / Key を Git にコミットしないでください。**

---

## Cursor / Claude Desktop への接続

ローカルで動かす例:

```json
{
  "mcpServers": {
    "rakuten-rms": {
      "command": "node",
      "args": ["/絶対パス/rakuten-rms-mcp/dist/index.js"],
      "env": {
        "RMS_SERVICE_SECRET": "your_service_secret",
        "RMS_LICENSE_KEY": "your_license_key",
        "RMS_SHOP_ID": "123456"
      }
    }
  }
}
```

- Cursor: MCP 設定に上記を追加
- Claude Desktop: `claude_desktop_config.json` の `mcpServers` に同様に追加

接続確認はツール `rms_health`（認証環境変数の有無チェック）が便利です。

---

## ツール一覧

ツール名はすべて `rms_` で始まります。日付は基本的に `YYYY-MM-DD` です（省略時は今日基準のデフォルト）。

### 受注・購入商品

| ツール | 説明 |
|--------|------|
| `rms_search_orders` | 受注検索。条件に合う注文番号リストを返す |
| `rms_order_detail` | 注文番号から注文詳細を取得 |
| `rms_get_payment` | 決済情報を取得 |
| `rms_confirm_order` | 受注確認（確認待ち → 楽天処理中） |
| `rms_update_shipping` | 発送完了報告（同期） |
| `rms_update_shipping_async` | 発送完了報告（非同期・大量向け） |
| `rms_get_shipping_async_result` | 非同期発送の処理結果を確認 |
| `rms_get_sub_status_list` | サブステータス定義の一覧 |
| `rms_update_sub_status` | サブステータスを更新 |
| `rms_update_memo` | 店舗側のひとことメモを更新 |
| `rms_update_remarks` | 購入者向け備考を更新 |
| `rms_update_sender` | 送付先情報を更新（発送前） |
| `rms_update_sender_after_shipping` | 送付先情報を更新（発送後） |
| `rms_update_orderer` | 注文者情報を更新 |
| `rms_update_delivery` | 配送／お届け先情報を更新 |
| `rms_cancel_order` | 注文キャンセル（発送前） |
| `rms_cancel_order_after_shipping` | 注文キャンセル（発送後） |
| `rms_simulate_coupon_amount` | クーポン利用額のシミュレーション |
| `rms_unconfirmed_orders` | 注文確認待ち（progress=100）の一覧 |
| `rms_pending_shipping` | 発送待ち（progress=300）の一覧 |
| `rms_search_order_items` | 購入商品 API: 検索 |
| `rms_get_order_items` | 購入商品 API: 詳細取得 |

### 売上集計（Order API の結果を集計）

専用の「売上 API」はなく、受注データをこのサーバ側で集計します。

| ツール | 説明 |
|--------|------|
| `rms_daily_sales` | 日別の件数・売上・税・クーポン・送料 |
| `rms_product_ranking` | 商品別の数量・売上・平均単価ランキング |
| `rms_cancel_rate` | 期間内のキャンセル件数と率 |

### 商品（ItemAPI 2.0）

| ツール | 説明 |
|--------|------|
| `rms_search_products` | 商品検索（ページ単位） |
| `rms_all_products` | 全商品をページング取得して一覧化 |
| `rms_get_product` | 管理番号で 1 商品を取得 |
| `rms_bulk_get_products` | 複数管理番号の一括取得 |
| `rms_upsert_product` | 商品の新規登録／更新（upsert） |
| `rms_patch_product` | 商品の部分更新 |
| `rms_update_price` | バリアント価格の変更（よく使う PATCH の短縮形） |
| `rms_delete_product` | 商品削除 |
| `rms_get_inventory_related_settings` | 在庫関連設定の取得 |
| `rms_update_inventory_related_settings` | 在庫関連設定の更新 |

### 在庫（InventoryAPI 2.1）

| ツール | 説明 |
|--------|------|
| `rms_get_inventory` | 指定商品のバリアント在庫を一覧 |
| `rms_get_variant_inventory` | バリアント 1 件の在庫取得 |
| `rms_upsert_variant_inventory` | バリアント在庫の更新（単体） |
| `rms_delete_variant_inventory` | バリアント在庫の削除 |
| `rms_update_inventory` | 在庫の一括更新（ABSOLUTE） |
| `rms_bulk_get_inventory` | 在庫の一括取得 |
| `rms_bulk_get_inventory_range` | 在庫数の範囲指定で一括取得 |
| `rms_get_variant_lists` | 商品のバリアント一覧取得 |

### クーポン（CouponAPI / ThanksCoupon）

通常クーポンは XML IF、サンキュークーポンは REST 形式です。

| ツール | 説明 |
|--------|------|
| `rms_search_coupons` | クーポン検索 |
| `rms_get_coupon` | クーポンコードで取得 |
| `rms_issue_coupon` | クーポン発行 |
| `rms_update_coupon` | クーポン更新 |
| `rms_patch_coupon` | クーポン部分更新 |
| `rms_delete_coupon` | クーポン削除 |
| `rms_thanks_coupon_issue` | サンキュークーポン発行 |
| `rms_thanks_coupon_update` | サンキュークーポン更新 |
| `rms_thanks_coupon_stop` | サンキュークーポン停止 |
| `rms_thanks_coupon_get` | サンキュークーポン取得 |
| `rms_thanks_coupon_search` | サンキュークーポン検索 |

### 問い合わせ（InquiryManagementAPI）

| ツール | 説明 |
|--------|------|
| `rms_inquiries` | `action` で操作を切替: `count` / `list` / `detail` / `reply` / `mark_read` / `mark_complete` / `mark_incomplete` |
| `rms_inquiry_attachment_post` | 添付ファイルの登録 |
| `rms_inquiry_attachment_get` | 添付ファイルの取得 |

`reply` には `shop_id` 引数、または環境変数 `RMS_SHOP_ID` が必要です。

### その他

| ツール | 説明 |
|--------|------|
| `rms_health` | サーバ起動と認証環境変数の設定有無を確認 |

---

## 開発コマンド

```bash
npm run typecheck   # 型チェック
npm test            # 単体テスト
npm run build       # dist へビルド
npm start           # stdio で MCP サーバ起動
```

---

## 注意事項

- 本リポジトリは **非公式** です。楽天の仕様変更に追随できない場合があります。
- 書き込み系ツール（キャンセル、削除、価格変更など）は本番店舗に影響します。先にテスト店舗での確認を推奨します。
- QPS 制限や公式 IF の制約は、RMS WEB SERVICE の各 IF 定義に従ってください。
- ChatGPT Developer Mode 向けの Remote MCP（HTTP）は未実装です。

---

## ライセンス

MIT