{ "markdown": "# @shiftyasan/mcp-server\n\n[![npm version](https://img.shields.io/npm/v/@shiftyasan/mcp-server.svg)](https://www.npmjs.com/package/@shiftyasan/mcp-server)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n\nModel Context Protocol (MCP) server for the **Shiftyasan** public solver API.\nLets AI agents (Claude Desktop, Cursor, Continue, etc.) call the shift-scheduling\nsolver from any MCP-aware host.\n\n> **Status:** open beta — `validate_shift_input`, `solve_shift`, and `get_solve_job`\n> (async polling for large problems). Usage queries (`get_usage`) coming next.\n\n---\n\n## Most people no longer need this package\n\nShiftyasan now runs a **remote MCP server**, which is the recommended way to connect:\n\n```\nhttps://api.shiftyasan.com/mcp\n```\n\n| | Remote (recommended) | This npm package |\n|---|---|---|\n| Node.js | not needed | **20 or newer required** |\n| API key | issued automatically when you connect | you create and paste it yourself |\n| Updates | server-side, nothing to do | you update the package |\n| Claude.ai (web) / ChatGPT | **works** | cannot run a local process |\n\nConnecting from Claude.ai or ChatGPT opens a Shiftyasan sign-in page in your browser; approve\nit once and you are done. Revoke a connection any time from\n[the dashboard](https://platform.shiftyasan.com/dashboard/) under \"Connected apps\".\n\n**This package is still supported** and existing setups keep working. Reach for it when you\nwant the server to run locally — for example on a host that cannot reach the internet directly,\nor when you prefer to hold your own API key.\n\nSee the [quickstart](https://api.shiftyasan.com/) for the remote setup.\n\n---\n\n## What is Shiftyasan?\n\n[Shiftyasan](https://shiftyasan.com) is a SaaS that auto-generates work shifts\nfor businesses (retail, hospitality, healthcare, etc.) using a\nconstraint-optimization engine. The same solver is exposed as a public HTTP API at\n`https://api.shiftyasan.com/v1/public/*`. This MCP server is a thin client\nwrapper that turns the API into discoverable tools for AI agents.\n\nDeveloper documentation — quickstart, the full list of supported constraints,\nand pricing — lives at **** (Japanese and English).\n\n## Tools\n\n| Tool | Description | Charged? |\n| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------- |\n| `validate_shift_input` | Validate a `SolveRequest` payload against the public-API schema (no solver). | No |\n| `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 |\n| `get_solve_job` | Poll an asynchronous job until `completed` / `failed`. | No |\n\nThe full `SolveRequest` / `SolveResponse` schema lives in the OpenAPI spec at\n`GET /v1/public/openapi.json` (base URL = `SHIFTYASAN_BASE_URL`,\ndefault `https://api.shiftyasan.com`).\n\n## Prompts\n\n| Prompt | What it does |\n| ------------ | ------------------------------------------------------------------------------------------------------------------------------- |\n| `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. |\n\nBoth arguments (`period`, `context`) are optional, so it can be invoked bare. In\nClaude Code it shows up as `/mcp__shiftyasan__plan_shift`; other hosts surface\nprompts in their own UI.\n\nUse it when you want the agent to interview you for the inputs rather than\nguessing them, or when a previous attempt produced a roster you could not check\nat a glance. The prompt tells the agent to render one row per person with the\nper-person totals on the right, which is what a shift manager reads first.\n\nThe server also sends workflow guidance in its `initialize` response (call\n`validate_shift_input` before `solve_shift`, poll `get_solve_job` on `202`,\nhow to read shortage markers and the infeasibility diagnosis). Hosts may add\nthis to the model's system prompt; Claude Code does, Claude Desktop currently\ndoes not, which is why the same ordering rules also live in the tool descriptions.\n\n### Constraints the schema accepts but the solver does not apply yet\n\nA few fields are accepted by the API and then dropped during translation, because the\nsolver has no equivalent. `validate_shift_input` and `solve_shift` **print an explicit\nwarning** listing exactly what was dropped, so an agent never reports them as honored.\n\n| Field | Status | Workaround |\n| ------------------------------------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| `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 |\n| `employees[].working_days_per_week.max` | Only `min` is used | Use `working_days_per_month` for an upper bound over the period |\n| `constraints.employee_pairings[].rule: \"require\"` | Not applied (only `exclude` works) | Use `fixed_assignments` to place them on the same shift |\n\nEverything else in the schema is applied by the solver.\n\n## Install\n\n> Running locally requires **Node.js 20 or newer**. If you would rather not manage that, use the\n> [remote server](#most-people-no-longer-need-this-package) instead.\n\nUse directly via `npx` (no global install needed):\n\n```bash\nnpx -y @shiftyasan/mcp-server\n```\n\nAlso listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as\n`com.shiftyasan/mcp-server`.\n\nOr install globally:\n\n```bash\nnpm install -g @shiftyasan/mcp-server\nshiftyasan-mcp-server\n```\n\n## Setup\n\n### 1. Get an API key\n\nIssue an `sk_live_...` key in the self-service dashboard:\n**** (your existing\n[Shiftyasan](https://shiftyasan.com) account works; sign-up is also available).\nIf anything goes wrong, email (Japanese or English).\n\nTreat the token like a password: it grants access to your solver quota.\n\n> **Beta note:** you may receive a base URL different from the default —\n> set it via `SHIFTYASAN_BASE_URL` (see below).\n\n### 2. Configure your MCP host\n\n#### Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`\n(macOS) or `%APPDATA%/Claude/claude_desktop_config.json` (Windows):\n\n```json\n{\n \"mcpServers\": {\n \"shiftyasan\": {\n \"command\": \"npx\",\n \"args\": [\"-y\", \"@shiftyasan/mcp-server\"],\n \"env\": {\n \"SHIFTYASAN_API_KEY\": \"sk_live_...\"\n }\n }\n }\n}\n```\n\nRestart Claude Desktop. The `shiftyasan` server appears in the tools menu and\nexposes `validate_shift_input`, `solve_shift`, and `get_solve_job`.\n\n#### Claude Code\n\n```bash\nclaude mcp add shiftyasan -e SHIFTYASAN_API_KEY=sk_live_... -- npx -y @shiftyasan/mcp-server\n```\n\n(Add `-e SHIFTYASAN_BASE_URL=...` if you were given a beta base URL.)\n\n#### Cursor / Continue / other MCP hosts\n\nAdd to your MCP server config in the same shape (`command` + `args` + `env`).\nRefer to your host's docs for the exact config file path.\n\n## Using from ChatGPT\n\nChatGPT cannot spawn local stdio MCP servers like this package, so use the\nHTTP API directly through a **Custom GPT with Actions** (the OpenAPI spec is\ndesigned to be Actions-compatible — fully inlined schemas, no external refs):\n\n1. ChatGPT → **My GPTs → Create a GPT → Configure → Actions →\n Import from URL**, and enter\n `/v1/public/openapi.json`\n (base URL = the one you received with your API key;\n default `https://api.shiftyasan.com`).\n2. If you were given a beta base URL, also edit the imported schema's\n `servers[0].url` to `/v1/public`.\n3. **Authentication** → API Key → Auth Type **Bearer** → paste your\n `sk_live_...` token.\n4. Suggested GPT instructions:\n\n > You can build optimized work shift schedules with the Shiftyasan actions.\n > Always call the validate action first (free), then solve. Large problems\n > return 202 with a job_id — poll the job endpoint every ~15 seconds until\n > the status is \"completed\" or \"failed\".\n\nNotes: creating custom GPTs requires a paid ChatGPT plan, and the API key is\nstored inside the GPT — do not share that GPT publicly.\n\nChatGPT's MCP connectors only support **hosted** MCP endpoints\n(Streamable HTTP), not local stdio processes. A hosted MCP endpoint is on our\nroadmap; until then, use Actions as above.\n\n## Environment variables\n\n| Variable | Required | Description |\n| --------------------- | -------- | ------------------------------------------------------------------------------------------ |\n| `SHIFTYASAN_API_KEY` | yes | Bearer API key. Format: `sk_(live\\|test)_<64 hex chars>`. |\n| `SHIFTYASAN_BASE_URL` | no | Override base URL (default `https://api.shiftyasan.com`). Useful for staging or self-host. |\n\n## Example session\n\nIn Claude Desktop, after configuring:\n\n> **You:** Schedule 3 employees over the first week of June across morning and\n> evening shifts. Use Shiftyasan.\n\nClaude will discover the tools, call `validate_shift_input` to confirm the\npayload it constructed is acceptable, then call `solve_shift` to get the\nassignment. Errors from the API (RFC 7807) are surfaced inline so Claude can\nself-correct (e.g., \"staffing_demand length must equal schedule_days\").\n\n## Pricing\n\n**The open beta is free.** Each API key comes with a free usage quota\n(`solve_shift` consumes units per call; `validate_shift_input` is always free).\nCheck your remaining quota with `GET /v1/public/usage` using your key.\nWhen you run out, email to get more.\n\nPaid plans are planned after the beta. The MCP server itself never charges;\nall metering happens against your `SHIFTYASAN_API_KEY` on the API side.\n\n## Local development\n\n```bash\ngit clone https://github.com/shiftyasan/mcp-server.git\ncd mcp-server\nnpm install\nnpm run build\nnpm test\n```\n\nTo run against a local gateway:\n\n```bash\nSHIFTYASAN_API_KEY=sk_test_... \\\nSHIFTYASAN_BASE_URL=http://localhost:8080 \\\n npm run dev\n```\n\nTest interactively with the [MCP inspector](https://github.com/modelcontextprotocol/inspector):\n\n```bash\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## Reporting issues\n\n- MCP server bugs / requests: \n- Underlying API issues: contact \n\n## License\n\nMIT — see [LICENSE](LICENSE).\n", "bytes": 11536, "sha": "8416fd5806b8c57d1b9129bde04be5695867561073ad710b831781517f4f621b", "repo_slug": "shiftyasan/mcp-server", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_com_shiftyasan_mcp_server_300ba56b/readme" }