mcp-server

# @shiftyasan/mcp-server

[![npm version](https://img.shields.io/npm/v/@shiftyasan/mcp-server.svg)](https://www.npmjs.com/package/@shiftyasan/mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](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.

---

## 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`).

### 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

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).