harukibox

@harukibox/mcp

harukibox 用的 Model Context Protocol サーバーです。公式 Agent API を通じて、AI エージェントが代購の在庫、注文、購入者、発送を管理できます。

プロトコルバージョン

MCP 2026-07-28（ステートレス、server/discover、resultType、キャッシュ可能な tools/list）を実装しつつ、デュアル世代対応を維持しています。旧版の initialize ハンドシェイクにも引き続き応答します。

つまり、現在の Claude Desktop / Claude Code（まだ 2025-11-25 以前）も、設定を変更せずに引き続き利用できます。クライアントが 2026-07-28 にアップグレードされると、自動的に新しい経路を使用します。こちらも設定変更は不要です。

@modelcontextprotocol/sdk の最新バージョン 1.30.0 は依然として 2025-11-25 のままで、server/discover / resultType / CacheableResult に対応していません。そのため、このサーバーは SDK を介さず wire format を直接出力します（これにより、このパッケージはランタイム依存関係ゼロでもあります）。SDK が新版に対応したら、SDK に戻す予定です。

インストール

npm install -g @harukibox/mcp

または、プロジェクト内で：

npm install @harukibox/mcp

API トークンの取得

@harukibox/cli で OAuth を実行して取得します（有効期間は 90 日です）：

npm install -g @harukibox/cli
harukibox login           # PKCE，預設打開瀏覽器
# 或無 GUI 環境：
harukibox login --device  # device flow，顯示 user_code 讓你在瀏覽器輸入

実行すると、トークンは ~/.config/harukibox/config.json（mode 0600）に書き込まれます。このトークンを HARUKIBOX_TOKEN に設定してください。

Claude Desktop の設定

~/Library/Application Support/Claude/claude_desktop_config.json を編集します：

{
  "mcpServers": {
    "harukibox": {
      "command": "harukibox-mcp",
      "env": {
        "HARUKIBOX_TOKEN": "hrk_live_your_token_here"
      }
    }
  }
}

リフレッシュトークン（上級者向け、デフォルトでは無効）

長期間稼働する MCP プロセス（あまり再起動しない場合）では、リフレッシュを有効にできます：

"env": {
  "HARUKIBOX_TOKEN": "hrk_live_...",
  "HARUKIBOX_ENABLE_REFRESH": "1",
  "HARUKIBOX_REFRESH_TOKEN": "hrk_refresh_..."
}

⚠️ 制限事項：リフレッシュトークンのローテーション後、新しいリフレッシュトークンはプロセスメモリにのみ保持されます。プロセスを再起動すると、環境変数には古いリフレッシュトークンが残っているため、サーバーは再利用と見なして、そのユーザーのすべてのトークンを取り消します。再起動前に harukibox login を手動で実行し、新しいトークンを取得してください。本番環境ではこのオプションを無効にし、90 日の有効期限後に OAuth を再実行する方法を推奨します。

Claude Code の設定

claude mcp add harukibox --command harukibox-mcp --env HARUKIBOX_TOKEN=hrk_live_your_token_here

利用可能なツール

ツール	必要なスコープ	説明
haruki_me	me	現在のユーザー／組織／トークン情報を取得
haruki_list_products	products:read	商品を一覧表示
haruki_get_product	products:read	単一の商品を取得
haruki_create_product	products:write	商品を作成
haruki_list_registrations	registrations:read	注文を一覧表示
haruki_list_buyers	buyers:read	購入者を一覧表示
haruki_list_shippings	shippings:read	発送を一覧表示
haruki_search	search	全体検索

セキュリティ

• トークンはすべて環境変数で指定し、ディスクには書き込みません
• すべてのリクエストは HTTPS 経由で送信され、sha256 ハッシュ検証を伴います
• 有効期限切れ／取り消し済み／IP 許可リスト不一致の場合、リクエストは直ちに拒否されます
• 呼び出しは毎回サーバー側の監査ログに記録されます（Web UI での確認機能はありません。エクスポートが必要な場合はサービス提供者にお問い合わせください）

セルフホスト／プライベートデプロイ

HARUKIBOX_BASE_URL=https://your-instance.example.com/api/agent \
HARUKIBOX_TOKEN=hrk_live_... \
harukibox-mcp

ライセンス

MIT