# 楽楽販売 MCPサーバー

楽楽販売(RAKUS)のAPI連携マニュアル(2025/02, 第15版)に基づき、以下のAPIをClaudeの「カスタムコネクタ」から呼び出せるようにするMCPサーバーです。

- ファイルアップロード / CSVファイルインポート / CSVデータインポート / CSVインポート状況確認 / CSVエクスポート
- レコード登録 / 更新 / 削除 / 参照

## 事前準備(楽楽販売 側)

1. **API連携オプション契約** ＋ **IPアクセス制限の設定**が必須です(マニュアル1章・5章)。
   デプロイ先サーバーの送信元IPを、管理者設定＞セキュリティ設定タブ＞IPアクセス制限に関する設定 で許可してください。
   (Renderなど固定IPを持たないPaaSの場合、静的Outbound IPアドオンの利用が必要になることがあります)
2. ユーザ設定画面でAPIトークンを発行・確定します(マニュアル3章)。
3. 各DBの「dbSchemaId」「importId」「項目ID」などは、管理者設定＞メンテナンス機能タブ＞APIパラメータ情報 から確認してください。

## デプロイ手順(Render・詳細版)

初めてPaaSを使う方向けに、GitHubへのpushからClaudeへの接続まで一気通貫の手順を
**[RENDER_DEPLOY.md](./RENDER_DEPLOY.md)** にまとめています。まずはこちらをご覧ください。
`render.yaml` を使ったBlueprintデプロイに対応しています。

要点だけ書くと:

1. このフォルダをGitHubリポジトリにpush
2. RenderでBlueprint(`render.yaml`)からWeb Serviceを作成(プランは`starter`以上)
3. 環境変数に `RAKURAKU_DOMAIN` / `RAKURAKU_ACCOUNT` / `RAKURAKU_API_TOKEN` / `MCP_SHARED_SECRET` を設定
4. Settings画面で「Static Outbound IP Addresses」を有効化し、表示された固定IPを楽楽販売のIPアクセス制限に登録
5. `https://<デプロイ先>.onrender.com/mcp` をClaudeのコネクタURLとして登録

Render以外(Railway / Fly.io / 自前VPS + PM2 など)でも、Node.js 18以上が動く環境であれば同様の手順でデプロイできます。

## Claude側のコネクタ設定

1. Claude.aiの設定画面で「カスタムコネクタを追加」を開きます。
2. 各項目を入力します。
   - 名前: 任意(例: 楽楽販売)
   - リモートMCPサーバーURL: `https://<デプロイ先>/mcp`
   - OAuth Client ID / Secret: 空欄でOK(このサーバーは簡易な共有シークレット方式のため)
3. `MCP_SHARED_SECRET` を設定した場合は、コネクタがヘッダ `Authorization: Bearer <MCP_SHARED_SECRET>` を送信できるように設定してください
   (現在のClaude.aiのカスタムコネクタUIでは追加ヘッダを直接指定できないことがあります。その場合は `MCP_SHARED_SECRET` を空にして運用するか、
   IPアクセス制限や独自の認証ミドルウェアで保護してください)。
4. 「追加」をクリックして接続します。

## ローカル動作確認

```bash
npm install
cp .env.example .env
# .env を編集して RAKURAKU_DOMAIN / RAKURAKU_ACCOUNT / RAKURAKU_API_TOKEN を設定
npm start
```

別ターミナルから疎通確認:

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```

## 提供ツール一覧

| ツール名 | 対応API | 説明 |
|---|---|---|
| rakuraku_file_upload | ファイルアップロードAPI | 一時領域にファイルをアップロード(fileId取得) |
| rakuraku_csv_file_import | CSVファイルインポートAPI | アップロード済みファイルをインポート予約 |
| rakuraku_csv_data_import | CSVデータインポートAPI | アップロードと予約を同時実行 |
| rakuraku_csv_import_status | CSVインポート状況確認API | インポート進捗・結果確認 |
| rakuraku_csv_export | CSVエクスポートAPI | レコードをCSVで取得 |
| rakuraku_record_create | レコード登録API | レコード新規登録 |
| rakuraku_record_update | レコード更新API | レコード更新(明細行更新含む) |
| rakuraku_record_delete | レコード削除API | レコード削除 |
| rakuraku_record_get | レコード参照API | レコード1件参照 |

## 注意事項

- レコード登録/更新API等の `values` に指定する項目ID(例: "105110")は、DBごとに異なります。事前に「APIパラメータ情報」画面で確認し、
  Claudeに「このDBの項目IDは〇〇です」と伝えてから操作を依頼してください。
- 楽楽販売APIには1分間20リクエストの制限があります(マニュアル5章)。大量データを扱う際はご注意ください。
- `RAKURAKU_API_TOKEN` は第三者に共有しないでください。デプロイ先の環境変数(Secret)機能を使い、コードやGitリポジトリに直接書かないことを推奨します。