Shiftyasan Shift Scheduling

@shiftyasan/mcp-server

Shiftyasan 公開ソルバー API 用の Model Context Protocol（MCP）サーバーです。 AI エージェント（Claude Desktop、Cursor、Continue など）が、MCP 対応ホストからシフト作成 ソルバーを呼び出せます。

ステータス： オープンベータ — validate_shift_input、solve_shift、get_solve_job （大規模な問題向けの非同期ポーリング）に対応しています。使用状況のクエリ（get_usage）は近日対応予定です。

---

ほとんどの方には、このパッケージは不要になりました

Shiftyasan では現在、リモート MCP サーバーを運用しています。こちらが推奨される接続方法です。

https://api.shiftyasan.com/mcp

	リモート（推奨）	この npm パッケージ
Node.js	不要	20 以降が必要
API キー	接続時に自動発行	自分で作成して貼り付け
アップデート	サーバー側で行われるため、対応不要	パッケージを更新
Claude.ai（ウェブ）／ChatGPT	利用可能	ローカルプロセスを実行できません

Claude.ai または ChatGPT から接続すると、ブラウザーで Shiftyasan のサインインページが開きます。一度承認すれば完了です。 接続はいつでもダッシュボードの「Connected apps」から取り消せます。

このパッケージも引き続きサポートされます。既存の設定もそのまま動作します。サーバーをローカルで実行したい場合は、こちらをお使いください。たとえば、インターネットに直接接続できないホストで使う場合や、自分で API キーを管理したい場合に適しています。

リモート接続の設定については、クイックスタートをご覧ください。

---

Shiftyasan とは？

Shiftyasan は、制約最適化エンジンを使用して、企業（小売、飲食、医療など）の勤務シフトを自動生成する SaaS です。同じソルバーは、https://api.shiftyasan.com/v1/public/* の公開 HTTP API として提供されています。この MCP サーバーは、API を AI エージェントが利用できる、検出可能なツールに変換する薄いクライアントラッパーです。

開発者向けドキュメント（クイックスタート、対応する制約の全一覧、料金）は、https://platform.shiftyasan.com（日本語・英語）でご覧いただけます。

ツール

ツール	説明	課金対象？
validate_shift_input	公開 API のスキーマに照らして SolveRequest ペイロードを検証します（ソルバーは実行しません）。	いいえ
solve_shift	ソルバーを実行します。小規模・中規模の問題は同期的に結果を返します。大規模な問題（従業員がおよそ 25 人以上）はキューに追加され、job_id とともに 202 を返します。	はい
get_solve_job	非同期ジョブが completed または failed になるまでポーリングします。	いいえ

SolveRequest／SolveResponse の完全なスキーマは、GET <base URL>/v1/public/openapi.json の OpenAPI 仕様にあります（ベース URL = SHIFTYASAN_BASE_URL、デフォルトは https://api.shiftyasan.com）。

プロンプト

プロンプト	説明
plan_shift	エージェントにスケジュールの作成手順を案内します。ユーザーに何を尋ねるか、いつ検証するか、完成した勤務表をどのように提示するかを説明します。

どちらの引数（period、context）も省略可能なため、引数なしで呼び出せます。Claude Code では /mcp__shiftyasan__plan_shift として表示されます。他のホストでは、それぞれの UI にプロンプトが表示されます。

エージェントに推測させるのではなく、必要な情報を尋ねてもらいたい場合や、前回の試行で、ひと目で確認できない勤務表が生成された場合に使ってください。このプロンプトは、1 人につき 1 行を表示し、右側に個人ごとの合計を示すようエージェントに指示します。シフト管理者が最初に確認するのはこの情報です。

サーバーは、initialize の応答でもワークフローのガイダンスを送信します（solve_shift の前に validate_shift_input を呼び出すこと、202 の場合は get_solve_job をポーリングすること、要員不足マーカーと実行不可能の診断結果の読み方など）。ホストはこれをモデルのシステムプロンプトに追加することがあります。Claude Code は追加しますが、Claude Desktop は現在追加しません。そのため、同じ実行順序のルールがツールの説明にも記載されています。

スキーマでは受け付けるものの、ソルバーではまだ適用されない制約

API で受け付けられても、ソルバーに相当する機能がないため、変換時に破棄されるフィールドがいくつかあります。validate_shift_input と solve_shift は、破棄されたフィールドを正確に列挙した明示的な警告を出力するため、エージェントがそれらを適用済みとして報告することはありません。

フィールド	状態	回避策
employees[].preferences[].type: "avoided_shift"	適用されません	該当するシフトをその従業員の assignable_shift_ids から削除します（強制）。または、代わりに割り当てるシフトを preferred_shift で指定します
employees[].working_days_per_week.max	min のみ使用されます	対象期間の上限には working_days_per_month を使用します
constraints.employee_pairings[].rule: "require"	適用されません（exclude のみ機能します）	fixed_assignments を使って、同じシフトに配置します

これ以外のスキーマの項目はすべて、ソルバーで適用されます。

インストール

ローカルで実行するには、Node.js 20 以降が必要です。Node.js を自分で管理したくない場合は、代わりに リモートサーバーを使用してください。

npx から直接使用できます（グローバルインストールは不要です）。

npx -y @shiftyasan/mcp-server

MCP Registry では com.shiftyasan/mcp-server としても掲載されています。

または、グローバルにインストールします。

