@shardflux/mcp 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+Every tool, field and variable the README shows is available from the version named here. Below 1.0, a minor release
+may break compatibility; breaking changes are marked **Breaking**. Versions before 0.3.0 were not published.
+
+## 0.3.0 (first public npm release; not yet published)
+
+Needs `@shardflux/sdk` 0.7.0 or later. New dependency: `yaml` (template.yaml).
+
+### Public npm package
+
+- First release on npm: `npx -y @shardflux/mcp` (bin `shardflux-mcp`) runs the stdio server. The package ships
+  compiled JavaScript and type declarations (`dist/`); Node.js 24 or later. Earlier versions ran only from a source
+  checkout.
+- Depends on the published `@shardflux/sdk` (`^0.7.0`), `@modelcontextprotocol/sdk` 1.30.0, `yaml` and `zod` (the MCP
+  SDK's peer dependency).
+- `mcpName` `dev.shardflux/mcp` in package.json and a `server.json` for the official MCP Registry.
+- The README covers setup for Claude Code, Cursor, Codex and Claude Desktop. License: Apache-2.0.
+
+### Tools
+
+- `workspace_open` takes `inputs` (`{"NAME": "value"}`: the template's text inputs); workspace results carry
+  `startup` (start commands and services: pending, running, ready or failed with the step, exit code and output
+  tail).
+- `template_get`: a template's versions with their settings (the inputs `workspace_open` takes); with `version`, that
+  version's recipe (the export).
+- `template_languages`: the languages and versions a base offers `build.languages`.
+- `template_build`: builds a version from a recipe v2 given as `recipe` (an object) or `file` (a template.yaml or
+  .json path). Local `from` paths are uploaded through the SDK. Every local path must resolve inside the server's
+  working directory (a path outside it is `invalid_arguments`, before any request). The version stays unpublished
+  unless `publish`; `wait` follows the build within the call's deadline. Returns the build (state, registration,
+  recipe_sha256, denied_hosts, failure) and the uploads.
+- An upload the storage refused is `upload_failed` with the storage's code.
+
+## 0.2.1
+
+Needs `@shardflux/sdk` 0.6.2 (the workspace version).
+
+The API no longer lets a start (open, resume, fork) wait in `capacity_pending` forever: one that no host could admit
+15 minutes after it began fails with `capacity_unavailable` (retryable; nothing was started, a suspended workspace
+stays suspended).
+
+- Failed-operation errors (`code: operation_failed`) carry `retryable`, the operation error's own flag, and
+  `details.reason` when the operation error has one. A `capacity_unavailable` failure's message adds that nothing was
+  started and the agent may retry later. The server does not retry.
+- A wait that times out while the start waits for capacity names when it gives up (the SDK's message).
+- Server instructions and the `workspace_open` description say a start waits for capacity for at most 15 minutes.
+
+## 0.2.0
+
+- `timing` (the SDK's lifecycle timing, compacted) in `workspace_open`, waited lifecycle, `operation_wait` and wake
+  results, and next to `error` when they fail.
+
+## 0.1.0
+
+- First version.

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,289 @@
+# @shardflux/mcp: `shardflux-mcp`
+
+The [Shardflux](https://shardflux.dev) MCP server. It gives Claude Code, Claude Desktop, Cursor,
+Codex or any other MCP client persistent cloud workspaces: open a workspace by key, then run
+commands, read and write files, use git, terminals and a browser in it, and suspend, resume or
+fork it.
+
+It runs locally over stdio and uses [`@shardflux/sdk`](https://www.npmjs.com/package/@shardflux/sdk)
+with the scoped project API key you give it. Each tool call becomes one SDK request or wait:
+
+- it has **no agent loop** of its own;
+- it keeps **no local workspace directory**;
+- it keeps **no state** beyond per-key workspace handles, so tool tokens are reused between calls.
+
+Documentation: <https://docs.shardflux.dev/reference/mcp>.
+
+> **Early access.** Shardflux is in early access, and this server is below 1.0: tools and results
+> may still change in a minor release.
+
+Requires Node.js 24 or later and a Shardflux project API key (`sfk_...`, from the Shardflux console).
+
+## Run
+
+MCP clients start the server themselves (see "Client setup"). The command is:
+
+```sh
+npx -y @shardflux/mcp
+```
+
+with `SHARDFLUX_API_KEY` in its environment. To try it by hand:
+
+```sh
+SHARDFLUX_API_KEY=sfk_... npx -y @shardflux/mcp
+```
+
+It logs one JSON `ready` line on stderr and then waits for MCP messages on stdin (stdout is the
+protocol). Close stdin or press Ctrl-C to stop it.
+
+Or install it globally and use the `shardflux-mcp` command instead of `npx -y @shardflux/mcp`:
+
+```sh
+npm install -g @shardflux/mcp
+```
+
+## Client setup
+
+Each example registers the server as `shardflux`. Replace `sfk_...` with your key, and add any
+other variable from "Configuration" the same way.
+
+### Claude Code
+
+```sh
+claude mcp add --scope user --env SHARDFLUX_API_KEY=sfk_... --transport stdio shardflux -- npx -y @shardflux/mcp
+claude mcp get shardflux
+```
+
+Options go before the name (`shardflux`), and everything after `--` is the command. `--scope user`
+makes the server available in every project; leave it out for the current project only, or use
+`--scope project` to write it to `.mcp.json` for your team. In `.mcp.json`, read the key from the
+environment instead of committing it:
+
+```json
+{
+  "mcpServers": {
+    "shardflux": {
+      "command": "npx",
+      "args": ["-y", "@shardflux/mcp"],
+      "env": { "SHARDFLUX_API_KEY": "${SHARDFLUX_API_KEY}" }
+    }
+  }
+}
+```
+
+In a session, `/mcp` shows the server's status.
+
+### Cursor
+
+Add the server to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one project):
+
+```json
+{
+  "mcpServers": {
+    "shardflux": {
+      "command": "npx",
+      "args": ["-y", "@shardflux/mcp"],
+      "env": { "SHARDFLUX_API_KEY": "${env:SHARDFLUX_API_KEY}" }
+    }
+  }
+}
+```
+
+`${env:SHARDFLUX_API_KEY}` reads the key from the environment Cursor runs in; you can also put the
+key itself there.
+
+### Codex
+
+Add the server to `~/.codex/config.toml` (or `.codex/config.toml` in a trusted project):
+
+```toml
+[mcp_servers.shardflux]
+command = "npx"
+args = ["-y", "@shardflux/mcp"]
+env_vars = ["SHARDFLUX_API_KEY"]  # forward the key from the environment Codex runs in
+startup_timeout_sec = 30          # the first run downloads the package (Codex default: 10)
+tool_timeout_sec = 180            # above the server's per-call deadline, 120 s by default (Codex default: 60)
+```
+
+To set the key in the file instead, replace `env_vars` with:
+
+```toml
+[mcp_servers.shardflux.env]
+SHARDFLUX_API_KEY = "sfk_..."
+```
+
+Or from the command line:
+
+```sh
+codex mcp add shardflux --env SHARDFLUX_API_KEY=sfk_... -- npx -y @shardflux/mcp
+```
+
+`workspace_open` waits until the workspace is ready, up to the server's per-call deadline
+(`SHARDFLUX_MCP_TOOL_TIMEOUT_MS`, default 120000 ms). Keep `tool_timeout_sec` above it, or Codex
+gives up on the call first.
+
+### Claude Desktop
+
+Open Settings, then Developer, then Edit Config. This opens `claude_desktop_config.json`
+(`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS,
+`%APPDATA%\Claude\claude_desktop_config.json` on Windows). Add:
+
+```json
+{
+  "mcpServers": {
+    "shardflux": {
+      "command": "npx",
+      "args": ["-y", "@shardflux/mcp"],
+      "env": { "SHARDFLUX_API_KEY": "sfk_..." }
+    }
+  }
+}
+```
+
+Then quit Claude Desktop completely and start it again. The server's stderr goes to
+`mcp-server-shardflux.log` in Claude Desktop's log folder (`~/Library/Logs/Claude` on macOS,
+`%APPDATA%\Claude\logs` on Windows).
+
+### Other clients
+
+Any client that starts stdio servers works: command `npx`, arguments `-y @shardflux/mcp`,
+environment `SHARDFLUX_API_KEY`.
+
+## Configuration (environment)
+
+| Variable | Meaning |
+| --- | --- |
+| `SHARDFLUX_API_KEY` | Scoped project API key. Required. Its tool permissions decide which workspace tools are listed. |
+| `SHARDFLUX_API_URL` | Default `https://api.shardflux.dev`. Plain `http://` is allowed only for loopback hosts. |
+| `SHARDFLUX_WORKSPACE_KEY` | Pins one workspace. `workspace_key` becomes optional on every tool, and a different key is refused with `workspace_pinned`. |
+| `SHARDFLUX_TEMPLATE` | Default template for `workspace_open`. |
+| `SHARDFLUX_MCP_TOOL_TIMEOUT_MS` | Default **and maximum** deadline per tool call, 1000-3600000 ms. Default 120000. A call's `timeout_ms` can only shorten it. |
+| `SHARDFLUX_WAKE` | `on` (default) or `off`. On: workspace tools resume a suspended workspace and then run (see "Contract"). Off: they return the `workspace_not_running` refusal. |
+| `SHARDFLUX_WAKE_TIMEOUT_MS` | Longest wait per tool call for a workspace to wake or finish a transition, 1000-3600000 ms. Default 120000. It is clamped to `SHARDFLUX_MCP_TOOL_TIMEOUT_MS`, and each wake also ends 250 ms before the call's own deadline. |
+| `SHARDFLUX_AGENT_LABEL` | Attribution label of every tool token this server obtains. Default `mcp`. It appears as an agent session in `GET /v1/workspaces/{id}/agent-sessions`, the console and `shard ws sessions`. |
+| `SHARDFLUX_MCP_LOG_LEVEL` | `debug`, `info` (default), `warn` or `error`. Logs are JSON lines on **stderr**; stdout is the protocol. The key is never logged, and anything key-shaped is redacted. |
+| `SHARDFLUX_HTTP_KEEPALIVE=1` | Reuse HTTP connections. By default every request uses a fresh connection (`Connection: close`), because on some Node.js releases a request sent on a reused keep-alive connection can stall until the request timeout. |
+
+Invalid configuration exits with code 2 before serving, with one JSON line on stderr, for example:
+
+```
+{"time":"2026-09-28T20:18:25.654Z","level":"error","service":"shardflux-mcp","message":"configuration error: SHARDFLUX_API_KEY is required (a scoped Shardflux project API key)"}
+```
+
+`template_build` reads local files (`file`, and `from` paths in a recipe) only inside the server's
+working directory: the directory your MCP client starts it in.
+
+## Tools
+
+The management tools:
+
+| Tool | Does |
+| --- | --- |
+| `workspace_open` | Open by key: create on first use, reconnect or resume afterwards, never reset. Waits until the workspace is ready (its template's start commands and services included) unless `wait: false`. `lifetime: "session"` opens a workspace that is discarded after its idle timeout. `inputs` (0.3.0) passes the template's text inputs, `{"NAME": "value"}`. |
+| `workspace_list` | List the project's workspaces, with `prefix`, `state`, `lifetime`, `purpose`, `include_deleted`, `limit` and `cursor`. By default only persistent standard workspaces are listed. |
+| `workspace_status` | One workspace plus its five most recent operations. |
+| `workspace_suspend`, `workspace_resume` | Lifecycle operation. Returns at once unless `wait: true` (then once it finished, through the SDK's own `wait`). |
+| `workspace_fork` | Fork into `new_key`. |
+| `operation_wait` | Keep waiting for an operation. |
+| `usage_summary` | The organization's usage summary for the current period. |
+| `template_get` | (0.3.0) A template's versions with their settings (env, inputs, start commands, services, defaults); with `version`, that version's recipe in request form. |
+| `template_languages` | (0.3.0) The languages and versions a base (`<slug>@<version>`) offers `build.languages`. |
+| `template_build` | (0.3.0) Build a version of an organization template from a recipe v2: `recipe` (the document) or `file` (a template.yaml or .json path). File entries may name local `from` paths, uploaded first (folders as a tar). **Every local path must resolve inside the server's working directory**; others are refused before any request. Unpublished unless `publish: true`; `wait: true` follows the build within the call's deadline. |
+
+The SDK's workspace tools come from `workspaceTools()`:
+
+- `exec`
+- `read_file`, `write_file`, `list_files`
+- `list_processes`, `signal_process`
+- `terminal_open`, `terminal_send`, `terminal_read`, `terminal_close`
+- `git_clone`, `git_status`, `git_commit`
+- `browser_screenshot`, `browser_content`
+
+They are published with **the SDK's JSON Schemas verbatim**, plus `workspace_key` and, where the
+SDK schema has none, `timeout_ms`. They are filtered by the key's tool permissions (if the server
+cannot read them, for example because the API is unreachable, it lists every workspace tool and logs
+a warning). `browser_screenshot` returns an MCP image content block.
+
+Deleting a workspace is deliberately not exposed to agents; use the
+[CLI](https://www.npmjs.com/package/@shardflux/cli) or the console.
+
+Every tool finds its workspace by exact key across every lifetime and purpose, so sessions, template drafts and test
+instances resolve too. The live workspace wins over tombstones that ended sessions left with the same key. Workspace
+results include `lifetime`, `purpose`, `disk_layout`, `idle_timeout_seconds`, `ended_reason` and (0.3.0) `startup`:
+the state of the template's start commands and services (`failed` names the step, its exit code and output tail).
+
+## Contract
+
+- **Arguments.** They are validated against the published schema with the SDK's `validateArgs`
+  before any request. A failure returns `isError` with `code: invalid_arguments` and the issues.
+- **Errors are tool results.** They carry `isError: true` and
+  `structuredContent.error = {code, message, status, request_id, retryable, operation_id, details, source}`,
+  using the API's or cell gateway's closed error codes. They are never protocol failures. The
+  only protocol error is an unknown tool name (`InvalidParams`).
+  - A failed operation is `code: operation_failed` with `details.error_code` (and `details.reason` when the
+    operation error has one) and, from 0.2.1, `retryable`: the operation error's own flag.
+  - An API or cell gateway the server cannot reach is `code: network_error`, `retryable: true`.
+- **Starts wait for capacity for at most 15 minutes (0.2.1+).** An open, resume or fork that no host can admit waits
+  in `capacity_pending`; a wait that ends first returns `code: timeout`, and its message names when the start gives
+  up. A start still pending then fails: `operation_failed`, `details.error_code: capacity_unavailable`,
+  `retryable: true`, and a message telling the agent that nothing was started and it may retry later. The server
+  never retries it itself. The server instructions say the same.
+- **Timing (0.2.0+).** A call that opens a workspace or waits says where the time went, from the SDK's lifecycle
+  timing, compact for model context:
+
+  ```json
+  "timing": {
+    "action": "open", "outcome": "succeeded", "operation_id": "01a0e5a8-3ef0-7ecb-975e-dff2d5ca6e33", "total_ms": 34180,
+    "phases": ["request(held) 20010 ms", "capacity_pending(no_ready_host) 13520 ms", "running 590 ms", "view 42 ms", "token 61 ms"],
+    "server": { "queued_ms": 33400, "run_ms": 620, "total_ms": 34020, "start_path": "warm" },
+    "outside_server_ms": 160, "retries": 0
+  }
+  ```
+
+  - `workspace_open` and `operation_wait` always carry it. `workspace_suspend`, `workspace_resume` and
+    `workspace_fork` carry it with `wait: true`. Workspace tools carry it when they had to wake the workspace
+    (`action: "wake"`). Other results do not.
+  - Phases are in order, as `phase(reason) ms`. `request(held)` means the API held the open until the workspace was
+    ready. `capacity_pending(no_ready_host)` is time spent waiting for a host.
+  - `server` is the operation's own queued, run and total time, plus the start or resume path the cell reported.
+  - `outside_server_ms` is everything else: network, polling, reading the workspace, the tool token.
+  - A failed or timed-out call carries it too, next to `error` (`{error, timing}`).
+  - `workspace_open` uses the SDK's waited open: the API holds the request until the workspace is ready and answers
+    with the first tool token, which the next tool call reuses.
+- **Deadlines.** Every call has one: `timeout_ms`, clamped to the ceiling.
+  - Waits time out just before the deadline with `code: timeout` and the `operation_id`; the
+    operation continues server side (a start waiting for capacity for at most 15 minutes).
+  - Any request still in flight at the deadline is aborted.
+  - `exec`'s command timeout is capped at the deadline minus 2 s, so its output comes back.
+- **Cancellation.** MCP `notifications/cancelled` aborts the SDK work behind the call: waits,
+  HTTP requests to the API and to the cell gateway, and backoff sleeps. No response is sent, and
+  the server stays up. The lifecycle operation itself is not canceled.
+- **Workspace tools wake suspended workspaces, but do not open new ones.** A workspace that was
+  never opened is `not_found`: call `workspace_open` first.
+  - A suspended workspace is resumed (or the resume or open already running is joined), and the
+    call runs once it is running. A call made during a suspend or resume waits for it to finish.
+    The call never runs twice: the refused attempt did nothing.
+  - The wait is bounded by `SHARDFLUX_WAKE_TIMEOUT_MS` and the call's deadline. Past it the
+    result is `code: timeout` with the `operation_id` and `last_state` of the resume or open. That
+    operation continues server side: `operation_wait` keeps waiting. A resume or open that fails
+    returns `code: operation_failed` (`retryable: true` for `capacity_unavailable`: the workspace stays
+    suspended).
+  - With `SHARDFLUX_WAKE=off` the API's refusal comes back instead (`conflict`,
+    `details.reason: workspace_not_running`, or `workspace_not_running` from the cell gateway).
+  - Tool tokens are never returned to the model.
+- **Keys, not ids.** Tools take workspace keys, resolved by exact match within the key's project.
+
+## Use as a library
+
+The package also exports the server for other MCP transports:
+
+```ts
+import { createShardfluxMcpServer, loadConfig } from '@shardflux/mcp';
+
+const server = createShardfluxMcpServer(loadConfig(process.env)); // an MCP SDK Server
+await server.connect(transport); // any @modelcontextprotocol/sdk transport
+```
+
+## License
+
+Apache-2.0

package/dist/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin.js

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/** `shardflux-mcp`: the local stdio MCP server (configuration from the environment; see README). */
+import { main } from "./main.js";
+const code = await main(process.env);
+if (code !== null)
+    process.exit(code);

package/dist/config.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Environment configuration of the local MCP server (README "Configuration").
+ * The API key is validated for shape only here; it is never logged or echoed.
+ */
+export interface McpConfig {
+    apiKey: string;
+    apiUrl: string;
+    /** Pinned workspace key: workspace tools default to (and are restricted to) it. */
+    workspaceKey: string | undefined;
+    /** Template used by workspace_open when the call names none. */
+    template: string | undefined;
+    /** Default and maximum per-call deadline (ms). */
+    toolTimeoutMs: number;
+    /** Workspace tools resume a suspended workspace on use (SHARDFLUX_WAKE, default on). */
+    wake: boolean;
+    /** Longest wait for a workspace to wake or finish a transition per call (ms); never above toolTimeoutMs. */
+    wakeTimeoutMs: number;
+    /** Attribution label on every tool token this server obtains (agent session). */
+    agentLabel: string;
+    logLevel: 'debug' | 'info' | 'warn' | 'error';
+}
+export declare class ConfigError extends Error {
+    name: string;
+}
+export declare const DEFAULT_TOOL_TIMEOUT_MS = 120000;
+export declare const MAX_TOOL_TIMEOUT_MS = 3600000;
+export declare const DEFAULT_WAKE_TIMEOUT_MS = 120000;
+export declare function apiUrlFrom(raw: string | undefined): string;
+export declare function loadConfig(env: Record<string, string | undefined>): McpConfig;

package/dist/config.js

@@ -0,0 +1,75 @@
+/**
+ * Environment configuration of the local MCP server (README "Configuration").
+ * The API key is validated for shape only here; it is never logged or echoed.
+ */
+export class ConfigError extends Error {
+    name = 'ConfigError';
+}
+const KEY_SHAPE = /^sfk_[a-z2-7]{16}_[A-Za-z0-9]+$/;
+/** Non-empty and free of C0 controls and DEL (the API's key/label pattern). */
+const printable = (s) => s.length > 0 && ![...s].some((ch) => ch.charCodeAt(0) < 0x20 || ch.charCodeAt(0) === 0x7f);
+const SLUG = /^[a-z0-9](?:[a-z0-9._-]{0,98}[a-z0-9])?$/;
+const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+export const DEFAULT_TOOL_TIMEOUT_MS = 120_000;
+export const MAX_TOOL_TIMEOUT_MS = 3_600_000;
+export const DEFAULT_WAKE_TIMEOUT_MS = 120_000;
+export function apiUrlFrom(raw) {
+    const text = (raw ?? '').trim() || 'https://api.shardflux.dev';
+    let u;
+    try {
+        u = new URL(text);
+    }
+    catch {
+        throw new ConfigError(`SHARDFLUX_API_URL is not a valid URL: "${text}"`);
+    }
+    if (u.protocol !== 'https:' && !(u.protocol === 'http:' && (LOOPBACK.has(u.hostname) || u.hostname.endsWith('.localhost')))) {
+        throw new ConfigError('SHARDFLUX_API_URL must use https (plain http only for localhost): the API key is a bearer credential');
+    }
+    if (u.username || u.password || u.search || u.hash)
+        throw new ConfigError('SHARDFLUX_API_URL must not contain credentials, a query or a fragment');
+    return u.toString().replace(/\/+$/, '');
+}
+export function loadConfig(env) {
+    const apiKey = env.SHARDFLUX_API_KEY?.trim();
+    if (!apiKey)
+        throw new ConfigError('SHARDFLUX_API_KEY is required (a scoped Shardflux project API key)');
+    if (!KEY_SHAPE.test(apiKey))
+        throw new ConfigError('SHARDFLUX_API_KEY is not a Shardflux project key (expected sfk_<key id>_<secret>)');
+    const workspaceKey = env.SHARDFLUX_WORKSPACE_KEY?.trim() || undefined;
+    if (workspaceKey !== undefined && (workspaceKey.length > 200 || !printable(workspaceKey))) {
+        throw new ConfigError('SHARDFLUX_WORKSPACE_KEY must be 1-200 printable characters');
+    }
+    const template = env.SHARDFLUX_TEMPLATE?.trim() || undefined;
+    if (template !== undefined && !SLUG.test(template))
+        throw new ConfigError('SHARDFLUX_TEMPLATE must be a template slug (lowercase letters, digits, . _ -)');
+    let toolTimeoutMs = DEFAULT_TOOL_TIMEOUT_MS;
+    const t = env.SHARDFLUX_MCP_TOOL_TIMEOUT_MS?.trim();
+    if (t) {
+        if (!/^\d+$/.test(t))
+            throw new ConfigError('SHARDFLUX_MCP_TOOL_TIMEOUT_MS must be an integer number of milliseconds');
+        toolTimeoutMs = Number(t);
+        if (toolTimeoutMs < 1000 || toolTimeoutMs > MAX_TOOL_TIMEOUT_MS)
+            throw new ConfigError(`SHARDFLUX_MCP_TOOL_TIMEOUT_MS must be between 1000 and ${MAX_TOOL_TIMEOUT_MS}`);
+    }
+    const wakeText = (env.SHARDFLUX_WAKE?.trim() || 'on').toLowerCase();
+    if (wakeText !== 'on' && wakeText !== 'off')
+        throw new ConfigError('SHARDFLUX_WAKE must be on or off');
+    let wakeTimeoutMs = DEFAULT_WAKE_TIMEOUT_MS;
+    const w = env.SHARDFLUX_WAKE_TIMEOUT_MS?.trim();
+    if (w) {
+        if (!/^\d+$/.test(w))
+            throw new ConfigError('SHARDFLUX_WAKE_TIMEOUT_MS must be an integer number of milliseconds');
+        wakeTimeoutMs = Number(w);
+        if (wakeTimeoutMs < 1000 || wakeTimeoutMs > MAX_TOOL_TIMEOUT_MS)
+            throw new ConfigError(`SHARDFLUX_WAKE_TIMEOUT_MS must be between 1000 and ${MAX_TOOL_TIMEOUT_MS}`);
+    }
+    // A wake can never outlast the call it serves.
+    wakeTimeoutMs = Math.min(wakeTimeoutMs, toolTimeoutMs);
+    const agentLabel = env.SHARDFLUX_AGENT_LABEL?.trim() || 'mcp';
+    if (agentLabel.length > 100 || !printable(agentLabel))
+        throw new ConfigError('SHARDFLUX_AGENT_LABEL must be 1-100 printable characters');
+    const level = (env.SHARDFLUX_MCP_LOG_LEVEL?.trim() || 'info');
+    if (!['debug', 'info', 'warn', 'error'].includes(level))
+        throw new ConfigError('SHARDFLUX_MCP_LOG_LEVEL must be debug, info, warn or error');
+    return { apiKey, apiUrl: apiUrlFrom(env.SHARDFLUX_API_URL), workspaceKey, template, toolTimeoutMs, wake: wakeText === 'on', wakeTimeoutMs, agentLabel, logLevel: level };
+}