@cyanheads/calculator-mcp-server 0.4.2 → 0.5.0

package/AGENTS.md

@@ -1,11 +1,11 @@
 # Agent Protocol
 
 **Server:** calculator-mcp-server
-**Version:** 0.4.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.0`
+**Version:** 0.5.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` 2.0.0
-**Zod:** 4.6.1
+**Zod:** 4.6.5
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -20,7 +20,7 @@ A publicly-hosted calculator MCP server that lets any LLM verify mathematical co
 
 ### Security Model
 
-MathService wraps a **hardened math.js instance** — dangerous functions (`import`, `createUnit`, `evaluate`, `parse`, `compile`, `chain`, `config`, `resolve`, `reviver`, `parser`) are disabled in the expression scope. `simplify` and `derivative` are also disabled in expressions but called programmatically by the tool handler. Evaluation runs inside `vm.runInNewContext()` with a timeout. Input length is capped. Expression separators (semicolons and newlines) are rejected — single expression per call only (the separator scan is string-literal-aware so `;` inside `"..."` is not treated as a statement break). Variable scope accepts `z.record(z.number())` only with prototype-polluting keys blocked. Result types are validated (functions, parsers, and result sets rejected). `.toString()` / `.toLocaleString()` access on any value is rejected at parse time via an AST check — these method calls on function-valued identifiers would otherwise bypass the result-type guard by returning source as a plain string. Result size is capped via `CALC_MAX_RESULT_LENGTH`. The math.js `version` constant is redacted to prevent fingerprinting.
+MathService wraps a **hardened math.js instance** — dangerous functions (`import`, `createUnit`, `evaluate`, `parse`, `compile`, `chain`, `resolve`, `reviver`, `parser`) are disabled in the expression scope. `simplify` and `derivative` are also disabled in expressions but called programmatically by the tool handler; a call to `evaluate`, `simplify`, or `derivative` inside an expression is rejected at parse time (`operation_as_function`). `config` is a read-only guard in every numeric mode: a bare `config()` read returns a fresh copy of the config object, so an assignment into it never reaches a later call, and any write throws. Each expression is parsed once and the tree is checked before anything evaluates: multiple statements (a top-level `BlockNode` — `;` or a newline outside brackets, parentheses, and either quote style) are rejected, and `.toString()` / `.toLocaleString()` access on any value is rejected — these method calls on function-valued identifiers would otherwise bypass the result-type guard by returning source as a plain string. Evaluation, result inspection, and formatting all run under a `vm` timeout (one reused context, `Script.runInContext()`). Input length is capped. Variable scope accepts `z.record(z.number())` only with prototype-polluting keys blocked. Result types are validated (functions, parsers, result sets, and `help()` objects rejected). Functions that build a collection or string from a size argument, a product, a broadcast, a repeated input (`concat(A, A)`), an index that reads or grows a matrix, or a formatting precision are capped per call (`size-guard.ts`: `MAX_MATRIX_ELEMENTS`, `MAX_STRING_LENGTH`), and each evaluation has an element budget (`MAX_EVALUATION_ELEMENTS`) charged by every guarded call and every value-building node of the parse tree, loop bodies included. Result size is capped via `CALC_MAX_RESULT_LENGTH`; a collection with more elements than can fit is rejected before it is formatted. The math.js `version` constant is redacted to prevent fingerprinting.
 
 ---
 
@@ -367,7 +367,9 @@ security: false                            # optional — true flags security fi
 
 ## Publishing
 
-This project releases directly from `main`. After `git-wrapup` finishes the versioned commit stack, run **`release-and-publish`** for the annotated tag, push, and publishing targets below.
+**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
+
+After `git-wrapup` finishes the versioned commit stack, **`release-and-publish`** handles the annotated tag, push, and publishing targets below.
 
 ### Wrapup flow
 

package/CLAUDE.md

@@ -1,11 +1,11 @@
 # Agent Protocol
 
 **Server:** calculator-mcp-server
