SuperSaaS Slots

SuperSaaS slots MCP サーバー

公開されている SuperSaaS スケジュールの空き枠を確認する、読み取り専用の MCP サーバーです。日中の予約、宿泊レンタルのような日付のみのスケジュール、クラスごとの定員を設定した定員制スケジュールに対応しています。SuperSaaS のスケジュール URL、または https://www.down-the-hatch.nl/reserveren/ のようにスケジュールへのリンクがある店舗ページを指定してください。アカウントも API キーも不要です。

SuperSaaS 公式の MCP サーバーではありません。 SuperSaaS は https://www.supersaas.com/mcp で独自のサーバーを提供しており、OAuth またはアカウントごとのベアラートークンでアカウントとして認証します。このサーバーは、アカウントで可能なあらゆる操作（予約、ユーザー、料金、クレジット残高）の読み取りや変更ができます。AI アシスタントで自分のスケジュールを管理する場合は、そちらをお使いください。このパッケージが答えるのは別の質問です。つまり、認証情報を使わず、何にも触れることなく、他の人の公開スケジュール、または訪問者から見える自分のスケジュールに何が空いているかを確認します。匿名のブラウザーで読み込めるページだけを読み取り、予約は行いません。また、いかなる種類のアカウントも必要ありません。どちらの立場かに応じて選んでください。SuperSaaS のサーバーは店舗のレジで、こちらはショーウィンドウです。

MIT License の下でライセンスされています。スケジュールデータの読み取り方法については、INTERNALS.md に記載されています。

インストール

公開後は、Python 3.10 以降を使用してください。

pip install supersaas-slots-mcp

プロジェクトディレクトリからローカル開発を行う場合：

python3 -m venv .venv
.venv/bin/python -m pip install -e .

依存関係は pyproject.toml で宣言されており、FastMCP はバージョン 4.0.10 に固定されています。supersaas-slots と supersaas-slots-mcp のどちらでもサーバーを起動できます。

接続

MCP クライアントに stdio MCP サーバーを設定してください。

{
  "mcpServers": {
    "supersaas-slots": {
      "command": "/absolute/path/to/supersaas-mcp/.venv/bin/supersaas-slots"
    }
  }
}

コマンドのパスを、プロジェクトディレクトリの絶対パスに置き換えてください。クライアントでは、このローカルプロセスによる www.supersaas.nl、www.supersaas.com、www.supersaas.co.uk への HTTPS リクエストを許可する必要があります。

または、PyPI から uvx を使って実行します。

{
  "mcpServers": {
    "supersaas-slots": {
      "command": "uvx",
      "args": ["supersaas-slots-mcp"]
    }
  }
}

ツール

find_available_slots

{
  "schedule_url": "https://www.supersaas.nl/schedule/downthehatch/SLEEP",
  "from_date": "2026-10-19",
  "through_date": "2026-10-25"
}

パラメーター	デフォルト	備考
schedule_url	必須	supersaas.nl、supersaas.com、supersaas.co.uk 上の SuperSaaS /schedule/ URL、またはその URL だけにリンクしているサードパーティのページです。www.、m.、d. の各ホストを受け付け、正規の www. URL として報告します。
from_date	必須	YYYY-MM-DD 形式で、指定日を含みます。
through_date	必須	YYYY-MM-DD 形式で、指定日を含みます。最大 366 日です。
max_results	500	返される slots リストの上限です。count は常に全件数です。
respect_booking_window	true	スケジュールの最小・最大予約可能期間を適用します。過去のデータを確認する場合は false に設定してください。

schedule_url の代わりに店舗ページを指定することもできます。サーバーはそのページをスキャンして SuperSaaS スケジュールへのリンクを探し、そのリンク先を開いて、参照元を linked_from として報告します。HTML にリンクの記載がない場合（シングルページサイトではリンクがバンドルされたスクリプト内にあることがあります）、同一オリジン内に限定し、最初の 10 個のスクリプトを対象として、ページ自身の JS ファイルもスキャンします。

応答

{
  "schedule_url": "https://www.supersaas.nl/schedule/downthehatch/SLEEP",
  "from_date": "2026-10-19",
  "through_date": "2026-10-25",
  "time_basis": "schedule wall time; epoch values interpreted as UTC",
  "unit": "slot",
  "duration_minutes": 180,
  "count": 1,
  "truncated": false,
  "slots": [{ "start": "2026-10-22 09:30", "end": "2026-10-22 12:30" }]
}

時刻はスケジュールの壁時計時刻を表す文字列で、形式は YYYY-MM-DD HH:MM です。truncated が示すのは slots のみなので、リストが完全だと判断する前に count と比較してください。呼び出しのたびにデータを再取得するため、他の人が予約すると結果が変わります。

unit は slot、night、または class です。予約スケジュールは、予約の長さに設定された duration_minutes とともに slot を返します。レンタルなどの日付単位のスケジュールは night を返し、次の3つのフィールドが追加されます。

{
  "unit": "night",
  "duration_minutes": 1440,
  "check_in": "14:00",
  "check_out": "12:00",
  "slots": [{ "start": "2026-10-05 14:00", "end": "2026-10-06 12:00" }],
  "stays": [{ "start": "2026-10-05", "end": "2026-10-10", "nights": 5 }]
}

