salonrunner-mcp

salonrunner-mcp

一个 MCP 服务，让 AI 助手通过你的个人 SalonRunner / Rosy Salon Software 客户端账户查找、预约和取消沙龙预约——许多沙龙都在使用同一预约网站。

它是可自托管的：你需要部署自己的实例。你可以在本地将它作为工具运行（Claude Desktop、Cursor、Copilot CLI），凭据会保留在你的设备上；也可以将它作为 claude.ai 的远程连接器，在连接器的登录页面使用你的 SalonRunner 账户登录。

⚠️ 非官方，使用未公开的端点，仅供个人使用。请阅读 DISCLAIMER.md。

工具

工作原理

list/find/book/cancel
        │
   this server ──login──► app.salonrunner.com  (session cookie)
        │      ──authv2─► customer JWT (30 min, auto-refreshed)
        │      ──reads──► app.rosysalonsoftware.com/api/v2  (Bearer JWT)
        └──────writes───► /customer/appointments/{book,cancel}.json  (cookie)

登录后会从你的账户中发现 customerId；corporateId 则从 JWT 中读取。 可预约时段根据服务人员针对每项服务设置的时长，以及沙龙的时段网格计算得出（SALONRUNNER_SLOT_MINUTES，默认为 15）。

配置

有两种运行方式，它们获取沙龙凭据的方式不同：

• **本地（stdio）：**凭据来自环境变量（.env）。
• 远程（HTTP，claude.ai）：在连接器的登录页面输入凭据，并将其加密后写入令牌——服务器环境中无需配置沙龙凭据。

在 HTTP 模式下，沙龙 id、用户名和密码会在登录页面收集（通过真实的 SalonRunner 登录进行验证），并加密后写入 OAuth 令牌，因此一个部署实例可以服务多家沙龙，服务器上也不会存储沙龙机密信息。

选项 A — 本地（Claude Desktop / Cursor / Copilot CLI）

此项目已作为 salonrunner-mcp 发布到 npm。全局安装：

npm install -g salonrunner-mcp

然后让客户端使用 salonrunner-mcp 命令（无需构建，也无需绝对路径）。Claude Desktop（claude_desktop_config.json）：

{
  "mcpServers": {
    "salonrunner": {
      "command": "salonrunner-mcp",
      "env": {
        "SALONRUNNER_SALON_ID": "21248",
        "SALONRUNNER_USERNAME": "[email protected]",
        "SALONRUNNER_PASSWORD": "your-password"
      }
    }
  }
}

不想全局安装？使用 "command": "npx" 和 "args": ["-y", "salonrunner-mcp"]，并配置相同的 env。

npm install && npm run build

无需托管，也无需 OAuth——凭据保留在你的设备上。如果你不需要使用 claude.ai，推荐此方式。

选项 B — 远程（claude.ai 自定义连接器）

claude.ai 只能使用远程 MCP 服务，因此你需要部署自己的实例。

部署到 Fly.io

fly launch --no-deploy          # pick a unique app name; creates the app
fly secrets set \
  SESSION_SIGNING_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))") \
  PUBLIC_URL=https://YOUR-APP.fly.dev
fly deploy
fly scale count 1               # in-memory MCP sessions: keep a single instance

此处未配置沙龙凭据——用户会在登录界面输入凭据。缺少 SESSION_SIGNING_KEY 时，服务拒绝启动。系统会通过真实的 SalonRunner 登录验证凭据，然后将其加密后嵌入（已签名的）令牌中，并由 claude.ai 保存。因此，应用在两次使用之间可以缩至零实例，而且你只需授权一次——冷启动（约 3 秒）对用户透明，也不会再次要求登录。

在 claude.ai 中连接

1. Settings → Connectors → Add custom connector。
2. URL：https://YOUR-APP.fly.dev/mcp
3. Claude 会打开连接器的登录界面 → 输入你的沙龙 ID + 用户名 + 密码。
4. 聊天中会显示六个工具。

在本地运行远程服务（测试）

SESSION_SIGNING_KEY=local-dev-please-change PUBLIC_URL=http://localhost:8787 npm run start:http

安全模型

两个独立的身份验证层：

1. claude.ai ↔ 此服务——OAuth 2.1（PKCE + 动态客户端注册）。登录界面通过真实的 SalonRunner 登录验证用户身份；随后，凭据会经 AES-GCM 加密，并嵌入由 HMAC 签名的令牌中（由 SESSION_SIGNING_KEY 作为密钥）。无需服务端会话存储，因此重启和缩至零实例后，授权仍然有效。
2. 此服务 ↔ SalonRunner——登录 → 会话 Cookie → 短期 JWT，并使用从调用方令牌中解密出的凭据自动刷新。

服务不会以静态形式保存任何沙龙凭据——凭据（加密后）存储在各用户的令牌中，并且每次请求只会在内存中解密。一次部署即可服务多个沙龙。泄露的令牌无法单独撤销；轮换 SESSION_SIGNING_KEY 即可使所有令牌失效（所有人都需要重新输入一次凭据）。请妥善保密 SESSION_SIGNING_KEY，并仅通过 HTTPS 提供服务。

注意事项与限制

• 本项目基于未公开文档的客户接口构建；接口可能随时变更，恕不另行通知。基础 URL 可配置，便于快速适配。
• 实际预订和取消会产生沙龙的取消政策费用。工具会在操作前显示服务、服务人员和时间；建议先使用 SALONRUNNER_READ_ONLY=true 运行。
• 为确保空闲时段信息准确，SALONRUNNER_SLOT_MINUTES 必须与沙龙的预约时间间隔一致（默认为 15）。
• 官方文档记录的、仅面向合作伙伴的 Rosy Salon Software API（api.salonrunner.com）是独立产品，需要沙龙签发的 ApiKey；本项目不使用该 API。

许可证

MIT——请参阅 LICENSE。不提供任何保证。