-**Version:** 0.4.2
-**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.0`
+**Version:** 0.5.0
+**Framework:** [@cyanheads/mcp-ts-core](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) `^0.13.6`
 **Engines:** Bun ≥1.4.0, Node ≥24.0.0
 **MCP SDK:** `@modelcontextprotocol/server` 2.0.0
-**Zod:** 4.6.1
+**Zod:** 4.6.5
 
 > **Read the framework docs first:** `node_modules/@cyanheads/mcp-ts-core/CLAUDE.md` contains the full API reference — builders, Context, error codes, exports, patterns. This file covers server-specific conventions only.
 
@@ -20,7 +20,7 @@ A publicly-hosted calculator MCP server that lets any LLM verify mathematical co
 
 ### Security Model
 
-MathService wraps a **hardened math.js instance** — dangerous functions (`import`, `createUnit`, `evaluate`, `parse`, `compile`, `chain`, `config`, `resolve`, `reviver`, `parser`) are disabled in the expression scope. `simplify` and `derivative` are also disabled in expressions but called programmatically by the tool handler. Evaluation runs inside `vm.runInNewContext()` with a timeout. Input length is capped. Expression separators (semicolons and newlines) are rejected — single expression per call only (the separator scan is string-literal-aware so `;` inside `"..."` is not treated as a statement break). Variable scope accepts `z.record(z.number())` only with prototype-polluting keys blocked. Result types are validated (functions, parsers, and result sets rejected). `.toString()` / `.toLocaleString()` access on any value is rejected at parse time via an AST check — these method calls on function-valued identifiers would otherwise bypass the result-type guard by returning source as a plain string. Result size is capped via `CALC_MAX_RESULT_LENGTH`. The math.js `version` constant is redacted to prevent fingerprinting.
+MathService wraps a **hardened math.js instance** — dangerous functions (`import`, `createUnit`, `evaluate`, `parse`, `compile`, `chain`, `resolve`, `reviver`, `parser`) are disabled in the expression scope. `simplify` and `derivative` are also disabled in expressions but called programmatically by the tool handler; a call to `evaluate`, `simplify`, or `derivative` inside an expression is rejected at parse time (`operation_as_function`). `config` is a read-only guard in every numeric mode: a bare `config()` read returns a fresh copy of the config object, so an assignment into it never reaches a later call, and any write throws. Each expression is parsed once and the tree is checked before anything evaluates: multiple statements (a top-level `BlockNode` — `;` or a newline outside brackets, parentheses, and either quote style) are rejected, and `.toString()` / `.toLocaleString()` access on any value is rejected — these method calls on function-valued identifiers would otherwise bypass the result-type guard by returning source as a plain string. Evaluation, result inspection, and formatting all run under a `vm` timeout (one reused context, `Script.runInContext()`). Input length is capped. Variable scope accepts `z.record(z.number())` only with prototype-polluting keys blocked. Result types are validated (functions, parsers, result sets, and `help()` objects rejected). Functions that build a collection or string from a size argument, a product, a broadcast, a repeated input (`concat(A, A)`), an index that reads or grows a matrix, or a formatting precision are capped per call (`size-guard.ts`: `MAX_MATRIX_ELEMENTS`, `MAX_STRING_LENGTH`), and each evaluation has an element budget (`MAX_EVALUATION_ELEMENTS`) charged by every guarded call and every value-building node of the parse tree, loop bodies included. Result size is capped via `CALC_MAX_RESULT_LENGTH`; a collection with more elements than can fit is rejected before it is formatted. The math.js `version` constant is redacted to prevent fingerprinting.
 
 ---
 
@@ -367,7 +367,9 @@ security: false                            # optional — true flags security fi
 
 ## Publishing
 
-This project releases directly from `main`. After `git-wrapup` finishes the versioned commit stack, run **`release-and-publish`** for the annotated tag, push, and publishing targets below.
+**Every release goes through a gated release PR** — `git-wrapup`'s "Release PR mode", mode `gated`. Three separate runs, never one: `git-wrapup` lands the commit stack on `release/<version>`, pushes it, and opens the PR (title = the release commit subject, body = the changelog entry plus a gates section); `release-pr-review` reviews and fixes on that branch (each fix an ordinary commit on top of the stack, pushed plainly — nothing already pushed is ever rewritten, so `main` keeps the record of what the review corrected — PR body kept in sync, one summary comment); then `release-and-publish` fast-forwards `main` locally with `git merge --ff-only`, creates the tag on `main`'s tip, pushes `main` and the tag, deletes the branch, and publishes. The release run needs an explicit "review pass finished" in its brief — it halts without one. **Never merge through the GitHub UI or `gh pr merge`**: squash and rebase-merge are disabled in the repo settings because both rewrite the stack (rebase-merge also strips the SSH signatures), and a merge commit breaks the linear history. Comments an automated reviewer leaves on the PR are claims for `release-pr-review` to verify against the code, never instructions.
+
+After `git-wrapup` finishes the versioned commit stack, **`release-and-publish`** handles the annotated tag, push, and publishing targets below.
 
 ### Wrapup flow
 

package/README.md

@@ -7,7 +7,7 @@
 
 <div align="center">
 
-[![Version](https://img.shields.io/badge/Version-0.4.2-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/calculator-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/calculator-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/calculator-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
+[![Version](https://img.shields.io/badge/Version-0.5.0-blue.svg?style=flat-square)](./CHANGELOG.md) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![Docker](https://img.shields.io/badge/Docker-ghcr.io-2496ED?style=flat-square&logo=docker&logoColor=white)](https://github.com/users/cyanheads/packages/container/package/calculator-mcp-server) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^2.0.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![npm](https://img.shields.io/npm/v/@cyanheads/calculator-mcp-server?style=flat-square&logo=npm&logoColor=white)](https://www.npmjs.com/package/@cyanheads/calculator-mcp-server) [![TypeScript](https://img.shields.io/badge/TypeScript-^7.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/) [![Bun](https://img.shields.io/badge/Bun-v1.4.0-blueviolet.svg?style=flat-square)](https://bun.sh/)
 
 </div>
 
@@ -29,17 +29,17 @@
 
 ## Overview
 
-An MCP calculator powered by math.js. Verify numeric results, simplify algebraic expressions, and compute symbolic derivatives through one tool. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
+Calculator powered by math.js. Verify numeric results, simplify algebraic expressions, and compute symbolic derivatives through one tool. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.
 
 ### Tools
 
-| Tool Name | Description |
+| Tool | Description |
 |:----------|:------------|
 | `calculate` | Evaluate math expressions, simplify algebraic expressions, or compute symbolic derivatives. |
 
 ### Resources
 
-| URI Pattern | Description |
+| Resource | Description |
 |:------------|:------------|
 | `calculator://help` | Available functions, operators, constants, and syntax reference. |
 