slots の各エントリーは1泊分で、ある日のチェックインから翌日のチェックアウトまでを表します。duration_minutes は標準的な1泊分の1440分です。stays では、連続して空いている宿泊日を実際に予約できる期間にまとめるため、連続する4泊分は1つの4泊の滞在になります。1泊ごとの料金を提示する場合は slots を、顧客に日付範囲を提示する場合は stays を使用してください。

Jazzercise などの定員制スケジュールは、unit: "class" と、通常の空席があるクラスごとに1つのエントリーを返します。

{
  "unit": "class",
  "slots": [{
    "id": 101,
    "start": "2026-10-01 19:00",
    "end": "2026-10-01 20:00",
    "title": "CardioSculpt",
    "location": "Village Hall",
    "capacity": 40,
    "booked": 32,
    "waiting": 0,
    "available": 8
  }]
}

クラスの id は SuperSaaS のスロット ID です。定員が無制限のクラスでは、capacity と available は null になります。SuperSaaS は待機リストの人数を booked に含めるため、available は capacity - booked + waiting です。通常の空席がないクラスは、スケジュールで待機リストを提供していても除外されます。クラスの長さは変動するため、このモードではトップレベルの duration_minutes はありません。

エラー

すべてのエラーには原因が示されており、ほとんどの場合は対処方法も記載されています。

エラー	対処方法
ページで訪問者にリソースの選択を求めている	.../Meeting_Rooms/Room_1 や .../Rental_Homes/House_1 のように、リソースの URL を1つ指定してください。
ページに複数のスケジュールへのリンクがある	メッセージに一覧表示されます。対象のスケジュールを直接指定してください。
スケジュールがログインの背後にある	対処方法はありません。スケジュールは公開されていません。
定員制スケジュールに公開スロットがない	ログインしないと、スケジュールのクラスデータは公開されません。
これはサービススケジュールです	共有スタッフの対応時間に予約するサービスのカタログです。対処方法はありません。
スケジュールに開始時刻のグリッドが定義されていない	訪問者が独自に開始時刻と終了時刻を選ぶため、固定のグリッドはありません。対処方法はありません。
スケジュールが複数日にまたがる単位で予約される	2日以上の商品です。対処方法はありません。
スケジュールには営業時間が公開されているが、開始時刻がない	対処方法はありません。スロットはリクエストごとに生成されます。
URL が公開された SuperSaaS HTTPS ページではない	認証情報やカスタムポートを指定せず、https:// を使用してください。

対応範囲

対応対象：単一のリソース、固定の予約時間、曜日ごとの例外やブロック時間を含む週単位の営業時間、予約済みの予定、バッファ時間、予約可能期間の制限、および slot と night の両方の単位を持つ、公開リソーススケジュールです。公開定員制スケジュールでは、各クラスのタイトル、場所、定員、予約済み人数、待機人数、残席数を含む、空席のあるクラスが一覧表示されます。

SuperSaaS には3種類のスケジュールがあり、サービススケジュールは非対応として報告されます。また、定期ルール、ユーザーごとの制限、最短宿泊日数のルール、支払いに依存する空き状況はモデル化されません。空きスロットは計算された候補であり、予約が保証されるわけではありません。予約時には予約ページが正確な情報となります。

開発

.venv/bin/python -m unittest -v test_supersaas_mcp.py
.venv/bin/python check_release.py

テストでは、実際の3つのリソーススケジュールの保存コピーと Jazzercise の定員制レスポンスを使ってオフラインで実行するため、顧客の予約によって結果が変わることはありません。各フィクスチャで固定される内容については、INTERNALS.md を参照してください。

リリース

リリースには、PyPI Trusted PublishingとMCP Registry GitHub OIDCを使用します。初回リリースの前に、次の手順を実行してください。

1. このGitHubリポジトリにpypi環境を作成し、バージョンタグからのデプロイを許可します。PyPIで、オーナーRichieB2B、リポジトリsupersaas-slots-mcp、ワークフローrelease.yml、環境pypiを指定して、保留中のTrusted Publisherを登録します。PyPIプロジェクトはまだ作成されていなくてもかまいません。
2. mcp-registry GitHub環境を作成し、バージョンタグからのデプロイを許可します。RegistryはGitHub OIDCを使用するため、レジストリトークンは不要です。
3. pyproject.toml、server.json（両方のバージョンフィールド）、FastMCPサーバーのコンストラクターでバージョンを一致させます。check_release.pyでこれを検証でき、候補タグを--tag v0.3.1で指定できます。タグを付ける前にリリースをコミットしてください。
4. 一致するタグをプッシュします。例：git tag v0.3.1 && git push origin v0.3.1。

リリースワークフローでは、ディストリビューションをテストしてビルドし、PyPIに公開した後、server.jsonをMCP Registryに送信します。CIワークフローでは、プッシュとプルリクエストの際にテストとパッケージのチェックを実行します。リリースタグをプッシュすると外部に公開されるため、事前にコミットと環境設定を確認してください。