# Numera MCP

`@vectojs/numera-mcp` is the safe local-first Model Context Protocol adapter for
Numera workbooks. It lets an MCP client inspect workbooks, read bounded ranges,
and write validated cell batches without launching a browser or subprocess.
The published stdio executable requires Bun.

The server supports `.numera.json`, `.json`, `.csv`, and `.xlsx` files through
exact-pinned Numera Core and XLSX packages. It is intentionally local and does
not provide collaboration, accounts, cloud storage, or remote network access.

## Run

```sh
numera-mcp --root /absolute/path/to/workbooks
```

The server uses stdio. Paths passed to tools are relative to `--root`. Mutation
tools require an expected input SHA-256 and a distinct, non-existing output
path, so a stale Agent cannot silently overwrite newer work.

## Tools

- `numera_inspect_workbook`: return the format, SHA-256, active sheet, sheet
  dimensions, populated-cell count, and used range.
- `numera_read_range`: return raw and display values for at most 10,000 cells.
- `numera_write_cells`: validate and atomically apply 1–1,000 typed cell writes
  to a new output workbook.

## Development

```sh
bun install
bun run verify
npm pack --dry-run
```

## Security

See [SECURITY.md](./SECURITY.md). Numera MCP treats workbook bytes, formulas,
paths, and MCP arguments as untrusted input.