Dine MCP

dine-mcp

面向 AI 助手（MCP）、命令行和 Python，查询餐厅实际使用的预订系统中的餐桌空位，覆盖全球各国。

询问“周五晚上能在 Harbour Grill 订到一张四人桌吗？”，助手会找到餐厅，确定其使用的预订系统（通过 Google Maps 的“预订餐桌”链接、餐厅的预订页面或整理好的事实信息），按餐厅所在时区查询空位，并提供预订服务商的预订页面；条件允许时，还会预先填写信息。dine-mcp 绝不会替你预订、占位或取消：你需要自行前往服务商页面预订。

服务商	国家/地区	模式	成熟度	上次在线验证
CatchTable (Korea)	KR	列表	实验性	未验证
Formitable (Zenchef)	NL, BE, FR, DE, GB	公开	实验性	未验证
ResDiary	GB, IE, AU, NZ, AE, SG, HK, MY, ZA	公开	Beta	2026-10-29
SevenRooms	HK, GB, US, AE, AU, SG, IE, CA	公开	Beta	2026-10-29
Tabelog	JP	列表	实验性	未验证
TableCheck	JP, HK, SG, KR, TW, TH, AU, GB, US	公开	Beta	2026-10-29
Zenchef	FR, NL, BE, GB, DE, CH, ES, IT	公开	实验性	未验证

SevenRooms 会返回可预订/可申请的时段、用餐体验和银行卡标记；ResDiary 还会列出就餐区域。TableCheck 不公布其放号时间，因此尚未开放的日期可能显示为客满。 其他预订页面仅提供链接；仅通过电话、消息或网站预订的餐厅会返回联系方式。 如果地点列表中没有预订链接，可选择启用网站发现功能，以检测受支持的小组件。

后续将通过定义和适配器支持更多服务商（CONTRIBUTING.md）；下一步计划见 docs/ROADMAP.md。

非官方项目，与任何预订服务商或 Google 均无关联。服务商条款限制自动访问：dine-mcp 只读取其公开预订小组件，供个人以正常人工操作的速度查询自己要预订的餐桌，且绝不代为预订。请仅用于个人、低频用途，风险自负。餐厅查询通过 google-maps-keyless-mcp 使用 Google Maps；该项目的条款提示同样适用。

快速开始

版本：0.2.10。 有关安全更新和空位查询修复，请参阅更新日志。从源码检出目录运行：

uv sync --locked
uv run dine-mcp --transport stdio

对应的安装包命令和客户端配置如下：

uvx dine-mcp --transport stdio            # for a local MCP client (Claude Desktop, Claude Code, …)

Claude Code：claude mcp add dine -- uvx dine-mcp --transport stdio。Claude Desktop （claude_desktop_config.json）：

{"mcpServers": {"dine": {"command": "uvx", "args": ["dine-mcp", "--transport", "stdio"]}}}

无需助手，也可以直接使用命令行执行相同操作：

uvx dine-mcp find "Harbour Grill" --area "Raffles Place" --country SG
uvx dine-mcp check v_abc123def456 --date 2026-11-06 --from-time 18:00 --to-time 21:30 --party 4

工具

工具	功能
dine_find_venue(name, area, country | url | google_place_id, limit)	识别一家餐厅及其预订渠道。名称不明确时会返回候选项及其 Google place id，不会猜测。预订链接只会与已知服务商匹配，不会抓取链接。
dine_get_venue(venue_id)	餐厅的完整信息：各服务商的预订规则（可提前预订的天数、人数限制）、预订链接、营业时间。
dine_check_availability(venue_ids ≤5, date_from, date_to ≤7 days, time_from, time_to, party_size, kinds, response_format)	每家餐厅和每个渠道各返回一条结果：餐厅所在时区的可订时段、覆盖范围、observed_at、预订链接。
dine_status(check=false)	服务商、预算和暂停状态。可选的限速探测共用一个持久化的 15 分钟冷却时间。

所有工具均为只读。每项结果也会以简短文本形式返回，供只显示文本的客户端使用。

要查询餐厅，先用 dine_find_venue 确认餐厅，然后调用 dine_check_availability。 请先询问缺少的日期和用餐人数，并说明使用的时间范围（API 默认值为 17:00–22:30）。dine_status 用于诊断服务；它不会查询餐厅的餐位。 请求失败和未经检查的日期表示可订情况未知，绝不能视为已订满的证据。

