Shiftyasan Shift Scheduling

@shiftyasan/mcp-server

适用于 Shiftyasan 公共求解器 API 的 Model Context Protocol（MCP）服务。 让 AI Agent（Claude Desktop、Cursor、Continue 等）能够从任意支持 MCP 的宿主调用排班求解器。

**状态：**公开测试版 — validate_shift_input、solve_shift 和 get_solve_job （大型问题的异步轮询）。用量查询（get_usage）即将推出。

---

大多数人现在都不再需要这个软件包

Shiftyasan 现已运行一个远程 MCP 服务，这是推荐的连接方式：

https://api.shiftyasan.com/mcp

	远程（推荐）	此 npm 软件包
Node.js	无需	需要 20 或更高版本
API 密钥	连接时自动签发	由你自行创建并粘贴
更新	服务端处理，无需操作	由你更新软件包
Claude.ai（网页）/ ChatGPT	可用	无法运行本地进程

从 Claude.ai 或 ChatGPT 连接时，浏览器会打开 Shiftyasan 登录页面；批准一次后即可完成。 你可以随时在控制面板的“Connected apps”下撤销连接。

此软件包仍受支持，现有配置也会继续正常运行。需要在本地运行服务时，可以使用此软件包 —— 例如，宿主无法直接访问互联网，或你希望自行保管 API 密钥时。

远程配置请参阅快速入门。

---

什么是 Shiftyasan？

Shiftyasan 是一款 SaaS 服务，使用约束优化引擎为企业（零售、酒店、医疗保健等）自动生成工作班次。同一求解器也通过 https://api.shiftyasan.com/v1/public/* 提供公共 HTTP API。此 MCP 服务是一个轻量客户端封装，将 API 转换为 AI Agent 可发现的工具。

开发者文档——快速入门、完整的支持约束列表和定价——位于 https://platform.shiftyasan.com（日语和英语）。

工具

工具	描述	收费？
validate_shift_input	根据公共 API 架构验证 SolveRequest 载荷（不运行求解器）。	否
solve_shift	运行求解器。小型/中型问题会同步返回；大型问题（大约 25 名以上员工）会进入队列，并返回 202 和 job_id。	是
get_solve_job	轮询异步任务，直到状态变为 completed / failed。	否

完整的 SolveRequest / SolveResponse 架构位于 OpenAPI 规范中，地址为 GET <base URL>/v1/public/openapi.json（基础 URL = SHIFTYASAN_BASE_URL， 默认值为 https://api.shiftyasan.com）。

提示词

提示词	功能说明
plan_shift	引导 Agent 制定排班表：询问用户需要哪些信息、何时进行验证，以及如何呈现最终排班表。

两个参数（period、context）均为可选，因此可以直接调用。在 Claude Code 中，它会显示为 /mcp__shiftyasan__plan_shift；其他宿主会在各自的界面中显示 提示词。

如果你希望 Agent 通过询问来收集输入，而不是自行猜测，或者上一次生成的排班表不便快速核对， 就可以使用它。提示词会要求 Agent 每人单独列一行，并在右侧列出每人的工时总计， 因为这是排班经理首先会查看的内容。

服务还会在其 initialize 响应中发送工作流指导（调用 validate_shift_input 后再调用 solve_shift，收到 202 后轮询 get_solve_job，以及如何读取缺员标记和不可行性诊断）。宿主可能会将这些内容添加到模型的系统提示词中；Claude Code 会这样做，Claude Desktop 目前则不会，这也是相同的顺序规则同时写在工具说明中的原因。

架构接受但求解器尚未应用的约束

API 会接受一些字段，但随后会在转换过程中将其舍弃，因为求解器没有与之对应的功能。 validate_shift_input 和 solve_shift 会打印明确警告，准确列出所有被舍弃的内容，因此 Agent 不会声称这些约束已生效。

字段	状态	解决方法
employees[].preferences[].type: "avoided_shift"	未应用	从该员工的 assignable_shift_ids 中移除该班次（硬性限制），或为其应分配的班次指定 preferred_shift
employees[].working_days_per_week.max	仅使用 min	使用 working_days_per_month 设置整个时段内的上限
constraints.employee_pairings[].rule: "require"	未应用（仅 exclude 有效）	使用 fixed_assignments 将他们安排在同一班次

架构中的其他所有内容都会由求解器应用。

安装

本地运行需要 Node.js 20 或更高版本。如果你不想管理它，也可以改用 远程服务。

直接通过 npx 使用（无需全局安装）：

npx -y @shiftyasan/mcp-server

也可在 MCP Registry 中找到，名称为 com.shiftyasan/mcp-server。

或者全局安装：

npm install -g @shiftyasan/mcp-server
shiftyasan-mcp-server

设置

1. 获取 API 密钥

