@cyanheads/calculator-mcp-server 0.1.6

package/README.md

@@ -0,0 +1,177 @@
+<div align="center">
+  <h1>@cyanheads/calculator-mcp-server</h1>
+  <p><b>A calculator MCP server that lets any LLM verify mathematical computations. Evaluate, simplify, and differentiate expressions via a single tool. Powered by math.js v15.</b></p>
+  <p><b>1 Tool · 1 Resource</b></p>
+</div>
+
+<div align="center">
+
+[![Version](https://img.shields.io/badge/Version-0.1.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-1.28.0-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-6.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/)
+
+</div>
+
+---
+
+## Tools
+
+One tool for all mathematical operations:
+
+| Tool Name | Description |
+|:----------|:------------|
+| `calculate` | Evaluate math expressions, simplify algebraic expressions, or compute symbolic derivatives. |
+
+### `calculate`
+
+A single tool covering 100% of the server's purpose. The `operation` parameter defaults to `evaluate`, so the common case is just `{ expression: "..." }`.
+
+- **Evaluate** — arithmetic, trigonometry, logarithms, statistics, matrices, complex numbers, unit conversion, combinatorics
+- **Simplify** — reduce algebraic expressions symbolically (e.g., `2x + 3x` -> `5 * x`). Supports algebraic and trigonometric identities
+- **Derivative** — compute symbolic derivatives (e.g., `3x^2 + 2x + 1` -> `6 * x + 2`)
+- Variable scope via `scope` parameter: `{ "x": 5, "y": 3 }`
+- Configurable precision for numeric results
+
+---
+
+## Resources
+
+| URI Pattern | Description |
+|:------------|:------------|
+| `calculator://help` | Available functions, operators, constants, and syntax reference. |
+
+---
+
+## Features
+
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
+
+- Declarative tool definitions — single file per tool, framework handles registration and validation
+- Unified error handling across all tools
+- Structured logging with optional OpenTelemetry tracing
+- Runs locally (stdio/HTTP) or in Docker
+
+Calculator-specific:
+
+- Hardened math.js v15 instance — dangerous functions disabled, evaluation sandboxed via `vm.runInNewContext()` with timeout
+- No auth required — all operations are read-only and stateless
+- Input validation: expression length limits, expression separator rejection (semicolons and newlines), variable name regex enforcement
+- Result validation: blocked result types (functions, parsers, result sets), configurable max result size
+- Scope sanitization: numeric-only values, prototype pollution prevention (blocked `__proto__`, `constructor`, etc.)
+
+---
+
+## Getting Started
+
+### MCP Client Configuration
+
+Add to your MCP client config (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "calculator": {
+      "type": "stdio",
+      "command": "bunx",
+      "args": ["@cyanheads/calculator-mcp-server@latest"]
+    }
+  }
+}
+```
+
+### Prerequisites
+
+- [Bun v1.2.0](https://bun.sh/) or higher
+
+### Installation
+
+1. **Clone the repository:**
+```sh
+git clone https://github.com/cyanheads/calculator-mcp-server.git
+```
+
+2. **Navigate into the directory:**
+```sh
+cd calculator-mcp-server
+```
+
+3. **Install dependencies:**
+```sh
+bun install
+```
+
+---
+
+## Configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+| `CALC_MAX_EXPRESSION_LENGTH` | Maximum allowed expression string length (10–10,000). | `1000` |
+| `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_PORT` | Port for HTTP server. | `3010` |
+| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
+| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
+
+---
+
+## Running the Server
+
+### Local Development
+
+- **Build and run the production version:**
+  ```sh
+  bun run build
+  bun run start:http   # or start:stdio
+  ```
+
+- **Run checks and tests:**
+  ```sh
+  bun run devcheck     # Lints, formats, type-checks
+  bun run test         # Runs test suite
+  ```
+
+### Docker
+
+```sh
+docker build -t calculator-mcp-server .
+docker run -p 3010:3010 calculator-mcp-server
+```
+
+---
+
+## Project Structure
+
+| Directory | Purpose |
+|:----------|:--------|
+| `src/mcp-server/tools/` | Tool definitions (`*.tool.ts`). |
+| `src/mcp-server/resources/` | Resource definitions (`*.resource.ts`). |
+| `src/services/` | Domain service integrations (MathService). |
+| `src/config/` | Environment variable parsing and validation with Zod. |
+| `docs/` | Generated directory tree. |
+
+---
+
+## Development Guide
+
+See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
+
+- Handlers throw, framework catches — no `try/catch` in tool logic
+- Use `ctx.log` for logging
+- Register new tools and resources in `src/index.ts`
+
+---
+
+## Contributing
+
+Issues and pull requests are welcome. Run checks before submitting:
+
+```sh
+bun run devcheck
+bun run test
+```
+
+---
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE) for details.

package/dist/config/server-config.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Server-specific configuration for calculator-mcp-server.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+declare const ServerConfigSchema: z.ZodObject<{
+    maxExpressionLength: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    evaluationTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    maxResultLength: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+}, z.core.$strip>;
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+/** Lazy-parsed server config from env vars. */
+export declare function getServerConfig(): ServerConfig;
+export {};
+//# sourceMappingURL=server-config.d.ts.map

package/dist/config/server-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,QAAA,MAAM,kBAAkB;;;;iBAsBtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,+CAA+C;AAC/C,wBAAgB,eAAe,IAAI,YAAY,CAO9C"}

package/dist/config/server-config.js

@@ -0,0 +1,39 @@
+/**
+ * @fileoverview Server-specific configuration for calculator-mcp-server.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+const ServerConfigSchema = z.object({
+    maxExpressionLength: z.coerce
+        .number()
+        .int()
+        .min(10)
+        .max(10_000)
+        .default(1000)
+        .describe('Maximum allowed expression string length (10–10,000)'),
+    evaluationTimeoutMs: z.coerce
+        .number()
+        .int()
+        .min(100)
+        .max(30_000)
+        .default(5000)
+        .describe('Maximum evaluation time in milliseconds (100–30,000)'),
+    maxResultLength: z.coerce
+        .number()
+        .int()
+        .min(1_000)
+        .max(1_000_000)
+        .default(100_000)
+        .describe('Maximum result string length in characters (1,000–1,000,000)'),
+});
+let _config;
+/** Lazy-parsed server config from env vars. */
+export function getServerConfig() {
+    _config ??= ServerConfigSchema.parse({
+        maxExpressionLength: process.env.CALC_MAX_EXPRESSION_LENGTH,
+        evaluationTimeoutMs: process.env.CALC_EVALUATION_TIMEOUT_MS,
+        maxResultLength: process.env.CALC_MAX_RESULT_LENGTH,
+    });
+    return _config;
+}
+//# sourceMappingURL=server-config.js.map

package/dist/config/server-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,mBAAmB,EAAE,CAAC,CAAC,MAAM;SAC1B,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,EAAE,CAAC;SACP,GAAG,CAAC,MAAM,CAAC;SACX,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,sDAAsD,CAAC;IACnE,mBAAmB,EAAE,CAAC,CAAC,MAAM;SAC1B,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,GAAG,CAAC;SACR,GAAG,CAAC,MAAM,CAAC;SACX,OAAO,CAAC,IAAI,CAAC;SACb,QAAQ,CAAC,sDAAsD,CAAC;IACnE,eAAe,EAAE,CAAC,CAAC,MAAM;SACtB,MAAM,EAAE;SACR,GAAG,EAAE;SACL,GAAG,CAAC,KAAK,CAAC;SACV,GAAG,CAAC,SAAS,CAAC;SACd,OAAO,CAAC,OAAO,CAAC;SAChB,QAAQ,CAAC,8DAA8D,CAAC;CAC5E,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,+CAA+C;AAC/C,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,kBAAkB,CAAC,KAAK,CAAC;QACnC,mBAAmB,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B;QAC3D,mBAAmB,EAAE,OAAO,CAAC,GAAG,CAAC,0BAA0B;QAC3D,eAAe,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB;KACpD,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview calculator-mcp-server entry point.
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview calculator-mcp-server entry point.
+ * @module index
+ */
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { getServerConfig } from './config/server-config.js';
+import { helpResource } from './mcp-server/resources/definitions/help.resource.js';
+import { calculateTool } from './mcp-server/tools/definitions/calculate.tool.js';
+import { initMathService } from './services/math/math-service.js';
+await createApp({
+    tools: [calculateTool],
+    resources: [helpResource],
+    setup() {
+        initMathService(getServerConfig());
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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,KAAK,EAAE,CAAC,aAAa,CAAC;IACtB,SAAS,EAAE,CAAC,YAAY,CAAC;IACzB,KAAK;QACH,eAAe,CAAC,eAAe,EAAE,CAAC,CAAC;IACrC,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/resources/definitions/help.resource.d.ts

@@ -0,0 +1,8 @@
+/**
+ * @fileoverview Help resource — static reference of available functions, operators, and syntax.
+ * @module mcp-server/resources/definitions/help.resource
+ */
+export declare const helpResource: import("@cyanheads/mcp-ts-core").ResourceDefinition<import("zod").ZodObject<Readonly<{
+    [k: string]: import("zod/v4/core").$ZodType<unknown, unknown, import("zod/v4/core").$ZodTypeInternals<unknown, unknown>>;
+}>, import("zod/v4/core").$strip>, undefined>;
+//# sourceMappingURL=help.resource.d.ts.map

package/dist/mcp-server/resources/definitions/help.resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.resource.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/help.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,eAAO,MAAM,YAAY;;6CAOvB,CAAC"}

package/dist/mcp-server/resources/definitions/help.resource.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Help resource — static reference of available functions, operators, and syntax.
+ * @module mcp-server/resources/definitions/help.resource
+ */
+import { resource } from '@cyanheads/mcp-ts-core';
+import { getMathService } from '../../../services/math/math-service.js';
+export const helpResource = resource('calculator://help', {
+    name: 'Calculator Help',
+    description: 'Available functions, operators, constants, and syntax reference.',
+    mimeType: 'text/markdown',
+    handler() {
+        return getMathService().getHelpContent();
+    },
+});
+//# sourceMappingURL=help.resource.js.map

package/dist/mcp-server/resources/definitions/help.resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"help.resource.js","sourceRoot":"","sources":["../../../../src/mcp-server/resources/definitions/help.resource.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEjE,MAAM,CAAC,MAAM,YAAY,GAAG,QAAQ,CAAC,mBAAmB,EAAE;IACxD,IAAI,EAAE,iBAAiB;IACvB,WAAW,EAAE,kEAAkE;IAC/E,QAAQ,EAAE,eAAe;IACzB,OAAO;QACL,OAAO,cAAc,EAAE,CAAC,cAAc,EAAE,CAAC;IAC3C,CAAC;CACF,CAAC,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview Calculate tool — evaluate, simplify, or differentiate math expressions.
+ * Single tool covering 100% of the server's purpose.
+ * @module mcp-server/tools/definitions/calculate.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const calculateTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    expression: z.ZodString;
+    operation: z.ZodDefault<z.ZodEnum<{
+        evaluate: "evaluate";
+        simplify: "simplify";
+        derivative: "derivative";
+    }>>;
+    variable: z.ZodOptional<z.ZodString>;
+    scope: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    precision: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>, z.ZodObject<{
+    result: z.ZodString;
+    resultType: z.ZodString;
+    expression: z.ZodString;
+}, z.core.$strip>>;
+//# sourceMappingURL=calculate.tool.d.ts.map

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

@@ -0,0 +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;AAIjD,eAAO,MAAM,aAAa;;;;;;;;;;;;;;kBA0GxB,CAAC"}

package/dist/mcp-server/tools/definitions/calculate.tool.js

@@ -0,0 +1,91 @@
+/**
+ * @fileoverview Calculate tool — evaluate, simplify, or differentiate math expressions.
+ * Single tool covering 100% of the server's purpose.
+ * @module mcp-server/tools/definitions/calculate.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { invalidParams } from '@cyanheads/mcp-ts-core/errors';
+import { getMathService } from '../../../services/math/math-service.js';
+export const calculateTool = tool('calculate', {
+    description: 'Evaluate math expressions, simplify algebraic expressions, or compute symbolic derivatives. ' +
+        'Supports arithmetic, trigonometry, statistics, matrices, complex numbers, units, and combinatorics. ' +
+        'Powered by math.js — use calculator://help for the full function reference.',
+    annotations: {
+        readOnlyHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+    input: z.object({
+        expression: z
+            .string()
+            .min(1)
+            .describe('Mathematical expression to evaluate. Supports standard notation: ' +
+            'arithmetic (+, -, *, /, ^, %), functions (sin, cos, sqrt, log, abs, round, etc.), ' +
+            'constants (pi, e, phi, i), matrices ([1, 2; 3, 4]), units (5 kg to lbs), ' +
+            'and variables (when scope is provided).'),
+        operation: z
+            .enum(['evaluate', 'simplify', 'derivative'])
+            .default('evaluate')
+            .describe('Operation to perform. ' +
+            '"evaluate" computes a numeric result (default). ' +
+            '"simplify" reduces an algebraic expression symbolically (e.g., "2x + 3x" -> "5 * x"). Supports algebraic and trigonometric identities. ' +
+            '"derivative" computes the symbolic derivative (requires variable parameter).'),
+        variable: z
+            .string()
+            .max(50)
+            .regex(/^[a-zA-Z_][a-zA-Z0-9_]*$/, 'Variable name must be alphanumeric (a-z, A-Z, 0-9, _).')
+            .optional()
+            .describe('Variable to differentiate with respect to. Required when operation is "derivative". Example: "x".'),
+        scope: z
+            .record(z.string(), z.number())
+            .optional()
+            .describe('Variable assignments for the expression. Example: { "x": 5, "y": 3 } makes "x + y" evaluate to 8.'),
+        precision: z
+            .number()
+            .int()
+            .min(1)
+            .max(16)
+            .optional()
+            .describe('Significant digits (1\u201316) for numeric results. Omit for full precision. Ignored for symbolic operations (simplify, derivative).'),
+    }),
+    output: z.object({
+        result: z.string().describe('The computed result as a string.'),
+        resultType: z
+            .string()
+            .describe('Type of result as reported by math.js: number, BigNumber, Complex, DenseMatrix, Unit, string, boolean. Symbolic operations return "string".'),
+        expression: z.string().describe('The original expression as received.'),
+    }),
+    handler(input, ctx) {
+        const math = getMathService();
+        switch (input.operation) {
+            case 'evaluate': {
+                const { result, resultType } = math.evaluateExpression(input.expression, input.scope, input.precision);
+                ctx.log.info('Evaluated expression', { expression: input.expression });
+                return { result, resultType, expression: input.expression };
+            }
+            case 'simplify': {
+                const { result, resultType } = math.simplifyExpression(input.expression);
+                ctx.log.info('Simplified expression', { expression: input.expression });
+                return { result, resultType, expression: input.expression };
+            }
+            case 'derivative': {
+                if (!input.variable) {
+                    throw invalidParams("The 'variable' parameter is required when operation is 'derivative'.");
+                }
+                const { result, resultType } = math.differentiateExpression(input.expression, input.variable);
+                ctx.log.info('Differentiated expression', {
+                    expression: input.expression,
+                    variable: input.variable,
+                });
+                return { result, resultType, expression: input.expression };
+            }
+        }
+    },
+    format: (output) => [
+        {
+            type: 'text',
+            text: `**Expression:** \`${output.expression}\`\n**Result:** ${output.result}\n**Type:** ${output.resultType}`,
+        },
+    ],
+});
+//# sourceMappingURL=calculate.tool.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calculate.tool.js","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/calculate.tool.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,40 @@
+/**
+ * @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.
+ * @module services/math/math-service
+ */
+import type { ServerConfig } from '../../config/server-config.js';
+import type { MathResult } from './types.js';
+export declare class MathService {
+    private readonly evaluate;
+    private readonly simplify;
+    private readonly derivative;
+    private readonly simplifyRules;
+    private readonly format;
+    private readonly typeOf;
+    private readonly config;
+    constructor(config: ServerConfig);
+    /** Evaluate a math expression with optional variable scope and precision. */
+    evaluateExpression(expression: string, scope?: Record<string, number>, precision?: number): MathResult;
+    /** Simplify an algebraic expression symbolically. */
+    simplifyExpression(expression: string): MathResult;
+    /** Compute the symbolic derivative of an expression with respect to a variable. */
+    differentiateExpression(expression: string, variable: string): MathResult;
+    /** Get formatted help content listing available functions, operators, and syntax. */
+    getHelpContent(): string;
+    private validateInput;
+    /** Reject scope keys that could pollute the object prototype chain. */
+    private sanitizeScope;
+    /** Reject result types that leak internals (functions, parsers, multi-expression ResultSets). */
+    private validateResultType;
+    /** Reject results that exceed the configured maximum size. */
+    private validateResultSize;
+    /** Runs a synchronous function inside a vm sandbox with timeout protection. */
+    private runWithTimeout;
+}
+/** Initialize the math service. Call once from createApp setup(). */
+export declare function initMathService(config: ServerConfig): void;
+/** Get the initialized math service instance. */
+export declare function getMathService(): MathService;
+//# sourceMappingURL=math-service.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"math-service.d.ts","sourceRoot":"","sources":["../../../src/services/math/math-service.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAsG7C,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4D;IACrF,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,CAA+D;IACtF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;gBAE1B,MAAM,EAAE,YAAY;IA2BhC,6EAA6E;IAC7E,kBAAkB,CAChB,UAAU,EAAE,MAAM,EAClB,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,SAAS,CAAC,EAAE,MAAM,GACjB,UAAU;IAkBb,qDAAqD;IACrD,kBAAkB,CAAC,UAAU,EAAE,MAAM,GAAG,UAAU;IAQlD,mFAAmF;IACnF,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,UAAU;IAQzE,qFAAqF;IACrF,cAAc,IAAI,MAAM;IAIxB,OAAO,CAAC,aAAa;IAcrB,uEAAuE;IACvE,OAAO,CAAC,aAAa;IAWrB,iGAAiG;IACjG,OAAO,CAAC,kBAAkB;IAQ1B,8DAA8D;IAC9D,OAAO,CAAC,kBAAkB;IAQ1B,+EAA+E;IAC/E,OAAO,CAAC,cAAc;CAiBvB;AAMD,qEAAqE;AACrE,wBAAgB,eAAe,CAAC,MAAM,EAAE,YAAY,GAAG,IAAI,CAE1D;AAED,iDAAiD;AACjD,wBAAgB,cAAc,IAAI,WAAW,CAG5C"}