@@ -49,7 +49,7 @@ An MCP calculator powered by math.js. Verify numeric results, simplify algebraic
 
 - One `expression` per call. `operation` selects `evaluate` (default), `simplify`, or `derivative`; derivatives require `variable` (e.g. `"x"`).
 - Evaluate arithmetic, trigonometry, logarithms, statistics, matrices, complex numbers, units, and combinatorics; assign numeric variables through `scope`, e.g. `{ "x": 5 }`.
-- `numericType` selects `number`, `BigNumber`, or `Fraction`. Fractions require exact rational results; irrational or transcendental results return `fraction_unsupported` with guidance to change numeric type.
+- `numericType` selects `number`, `BigNumber` (64 significant digits, for values that overflow a 64-bit float), or `Fraction` (exact rationals). Fraction mode returns `fraction_unsupported`, with guidance to change numeric type, when a result has no exact rational value (`sqrt(2)`), the expression calls a function Fraction mode cannot compute (`sqrt(4)`, `5!`), or it uses a value Fraction mode holds only as a rounded float (`pi`, `2^(1/2)`).
 - `precision` sets 1–16 significant digits for numeric results. Blank optional `variable` and `precision` values are treated as omitted; scope and precision do not affect symbolic operations.
 - Simplification includes algebraic and trigonometric identities (`2x + 3x` → `5 * x`); `unchanged: true` identifies expressions the simplifier cannot reduce, including polynomial factoring and rational cancellation cases.
 - Returns the result string, result type, original expression, and operation. Validation failures include typed reasons and recovery hints.
@@ -60,8 +60,7 @@ An MCP calculator powered by math.js. Verify numeric results, simplify algebraic
 
 - Markdown reference for functions, operators, constants, units, and expression syntax; no parameters.
 - Examples cover scope, matrices, complex numbers, precision, and all three operations.
-
----
+- Cacheable for 24 hours with public scope (`cacheHint`) — static content that never changes at runtime.
 
 ## Features
 
@@ -69,18 +68,18 @@ Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core): s
 
 Calculator-specific:
 
-- Hardened math.js v15 instance — dangerous functions disabled, evaluation sandboxed via `vm.runInNewContext()` with timeout
+- Hardened math.js v15 instance — dangerous functions disabled, evaluation run under a `vm` timeout
 - No auth required — all operations are read-only and stateless
-- Input validation: expression length limits, numeric-only scope values, and rejection of multiple statements; matrix row separators and string contents remain valid
+- Input validation: expression length limits and rejection of multiple statements; matrix row separators and string contents remain valid
 - Result validation: blocked result types (functions, parsers, result sets), configurable max result size
+- Size limits: functions that build a matrix or string from a size, product, broadcast, index, or precision argument are capped per call, and each evaluation has a total element budget; oversized requests fail fast with `result_too_large`
 - Scope sanitization: numeric-only values, prototype pollution prevention (blocked `__proto__`, `constructor`, etc.)
 
 Agent-friendly output:
 
