@euclid-tools/euclid 0.2.0

package/dist/index.js

@@ -0,0 +1,465 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { createRequire } from "module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/tools/calculate.ts
+import { z } from "zod/v4";
+
+// src/engine.ts
+import { create, all } from "mathjs";
+import vm from "vm";
+
+// src/normalization.ts
+var UNIT_ALIASES = {
+  celsius: "degC",
+  fahrenheit: "degF",
+  "kilometers per hour": "km/hour",
+  "miles per hour": "mile/hour",
+  "meters per second": "m/s",
+  "feet per second": "ft/s",
+  "square meters": "m^2",
+  "square feet": "ft^2",
+  "square kilometers": "km^2",
+  "square miles": "mile^2",
+  "cubic meters": "m^3",
+  "cubic feet": "ft^3",
+  "cubic inches": "in^3",
+  litres: "liter"
+};
+function normalizeUnit(input) {
+  const trimmed = input.trim();
+  const key = trimmed.toLowerCase();
+  const mapped = UNIT_ALIASES[key];
+  if (mapped) {
+    return { value: mapped, wasTransformed: true, original: input };
+  }
+  return { value: trimmed, wasTransformed: trimmed !== input, original: input };
+}
+var EXPRESSION_REPLACEMENTS = [
+  [/×/g, "*"],
+  [/÷/g, "/"],
+  [/²/g, "^2"],
+  [/³/g, "^3"],
+  [/√\(/g, "sqrt("],
+  [/√(\d+(?:\.\d+)?)/g, "sqrt($1)"],
+  [/\u2212/g, "-"],
+  [/π/g, "pi"]
+];
+function normalizeExpression(input) {
+  let value = input;
+  for (const [pattern, replacement] of EXPRESSION_REPLACEMENTS) {
+    value = value.replace(pattern, replacement);
+  }
+  value = value.replace(/\d{1,3}(?:,\d{3})+(?!\d)/g, (match) => match.replace(/,/g, ""));
+  return {
+    value,
+    wasTransformed: value !== input,
+    original: input
+  };
+}
+
+// src/engine.ts
+var MAX_EXPRESSION_LENGTH = 1e3;
+var TIMEOUT_MS = 5e3;
+var MAX_DATA_LENGTH = 1e4;
+var math = create(all);
+var limitedEvaluate = math.evaluate;
+math.createUnit("mph", "1 mile/hour");
+math.createUnit("kph", "1 km/hour");
+math.createUnit("kmh", "1 km/hour");
+math.createUnit("knot", "1.852 km/hour");
+math.createUnit("knots", "1 knot");
+math.createUnit("kn", "1 knot");
+math.createUnit("kt", "1 knot");
+math.createUnit("nmi", "1.852 km");
+math.import(
+  {
+    import: () => {
+      throw new Error("Function import is disabled");
+    },
+    createUnit: () => {
+      throw new Error("Function createUnit is disabled");
+    },
+    evaluate: () => {
+      throw new Error("Function evaluate is disabled");
+    },
+    parse: () => {
+      throw new Error("Function parse is disabled");
+    },
+    simplify: () => {
+      throw new Error("Function simplify is disabled");
+    },
+    derivative: () => {
+      throw new Error("Function derivative is disabled");
+    },
+    resolve: () => {
+      throw new Error("Function resolve is disabled");
+    },
+    reviver: () => {
+      throw new Error("Function reviver is disabled");
+    }
+  },
+  { override: true }
+);
+function evaluateExpression(expression, precision = 14) {
+  if (expression.trim().length === 0) {
+    return { error: "Expression is empty" };
+  }
+  if (expression.length > MAX_EXPRESSION_LENGTH) {
+    return {
+      error: `Expression too long (${expression.length} chars, max ${MAX_EXPRESSION_LENGTH})`
+    };
+  }
+  const norm = normalizeExpression(expression);
+  try {
+    const sandbox = { fn: limitedEvaluate, expr: norm.value };
+    const raw = vm.runInNewContext("fn(expr)", sandbox, { timeout: TIMEOUT_MS });
+    const formatted = math.format(raw, { precision, upperExp: 14, lowerExp: -14 });
+    const engineResult = { result: formatted };
+    if (norm.wasTransformed) {
+      engineResult.note = `Expression '${norm.original}' was interpreted as '${norm.value}'`;
+    }
+    return engineResult;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("Script execution timed out")) {
+      return { error: "Computation timed out after 5 seconds" };
+    }
+    return { error: message };
+  }
+}
+function convertUnit(value, from, to) {
+  const normFrom = normalizeUnit(from);
+  const normTo = normalizeUnit(to);
+  try {
+    const unit = math.unit(value, normFrom.value);
+    const converted = unit.to(normTo.value);
+    const num = converted.toNumber();
+    const engineResult = { result: String(num) };
+    const notes = [];
+    if (normFrom.wasTransformed) {
+      notes.push(`'${normFrom.original}' was interpreted as '${normFrom.value}'`);
+    }
+    if (normTo.wasTransformed) {
+      notes.push(`'${normTo.original}' was interpreted as '${normTo.value}'`);
+    }
+    if (notes.length > 0) {
+      engineResult.note = notes.join("; ");
+    }
+    return engineResult;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: message };
+  }
+}
+function computeStatistic(operation, data, percentile) {
+  if (data.length === 0) {
+    return { error: "Data array is empty" };
+  }
+  if (data.length > MAX_DATA_LENGTH) {
+    return { error: `Data array too many elements (${data.length}, max ${MAX_DATA_LENGTH})` };
+  }
+  try {
+    let result;
+    switch (operation) {
+      case "mean":
+        result = math.mean(data);
+        break;
+      case "median":
+        result = math.median(data);
+        break;
+      case "mode":
+        result = math.mode(data);
+        result = Array.isArray(result) ? result[0] : result;
+        break;
+      case "std":
+        result = math.std(data);
+        break;
+      case "variance":
+        result = math.variance(data);
+        break;
+      case "min":
+        result = math.min(data);
+        break;
+      case "max":
+        result = math.max(data);
+        break;
+      case "sum":
+        result = math.sum(data);
+        break;
+      case "percentile":
+        if (percentile === void 0) {
+          return { error: 'Percentile value is required when operation is "percentile"' };
+        }
+        if (percentile < 0 || percentile > 100) {
+          return { error: "Percentile must be between 0 and 100" };
+        }
+        result = math.quantileSeq(data, percentile / 100);
+        break;
+      default:
+        return { error: `Unknown operation: ${operation}` };
+    }
+    return { result: String(result) };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { error: message };
+  }
+}
+
+// src/error-hints.ts
+var CALCULATE_EXAMPLES = ["2 * 3", "sqrt(16)", "sin(pi / 4)", "log(100, 10)", "12! / (4! * 8!)"];
+var CONVERT_EXAMPLES = [
+  "convert(5, 'km', 'mile')",
+  "convert(100, 'degF', 'degC')",
+  "convert(1, 'lb', 'kg')"
+];
+var STATISTICS_EXAMPLES = [
+  "statistics('mean', [1, 2, 3])",
+  "statistics('percentile', [10, 20, 30], 90)"
+];
+function getCalculateHint(errorMessage) {
+  if (errorMessage.includes("Unexpected") || errorMessage.includes("Parenthesis") || errorMessage.includes("Value expected")) {
+    return "Check expression syntax. Use * for multiplication, / for division, ^ for exponents, and ensure parentheses are balanced.";
+  }
+  if (errorMessage.includes("Undefined symbol") || errorMessage.includes("Undefined function")) {
+    return "Unknown variable or function. Supported functions include: sqrt, sin, cos, tan, log, exp, abs, ceil, floor, round.";
+  }
+  if (errorMessage.includes("is disabled")) {
+    return "This function is disabled for security. Use basic arithmetic and math functions only.";
+  }
+  return "Invalid expression. Use standard mathematical notation with operators: +, -, *, /, ^.";
+}
+function getConvertHint(errorMessage) {
+  if (errorMessage.includes("not found")) {
+    return "Unit not recognized. Use standard abbreviations: km, m, ft, mile, lb, kg, degC, degF, mph, kph.";
+  }
+  if (errorMessage.includes("do not match")) {
+    return "Units are incompatible. Ensure both measure the same quantity (e.g., length to length, weight to weight).";
+  }
+  return "Invalid conversion. Provide a numeric value with valid source and target units.";
+}
+function getStatisticsHint(errorMessage) {
+  if (errorMessage.includes("Unknown operation")) {
+    return "Valid operations: mean, median, mode, std, variance, min, max, sum, percentile.";
+  }
+  if (errorMessage.includes("Percentile")) {
+    return "The percentile parameter is required and must be between 0 and 100.";
+  }
+  if (errorMessage.includes("empty")) {
+    return "Data array must contain at least one number.";
+  }
+  return "Provide a valid operation and a non-empty array of numbers.";
+}
+function getErrorHint(tool, errorMessage) {
+  switch (tool) {
+    case "calculate":
+      return { hint: getCalculateHint(errorMessage), examples: CALCULATE_EXAMPLES };
+    case "convert":
+      return { hint: getConvertHint(errorMessage), examples: CONVERT_EXAMPLES };
+    case "statistics":
+      return { hint: getStatisticsHint(errorMessage), examples: STATISTICS_EXAMPLES };
+  }
+}
+
+// src/tools/calculate.ts
+var calculateTool = {
+  name: "calculate",
+  description: `Deterministic calculator for mathematical expressions. Use this tool whenever you need to compute a numerical result rather than predict one. This includes: arithmetic operations, percentages, exponents, roots, trigonometry, logarithms, factorials, and any expression that has a single correct numerical answer.
+
+DO NOT attempt to calculate results from memory or prediction. If a user asks a question that requires computation, use this tool.
+
+Examples of when to use this tool:
+- "What is 15% of 847?" \u2192 calculate("0.15 * 847")
+- "Calculate 2^32" \u2192 calculate("2^32")
+- "What's 3,456 \xD7 7,891?" \u2192 calculate("3456 * 7891")
+- "Square root of 7" \u2192 calculate("sqrt(7)")
+- "sin(30 degrees)" \u2192 calculate("sin(30 deg)")
+- "12! / (4! * 8!)" \u2192 calculate("12! / (4! * 8!)")
+
+Examples of when NOT to use this tool:
+- Rough estimates ("about how many people fit in a stadium")
+- Conceptual math explanations ("explain what a derivative is")
+- Symbolic algebra that doesn't evaluate to a number`,
+  inputSchema: z.object({
+    expression: z.string().describe("Mathematical expression to evaluate, e.g. '(245 * 389) + (12^3 / 7)'"),
+    precision: z.number().optional().describe("Significant digits for the result. Default: 14")
+  }),
+  handler: async (args) => {
+    const result = evaluateExpression(args.expression, args.precision);
+    if ("error" in result) {
+      const { hint, examples } = getErrorHint("calculate", result.error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: result.error,
+              expression: args.expression,
+              hint,
+              examples
+            })
+          }
+        ],
+        isError: true
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            result: result.result,
+            expression: args.expression,
+            ...result.note && { note: result.note }
+          })
+        }
+      ]
+    };
+  }
+};
+
+// src/tools/convert.ts
+import { z as z2 } from "zod/v4";
+var convertTool = {
+  name: "convert",
+  description: `Converts between units of measurement deterministically. Supports length, weight, volume, temperature, area, speed, time, data (bytes/bits), and 100+ other units.
+
+Use this tool whenever a user asks to convert between units. The value, source unit, and target unit must be specified separately.
+
+Common aliases like "mph", "kph", "knots" are supported in addition to standard mathjs units.
+
+Examples:
+- "Convert 5 km to miles" \u2192 convert(5, "km", "miles")
+- "100\xB0F in Celsius" \u2192 convert(100, "fahrenheit", "celsius")
+- "1 lb in kg" \u2192 convert(1, "lb", "kg")
+- "1024 bytes to kB" \u2192 convert(1024, "bytes", "kB")
+- "60 mph to km/h" \u2192 convert(60, "mph", "kph")`,
+  inputSchema: z2.object({
+    value: z2.number().describe("The numeric value to convert"),
+    from: z2.string().describe("Source unit, e.g. 'km', 'fahrenheit', 'lb'"),
+    to: z2.string().describe("Target unit, e.g. 'miles', 'celsius', 'kg'")
+  }),
+  handler: async (args) => {
+    const result = convertUnit(args.value, args.from, args.to);
+    if ("error" in result) {
+      const { hint, examples } = getErrorHint("convert", result.error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: result.error,
+              value: args.value,
+              from: args.from,
+              to: args.to,
+              hint,
+              examples
+            })
+          }
+        ],
+        isError: true
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            result: result.result,
+            value: args.value,
+            from: args.from,
+            to: args.to,
+            ...result.note && { note: result.note }
+          })
+        }
+      ]
+    };
+  }
+};
+
+// src/tools/statistics.ts
+import { z as z3 } from "zod/v4";
+var statisticsTool = {
+  name: "statistics",
+  description: `Computes statistical measures on a dataset deterministically. Use this tool when a user asks for mean, median, mode, standard deviation, variance, min, max, sum, or percentile calculations on a set of numbers.
+
+Examples:
+- "What's the average of these test scores?" \u2192 statistics("mean", [85, 92, 78, 95, 88])
+- "Find the median household income" \u2192 statistics("median", [45000, 52000, 61000, 38000])
+- "90th percentile of response times" \u2192 statistics("percentile", [120, 340, 200, 150, 180], 90)
+- "Standard deviation of this sample" \u2192 statistics("std", [23, 45, 12, 67, 34])`,
+  inputSchema: z3.object({
+    operation: z3.enum(["mean", "median", "mode", "std", "variance", "min", "max", "sum", "percentile"]).describe("The statistical operation to perform"),
+    data: z3.array(z3.number()).describe("Array of numbers to compute the statistic on"),
+    percentile: z3.number().optional().describe('Percentile value (0-100), required if operation is "percentile"')
+  }),
+  handler: async (args) => {
+    const result = computeStatistic(args.operation, args.data, args.percentile);
+    if ("error" in result) {
+      const { hint, examples } = getErrorHint("statistics", result.error);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({
+              error: result.error,
+              operation: args.operation,
+              hint,
+              examples
+            })
+          }
+        ],
+        isError: true
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({
+            result: result.result,
+            operation: args.operation,
+            ...result.note && { note: result.note }
+          })
+        }
+      ]
+    };
+  }
+};
+
+// src/index.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var server = new McpServer({
+  name: "euclid",
+  version
+});
+server.registerTool(
+  calculateTool.name,
+  {
+    description: calculateTool.description,
+    inputSchema: calculateTool.inputSchema
+  },
+  async (args) => calculateTool.handler(args)
+);
+server.registerTool(
+  convertTool.name,
+  {
+    description: convertTool.description,
+    inputSchema: convertTool.inputSchema
+  },
+  async (args) => convertTool.handler(args)
+);
+server.registerTool(
+  statisticsTool.name,
+  {
+    description: statisticsTool.description,
+    inputSchema: statisticsTool.inputSchema
+  },
+  async (args) => statisticsTool.handler(args)
+);
+var transport = new StdioServerTransport();
+await server.connect(transport);

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
+            "async": false
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks/run-hook.cmd

