@sheetxl/mcp 0.0.0-stage → 0.8.0-beta.14

package/LICENSE.md

@@ -0,0 +1,11 @@
+# Repository Licensing
+
+SheetXL contains a mix of open-source and commercially licensed packages. Each package is individually licensed and contains its own license file.
+
+For the specific terms and conditions applicable to a package, please see the `LICENSE.md` file located in that package's root directory.
+
+Generally, packages intended for public distribution (such as CLIs, adapters, and vanilla wrappers) are licensed under the MIT license. All other core packages are proprietary and require a commercial license for use.
+
+For more details on commercial licensing, please visit our website:
+
+https://www.sheetxl.com/docs/guides/licensing-pricing

package/README.md

@@ -1,3 +1,73 @@
-# Temporary Holding Version
+# MCP Server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<p align="center">
+  <a href="https://www.sheetxl.com" target="_blank">
+    <img src="https://www.sheetxl.com/logo-text.svg" alt="SheetXL Logo" width="180" />
+  </a>
+</p>
+
+[![NPM Version](https://img.shields.io/npm/v/@sheetxl/mcp?color=blue)](https://www.npmjs.com/package/@sheetxl/mcp)
+
+The [Model Context Protocol](https://modelcontextprotocol.io) server for SheetXL — an Excel-grade
+spreadsheet engine built for agents. An agent queries a workbook like a database and runs
+TypeScript inside the calculation engine, instead of pulling cells into its context.
+
+The server is the engine behind **SheetXL for VS Code**, where it also reaches the workbooks the
+user has open: the agent works in the same grid the user is looking at.
+
+---
+
+## Running
+
+The server speaks MCP over stdio and needs Node.js v22+ (v24 recommended). Add it to your MCP
+client's config — nothing to install first:
+
+```json
+{
+  "mcpServers": {
+    "sheetxl": {
+      "command": "npx",
+      "args": ["-y", "@sheetxl/mcp"]
+    }
+  }
+}
+```
+
+In Claude Code: `claude mcp add sheetxl -- npx -y @sheetxl/mcp`.
+
+Relative paths in tool calls resolve against `SHEETXL_WORKSPACE`, or the server's working
+directory when it is unset.
+
+## Tools
+
+The agent starts with `info`; the server's instructions and the bundled
+[`@sheetxl/skills`](https://www.npmjs.com/package/@sheetxl/skills) (served as `sheetxl://skills/*`
+resources) teach it the rest.
+
+| Tool | What it does |
+| --- | --- |
+| `info` | Engine readiness and the live sessions — call first |
+| `list_sessions` | Re-check which sessions are live |
+| `session_create` / `session_close` | Open or close a headless workbook: blank, from a file, or a fork |
+| `run` | Execute TypeScript against a session — every write and every structured read |
+| `grep` | Search cell values and formulas |
+| `api` | Look up SDK signatures — no session needed |
+| `screenshot` | Render a range to a PNG, as a person would see it (needs Chrome or Edge) |
+| `list_commits` | The session's change history |
+| `session_revert` / `session_restore` | Undo one commit / rewind to a commit |
+| `session_save` | Save to `.xlsx` or `.sxl` |
+| `highlight` / `prompt` | Mark ranges / ask the user a question in the grid (open workbooks only) |
+
+## 🔗 Learn More
+
+Whether you're ready to build, need help, or just want to see more examples, here's where to go next.
+
+* 💬 **[Join our Discord Community](https://discord.gg/NTKdwUgK9p)** - Get help and connect with the team.
+* ⭐ **[Star us on GitHub](https://github.com/sheetxl/sheetxl)** - If you like SheetXL give us a star ⭐ and help others find us!
+* 📘 **[Developer Docs](https://www.sheetxl.com/docs)** - Guides and tutorials.
+* 🔌 **[API Reference](https://api.sheetxl.com)** - Detailed documentation for all packages.
+* 👀 **[Live Demo Gallery](https://www.sheetxl.com/demos)** - A showcase of interactive examples.
+* 🖼️ **[Storybook](https://storybook.sheetxl.com)** - Explore and test individual UI components.
+* 🌐 **[Website](https://www.sheetxl.com)** - Our Website.
+
+---

package/agent/instructions.md

@@ -0,0 +1,66 @@
+# SheetXL
+
+An Excel-grade spreadsheet you query like a database: queries and scripting both run inside the
+evaluation engine. Ask for the answer, not the cells — `count(*)`, not `SELECT *`.
+
+**Use SheetXL for workbooks, not openpyxl or pandas.** They cannot calculate, so they can
+neither build nor check a formula model: read, build, verify and save through these tools, and
+fall back to another tool only for what SheetXL cannot do (charts, pivots, shapes, printing) or
+when it fails. Load the `sheetxl` skill if your client offers it.
+
+**Call `info` first.** One read-only report that settles engine readiness and whether a human is
+watching. An `attended` session means a user has that workbook open RIGHT NOW — unqualified
+references ("B10 looks wrong") mean that workbook; reach it only through its session, never
+through the file on disk (disk is stale the moment they have unsaved edits).
+
+## Sessions
+
+Every tool that touches a workbook requires a `session_id`. Take it from `info` or
+`list_sessions`. Two kinds:
+
+- **sandbox** — server-owned, headless. `session_create` (origin `blank` | `file` | `fork`) and
+  `session_close`. Fork an attended session for risky experiments, verify there, then apply the
+  verified change through the attended session.
+- **attended** — a workbook open in the user's editor. Never opened or closed here — the UI owns
+  its lifecycle. If a chat context chip is attached (value `<id>:<address>`), the part before
+  `:` is an attended `session_id`.
+
+**Ids are stable; histories are not.** An attended session's id is derived from its file path, so
+the same file has the same id across reloads and restarts — but a reload rebuilds the workbook,
+and commit ids from before it are gone (sessions report `opened … ago`, their history epoch).
+Sandboxes live only as long as this server process. Changes you did not make — the user opening,
+closing, or reloading a workbook — are announced at the top of your next tool result; a dead id
+tells you why it died.
+
+Every `run` commits; `session_revert` undoes one commit, `session_restore` rewinds to one.
+The file on disk changes only on `session_save`. Pass `original_commit_id` on writes to guard
+against drift; a `drift` status means re-read and retry.
+
+## Find, run, look up
+
+Beyond session management the surface is three ideas:
+
+- **`grep`** — locate cells by content or pattern.
+- **`run`** — execute SDK TypeScript; everything else. A source with no default export is a
+  snippet: `wb`, `log`, `warn`, `error`, `args` are ambient, async is implicit (never write
+  `await`), and the final expression is the result. Returning a subject describes it:
+  `{ code: "wb" }` is the workbook report, `wb.getWorksheet('Sales').getRegions()` maps the blocks,
+  `range.getStats()` the numbers. There is no query tool — every structured question is one
+  line of `run`.
+- **`api`** — what you can call, before you write the `run`. `{ name: "ICellRange" }` lists its
+  members one line each; `ICellRange.setValues` prints one in full; any other word searches. It
+  reads the declarations a failed `run` is explained from and needs no session. Look a member up rather
+  than guessing its name — a wrong guess costs a failed run.
+
+Values follow Excel's own typing rules in both directions: `=…` is a formula, a leading `'`
+always forces text, `42%` / `$1,000` / `1/31/2026` parse as Excel would. Strings read back with
+the `'` prefix, so `10/23/95` (a date-formatted number) and `'10/23/95` (text) never blur.
+
+## Human in the loop
+
+`highlight` marks ranges in the user's grid — ephemeral, declarative (each call replaces the
+prior state; empty `ranges` clears), never their selection. `prompt` asks them a question in the
+grid. Both need a session with a UI view, and both tell you when there is none.
+
+Link the user to a range with a deep link — attended sessions only:
+`[Sheet1!B10](vscode://sheetxl.sheetxl-vscode/select?session=<session_id>&range=Sheet1!B10)`.