在自助服务控制面板中创建一个 sk_live_... 密钥： https://platform.shiftyasan.com/dashboard/（你现有的 Shiftyasan 账户可以直接使用；也可以注册新账户）。 如有问题，请发送邮件至 [email protected]（日语或英语均可）。

请像对待密码一样保管该令牌：它可以访问你的求解器配额。

**Beta 说明：**你收到的基础 URL 可能与默认值不同 — 请通过 SHIFTYASAN_BASE_URL 设置（见下文）。

2. 配置 MCP 宿主

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）或 %APPDATA%/Claude/claude_desktop_config.json（Windows）：

{
  "mcpServers": {
    "shiftyasan": {
      "command": "npx",
      "args": ["-y", "@shiftyasan/mcp-server"],
      "env": {
        "SHIFTYASAN_API_KEY": "sk_live_..."
      }
    }
  }
}

重启 Claude Desktop。shiftyasan 服务会出现在工具菜单中，并提供 validate_shift_input、solve_shift 和 get_solve_job。

Claude Code

claude mcp add shiftyasan -e SHIFTYASAN_API_KEY=sk_live_... -- npx -y @shiftyasan/mcp-server

（如果提供给你的是 beta 基础 URL，请添加 -e SHIFTYASAN_BASE_URL=...。）

Cursor / Continue / 其他 MCP 宿主

按相同结构（command + args + env）添加到 MCP 服务配置中。 具体配置文件路径请参阅宿主的文档。

在 ChatGPT 中使用

ChatGPT 无法像此软件包那样启动本地 stdio MCP 服务，因此请通过带 Actions 的自定义 GPT直接使用 HTTP API（OpenAPI 规范设计为兼容 Actions — 架构完全内联，不使用外部引用）：

1. ChatGPT → 我的 GPT → 创建 GPT → 配置 → Actions → 从 URL 导入，然后输入 <base URL>/v1/public/openapi.json （基础 URL = 随 API 密钥提供给你的 URL； 默认值为 https://api.shiftyasan.com）。

2. 如果提供给你的是 beta 基础 URL，还要将导入的架构中的 servers[0].url 编辑为 <base URL>/v1/public。

3. 身份验证 → API Key → Auth Type Bearer → 粘贴你的 sk_live_... 令牌。

4. 推荐的 GPT 指令：

   你可以使用 Shiftyasan actions 创建经过优化的轮班计划。 始终先调用 validate action（免费），然后再求解。大型问题 会返回 202 和一个 job_id — 每隔约 15 秒轮询一次任务端点，直到 状态变为 "completed" 或 "failed"。

注意：创建自定义 GPT 需要付费 ChatGPT 计划，且 API 密钥会存储在 GPT 中 — 请勿公开分享该 GPT。

ChatGPT 的 MCP 连接器仅支持托管 MCP 端点 （Streamable HTTP），不支持本地 stdio 进程。托管 MCP 端点已列入我们的路线图；在推出之前，请按上述方式使用 Actions。

环境变量

变量	必需	描述
SHIFTYASAN_API_KEY	是	Bearer API 密钥。格式：sk_(live|test)_<64 hex chars>。
SHIFTYASAN_BASE_URL	否	覆盖基础 URL（默认值为 https://api.shiftyasan.com）。适用于暂存环境或自托管。

会话示例

在 Claude Desktop 中完成配置后：

你： 使用 Shiftyasan，为 6 月第一周的早班和晚班安排 3 名员工。

Claude 会发现这些工具，调用 validate_shift_input 确认其构建的负载可接受，然后调用 solve_shift 获取分配结果。API 错误（RFC 7807）会直接显示，方便 Claude 自行修正（例如，“staffing_demand length must equal schedule_days”）。

定价

开放测试版免费。 每个 API 密钥都附带免费使用额度 （solve_shift 每次调用会消耗额度；validate_shift_input 始终免费）。 使用你的密钥调用 GET /v1/public/usage，即可查看剩余额度。 额度用完后，请发送邮件至 [email protected] 获取更多额度。

测试版结束后计划推出付费方案。MCP 服务本身不会收费； 所有用量均由 API 端根据你的 SHIFTYASAN_API_KEY 计量。

本地开发

git clone https://github.com/shiftyasan/mcp-server.git
cd mcp-server
npm install
npm run build
npm test

若要对接本地网关：

SHIFTYASAN_API_KEY=sk_test_... \
SHIFTYASAN_BASE_URL=http://localhost:8080 \
  npm run dev

使用 MCP 检查器进行交互式测试：

npx @modelcontextprotocol/inspector node dist/index.js

问题反馈

• MCP 服务错误 / 功能请求：https://github.com/shiftyasan/mcp-server/issues
• 底层 API 问题：联系 [email protected]

许可证

MIT — 参见 LICENSE。