@@ -0,0 +1,40 @@
+: << 'CMDBLOCK'
+@echo off
+REM Cross-platform polyglot wrapper for hook scripts.
+REM On Windows: cmd.exe runs the batch portion, which finds and calls bash.
+REM On Unix: the shell interprets this as a script (: is a no-op in bash).
+
+if "%~1"=="" (
+    echo run-hook.cmd: missing script name >&2
+    exit /b 1
+)
+
+set "HOOK_DIR=%~dp0"
+
+REM Try Git for Windows bash in standard locations
+if exist "C:\Program Files\Git\bin\bash.exe" (
+    "C:\Program Files\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+if exist "C:\Program Files (x86)\Git\bin\bash.exe" (
+    "C:\Program Files (x86)\Git\bin\bash.exe" "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM Try bash on PATH (e.g. user-installed Git Bash, MSYS2, Cygwin)
+where bash >nul 2>nul
+if %ERRORLEVEL% equ 0 (
+    bash "%HOOK_DIR%%~1" %2 %3 %4 %5 %6 %7 %8 %9
+    exit /b %ERRORLEVEL%
+)
+
+REM No bash found - exit silently rather than error
+REM (plugin still works, just without SessionStart context injection)
+exit /b 0
+CMDBLOCK
+
+# Unix: run the named script directly
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+SCRIPT_NAME="$1"
+shift
+exec bash "${SCRIPT_DIR}/${SCRIPT_NAME}" "$@"

package/hooks/session-start

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# SessionStart hook for Euclid plugin
+# 1. Auto-registers MCP server if not already present
+# 2. Injects context reminder that Euclid tools are available
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
+PLUGIN_ROOT="$(cd "${SCRIPT_DIR}/.." && pwd)"
+
+# Check if euclid MCP server is already registered
+if ! claude mcp list 2>/dev/null | grep -q "euclid"; then
+  claude mcp add euclid -- npx -y @euclid-tools/euclid 2>/dev/null || true
+fi
+
+# JSON-escape helper
+escape_for_json() {
+    local s="$1"
+    s="${s//\\/\\\\}"
+    s="${s//\"/\\\"}"
+    s="${s//$'\n'/\\n}"
+    s="${s//$'\r'/\\r}"
+    s="${s//$'\t'/\\t}"
+    printf '%s' "$s"
+}
+
+context="Euclid deterministic math tools are available via MCP. For ANY numerical computation, unit conversion, or statistical calculation, use the Euclid MCP tools (calculate, convert, statistics) instead of mental math. Never predict or estimate when a deterministic tool is available."
+context_escaped=$(escape_for_json "$context")
+
+# Output context injection
+# Claude Code sets CLAUDE_PLUGIN_ROOT; other platforms do not
+if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ]; then
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "SessionStart",
+    "additionalContext": "${context_escaped}"
+  }
+}
+EOF
+else
+  cat <<EOF
+{
+  "additional_context": "${context_escaped}"
+}
+EOF
+fi
+
+exit 0

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@euclid-tools/euclid",
+  "version": "0.2.0",
+  "description": "Deterministic math tools for LLMs — an MCP server and Claude Code plugin powered by mathjs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/euclidtools/euclid.git"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "euclid-mcp": "dist/index.js",
+    "euclid": "dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsup",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src/",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  },
+  "keywords": [
+    "mcp",
+    "calculator",
+    "math",
+    "deterministic",
+    "llm",
+    "mathjs"
+  ],
+  "files": [
+    "dist",
+    ".claude-plugin",
+    "skills",
+    "hooks"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "mathjs": "^15.1.1",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.4.0",
+    "eslint": "^10.0.3",
+    "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.57.0",
+    "vitest": "^4.0.18"
+  }
+}