@cyanheads/calculator-mcp-server 0.4.3 → 0.5.0

package/dist/services/math/math-service.d.ts

@@ -1,7 +1,9 @@
 /**
  * @fileoverview Hardened math.js wrapper for secure expression evaluation.
  * Creates a restricted math.js instance with dangerous functions disabled in
- * the expression scope, and wraps evaluation in a vm sandbox with timeout.
+ * the expression scope, parses each expression once and checks the tree before
+ * anything runs, and evaluates, inspects, and formats the result inside a vm
+ * sandbox with a timeout.
  * @module services/math/math-service
  */
 import type { Context } from '@cyanheads/mcp-ts-core';
@@ -10,15 +12,16 @@ import type { MathResult, NumericType } from './types.js';
 export declare class MathService {
     /** Default IEEE 754 instance — used for the vast majority of evaluations. */
     private readonly defaultInstance;
-    /** BigNumber instance — arbitrary precision; selected via numericType: "BigNumber". */
+    /** BigNumber instance — 64 significant digits; selected via numericType: "BigNumber". */
     private readonly bigNumberInstance;
     /** Fraction instance — exact rational arithmetic; selected via numericType: "Fraction". */
     private readonly fractionInstance;
-    private readonly parse;
     private readonly simplify;
     private readonly derivative;
     private readonly simplifyRules;
     private readonly config;
+    /** vm context reused by every timed call; see {@link runWithTimeout}. */
+    private readonly sandbox;
     constructor(config: ServerConfig);
     /** Select the pre-initialized evaluate/format/typeOf bundle for a given numeric type. */
     private instanceFor;
@@ -31,36 +34,72 @@ export declare class MathService {
     /** Get formatted help content listing available functions, operators, and syntax. */
     getHelpContent(): string;
     private validateInput;
+    /**
+     * Parse once and check the tree before anything evaluates. A parse failure is
+     * `parse_failed`. Multiple statements are detected structurally — math.js parses
+     * `a; b` and a top-level newline into a `BlockNode` — so `;` inside a matrix or
+     * inside either quote style (`"a;b"`, `'a;b'`) is data, transpose `A'` stays an
+     * operator, and a real separator is rejected before either statement runs (#32).
+     * math.js treats a bare carriage return as a syntax error rather than a
+     * separator; when it is what broke the parse, the input is re-parsed with line
+     * feeds purely to report `multiple_expressions` — the rewritten text is never
+     * evaluated. The same tree then gets the stringifier check, the
+     * operation-as-function check (#27), and the notation rename (#24), and yields
+     * the names it uses as values that resolve to functions (#38). Every operation
+     * starts here, so it also resets the instance's auto unit system (#37).
+     */
+    private parseExpression;
+    /** Whether `expression` parses to multiple statements. */
+    private parsesAsBlock;
+    private multipleExpressions;
     /** Reject scope keys that could pollute the object prototype chain. */
     private validateScope;
     /** Reject result types that leak internals (functions, parsers, multi-expression ResultSets). */
     private validateResultType;
-    /** Reject results holding a non-finite value (Infinity, -Infinity, NaN), including inside matrices and complex numbers. */
-    private validateFinite;
+    /**
+     * Inspect a result before it is formatted: reject a `help()` object (its
+     * rendering evaluates the documentation examples, #31), a collection too large
+     * to ever fit `maxResultLength` (checked before formatting, so it is never
+     * stringified), any non-finite number, scalar or nested (#21), and under
+     * numericType "Fraction", any float approximation, scalar or nested (#35).
+     */
+    private validateResultValue;
     /** Reject results that exceed the configured maximum size. */
     private validateResultSize;
+    private resultTooLarge;
     /**
-     * Reject expressions that access `.toString` / `.toLocaleString` on any value.
-     * math.js permits these methods on function-valued identifiers (`cos.toString()`,
-     * `import.toString()`), returning the function's source as a plain string — which
-     * slips past {@link validateResultType}, whose function defense only inspects the
-     * value AFTER stringification. The check is parse-time and AST-based rather than a
-     * runtime `Function.prototype` patch: math.js itself calls `toString` on functions
-     * internally while evaluating units, statistics, and complex results, so patching
-     * the prototype would reject legitimate expressions. No real calculator expression
-     * needs `.toString()`/`.toLocaleString()`, so blocking the accessor outright (dot
-     * or bracket form, on any operand) is both sufficient and side-effect-free. String
-     * literals that merely contain the text "toString" parse as ConstantNodes, not
-     * accessors, so they are unaffected.
+     * Runs a synchronous function inside a vm sandbox with timeout protection and
+     * maps anything it throws to a declared reason via {@link classifyFailure}.
+     *
+     * The context exists only to carry the timeout — `fn` and everything it calls
+     * run in this realm — so one context is reused for every call and cleared
+     * afterwards. A fresh context per call costs ~100 µs and, under Bun, retains
+     * ~100 KB of memory per call.
      */
-    private validateNoFunctionStringification;
+    private runWithTimeout;
     /**
-     * Runs a synchronous function inside a vm sandbox with timeout protection.
-     * `numericType` is supplied only by the evaluate path so a Fraction-mode
-     * conversion failure can be remapped to the actionable `fraction_unsupported`
-     * error instead of the misleading `parse_failed` (#19).
+     * Classify a failure raised after the expression parsed (evaluation, result
+     * inspection, formatting, or a symbolic operation). First match wins:
+     *
+     * 1. Already-classified `McpError`s (result checks) pass through.
+     * 2. Timeout → `evaluation_timeout`.
+     * 3. A size guard (see size-guard.ts) → `result_too_large`.
+     * 4. Fraction mode calling a function with no Fraction implementation (sqrt,
+     *    sin, log, factorial, …) → `fraction_unsupported` (#19); so does Fraction
+     *    mode meeting a float with no equal Fraction (`pi * 2/3`, #35).
+     * 5. fraction.js `Division by Zero`, in any numericType → `undefined_result` (#21).
+     * 6. Name errors (undefined symbol/function/unit, disabled function, blocked
+     *    property) → `parse_failed`.
+     * 7. A symbolic operation (simplify, derivative) that cannot process the parsed
+     *    tree → `evaluation_failed`, with a hint about the symbolic engine rather
+     *    than about argument values (see {@link symbolicFailure}).
+     * 8. Operand type/unit errors (typed-function `wrongType`, unit mismatch,
+     *    string-to-number) → `type_mismatch`.
+     * 9. Anything else — arity, domain, singular matrix, dimensions, index →
+     *    `evaluation_failed` (#29). Stage decides, not error class: a runtime
+     *    `SyntaxError` such as `number("abc")` lands here, never in `parse_failed`.
      */
-    private runWithTimeout;
+    private classifyFailure;
 }
 /** Initialize the math service. Call once from createApp setup(). */
 export declare function initMathService(config: ServerConfig): void;

package/dist/services/math/math-service.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"math-service.d.ts","sourceRoot":"","sources":["../../../src/services/math/math-service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAGtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAgT1D,qBAAa,WAAW;IACtB,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAe;IAC/C,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAe;IACjD,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAe;IAEhD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA6B;IACnD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAmE;IAC5F,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6D;IACxF,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IAEtC,YAAY,MAAM,EAAE,YAAY,EAmB/B;IAED,yFAAyF;IACzF,OAAO,CAAC,WAAW;IAWnB,4FAA4F;IAC5F,kBAAkB,CAChB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,OAAO,EACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,GAAE,WAAsB,GAClC,UAAU,CAuBZ;IAED,qDAAqD;IACrD,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,CA0B/D;IAED,mFAAmF;IACnF,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,CAQtF;IAED,qFAAqF;IACrF,cAAc,IAAI,MAAM,CAEvB;IAED,OAAO,CAAC,aAAa;IAqBrB,uEAAuE;IACvE,OAAO,CAAC,aAAa;IAWrB,iGAAiG;IACjG,OAAO,CAAC,kBAAkB;IAS1B,2HAA2H;IAC3H,OAAO,CAAC,cAAc;IAStB,8DAA8D;IAC9D,OAAO,CAAC,kBAAkB;IAS1B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,iCAAiC;IAyBzC;;;;;OAKG;IACH,OAAO,CAAC,cAAc;CA6BvB;AAMD,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED,iDAAiD;AACjD,wBAAgB,cAAc,IAAI,WAAW,CAG5C"}
+{"version":3,"file":"math-service.d.ts","sourceRoot":"","sources":["../../../src/services/math/math-service.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAkBtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAQ9D,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAioB1D,qBAAa,WAAW;IACtB,6EAA6E;IAC7E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAe;IAC/C,yFAAyF;IACzF,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAe;IACjD,2FAA2F;IAC3F,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAe;IAEhD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2B;IACpD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA6B;IACxD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAiB;IAC/C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,yEAAyE;IACzE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4C;IAEpE,YAAY,MAAM,EAAE,YAAY,EAkB/B;IAED,yFAAyF;IACzF,OAAO,CAAC,WAAW;IAWnB,4FAA4F;IAC5F,kBAAkB,CAChB,UAAU,EAAE,MAAM,EAClB,GAAG,EAAE,OAAO,EACZ,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,EAClB,WAAW,GAAE,WAAsB,GAClC,UAAU,CAsCZ;IAED,qDAAqD;IACrD,kBAAkB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,CAe/D;IAED,mFAAmF;IACnF,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,GAAG,UAAU,CAStF;IAED,qFAAqF;IACrF,cAAc,IAAI,MAAM,CAEvB;IAED,OAAO,CAAC,aAAa;IAarB;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,eAAe;IA6CvB,0DAA0D;IAC1D,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,mBAAmB;IAQ3B,uEAAuE;IACvE,OAAO,CAAC,aAAa;IAYrB,iGAAiG;IACjG,OAAO,CAAC,kBAAkB;IAU1B;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;IA0B3B,8DAA8D;IAC9D,OAAO,CAAC,kBAAkB;IAI1B,OAAO,CAAC,cAAc;IAQtB;;;;;;;;OAQG;IACH,OAAO,CAAC,cAAc;IAetB;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,OAAO,CAAC,eAAe;CA8CxB;AAiFD,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED,iDAAiD;AACjD,wBAAgB,cAAc,IAAI,WAAW,CAG5C"}