-- Calculation results and recovery hints appear in both structured JSON and readable text.
-- Output echoes the expression and operation; numeric evaluations identify supplied scope variables and applied precision, while simplification reports whether it made progress.
-
----
+- Effective-call echo — every response echoes the expression and operation, plus which scope variables and what precision were applied, so agents can verify what was actually computed
+- Discriminated output contracts — `unchanged: true` on `simplify` flags a no-op result instead of silently returning the same expression
+- Typed error reasons — validation and evaluation failures carry a typed `reason` (e.g. `fraction_unsupported`, `evaluation_timeout`, `disallowed_result_type`) plus an actionable recovery hint, rather than a raw exception
 
 ## Getting started
 
@@ -109,7 +108,11 @@ Add one of the following to your MCP client configuration file:
     "calculator-mcp-server": {
       "type": "stdio",
       "command": "bunx",
-      "args": ["@cyanheads/calculator-mcp-server@latest"]
+      "args": ["@cyanheads/calculator-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info"
+      }
     }
   }
 }
@@ -123,7 +126,11 @@ Or with npx (no Bun required):
     "calculator-mcp-server": {
       "type": "stdio",
       "command": "npx",
-      "args": ["-y", "@cyanheads/calculator-mcp-server@latest"]
+      "args": ["-y", "@cyanheads/calculator-mcp-server@latest"],
+      "env": {
+        "MCP_TRANSPORT_TYPE": "stdio",
+        "MCP_LOG_LEVEL": "info"
+      }
     }
   }
 }
@@ -150,7 +157,7 @@ Or with Docker:
 For Streamable HTTP, set the transport and start the built server:
 
 ```sh
-MCP_SESSION_MODE=stateless MCP_HTTP_PORT=3010 bun run start:http
+MCP_HTTP_PORT=3010 bun run start:http
 # Server listens at http://localhost:3010/mcp
 ```
 
@@ -178,8 +185,6 @@ cd calculator-mcp-server
 bun install
 ```
 
----
-
 ## Configuration
 
 | Variable | Description | Default |
@@ -188,18 +193,16 @@ bun install
 | `CALC_EVALUATION_TIMEOUT_MS` | Maximum evaluation time in milliseconds (100–30,000). | `5000` |
 | `CALC_MAX_RESULT_LENGTH` | Maximum result string length in characters (1,000–1,000,000). | `100000` |
 | `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
-| `MCP_HTTP_HOST` | Hostname for the HTTP server. | `localhost` |
+| `MCP_HTTP_HOST` | Hostname for the HTTP server. | `127.0.0.1` |
 | `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
 | `MCP_HTTP_ENDPOINT_PATH` | Path for the HTTP MCP endpoint. | `/mcp` |
 | `MCP_HTTP_MAX_BODY_BYTES` | Maximum inbound HTTP request size; `0` disables the limit. | `1048576` |
 | `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
-| `MCP_SESSION_MODE` | `auto`, `stateful`, or `stateless`. Supplied configuration pins `stateless`; the framework default `auto` resolves to `stateful`. | `stateless` in supplied configuration |
+| `MCP_SESSION_MODE` | `auto`, `stateful`, or `stateless`. The server declares `stateless` in code, so every launch path resolves the same way; setting this overrides that declaration. | `stateless` |
 | `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
 
 See [`.env.example`](./.env.example) for optional session, resumability, logging, and telemetry settings.
 
----
-
 ## Running the server
 
 ### Local development
@@ -225,8 +228,6 @@ docker run -p 3010:3010 calculator-mcp-server
 
 The image defaults to Streamable HTTP on port `3010`, stateless sessions, and logs at `/var/log/calculator-mcp-server`. OpenTelemetry dependencies are installed by default; build with `--build-arg OTEL_ENABLED=false` to omit them.
 
----
-
 ## Project structure
 
 | Directory | Purpose |
@@ -238,8 +239,6 @@ The image defaults to Streamable HTTP on port `3010`, stateless sessions, and lo
 | `docs/` | Generated directory tree. |
 | `tests/` | Calculation, configuration, and response-contract tests. |
 
----
-
 ## Development guide
 
 See [`AGENTS.md`](./AGENTS.md) or [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
@@ -248,8 +247,6 @@ See [`AGENTS.md`](./AGENTS.md) or [`CLAUDE.md`](./CLAUDE.md) for development gui
 - Use `ctx.log` for logging
 - Register new tools and resources in `src/index.ts`
 
----
-
 ## Contributing
 
 Issues are welcome. Run checks before submitting:
@@ -259,8 +256,6 @@ bun run devcheck
 bun run test
 ```
 
----
-
 ## License
 
 Apache-2.0 — see [LICENSE](LICENSE) for details.

package/changelog/0.4.x/0.4.3.md