状态（按餐厅和渠道）：ok、none_available、not_yet_open（日期尚未开放预订；已知时会提供 opens_at）、party_too_small（附带 min_party）或 party_too_large（附带餐厅的在线人数上限及其联系方式）、closed、contact_only、unsupported（dine-mcp 无法读取的预订系统；会提供链接）、blocked / rate_limited（服务商要求我们降低请求频率）、unavailable、unknown_venue、skipped_deadline。任何一个服务商失败都不会导致整个调用失败。

**限制：**每次查询可订情况最多查询 5 家餐厅和 7 天。预计会产生超过 20 次服务商请求的计划将被拒绝，并返回 too_broad；实际发送的请求（包括重定向请求）共用相同的上限。查找、获取和查询可订情况共用 30 秒的端到端截止时间，涵盖查找、规划和服务商处理。已完成的批次会保留，不受后续错误和超时影响；未返回的日期仍为未知，绝不能视为无可订时段。观察结果缓存 2 分钟。TableCheck 的结果复用要求时间范围相同；因服务商限流而返回较早的观察结果时，会标注其原始时间。stdio 支持进度通知；无状态 JSON HTTP 会返回已完成的结果。

错误是带有 isError 的工具结果，其文本为 {"error": {"code", "retryable", "retry_after_seconds", "action", "next_step"}}。

运行服务

经过加固的 Compose 示例提供了只读根文件系统、已移除的能力和私有状态卷。部署时，将 DINE_IMAGE 设为经过验证的不可变镜像摘要。 接受远程客户端之前，请为代理配置 HTTP Host/Origin 允许列表。

在源码检出目录中运行 uv run dine-mcp --transport http，或者在启动容器前，将 DINE_IMAGE 设为 0.2.10 镜像经过验证的不可变摘要：

docker run -d -p 127.0.0.1:8000:8000 -v dine-state:/state \
  -e MCP_BEARER_TOKEN="$(openssl rand -hex 32)" \
  "${DINE_IMAGE:?set a verified immutable image digest}"

MCP 端点为 /mcp（可流式传输的 HTTP、无状态 JSON）；/health 为开放端点。由调用方决定使用哪部分请求预算：

模式	设置	用户
single	MCP_BEARER_TOKEN	一位用户，owner
users（独立多用户）	DINE_USERS_FILE；dine-mcp users add <id> --file users.toml 会将该用户的令牌显示一次	提交令牌的用户
gateway	MCP_BEARER_TOKEN（网关的令牌）和 DINE_PERSON_HEADER（例如 X-Person）	经验证的用户，由通过身份验证的网关声明；首次联系时会创建记录
stdio	--transport stdio	本地用户
变量	默认值	含义
---	---	---
DINE_STATE_DIR	$XDG_STATE_HOME/dine-mcp（镜像中为 /state）	场所、预算、断路器、名单
DINE_OVERRIDES	无	运营方开关（如下）
DINE_PLACES	google	none 会关闭按名称搜索场所（链接仍可使用）
DINE_GOOGLE_DAILY_BUDGET	200	Google Maps 每日请求数
DINE_WEBSITE_DISCOVERY	0	设为 1 可在场所来源提供的网站上进行有界 HTML 探索
DINE_DEADLINE_SECONDS	30	find/get/check 和显式 canary 的端到端超时
DINE_HTTP_ALLOWED_HOSTS	localhost,127.0.0.1,[::1]	显式 HTTP Host 允许列表；添加反向代理主机名
DINE_HTTP_ALLOWED_ORIGINS	空	以逗号分隔的精确跨源 HTTP 来源；接受同源请求
DINE_APPS	0	设为 1 可启用可选的 MCP Apps 可用性网格；文本结果仍可用
DINE_HOST、DINE_PORT	127.0.0.1、8000	HTTP 监听地址

覆盖项（DINE_OVERRIDES，TOML）是运营方唯一的开关，在启动时应用：

disabled = false                 # true: find/get/check refuse before external work
[providers.tablecheck]
access_mode = "listing"          # stop reading availability; return links only (never raise a mode)
[providers.sevenrooms]
enabled = false                  # off entirely

