Shiftyasan Shift Scheduling
Generate optimized work shift schedules from staffing demand, availability and fairness rules.
Open source Repository Open in the app JSON README (API)
About
Generate optimized work shift schedules from staffing demand, availability and fairness rules.
Details
- Kind
- MCP servers
- Topic
- Productivity
- Publisher
- com.shiftyasan
- Origin
- official
- Category
- ferramentas
- Transport
- http
- Version
- 0.3.0
- Open pull requests
- 2
- Last push
- 2026-08-13T00:56:56Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:01:22
- Updated
- 2026-08-29 03:01:22
- Origin id
com.shiftyasan/mcp-server
README
# @shiftyasan/mcp-server
[](https://www.npmjs.com/package/@shiftyasan/mcp-server)
[](LICENSE)
Model Context Protocol (MCP) server for the **Shiftyasan** public solver API.
Lets AI agents (Claude Desktop, Cursor, Continue, etc.) call the shift-scheduling
solver from any MCP-aware host.
> **Status:** open beta — `validate_shift_input`, `solve_shift`, and `get_solve_job`
> (async polling for large problems). Usage queries (`get_usage`) coming next.
---
## Most people no longer need this package
Shiftyasan now runs a **remote MCP server**, which is the recommended way to connect:
```
https://api.shiftyasan.com/mcp
```
| | Remote (recommended) | This npm package |
|---|---|---|
| Node.js | not needed | **20 or newer required** |
| API key | issued automatically when you connect | you create and paste it yourself |
| Updates | server-side, nothing to do | you update the package |
| Claude.ai (web) / ChatGPT | **works** | cannot run a local process |
Connecting from Claude.ai or ChatGPT opens a Shiftyasan sign-in page in your browser; approve
it once and you are done. Revoke a connection any time from
[the dashboard](https://platform.shiftyasan.com/dashboard/) under "Connected apps".
**This package is still supported** and existing setups keep working. Reach for it when you
want the server to run locally — for example on a host that cannot reach the internet directly,
or when you prefer to hold your own API key.
See the [quickstart](https://api.shiftyasan.com/) for the remote setup.
---
## What is Shiftyasan?
[Shiftyasan](https://shiftyasan.com) is a SaaS that auto-generates work shifts
for businesses (retail, hospitality, healthcare, etc.) using a
constraint-optimization engine. The same solver is exposed as a public HTTP API at
`https://api.shiftyasan.com/v1/public/*`. This MCP server is a thin client
wrapper that turns the API into discoverable tools for AI agents.
Developer documentation — quickstart, the full list of supported constraints,
and pricing — lives at **<https://platform.shiftyasan.com>** (Japanese and English).
## Tools
| Tool | Description | Charged? |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
| `validate_shift_input` | Validate a `SolveRequest` payload against the public-API schema (no solver). | No |
| `solve_shift` | Run the solver. Small/medium problems return synchronously; large problems (roughly 25+ employees) are queued and return `202` with a `job_id`. | Yes |
| `get_solve_job` | Poll an asynchronous job until `completed` / `failed`. | No |
The full `SolveRequest` / `SolveResponse` schema lives in the OpenAPI spec at
`GET <base URL>/v1/public/openapi.json` (base URL = `SHIFTYASAN_BASE_URL`,
default `https://api.shiftyasan.com`).
## Prompts
| Prompt | What it does |
| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `plan_shift` | Walks the agent through building a schedule: what to ask the user for, when to validate, and how to present the finished roster. |
Both arguments (`period`, `context`) are optional, so it can be invoked bare. In
Claude Code it shows up as `/mcp__shiftyasan__plan_shift`; other hosts surface
prompts in their own UI.
Use it when you want the agent to interview you for the inputs rather than
guessing them, or when a previous attempt produced a roster you could not check
at a glance. The prompt tells the agent to render one row per person with the
per-person totals on the right, which is what a shift manager reads first.
The server also sends workflow guidance in its `initialize` response (call
`validate_shift_input` before `solve_shift`, poll `get_solve_job` on `202`,
how to read shortage markers and the infeasibility diagnosis). Hosts may add
this to the model's system prompt; Claude Code does, Claude Desktop currently
does not, which is why the same ordering rules also live in the tool descriptions.
### Constraints the schema accepts but the solver does not apply yet
A few fields are accepted by the API and then dropped during translation, because the
solver has no equivalent. `validate_shift_input` and `solve_shift` **print an explicit
warning** listing exactly what was dropped, so an agent never reports them as honored.
| Field | Status | Workaround |
| ------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `employees[].preferences[].type: "avoided_shift"` | Not applied | Remove the shift from that employee's `assignable_shift_ids` (hard), or state a `preferred_shift` for the shift they should get instead |
| `employees[].working_days_per_week.max` | Only `min` is used | Use `working_days_per_month` for an upper bound over the period |
| `constraints.employee_pairings[].rule: "require"` | Not applied (only `exclude` works) | Use `fixed_assignments` to place them on the same shift |
Everything else in the schema is applied by the solver.
## Install
> Running locally requires **Node.js 20 or newer**. If you would rather not manage that, use the
> [remote server](#most-people-no-longer-need-this-package) instead.
Use directly via `npx` (no global install needed):
```bash
npx -y @shiftyasan/mcp-server
```
Also listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as
`com.shiftyasan/mcp-server`.
Or install globally:
```bash
npm install -g @shiftyasan/mcp-server
shiftyasan-mcp-server
```
## Setup
### 1. Get an API key
Issue an `sk_live_...` key in the self-service dashboard:
**<https://platform.shiftyasan.com/dashboard/>** (your existing
[Shiftyasan](https://shiftyasan.com) account works; sign-up is also available).
If anything goes wrong, email <info@shiftyasan.com> (Japanese or English).
Treat the token like a password: it grants access to your solver quota.
> **Beta note:** you may receive a base URL different from the default —
> set it via `SHIFTYASAN_BASE_URL` (see below).
### 2. Configure your MCP host
#### Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):
```json
{
"mcpServers": {
"shiftyasan": {
"command": "npx",
"args": ["-y", "@shiftyasan/mcp-server"],
"env": {
"SHIFTYASAN_API_KEY": "sk_live_..."
}
}
}
}
```
Restart Claude Desktop. The `shiftyasan` server appears in the tools menu and
exposes `validate_shift_input`, `solve_shift`, and `get_solve_job`.
#### Claude Code
```bash
claude mcp add shiftyasan -e SHIFTYASAN_API_KEY=sk_live_... -- npx -y @shiftyasan/mcp-server
```
(Add `-e SHIFTYASAN_BASE_URL=...` if you were given a beta base URL.)
#### Cursor / Continue / other MCP hosts
Add to your MCP server config in the same shape (`command` + `args` + `env`).
Refer to your host's docs for the exact config file path.
## Using from ChatGPT
ChatGPT cannot spawn local stdio MCP servers like this package, so use the
HTTP API directly through a **Custom GPT with Actions** (the OpenAPI spec is
designed to be Actions-compatible — fully inlined schemas, no external refs):
1. ChatGPT → **My GPTs → Create a GPT → Configure → Actions →
Import from URL**, and enter
`<base URL>/v1/public/openapi.json`
(base URL = the one you received with your API key;
default `https://api.shiftyasan.com`).
2. If you were given a beta base URL, also edit the imported schema's
`servers[0].url` to `<base URL>/v1/public`.
3. **Authentication** → API Key → Auth Type **Bearer** → paste your
`sk_live_...` token.
4. Suggested GPT instructions:
> You can build optimized work shift schedules with the Shiftyasan actions.
> Always call the validate action first (free), then solve. Large problems
> return 202 with a job_id — poll the job endpoint every ~15 seconds until
> the status is "completed" or "failed".
Notes: creating custom GPTs requires a paid ChatGPT plan, and the API key is
stored inside the GPT — do not share that GPT publicly.
ChatGPT's MCP connectors only support **hosted** MCP endpoints
(Streamable HTTP), not local stdio processes. A hosted MCP endpoint is on our
roadmap; until then, use Actions as above.
## Environment variables
| Variable | Required | Description |
| --------------------- | -------- | ------------------------------------------------------------------------------------------ |
| `SHIFTYASAN_API_KEY` | yes | Bearer API key. Format: `sk_(live\|test)_<64 hex chars>`. |
| `SHIFTYASAN_BASE_URL` | no | Override base URL (default `https://api.shiftyasan.com`). Useful for staging or self-host. |
## Example session
In Claude Desktop, after configuring:
> **You:** Schedule 3 employees over the first week of June across morning and
> evening shifts. Use Shiftyasan.
Claude will discover the tools, call `validate_shift_input` to confirm the
payload it constructed is acceptable, then call `solve_shift` to get the
assignment. Errors from the API (RFC 7807) are surfaced inline so Claude can
self-correct (e.g., "staffing_demand length must equal schedule_days").
## Pricing
**The open beta is free.** Each API key comes with a free usage quota
(`solve_shift` consumes units per call; `validate_shift_input` is always free).
Check your remaining quota with `GET /v1/public/usage` using your key.
When you run out, email <info@shiftyasan.com> to get more.
Paid plans are planned after the beta. The MCP server itself never charges;
all metering happens against your `SHIFTYASAN_API_KEY` on the API side.
## Local development
```bash
git clone https://github.com/shiftyasan/mcp-server.git
cd mcp-server
npm install
npm run build
npm test
```
To run against a local gateway:
```bash
SHIFTYASAN_API_KEY=sk_test_... \
SHIFTYASAN_BASE_URL=http://localhost:8080 \
npm run dev
```
Test interactively with the [MCP inspector](https://github.com/modelcontextprotocol/inspector):
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
## Reporting issues
- MCP server bugs / requests: <https://github.com/shiftyasan/mcp-server/issues>
- Underlying API issues: contact <info@shiftyasan.com>
## License
MIT — see [LICENSE](LICENSE).