Floyd

Floyd MCP 服务

通过 MCP 服务向 AI Agent 提供 Floyd Engine 的排期和预订工具。基于 Model Context Protocol 的 Streamable HTTP 传输方式构建。

如需查看引擎的 API 文档，请参阅引擎仓库中的 docs 文件夹。

工具

工具	描述
floyd_get_available_slots	查询服务的可预约时段
floyd_hold_booking	临时保留一个时段
floyd_confirm_booking	确认已保留的预订（需要用户明确同意）
floyd_cancel_booking	取消已保留或已确认的预订
floyd_reschedule_booking	将预订调整到新的时段
floyd_update_booking	更新预订的元数据
floyd_get_booking	获取预订详情和状态

设置

pnpm install

环境变量

变量	必填	默认值	描述
FLOYD_BASE_URL	否	http://localhost:4000/v1	Floyd Engine 基础 URL
PORT	否	3000	HTTP 服务端口

使用方法

HTTP 模式（Streamable HTTP）

pnpm dev

MCP 端点：POST / 健康检查：GET /health

Stdio 模式

pnpm dev -- --stdio

身份验证

当 Floyd engine 需要身份验证时，连接的 Agent 可通过以下方式提供 API 密钥：

1. Authorization: Bearer <token> 标头（首选）
2. ?token=<value> 查询参数

每次请求都会将 API 密钥转发给 Floyd engine。如果引擎已禁用身份验证（例如，可自托管），则无需密钥。

预订流程

get_available_slots → hold_booking → confirm_booking
                                   ↘ cancel_booking
                                   ↘ reschedule_booking
                                   ↘ update_booking (metadata)

1. 查询时段 — 查询可预约时段，并返回签名的 slotId 令牌
2. 保留 — 使用 slotId（或明确指定的字段）预留时段。创建状态为 held 的预订
3. 确认 — 最终确认预订。需要 userConfirmed: true
4. 取消 — 释放已保留或已确认的预订
5. 改期 — 将预订调整到新的时段，同时保留其身份
6. 更新 — 添加或替换元数据（例如，人数、特殊要求）

开发

pnpm test          # run tests
pnpm typecheck     # type-check
pnpm lint          # eslint
pnpm format        # prettier
pnpm build         # bundle with tsup

生产环境

pnpm build
pnpm start

服务会处理 SIGTERM/SIGINT，以实现平稳关闭。向 Floyd API 发送的 HTTP 请求超时时间为 10 秒。