@sheetpane/mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Arpit Arya
+
+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

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @sheetpane/mcp
 
-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.
+**A Model Context Protocol server for sheetpane: agents ask, it answers from what ships — never a guess.**
+
+```bash
+npx -y @sheetpane/mcp        # stdio; any MCP client
+npx sheetpane-skills install # registers it for Claude Code, Kiro and Codex (with the skills)
+```
+
+| tool | ask | answer, computed from |
+|---|---|---|
+| `describe_api` | `{ "name": "flagging" }` — an element, attribute, property, method, event, `--sp-*` property, slot, part or plugin | its entry in `custom-elements.json` (with its TSDoc) and the record that specifies it |
+| `inspect_workbook` | `{ "path": "data/q3.xlsx" }` | sheets, size, header-row guess, titles, each column's type, blanks and values, merges, and which plugins the file would use — `@sheetpane/import` |
+| `draft_rules` | `{ "path": "data/q3.xlsx", "sheet"?: "Sales" }` | a rules file for `<sheetpane-excel rules-src>`: `required`, `type`, `oneOf` per titled column — **a draft to review** |
+| `check_rules` | `{ "rules": {…} or "…json…", "path"?: "data/q3.xlsx" }` | the grid's own check, each rule in words, and the sheets and titles the workbook lacks |
+| `explain_code` | `{ "code": "SP-1002" }` | meaning, likely cause, fix and link — [docs/ERRORS.md](../../docs/ERRORS.md) |
+| `find_skill` | `{ "task": "validate columns from a JSON file" }` | the skill to read, with its `SKILL.md` path |
+
+## Registering it by hand
+
+| tool | file | entry |
+|---|---|---|
+| Claude Code | `.mcp.json` | `{ "mcpServers": { "sheetpane": { "command": "npx", "args": ["-y", "@sheetpane/mcp"] } } }` |
+| Kiro | `.kiro/settings/mcp.json` | the same |
+| Codex | `.codex/config.toml` (trusted projects) | `[mcp_servers.sheetpane]` · `command = "npx"` · `args = ["-y", "@sheetpane/mcp"]` |
+
+## What it is and is not
+
+- **Protocol:** MCP revision 2026-07-28 — stateless, `server/discover`, the version in each request's `_meta` — and 2025-11-25 / 2025-06-18 clients through `initialize`. JSON-RPC over stdio, one message per line. **Tools only.**
+- **Read-only:** paths are only read; `.xlsx` and `.csv` only; 256 MB at most; no network, no writes.
+- **Deterministic:** the same input gives the same output (the tests compare against golden files).
+- **Errors** are tool results with `isError: true` and an SP code first — `SP-7001`…`SP-7007`, or the reader's own `SP-10xx`.
+
+Spec: [SR-MCP](../../records/0119_MCP.md). MIT.