SuperSaaS Slots

SuperSaaS 时段 MCP 服务

一个只读 MCP 服务，用于查询公开 SuperSaaS 日程中哪些时段有空。它支持日内预约、按日期安排的日程（例如过夜租赁），以及每堂课设有席位数的容量日程。提供 SuperSaaS 日程 URL，或链接到该日程的商家页面，例如 https://www.down-the-hatch.nl/reserveren/。无需账号或 API 密钥。

这不是 SuperSaaS 官方 MCP 服务。 SuperSaaS 提供自己的服务，地址为 https://www.supersaas.com/mcp，通过 OAuth 或每个账号专属的 bearer token 以你的账号进行身份验证，并且可以读取和更改该账号可操作的任何内容：预订、用户、价格、信用余额。如果你想用 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 请求。

或者使用 uvx 从 PyPI 运行：

{
  "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，或链接到恰好一个此类日程的第三方页面。接受 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 中没有此类链接（单页网站会将链接放在打包的脚本中），服务也会扫描页面自身的 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。预约日程返回 slot，并将 duration_minutes 设为预约时长。仅含日期的日程（例如租赁日程）返回 night，并额外添加三个字段：

{
  "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 条目代表一晚，从某日入住到次日退房；duration_minutes 为名义上的 1440 分钟夜间时长。stays 会将连续的空闲夜晚合并为实际可预订的日期范围，因此四个相邻夜晚会成为一个四晚住宿。按晚计价时使用 slots，向客户提供日期范围时使用 stays。

容量日程（例如 Jazzercise）会返回 unit: "class"，并为每堂有普通座位可用的课程返回一个条目：

{
  "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。

错误

每条错误都会说明原因，大多数错误也会提供解决方法：

错误	处理方法
页面要求访客选择资源	传入一个资源 URL，例如 .../Meeting_Rooms/Room_1 或 .../Rental_Homes/House_1。
页面链接到多个日程	消息会列出这些日程；直接传入目标日程。
日程需要登录才能访问	无需处理——该日程不是公开的。
容量日程未发布任何公开时段	该日程要求登录才能查看课程数据。
这是服务日程	这是由共享工作人员提供服务的目录。无需处理。
日程未声明开始时间网格	访客可自行选择开始和结束时间，因此没有固定网格。无需处理。
日程按多日为单位预订	这是一个为期两天或更长时间的产品。无需处理。
日程发布了营业时间，但没有开始时间	无需处理——时段会按请求生成。
URL 不是公开的 SuperSaaS HTTPS 页面	使用 https://，且不带凭据或自定义端口。

范围

支持：公开的单资源 resource 日程、固定预约时长、每周营业时间及按天设置的例外和屏蔽时段、已预订的预约、缓冲时间、提前预订限制，以及 slot 和 night 两种单位。公开的 capacity 日程会列出有可用座位的课程，包括每堂课的标题、地点、容量、已预订和候补人数，以及剩余座位数。

SuperSaaS 提供三种日程类型；服务日程会标记为不支持。此外，尚未建模的内容包括：重复规则、每位用户的限制、最短住宿规则，以及依赖付款的可用性。可用时段只是计算得出的候选项，并不保证一定能预订——预订时应以预订页面为准。

开发

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

测试会使用保存的三个真实资源日程副本和一份 Jazzercise 容量响应离线运行，因此不会因客户预订而发生变化。有关每个固定样本的内容，请参阅 INTERNALS.md。

发布

发布使用 PyPI Trusted Publishing 和 MCP Registry GitHub OIDC。首次发布前：

1. 在此 GitHub 仓库中创建 pypi 环境，并允许从版本标签部署。在 PyPI 中，为所有者 RichieB2B、仓库 supersaas-slots-mcp、工作流 release.yml 和环境 pypi 注册一个待处理的可信发布者。此时无需创建 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 工作流会在推送和拉取请求时运行测试和软件包检查。推送发布标签会将内容发布到外部；请先检查其提交和环境设置。