每个提供方的请求频率限制为每两秒一次，且一次只处理一个请求；每日预算由服务器上的所有人共享（每人最多使用一半）。如果提供方拒绝请求（返回 429、401 或 403，或出现机器人检查），则至少暂停五分钟。它绝不会重试或解决挑战。

启用网站探索后，如果未知预订渠道，find/get/check 可能会读取当前场所来源网站。它能识别受支持的锚点和 iframe/button 属性，不运行 JavaScript，也不进行爬取。若检测到多个不同的场所组件，则视为存在歧义，不推断渠道。检测到的链接为暂定链接（source=website、verified=false），缓存时间最长为一天，且绝不会超出场所来源记录的范围；这些链接不会创建永久场所别名。

预订提供方的主机仍由其适配器管理；网站探索无法绕过其固定操作或预算。如果来源网站已列出受支持的预订场所，则无需抓取即可识别。网站读取使用独立的无凭据客户端，解码后正文上限为 512 kB，可选信息补充的截止时间为五秒。强制使用 HTTPS、公共 DNS 和精确主机重定向。所有网站合计每天最多读取 50 次，每人最多使用一半，请求间隔至少一秒；重定向也计入次数。读取失败后暂停 15 分钟，拒绝请求则触发共享的持久暂停。目录结果不受探索失败影响。dine_status 会报告该功能的总预算和暂停状态，但不会读取网站。禁用该功能并重启即可移除缓存的探索数据。网站请求会省略跟踪参数和片段；带有其他查询参数的来源 URL，以及带有查询参数的重定向，都会被拒绝。探索仅存储不含查询参数的已识别预订链接，不存储原始 HTML 或 Cookie。原始场所数据遵循其通常的保留政策。

身份验证、运营方操作、撤销和共享数据的说明见 docs/PERMISSIONS.md。

用作库

from dine_mcp.composition import build_app

app = build_app()
found = await app.service.find_venue("me", name="Harbour Grill", area="Raffles Place", country="SG")
venue_id = found["venues"][0]["venue_id"]
result = await app.service.check_availability("me", [venue_id], "2026-11-06", party_size=4)

工具接口遵循 SemVer；Python API 尚未稳定（0.x）。

工作原理

docs/ARCHITECTURE.md 介绍场所解析、提供方协议、请求预算和安全边界；docs/PROVIDERS.md 列出各提供方的端点、限制和特性；docs/ROADMAP.md 说明后续计划。

验证

make check 会运行离线安全、契约、真实 stdio/HTTP、隔离和回归检查。 make qualify 还会安装固定版本的 Node 22+ 工具，并运行 Inspector 以及适用的通用 MCP 一致性场景。有关范围、软件包检查以及单独设门控的运营方 canary，请参阅验证。运行状况检查绝不会联系提供方。

许可证

Apache-2.0。先前成果和依赖项均已在 NOTICE 中致谢。

可选的可用性网格

设置 DINE_APPS=1，即可向 MCP Apps 宿主公布 ui://dine/availability.html。 内置视图会按场所当地的服务日期显示各场所的可用情况，包括午夜后的时段、 观测时间戳和未知覆盖情况。筛选在本地执行。只有在用户点击后，预订页面导航才会请求 宿主打开 HTTPS 链接；视图本身不会调用服务提供方或工具。 不支持 Apps 的客户端仍会收到文本和结构化结果。此选项默认关闭。

运行 make ui（重新构建）和 make ui-check（锁定依赖、 可复现的打包产物和声明，以及离线渲染/SDK 测试）需要 Node 22+。Python 安装无需 Node。 剩余的服务提供方和连接前置条件请参阅路线图。

生成的接口参考记录了完整的 MCP 发现信息 （包括可选的 App 配置文件）和 CLI 解析器声明。有意更改接口后，运行 python scripts/surface.py update，并结合参考文档差异审查 surface.json。缺少基线或基线过期时，make check 会拒绝通过。在 这些声明仍分散于各加载器期间，环境和配置覆盖范围明确为不完整； 本参考不会取代上文的配置指南。图像冒烟测试会比较已安装入口点的完整 发现模式，以及合成的成功/错误行为。