@simular-ai/sai-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simular LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# @simular-ai/sai-mcp
+
+MCP server that lets a coding agent — Claude Code, Codex, Cursor, or any MCP
+client — delegate work to [Sai](https://sai.simular.ai), Simular's
+computer-use agent. Sai operates a real desktop (browser, native apps, files,
+your logged-in accounts) on a machine registered to your account; this server
+exposes that as six tools over stdio.
+
+Requires Node.js 22.12 or newer and a Sai API key
+(`sapi_…`, created at <https://sai.simular.ai/settings/api-keys>).
+
+## Install
+
+### Claude Code
+
+```bash
+claude mcp add sai -e SAI_API_KEY=sapi_... -- npx -y @simular-ai/sai-mcp
+```
+
+Optionally install the `sai` skill too (same as `simulang init-claude`). It
+teaches the loop, and covers sessions where the MCP server is not loaded by
+falling back to plain HTTP:
+
+```bash
+npx -y @simular-ai/sai-mcp init-claude            # ~/.claude/skills/sai
+npx -y @simular-ai/sai-mcp init-claude --project  # ./.claude/skills/sai
+npx -y @simular-ai/sai-mcp init-claude --check    # exit 1 when missing or stale
+```
+
+It never overwrites a `SKILL.md` you edited; `--force` does.
+
+### Codex
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.sai]
+command = "npx"
+args = ["-y", "@simular-ai/sai-mcp"]
+
+[mcp_servers.sai.env]
+SAI_API_KEY = "sapi_..."
+```
+
+### Cursor
+
+`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):
+
+```json
+{
+  "mcpServers": {
+    "sai": {
+      "command": "npx",
+      "args": ["-y", "@simular-ai/sai-mcp"],
+      "env": { "SAI_API_KEY": "sapi_..." }
+    }
+  }
+}
+```
+
+The same JSON block works for any client that speaks stdio MCP.
+
+## Environment
+
+| Variable         | Required | Meaning                                                                                                                                            |
+| ---------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SAI_API_KEY`    | yes      | A Sai API key (`sapi_…`) or a Firebase ID token. Sent as `Authorization: Bearer`.                                                                  |
+| `SAI_API_URL`    | no       | Cloud API base URL. Default: production (`https://simular-cloud-api-149671192594.us-central1.run.app`).                                            |
+| `SAI_PUSH`       | no       | `1` enables channel push (see below). Only with `--dangerously-load-development-channels server:sai`; otherwise results are dropped.               |
+| `SAI_EVENTS_API` | no       | `1` switches to the `wait:false` + `GET /v1/agents/events` transport once cloud-api ships it. Default off: the SSE stream is collected in-process. |
+
+## Tools
+
+| Tool               | Input                                               | Output                                                                                       |
+| ------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `sai_machines`     | —                                                   | `{ machines: [{ machineId, name, kind?, online? }], default? }` — `default` when exactly one |
+| `sai_task_start`   | `{ task, machine_id?, file_ids?, new_session? }`    | `{ session_id, machine_id, queued, push }`                                                   |
+| `sai_task_wait`    | `{ session_id, timeout_s? (90, max 110), cursor? }` | `{ status, events, text, approval?, cursor, error? }`                                        |
+| `sai_task_approve` | `{ approval_id, decision, selections? }`            | `{ ok: true }` or `{ ok: false, reason: 'link_only', approval_url }`                         |
+| `sai_task_abort`   | `{ session_id }`                                    | `{ ok, aborted, reason? }`                                                                   |
+| `sai_upload`       | `{ path }`                                          | `{ file_id, name, mime, size }`                                                              |
+
+`decision` is `approve` (this one request), `approve_for_task` (trust similar
+requests for the rest of the task) or `deny`. `status` is `running`,
+`needs_approval`, `idle` or `error`.
+
+There is no screenshot tool: Sai sees the screen itself and reports back in
+text.
+
+## The loop
+
+The server's `instructions` teach the model this loop; it is what you will see
+it do:
+
+1. `sai_machines` once — skip when the machine id is already known.
+2. `sai_task_start { task }` → `session_id`. The task keeps running on the
+   machine.
+3. `sai_task_wait { session_id }` and repeat while `status` is `running`,
+   passing back the `cursor` each time (each call blocks up to `timeout_s`,
+   under Claude Code's two-minute tool limit).
+   - `needs_approval`: read `approval`. If `isLinkOnly` is false, decide with
+     `sai_task_approve`. If it is true (OAuth consent, credentials, phone
+     verification) the model hands `approval.approvalUrl` to you and keeps
+     waiting.
+   - `idle`: `text` is Sai's answer.
+   - `error`: `error` says what went wrong.
+4. `sai_task_abort` to stop a task you no longer want.
+
+One conversation per machine persists on Sai's `api` channel across calls, so
+follow-up tasks can refer to earlier ones. `new_session: true` starts clean.
+
+Files: `sai_upload` a local file first, then pass its `file_id` in
+`sai_task_start.file_ids` (uploads are remembered for the lifetime of the
+server process).
+
+## Channels (Claude Code, research preview)
+
+Claude Code [channels](https://code.claude.com/docs/en/channels) let a server
+push events into the session instead of being polled. This server always
+declares the `claude/channel` capability; with `SAI_PUSH=1` it also acts on it:
+`sai_task_start` returns `push: true`, the model stops calling
+`sai_task_wait`, and the server delivers `needs_approval`, `idle` and `error`
+as `<channel source="sai" session_id=… event=… approval_id=… approval_url=…>`
+notifications while Claude carries on with other work.
+
+Constraints of the preview:
+
+- Only Claude Code supports channels; Codex and Cursor poll (the default).
+- Channels are allow-listed. Add the server with push on and load it as a
+  development channel, which skips the allowlist after a confirmation prompt
+  (the organization `channelsEnabled` policy still applies):
+
+  ```bash
+  claude mcp add sai -e SAI_API_KEY=sapi_... -e SAI_PUSH=1 -- npx -y @simular-ai/sai-mcp
+  claude --dangerously-load-development-channels server:sai
+  ```
+
+  Never set `SAI_PUSH=1` without that flag: the model is told not to poll and
+  the pushed results are dropped.
+
+- Anthropic auth only.
+
+Polling is the baseline and works everywhere; push is an optimisation for
+long tasks.
+
+## Development
+
+From the monorepo root:
+
+```bash
+npm run test -w @simular-ai/sai-mcp       # vitest
+npm run typecheck -w @simular-ai/sai-mcp
+npm run build -w @simular-ai/sai-mcp      # dist/server.js (esbuild bundle)
+SAI_API_KEY=... node packages/sai-mcp/dist/server.js   # run over stdio
+```
+
+Point at staging with `SAI_API_URL=https://staging.cloud-api.simular.cloud`.
+
+## Releasing
+
+Same as `sai-cli` (see `.github/workflows/publish-sai-mcp.yml`): bump `version`
+in `package.json` and `SERVER_VERSION` in `src/server.ts`, merge, then
+`git tag sai-mcp-vX.Y.Z && git push origin sai-mcp-vX.Y.Z`. CI publishes to npm
+with trusted publishing (OIDC) and creates a GitHub release.

package/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: sai
+description: Hand a task to Sai, a computer-use agent on a real Windows or macOS computer, over plain HTTP with curl and jq, and bring back the result.
+---
+
+# Sai over HTTP
+
+Use this skill when the user asks to do something on a computer that this environment cannot do itself: open a desktop application, work in a browser with the user's accounts, read or produce files on their machine, or anything that needs a screen. Sai runs the task on the user's computer and returns text.
+
+Do not use it for work that can be done locally in this repository.
+
+If the `sai` MCP tools (`sai_task_start`, `sai_task_wait`, `sai_task_approve`) are available in this session, use them instead: they run the same loop below without shell commands. The HTTP steps here are for sessions without the MCP server.
+
+## Prerequisites
+
+- `SAI_API_KEY` is set in the environment. If it is not, stop and ask the user to create one at https://platform.simular.ai and export it. Never ask for the key value in chat.
+- `SAI_API_URL` is optional. Default to `https://api.simular.ai`.
+- `curl` and `jq` are on the path.
+
+Every request carries `-H "Authorization: Bearer $SAI_API_KEY"`.
+
+## The loop
+
+Run these steps in order. Do not skip the poll.
+
+1. **Start.** `POST /v1/agents/message` with `{"message": <task>, "wait": false}`. Read `sessionId` from the `202` body. Omit `machineId` unless the user named a computer or a previous `400` listed candidates.
+2. **Poll.** `GET /v1/agents/events?sessionId=<id>&wait=30`, then repeat with `&since=<cursor>` from the last response. Print each `data-progress` text as a short progress line. Stop polling when `status` is not `running`.
+3. **On `needs_approval`.** Read the top-level `approval` object in the poll response (same shape as a `data-approval-request` event's `data`) and check `approval.isLinkOnly`.
+   - `false`: decide whether the action is what the user asked for. If yes, `POST /v1/agents/approve` with `{"approvalId": ..., "response": "yes"}`. Use `"response": "task"` when the same kind of request will repeat within this task. Use `"no"` when it is outside the task. For `approvalType: "choice"`, add `"selections"`, one inner array per question, using values from `questions[].options[].value`; if the answer is not obvious from the task, ask the user with AskUserQuestion first.
+   - `true`: you cannot answer it. Call AskUserQuestion and hand the user `approval.approvalUrl` with one sentence saying what it is for (Google connect, a site password, phone verification). When they confirm they are done, go back to step 2 with the same cursor.
+4. **On `idle`.** Report `text` to the user verbatim, then summarise if it is long.
+5. **On `error`.** Report the `error` event's `errorText`. Do not retry automatically. If the event (or a `tool-output-error`) carries `code`, stop and do not start the task again today:
+   - `insufficient_credits`: tell the user their credit is spent. Free plan: it refreshes at `resetsAt` (UTC midnight; convert to their local time). Paid plan: top up at https://platform.simular.ai. Call `GET /v1/agents/account` and include `plan.title` and `credits.usd` in the message.
+   - `free_computer_time_exhausted`: tell the user the free plan's daily computer time is used up and the computer was shut down. It resets daily (exact local time in the Sai app); they can come back tomorrow or upgrade. No retry today.
+
+To run a task on a specific model, add `"model": <id>` to the start body. Ids come from `GET /v1/agents/models` (`allowed: false` means not on this plan); `"auto"` is the default. The choice sticks to the session, so send it once.
+
+A free account's first task of the day can stay in `running` for about two minutes while the computer starts. Keep polling.
+
+## Rate limits and errors
+
+- `429` on any call: wait 60 seconds and retry once. If it happens again, tell the user the account's hourly limit is reached (60 messages per hour, 1200 polls per hour) and stop. Never poll with `wait=0` in a loop.
+- `400` on start with a `machines` array: several computers exist. Pick the one the user named, or ask with AskUserQuestion.
+- `400 {"error":"unknown_model"}` or `403 {"error":"model_not_allowed_for_plan"}` on start: drop `model` or pick one from the `allowedModels` list in the reply.
+- `403` on start: the `machineId` is not on this account. Call `GET /v1/agents/machines` and use one of the returned ids.
+- `409` on start: the message was refused; report `error` to the user.
+- `403` on poll: the `sessionId` is wrong or not this account's. Check the value you saved from the start response.
+- `409 {"error":"link_only"}` on approve: treat as `isLinkOnly: true` and hand over `approvalUrl`.
+
+## Cancelling
+
+If the user cancels, or you decide the task should stop, call `POST /v1/agents/abort` with `{"sessionId": <id>}` using the session from the start response. Report `aborted` from the reply.
+
+## Commands
+
+Start a task and capture the session id:
+
+```bash
+SESSION=$(curl -sS "${SAI_API_URL:-https://api.simular.ai}/v1/agents/message" \
+  -H "Authorization: Bearer $SAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$(jq -n --arg m "Open Notepad, type hello, save it to the desktop as hello.txt" '{message:$m, wait:false}')" \
+  | tee /dev/stderr | jq -r .sessionId)
+```
+
+Poll once (repeat, feeding `cursor` back as `since`):
+
+```bash
+curl -sS "${SAI_API_URL:-https://api.simular.ai}/v1/agents/events?sessionId=$SESSION&since=$CURSOR&wait=30" \
+  -H "Authorization: Bearer $SAI_API_KEY" \
+  | jq '{status, cursor, text, approval, progress: [.events[] | select(.type=="data-progress") | .data.text]}'
+```
+
+Approve a command request:
+
+```bash
+curl -sS "${SAI_API_URL:-https://api.simular.ai}/v1/agents/approve" \
+  -H "Authorization: Bearer $SAI_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d "$(jq -n --arg id "$APPROVAL_ID" '{approvalId:$id, response:"yes"}')"
+```
+
+Build JSON bodies with `jq -n` as above so user text with quotes never breaks the request.
+
+## Reference
+
+Full API documentation: https://docs.simular.ai/sai-api/introduction. Endpoints used here: `POST /v1/agents/message`, `GET /v1/agents/events`, `POST /v1/agents/approve`, `POST /v1/agents/abort`, `GET /v1/agents/machines`, `GET /v1/agents/models`, `GET /v1/agents/account`.