@simular-ai/sai-mcp 0.2.2 → 0.3.0-rc.1

package/README.md

@@ -1,10 +1,16 @@
 # @simular-ai/sai-mcp
 
 Give your coding agent a computer. This MCP server lets Claude Code, Codex,
-Cursor or any MCP client hand tasks to [Sai](https://www.simular.ai), Simular's
-computer-use agent. Sai does the work on a real desktop (a browser, native
-apps, files) and reports back. Sai runs on a cloud computer we host; the free
-plan includes one.
+Cursor or any MCP client hand tasks to [Sai](https://platform.simular.ai),
+Simular's computer-use agent, #1 on OSWorld 2.0 (73%). Sai uses apps and
+websites the way a person does, by seeing the screen, clicking and typing, so
+your agent can get work done where there is no API: web apps behind a login,
+admin consoles, desktop software, forms with no import. Sai runs on a
+cloud computer we host; the free plan includes one.
+
+Run a workflow once and Sai can save it as code: later runs replay that code
+and ask the model only where the screen matters, so they are faster and
+cheaper, and the agent takes over when the UI changes.
 
 You need Node.js 22.12 or newer and a Sai API key (`sapi_…`). Sign in at
 [platform.simular.ai](https://platform.simular.ai) and create one under
@@ -12,6 +18,43 @@ You need Node.js 22.12 or newer and a Sai API key (`sapi_…`). Sign in at
 
 Docs: [platform.simular.ai/documentation](https://platform.simular.ai/documentation)
 
+## When to use Sai
+
+Use Sai when:
+
+- There is no API, or the API doesn't cover the task: vendor portals, admin
+  consoles, legacy web apps.
+- The task needs a real browser session with someone's accounts. Sign-ins,
+  passwords and phone checks go to the human as an approval link.
+- The work happens in a desktop app, on Windows, macOS or Linux.
+- It is a one-off, and a script would cost more to write and keep working than
+  the task itself.
+- You need to see what a real user sees: testing a sign-up flow, reproducing a
+  bug report.
+- It is a workflow you will repeat (see below).
+
+Write code yourself when a documented API or SDK does the job, the data is
+already local, or you need exact, byte-for-byte output.
+
+## Run once, replay as code
+
+1. Run the task once with Sai.
+2. Ask: `Save this as a replayable skill named invoice_export, with vendor and month as parameters.`
+3. Next time: `Run invoice_export for vendor Acme, month March.` Sai replays
+   the code; when a step breaks because the UI changed, the agent takes over.
+
+The research behind it: [Neuro-Symbolic Computer Use](https://arxiv.org/abs/2609.36927)
+(Sep 2026). Learned policies cut per-run cost 15–217× and latency 3.4–5.1×, and
+raised Pass^3 by 3.6–15.8 points over the base agent on OSWorld-Verified and
+ScienceBoard.
+
+## Example tasks
+
+- `Open our staging site in Chrome, sign up with the test Gmail account, click the verification email, and tell me where the flow breaks.`
+- `Log in to the vendor portal (it has no API) and list last month's invoices with their totals.`
+- `Enter each row of the uploaded CSV into the supplier form at <url>, which has no import, and report the rows that failed validation.`
+- `Follow the steps in this bug report in Chrome on Windows and describe exactly what happens at each step.`
+
 ## Install
 
 Replace `sapi_YOUR_KEY` with your key.
@@ -44,8 +87,6 @@ Or in `~/.codex/config.toml`:
 [mcp_servers.sai]
 command = "npx"
 args = ["-y", "@simular-ai/sai-mcp"]
-# sai_task_wait holds for up to 110 s; Codex's default tool timeout is 60 s.
-tool_timeout_sec = 120
 
 [mcp_servers.sai.env]
 SAI_API_KEY = "sapi_YOUR_KEY"
@@ -113,11 +154,13 @@ the view says so and offers **Watch here**.
 
 ## Environment
 
-| Variable         | Required | Meaning                                                              |
-| ---------------- | -------- | -------------------------------------------------------------------- |
-| `SAI_API_KEY`    | yes      | Your Sai API key (`sapi_…`).                                         |
-| `SAI_PUSH`       | no       | `1` turns on Claude Code channels (below). Leave it unset otherwise. |
-| `SAI_LOCAL_VIEW` | no       | `0` turns off the local `watch_url` page.                            |
+| Variable         | Required | Meaning                                                                   |
+| ---------------- | -------- | ------------------------------------------------------------------------- |
+| `SAI_API_KEY`    | yes      | Your Sai API key (`sapi_…`).                                              |
+| `SAI_PUSH`       | no       | `1` turns on Claude Code channels (below). Leave it unset otherwise.      |
+| `SAI_LOCAL_VIEW` | no       | `0` turns off the local `watch_url` page.                                 |
+| `SAI_CONTROL`    | no       | `0` leaves out the direct control tools (below), which are on by default. |
+| `SAI_OSWORLD`    | no       | `1` adds the OSWorld tools (below); keeps the direct control tools on.    |
 
 ## Claude Code channels (research preview)
 
@@ -134,6 +177,37 @@ claude --dangerously-load-development-channels server:sai
 Only set `SAI_PUSH=1` together with that flag. Without it, pushed results are
 dropped and your agent is told not to poll.
 
+## Direct control (research preview)
+
+Your agent can also drive the computer itself instead of
+handing Sai a task: `sai_control_open`, then `sai_control_exec` blocks of Simulang
+(JavaScript) that run on the computer, then `sai_control_close`. Each block
+returns its value and console output, plus a screenshot as an image your
+agent's own model sees. The Simulang reference is the MCP resource
+`sai://simulang/reference`. Any account can use it; model calls the code makes
+(`callLLM`, `ground`, `stateSatisfies`) are billed to your account as usual. Set
+`SAI_CONTROL=0` to leave these tools out.
+Docs: [Direct control](https://platform.simular.ai/documentation/concepts/direct-control).
+
+```bash
+claude mcp add sai -e SAI_API_KEY=sapi_YOUR_KEY -- npx -y @simular-ai/sai-mcp
+```
+
+## OSWorld (research preview)
+
+With `SAI_OSWORLD=1`, your agent can run OSWorld V2.1 tasks: `osworld_start`
+sets a task up on a fresh cloud computer and returns its instruction, your agent
+does the task through direct control of that computer, and `osworld_submit` grades
+it (with `outcome: "fail"` when the agent concludes the task cannot be done; some
+tasks are infeasible on purpose). `osworld_ask_user` answers questions for tasks that have a user, and
+`osworld_abandon` ends an attempt without grading so you can start it again.
+Setup and grading run on Simular's side; your agent only sees the instruction
+and the computer. Needs Benchmarks access on your account.
+
+```bash
+claude mcp add sai -e SAI_API_KEY=sapi_YOUR_KEY -e SAI_OSWORLD=1 -- npx -y @simular-ai/sai-mcp
+```
+
 ## Support
 
 [support@simular.ai](mailto:support@simular.ai)

package/SKILL.md

@@ -39,7 +39,7 @@ A free account's first task of the day can stay in `running` for about two minut
 
 ## 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.
+- `429` on any call: wait 60 seconds and retry once. If it happens again, tell the user the account's hourly limit is reached (600 messages per hour on a paid plan, 60 on free; 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.