npm install -g @shiftyasan/mcp-server
shiftyasan-mcp-server

セットアップ

1. API キーを取得する

セルフサービスダッシュボードで sk_live_... キーを発行します。 https://platform.shiftyasan.com/dashboard/（既存の Shiftyasan アカウントを使用できます。新規登録も可能です）。 問題が発生した場合は、[email protected] までメールでお問い合わせください（日本語または英語）。

このトークンはパスワードと同様に扱ってください。ソルバーの利用枠にアクセスできるようになります。

ベータ版に関する注意： デフォルトとは異なるベース URL が提供される場合があります。 SHIFTYASAN_BASE_URL で設定してください（下記を参照）。

2. MCP ホストを設定する

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json （macOS）または %APPDATA%/Claude/claude_desktop_config.json（Windows）を編集します。

{
  "mcpServers": {
    "shiftyasan": {
      "command": "npx",
      "args": ["-y", "@shiftyasan/mcp-server"],
      "env": {
        "SHIFTYASAN_API_KEY": "sk_live_..."
      }
    }
  }
}

Claude Desktop を再起動します。shiftyasan サーバーがツールメニューに表示され、validate_shift_input、solve_shift、get_solve_job が利用できるようになります。

Claude Code

claude mcp add shiftyasan -e SHIFTYASAN_API_KEY=sk_live_... -- npx -y @shiftyasan/mcp-server

（ベータ版のベース URL を受け取っている場合は、-e SHIFTYASAN_BASE_URL=... を追加します。）

Cursor / Continue / その他の MCP ホスト

同じ形式（command + args + env）で、MCP サーバー設定に追加します。 正確な設定ファイルのパスについては、ご利用のホストのドキュメントを参照してください。

ChatGPT からの利用

ChatGPT はこのパッケージのようなローカル stdio MCP サーバーを起動できないため、Actions を使用するカスタム GPT を通じて HTTP API を直接利用してください（OpenAPI 仕様は Actions 互換となるよう設計されており、スキーマはすべてインライン化され、外部参照はありません）。

1. ChatGPT → GPT を探す → GPT を作成 → 設定 → Actions → URL からインポートを選択し、 <base URL>/v1/public/openapi.json を入力します（base URL = API キーとともに受け取った URL。 デフォルトは https://api.shiftyasan.com）。

2. ベータ版のベース URL を受け取っている場合は、インポートしたスキーマの servers[0].url も <base URL>/v1/public に編集します。

3. 認証 → API Key → 認証タイプ Bearer → sk_live_... トークンを貼り付けます。

4. GPT への指示の例：

   Shiftyasan のアクションを使って、最適化された勤務シフトを作成できます。 必ず最初に検証アクション（無料）を呼び出してから、solve を実行してください。大規模な問題では job_id とともに 202 が返されます。ステータスが "completed" または "failed" になるまで、約 15 秒ごとにジョブエンドポイントをポーリングしてください。

注：カスタム GPT の作成には有料の ChatGPT プランが必要です。また、API キーは GPT 内に保存されるため、その GPT を一般公開しないでください。

ChatGPT の MCP コネクターがサポートしているのはホスト型 MCP エンドポイント（Streamable HTTP）のみで、ローカルの stdio プロセスには対応していません。ホスト型 MCP エンドポイントはロードマップに含まれています。それまでは、上記の Actions をご利用ください。

環境変数

変数	必須	説明
SHIFTYASAN_API_KEY	はい	Bearer API キー。形式：sk_(live|test)_<64 hex chars>。
SHIFTYASAN_BASE_URL	いいえ	ベース URL を上書きします（デフォルトは https://api.shiftyasan.com）。ステージングやセルフホストに便利です。

セッション例

Claude Desktop を設定した後：

あなた： Shiftyasan を使って、6 月の最初の週に 3 人の従業員の朝番と夕番のシフトを組んでください。

Claude はツールを検出し、validate_shift_input を呼び出して構築したペイロードが受け入れ可能であることを確認してから、solve_shift を呼び出して割り当てを取得します。API エラー（RFC 7807）はインラインで表示されるため、Claude は自己修正できます（例：「staffing_demand の長さは schedule_days と一致する必要があります」）。

料金

オープンベータは無料です。 各 API キーには無料利用枠があります（solve_shift は呼び出しごとにユニットを消費します。validate_shift_input は常に無料です）。 キーを使って GET /v1/public/usage を実行すると、残りの利用枠を確認できます。 使い切った場合は、[email protected] にメールして追加分をお申し込みください。

ベータ終了後に有料プランを提供する予定です。MCP サーバー自体に料金はかかりません。使用量の計測はすべて、API 側で SHIFTYASAN_API_KEY に対して行われます。

ローカル開発

git clone https://github.com/shiftyasan/mcp-server.git
cd mcp-server
npm install
npm run build
npm test

ローカルゲートウェイに接続して実行するには：

SHIFTYASAN_API_KEY=sk_test_... \
SHIFTYASAN_BASE_URL=http://localhost:8080 \
  npm run dev

MCP inspector を使って対話的にテストします：

npx @modelcontextprotocol/inspector node dist/index.js

問題の報告

• MCP サーバーのバグや機能リクエスト：https://github.com/shiftyasan/mcp-server/issues
• 基盤となる API の問題：[email protected] までお問い合わせください

ライセンス

MIT — LICENSE を参照してください。