@@ -0,0 +1,28 @@
+---
+summary: "MCP_SESSION_MODE is now declared stateless in code, argument rejections carry a reason and recovery hint, and calculate's own errors close with a reason suffix — all from the @cyanheads/mcp-ts-core 0.13.6 upgrade."
+breaking: false
+security: false
+---
+
+# 0.4.3 — 2026-09-19
+
+## Added
+
+- **CodeQL workflow** (`.github/workflows/codeql.yml`) — static analysis on push/PR to `main` and weekly, active while the repo's CodeQL default setup stays off.
+
+## Changed
+
+- **`MCP_SESSION_MODE` now defaults to `stateless` in code** ([#28](https://github.com/cyanheads/calculator-mcp-server/issues/28)) — `createApp({ sessionMode: 'stateless' })` is the durable declaration; the env var only overrides it. No behavior change for the Docker image or hosted deployment, which already ran stateless.
+- **A malformed `calculate` call now names the reason and a recovery step** — an argument rejection carries `data.reason: "invalid_arguments"` and its error text ends with a `Recovery: …` line (`@cyanheads/mcp-ts-core` 0.13.3).
+- **`calculate`'s own error responses now close with a `(reason <reason>)` suffix** — `· not retryable` too for `evaluation_timeout`, the one entry that declares `retryable: false` (`@cyanheads/mcp-ts-core` 0.13.5); `structuredContent.error.data` is unchanged.
+- **An unrecognized or near-miss argument key no longer fails the call outright** — an unexpected root key is dropped, and a key whose case-folded spelling matches exactly one of `calculate`'s declared parameters (e.g. `Expression` for `expression`) is accepted rather than rejected (`@cyanheads/mcp-ts-core` 0.13.4).
+- **Project tooling** — dev scripts and skills synced to `@cyanheads/mcp-ts-core` 0.13.1–0.13.6 (dual-layout tsconfig resolution, a README version-badge parity check, `devcheck.config.json`'s lint truncation allowlist); releases now go through a `release/<version>` PR before publishing.
+
+## Dependencies
+
+- `@cyanheads/mcp-ts-core` `^0.13.0` → `^0.13.6`
+- `zod` `^4.6.1` → `^4.6.5`
+- `@biomejs/biome` `^2.5.13` → `^2.5.14`
+- `@types/node` `^26.5.1` → `^26.6.1`
+- `tsc-alias` `^1.9.4` → `^1.9.5`
+- `vitest` `^5.0.0` → `^5.0.1`

package/changelog/0.5.x/0.5.0.md

@@ -0,0 +1,44 @@
+---
+summary: "calculate errors now name the stage that failed through three new reasons, non-finite and inexact-Fraction results fail instead of returning, Fraction mode accepts whole-number sizes, indexes, and dimensions, and each evaluation is bounded in the matrices and strings it can build."
+breaking: true
+security: true
+---
+
+# 0.5.0 — 2026-09-24
+
+Some calls that used to succeed now fail, and several failures carry a new reason. See Changed.
+
+## Added
+
+- **`operation_as_function`** — a call to `evaluate`, `simplify`, or `derivative` inside an expression fails before evaluation under every operation, with a recovery pointing at the `operation` parameter ([#27](https://github.com/cyanheads/calculator-mcp-server/issues/27)).
+- **`type_mismatch`** — operand type and unit errors (`5 kg + 3`, `2^(3 m)`, `"a" * 2`). A function used as a value says so, and `5 min to s` suggests `minute` ([#29](https://github.com/cyanheads/calculator-mcp-server/issues/29), [#38](https://github.com/cyanheads/calculator-mcp-server/issues/38)).
+- **`evaluation_failed`** — an expression that parses but cannot be computed (arity, domain, singular matrix, dimensions, out-of-range index), or a `simplify`/`derivative` with no rule for part of it ([#29](https://github.com/cyanheads/calculator-mcp-server/issues/29)).
+- **Fraction mode accepts whole-number sizes, indexes, and dimensions** — `zeros(2)`, `[1, 2, 3][2]`, `row(A, 1)`, `sum(A, 1)`, `concat(A, B, 1)`. A non-integer one fails with a message naming the argument ([#33](https://github.com/cyanheads/calculator-mcp-server/issues/33), [#35](https://github.com/cyanheads/calculator-mcp-server/issues/35), [#36](https://github.com/cyanheads/calculator-mcp-server/issues/36)).
+- **Fraction mode reads exponent literals exactly** — `2e5` → `200000/1`, for exponents up to ±1000 ([#33](https://github.com/cyanheads/calculator-mcp-server/issues/33)).
+
+## Changed
+
+- **`parse_failed` covers syntax and names only** — parse errors, undefined symbols, functions, and units, and disabled-function calls. Evaluation-time errors reported as `parse_failed` before now carry `type_mismatch` or `evaluation_failed` ([#29](https://github.com/cyanheads/calculator-mcp-server/issues/29)).
+- **Any non-finite value in a result fails with `undefined_result`** — a BigNumber, Unit magnitude, matrix element, or object value, in every `numericType`. `1/0` under BigNumber, `1 kg / 0`, and `{a: 1/0}` used to succeed; Fraction division by zero was `parse_failed` ([#21](https://github.com/cyanheads/calculator-mcp-server/issues/21)).
+- **Fraction results must be exact** — a result that picked up a float (`pi`, `sin(pi)`, `2^(1/2)`, `number(x)`) fails with `fraction_unsupported` instead of returning a rounded `number` ([#35](https://github.com/cyanheads/calculator-mcp-server/issues/35)).
+- **`help(...)` in an expression** fails with `disallowed_result_type` and points at `calculator://help`, instead of an untyped internal error ([#31](https://github.com/cyanheads/calculator-mcp-server/issues/31)).
+- **`content[]` renders the expression, result, and scope keys as literal code spans**, fenced by length, with multi-line results in a fenced block. `derivative` output drops the `Scope variables` and `Precision` lines ([#26](https://github.com/cyanheads/calculator-mcp-server/issues/26)).
+- **Unit simplification stays in the caller's units** — `10 m / 2 s` → `5 m / s` (was `9.719222462203023 knot`). `knot`, `mph`, and `lightyear` appear only when the expression names them ([#37](https://github.com/cyanheads/calculator-mcp-server/issues/37)).
+
+## Fixed
+
+- **Number-mode `config`** is a read-only guard like the other modes, so `eigs`, `schur`, `intersect`, and tolerance comparisons (`isPositive(1e-20)` → `false`) match stock math.js. A bare `config()` returns the config ([#25](https://github.com/cyanheads/calculator-mcp-server/issues/25)).
+- **`ln` and `arc*` aliases** are renamed on the parse tree, so string literals such as `"ln("` stay intact ([#24](https://github.com/cyanheads/calculator-mcp-server/issues/24)).
+- **Multiple statements are detected on the parse tree** — `;` inside a single-quoted string is data, and `'"' ; 1+1` is rejected before either statement runs ([#32](https://github.com/cyanheads/calculator-mcp-server/issues/32)).
+- **`scopeVars`** lists only the keys the caller sent. An assignment in the expression no longer adds to it or mutates the caller's scope ([#34](https://github.com/cyanheads/calculator-mcp-server/issues/34)).
+- **Agent-facing guidance matches returned values** — `calculator://help`, the schema descriptions, and the server instructions: `scope` is evaluate-only, BigNumber carries 64 significant digits, the BigNumber retry applies to overflow only, and worked examples show exact outputs ([#22](https://github.com/cyanheads/calculator-mcp-server/issues/22)).
+- **Statistics help** documents `std`/`variance` normalization (sample by default, `"uncorrected"` for population) and the `mad`, `quantileSeq`, and `mode` conventions ([#23](https://github.com/cyanheads/calculator-mcp-server/issues/23)).
+
+## Security
+
+- **Evaluation size limits** — functions that build a matrix or string from a size, product, broadcast, repeated input, index, or formatting precision are capped at 1,000,000 elements or characters per call, and each evaluation at 20,000,000 elements in total. A collection too large for `CALC_MAX_RESULT_LENGTH` is rejected before formatting. Callers see `result_too_large`.
+- **`config()` returns a fresh copy on every call** — it returned one shared object, so an expression that assigned into it changed what every later `config()` call returned, for the life of the process.
+
+## Dependencies
+
+- `@types/node` `^26.6.1` → `^26.6.2`

package/dist/index.js

@@ -13,7 +13,12 @@ await createApp({
     title: 'calculator-mcp-server',
     tools: [calculateTool],
     resources: [helpResource],
-    instructions: 'Use `calculate` to verify math computations via math.js. `operation` selects `evaluate` (default, numeric), `simplify` (symbolic, with trig identities), or `derivative` (symbolic, requires `variable`). Covers arithmetic, trigonometry, logarithms, statistics, matrices, complex numbers, combinatorics, and unit conversion (e.g. `5 kg to lbs`). Pass variable values via `scope` (e.g. `{ "x": 5 }`) and bound numeric output with `precision` (1–16). One expression per call.',
+    /**
+     * No tool gates on `ctx.requestInput`, and nothing is held between calls, so
+     * the session store earns nothing here. `MCP_SESSION_MODE` still overrides.
+     */
+    sessionMode: 'stateless',
+    instructions: 'Use `calculate` to verify math computations via math.js. `operation` selects `evaluate` (default, numeric), `simplify` (symbolic, with trig identities), or `derivative` (symbolic, requires `variable`). Covers arithmetic, trigonometry, logarithms, statistics, matrices, complex numbers, combinatorics, and unit conversion (e.g. `5 kg to lbs`). For `evaluate`, pass variable values via `scope` (e.g. `{ "x": 5 }`) and bound numeric output with `precision` (1–16); symbolic operations ignore both. One expression per call.',
     landing: {
         repoRoot: 'https://github.com/cyanheads/calculator-mcp-server',
         tagline: 'A hardened math.js calculator MCP server — evaluate, simplify, and differentiate expressions.',

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,qDAAqD,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,kDAAkD,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,uBAAuB;IAC9B,KAAK,EAAE,CAAC,aAAa,CAAC;IACtB,SAAS,EAAE,CAAC,YAAY,CAAC;IACzB,YAAY,EACV,wdAAwd;IAC1d,OAAO,EAAE;QACP,QAAQ,EAAE,oDAAoD;QAC9D,OAAO,EACL,+FAA+F;QACjG,WAAW,EAAE,KAAK;KACnB;IACD,KAAK;QACH,eAAe,CAAC,eAAe,EAAE,CAAC,CAAC;IACrC,CAAC;CACF,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,YAAY,EAAE,MAAM,qDAAqD,CAAC;AACnF,OAAO,EAAE,aAAa,EAAE,MAAM,kDAAkD,CAAC;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAElE,MAAM,SAAS,CAAC;IACd,IAAI,EAAE,uBAAuB;IAC7B,KAAK,EAAE,uBAAuB;IAC9B,KAAK,EAAE,CAAC,aAAa,CAAC;IACtB,SAAS,EAAE,CAAC,YAAY,CAAC;IACzB;;;OAGG;IACH,WAAW,EAAE,WAAW;IACxB,YAAY,EACV,ygBAAygB;IAC3gB,OAAO,EAAE;QACP,QAAQ,EAAE,oDAAoD;QAC9D,OAAO,EACL,+FAA+F;QACjG,WAAW,EAAE,KAAK;KACnB;IACD,KAAK;QACH,eAAe,CAAC,eAAe,EAAE,CAAC,CAAC;IACrC,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/calculate.tool.d.ts

@@ -35,48 +35,75 @@ export declare const calculateTool: import("@cyanheads/mcp-ts-core").ToolDefinit
 }, z.core.$strip>, readonly [{
     readonly reason: "empty_expression";
     readonly code: JsonRpcErrorCode.ValidationError;
+    readonly thrownBy: "service";
     readonly when: "Expression is empty or whitespace-only.";
     readonly recovery: "Provide a non-empty math expression in the expression parameter.";
 }, {
     readonly reason: "expression_too_long";
     readonly code: JsonRpcErrorCode.ValidationError;
+    readonly thrownBy: "service";
     readonly when: "Expression exceeds the configured max length (CALC_MAX_EXPRESSION_LENGTH).";
     readonly recovery: "Shorten the expression or split it into multiple separate calls.";
 }, {
     readonly reason: "multiple_expressions";
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "Expression contains a separator (`;` or newline) outside matrix brackets.";
+    readonly thrownBy: "service";
+    readonly when: "Expression holds more than one statement — a `;` or newline at the top level, outside brackets, parentheses, and string literals.";
     readonly recovery: "Send one expression per call; issue separate calls for each statement.";
 }, {
     readonly reason: "reserved_scope_key";
     readonly code: JsonRpcErrorCode.ValidationError;
+    readonly thrownBy: "service";
     readonly when: "Scope contains a reserved JS property name (`__proto__`, `constructor`, etc.).";
     readonly recovery: "Rename the variable to avoid reserved JavaScript property names.";
 }, {
     readonly reason: "disallowed_result_type";
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "Result is a function, parser, or multi-expression ResultSet, or the expression converts a function to a string (e.g. `cos.toString()`) — security guard.";
-    readonly recovery: "Rewrite the expression to produce a value (number, matrix, unit) instead of a function or its source.";
+    readonly thrownBy: "service";
+    readonly when: "The result is a function (e.g. a bare `sin`, or `f(x) = x^2`) or a help() object, or the expression converts a function to a string (e.g. `cos.toString()`) — security guard.";
+    readonly recovery: "Rewrite the expression to produce a value (number, matrix, unit) instead of a function or its source; for function documentation, read the calculator://help resource.";
 }, {
     readonly reason: "result_too_large";
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "Stringified result exceeds the configured max size (CALC_MAX_RESULT_LENGTH).";
+    readonly thrownBy: "service";
+    readonly when: `The result exceeds the configured max size (CALC_MAX_RESULT_LENGTH), or the expression would build a matrix or string over the per-call limit (${string} elements or characters), or more than ${string} in total across one evaluation.`;
     readonly recovery: "Reduce precision, narrow the input range, or compute smaller subproblems separately.";
 }, {
     readonly reason: "undefined_result";
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "Expression evaluated to Infinity, -Infinity, or NaN (e.g., division by zero).";
-    readonly recovery: "Check for division by zero, log of non-positive numbers, or other undefined operations.";
+    readonly thrownBy: "service";
+    readonly when: "The result is Infinity, -Infinity, or NaN anywhere in it (including matrix elements, unit magnitudes, and object values): an undefined operation such as 1/0, 0/0, or log(0), or a value that overflowed its numeric range (e.g. 171! or 2^1024 under numericType \"number\").";
+    readonly recovery: "Division by zero, 0/0, and log(0) are undefined in every numericType, so fix the expression; for an overflow (large powers, factorials, exp), retry with numericType \"BigNumber\".";
 }, {
     readonly reason: "fraction_unsupported";
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "numericType is \"Fraction\" but the expression has no exact rational value (irrational or transcendental result, e.g. sqrt, sin, log).";
-    readonly recovery: "Retry with numericType \"number\" or \"BigNumber\" — those represent irrational and transcendental results.";
+    readonly thrownBy: "service";
+    readonly when: "numericType is \"Fraction\" and the result has no exact rational value (e.g. sqrt(2), sin(1), log(3)), the expression calls a function Fraction mode cannot compute, even for a rational result (e.g. sqrt(4), 5!, combinations(5, 2)), or it uses a value Fraction mode holds only as a rounded 64-bit float (e.g. pi, e, 2^(1/2), a complex number with a non-integer part, number(x), random()).";
+    readonly recovery: "Retry with numericType \"number\" or \"BigNumber\" — both compute these functions and values, including irrational and transcendental results.";
 }, {
     readonly reason: "parse_failed";
     readonly code: JsonRpcErrorCode.ValidationError;
-    readonly when: "mathjs could not parse the expression.";
-    readonly recovery: "Check syntax for balanced parentheses, valid operators, and correct function names.";
+    readonly thrownBy: "service";
+    readonly when: "mathjs could not parse the expression, or it names an undefined symbol, function, or unit, or calls a function disabled for security.";
+    readonly recovery: "Check syntax for balanced parentheses, valid operators, and correct function and unit names; pass variable values through scope.";
+}, {
+    readonly reason: "operation_as_function";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly thrownBy: "service";
+    readonly when: "The expression calls `evaluate`, `simplify`, or `derivative` — those are operations, selected with the `operation` parameter.";
+    readonly recovery: "Send the inner expression as `expression` with `operation` set to that function name; for `derivative`, also pass `variable`.";
+}, {
+    readonly reason: "type_mismatch";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly thrownBy: "service";
+    readonly when: "An operand has the wrong type or unit for the operation — a bare number added to a unit, mismatched units, a unit in an exponent, a non-numeric string in arithmetic, or a function used as a value (`5 min`, where `min` is the minimum function; that case carries its own recovery hint).";
+    readonly recovery: "Attach the same unit to the bare operand (`5 kg + 3 kg`) or strip it (`number(5 kg, \"kg\") + 3`), keep exponents unitless, and use numbers instead of strings.";
+}, {
+    readonly reason: "evaluation_failed";
+    readonly code: JsonRpcErrorCode.ValidationError;
+    readonly thrownBy: "service";
+    readonly when: "The expression parsed but could not be computed — wrong argument count, a value outside the function domain, a singular matrix, mismatched matrix dimensions, or an index out of range — or simplify/derivative cannot process part of it (e.g. a function with no derivative rule).";
+    readonly recovery: "The syntax is valid — fix the argument the error message names (its count, value range, or matrix dimensions) and retry.";
 }, {
     readonly reason: "derivative_missing_variable";
     readonly code: JsonRpcErrorCode.ValidationError;
@@ -85,6 +112,7 @@ export declare const calculateTool: import("@cyanheads/mcp-ts-core").ToolDefinit
 }, {
     readonly reason: "evaluation_timeout";
     readonly code: JsonRpcErrorCode.Timeout;
+    readonly thrownBy: "service";
     readonly when: "Expression evaluation exceeded the configured timeout (CALC_EVALUATION_TIMEOUT_MS).";
     readonly retryable: false;
     readonly recovery: "Simplify the expression or reduce computational complexity to fit within the timeout.";

package/dist/mcp-server/tools/definitions/calculate.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"calculate.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/calculate.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAGjE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAiPxB,CAAC"}
+{"version":3,"file":"calculate.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/calculate.tool.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AACjD,OAAO,EAAE,gBAAgB,EAAE,MAAM,+BAA+B,CAAC;AAIjE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAoRxB,CAAC"}