{"_id":"@brainycalc/mcpmathserver","name":"@brainycalc/mcpmathserver","dist-tags":{"latest":"1.0.1"},"versions":{"1.0.1":{"name":"@brainycalc/mcpmathserver","version":"1.0.1","description":"The trusted mathematical computation backend for AI agents. Provides powerful math, calculation, and numerical tools through the Model Context Protocol (MCP).","type":"module","main":"src/index.js","bin":{"mcpmathserver":"src/index.js"},"scripts":{"start":"node src/index.js","test":"node src/test.js"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.23.8"},"keywords":["mcp","math","calculator","model-context-protocol"],"license":"MIT","_id":"@brainycalc/mcpmathserver@1.0.1","_nodeVersion":"24.15.0","_npmVersion":"11.12.1","dist":{"integrity":"sha512-Lg1KCH1NjTEqkhHBjOvkB2vcA1Jbro3s9DIyoO2mJDE8h8va07Rw9yK2dJ0ZH6FbQU2dbug+NqYsm0MRc9/Wsw==","shasum":"37ce16e2bdbf0c400d8b5a988ddc20ff5f6130e1","tarball":"https://registry.npmjs.org/@brainycalc/mcpmathserver/-/mcpmathserver-1.0.1.tgz","fileCount":5,"unpackedSize":34130,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIFzdED0yYvanMcEikWk9tv/d4ReuEn6D6fv2p6Rz7mvYAiAwoliURsNBLzm+sbLDDmHWAa+azDV0j4KHPyvE6/v7bQ=="}]},"_npmUser":{"name":"jonbill","email":"codibits@gmail.com"},"directories":{},"maintainers":[{"name":"jonbill","email":"codibits@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcpmathserver_1.0.1_1786357247361_0.7452275765436511"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-10T10:20:47.216Z","1.0.1":"2026-08-10T10:20:47.513Z","modified":"2026-08-10T10:20:47.812Z"},"maintainers":[{"name":"jonbill","email":"codibits@gmail.com"}],"description":"The trusted mathematical computation backend for AI agents. Provides powerful math, calculation, and numerical tools through the Model Context Protocol (MCP).","keywords":["mcp","math","calculator","model-context-protocol"],"license":"MIT","readme":"# MCP Math Server\n\n[MCP Math Server](https://www.brainycalc.com/) is a Model Context Protocol (MCP) server that provides mathematical calculation tools to AI assistants and MCP-compatible clients.\n\nIt runs over **stdio**, making it suitable for local MCP clients such as LM Studio and other MCP-compatible applications.\n\n## Features\n\n- Mathematical expression evaluation\n- Percentage calculations\n- Descriptive statistics\n- Quadratic equation solving\n- GCD and LCM calculations\n- Prime factorization\n- Powers and nth roots\n- Factorials, permutations, and combinations\n- Fraction simplification\n- Geometry calculations\n- Trigonometry\n- Logarithms\n- Area, perimeter, volume, and surface-area calculations\n- Safe input validation and mathematical error handling\n\nThe server exposes the mathematical functionality through a unified MCP tool registry.\n\n---\n\n# MCP Client Configuration\n\n## LM Studio\n\nAdd the server to your MCP configuration.\n\n### Using npx\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpmath\": {\n      \"command\": \"npx\",\n      \"args\": [\n        \"-y\",\n        \"@brainycalc/mcpmathserver\"\n      ]\n    }\n  }\n}\n```\n\nIf your published package name is different, replace `@brainycalc/mcpmathserver` with the actual npm package name.\n\n### Using the local source\n\n```json\n{\n  \"mcpServers\": {\n    \"mcpmath\": {\n      \"command\": \"node\",\n      \"args\": [\n        \"/absolute/path/to/mcpmathserver/src/index.js\"\n      ]\n    }\n  }\n}\n```\n\nUse an absolute path for the local installation.\n\n---\n\n# MCP Architecture\n\nThe server is built around the Model Context Protocol SDK.\n\nThe main server:\n\n```text\nsrc/index.js\n```\n\nThe mathematical implementation:\n\n```text\nsrc/math.js\n```\n\nThe server imports the math tool registry:\n\n```js\nimport { mathTools } from \"./math.js\";\n```\n\nAll mathematical tools are collected into one registry:\n\n```js\nconst ALL_TOOLS = [\n  ...mathTools\n];\n```\n\nA map can then be used for fast tool lookup:\n\n```js\nconst toolMap = new Map(\n  ALL_TOOLS.map((tool) => [tool.name, tool])\n);\n```\n\nThe MCP server implements:\n\n- `ListTools`\n- `CallTool`\n\nand communicates through:\n\n```js\nStdioServerTransport\n```\n\n---\n\n# Available MCP Tools\n\nThe current package contains **11 math tools**.\n\n| Tool | Description |\n|---|---|\n| `math_evaluate` | Evaluate a mathematical expression |\n| `math_percentage` | Perform percentage calculations |\n| `math_statistics` | Calculate descriptive statistics |\n| `math_quadratic` | Solve quadratic equations |\n| `math_gcd_lcm` | Calculate GCD and LCM |\n| `math_prime_factors` | Find prime factors and test primality |\n| `math_power_root` | Calculate powers and nth roots |\n| `math_permutations_combinations` | Calculate factorials, permutations, and combinations |\n| `math_simplify_fraction` | Simplify fractions and convert to mixed fractions |\n| `math_geometry` | Calculate geometry measurements |\n| `math_trigonometry` | Calculate trigonometric functions |\n| `math_logarithm` | Calculate logarithms with a custom base |\n\n---\n\n# Tool Details\n\n## `math_evaluate`\n\nEvaluate a mathematical expression.\n\nExample:\n\n```json\n{\n  \"expression\": \"(12 + 8) * 3 / 2\"\n}\n```\n\nThe expression evaluator accepts numbers, arithmetic operators, parentheses, exponents, spaces, and `%`.\n\nThe implementation converts `^` to JavaScript exponentiation before evaluation and rejects invalid or non-finite results.\n\n---\n\n## `math_percentage`\n\nPerform percentage calculations.\n\nSupported modes:\n\n```text\npercentage_of\nwhat_percent_is\npercentage_change\npercentage_difference\n```\n\nExample:\n\n```json\n{\n  \"mode\": \"percentage_of\",\n  \"a\": 20,\n  \"b\": 150\n}\n```\n\n---\n\n## `math_statistics`\n\nCalculate descriptive statistics for an array of numbers.\n\nExample:\n\n```json\n{\n  \"numbers\": [10, 20, 20, 30, 40]\n}\n```\n\nReturns:\n\n- count\n- sum\n- mean\n- median\n- mode\n- minimum\n- maximum\n- range\n- variance\n- standard deviation\n\n---\n\n## `math_quadratic`\n\nSolve a quadratic equation:\n\n```text\nax² + bx + c = 0\n```\n\nExample:\n\n```json\n{\n  \"a\": 1,\n  \"b\": -5,\n  \"c\": 6\n}\n```\n\nThe tool identifies:\n\n- two real roots\n- one real root\n- complex roots\n\nand returns the discriminant and corresponding roots.\n\n---\n\n## `math_gcd_lcm`\n\nCalculate the Greatest Common Divisor (GCD) and Least Common Multiple (LCM).\n\nExample:\n\n```json\n{\n  \"a\": 12,\n  \"b\": 18\n}\n```\n\n---\n\n## `math_prime_factors`\n\nFind the prime factorization of an integer and determine whether it is prime.\n\nExample:\n\n```json\n{\n  \"number\": 84\n}\n```\n\nExample result:\n\n```json\n{\n  \"number\": 84,\n  \"isPrime\": false,\n  \"factors\": [2, 2, 3, 7]\n}\n```\n\n---\n\n## `math_power_root`\n\nCalculate a power or an nth root.\n\n### Power\n\n```json\n{\n  \"base\": 2,\n  \"exponent\": 10,\n  \"mode\": \"power\"\n}\n```\n\n### Root\n\n```json\n{\n  \"base\": 256,\n  \"exponent\": 4,\n  \"mode\": \"root\"\n}\n```\n\n---\n\n## `math_permutations_combinations`\n\nCalculate factorials, permutations, and combinations.\n\nSupported modes:\n\n```text\nfactorial\nnPr\nnCr\n```\n\n### Factorial\n\n```json\n{\n  \"n\": 5,\n  \"mode\": \"factorial\"\n}\n```\n\n### Permutation\n\n```json\n{\n  \"n\": 10,\n  \"r\": 3,\n  \"mode\": \"nPr\"\n}\n```\n\n### Combination\n\n```json\n{\n  \"n\": 10,\n  \"r\": 3,\n  \"mode\": \"nCr\"\n}\n```\n\n---\n\n## `math_simplify_fraction`\n\nSimplify a fraction to its lowest terms and return a mixed-fraction and decimal representation.\n\nExample:\n\n```json\n{\n  \"numerator\": 42,\n  \"denominator\": 56\n}\n```\n\nReturns:\n\n- original fraction\n- simplified fraction\n- mixed fraction\n- decimal value\n\n---\n\n## `math_geometry`\n\nCalculate measurements for common 2D and 3D shapes.\n\nSupported shapes:\n\n```text\ncircle\nrectangle\ntriangle\nsphere\ncylinder\n```\n\n### Circle\n\n```json\n{\n  \"shape\": \"circle\",\n  \"dimensions\": {\n    \"radius\": 5\n  }\n}\n```\n\nReturns area and circumference.\n\n### Rectangle\n\n```json\n{\n  \"shape\": \"rectangle\",\n  \"dimensions\": {\n    \"length\": 10,\n    \"width\": 4\n  }\n}\n```\n\nReturns area and perimeter.\n\n### Triangle\n\n```json\n{\n  \"shape\": \"triangle\",\n  \"dimensions\": {\n    \"base\": 10,\n    \"height\": 6\n  }\n}\n```\n\nReturns area.\n\n### Sphere\n\n```json\n{\n  \"shape\": \"sphere\",\n  \"dimensions\": {\n    \"radius\": 5\n  }\n}\n```\n\nReturns volume and surface area.\n\n### Cylinder\n\n```json\n{\n  \"shape\": \"cylinder\",\n  \"dimensions\": {\n    \"radius\": 5,\n    \"height\": 10\n  }\n}\n```\n\nReturns volume and surface area.\n\n---\n\n## `math_trigonometry`\n\nCalculate basic trigonometric functions.\n\nSupported functions:\n\n```text\nsin\ncos\ntan\nasin\nacos\natan\n```\n\nAngle units:\n\n```text\ndeg\nrad\n```\n\nExample:\n\n```json\n{\n  \"func\": \"sin\",\n  \"angleValue\": 30,\n  \"unit\": \"deg\"\n}\n```\n\n---\n\n## `math_logarithm`\n\nCalculate a logarithm using a custom base.\n\nExample:\n\n```json\n{\n  \"value\": 100,\n  \"base\": 10\n}\n```\n\nNatural logarithms can also be calculated using the `e` base.\n\n---\n\n# Mathematical Input Validation\n\nThe server validates inputs before performing calculations.\n\nExamples include:\n\n- rejecting invalid mathematical expressions\n- preventing division by zero\n- validating quadratic coefficients\n- validating non-empty statistics arrays\n- preventing zero denominators\n- validating root indexes\n- preventing invalid even roots of negative numbers\n- validating geometry dimensions\n- validating logarithm values and bases\n\nErrors are returned when an operation cannot be performed.\n\n---\n\n# MCP Tool Execution\n\nAn MCP client sends a tool call containing a tool name and arguments.\n\nFor example:\n\n```json\n{\n  \"name\": \"math_percentage\",\n  \"arguments\": {\n    \"mode\": \"percentage_change\",\n    \"a\": 100,\n    \"b\": 125\n  }\n}\n```\n\nThe server finds the corresponding tool and executes it.\n\nThe result is returned to the MCP client as structured text/JSON according to the MCP server implementation.\n\n---\n\n# Dependencies\n\nThe MCP server uses the Model Context Protocol SDK.\n\nTypical dependencies include:\n\n```json\n{\n  \"@modelcontextprotocol/sdk\": \"^1.0.0\",\n  \"zod\": \"^3.23.8\"\n}\n```\n\nThe MCP SDK provides the MCP server implementation and stdio transport.\n\n---\n\n# Package Structure\n\nA typical package structure is:\n\n```text\nmcpmathserver/\n├── package.json\n└── src/\n    ├── index.js\n    └── math.js\n```\n\n`src/index.js` is the executable MCP server.\n\n`src/math.js` contains the mathematical calculation functions and MCP tool definitions.\n\n---\n\n# Security and Runtime Notes\n\nThe server communicates through **stdio** and does not expose an HTTP port by default.\n\nIt is intended to be launched by an MCP host such as:\n\n- LM Studio\n- MCP-compatible AI clients\n- Local AI agents\n- MCP development tools\n\nThe expression evaluator validates the input expression before evaluation and rejects characters outside the supported mathematical syntax.\n\n---\n\n# License\n\nMIT License.\n\nSee the `LICENSE` file for the complete license text.\n\n---\n\n# Links\n\n- [BrainyCalc](https://www.brainycalc.com/)\n- [Documentation](https://www.brainycalc.com/)\n\n---\n\n# Keywords\n\nRecommended npm keywords:\n\n```text\nmcp\nmcp-server\nmodel-context-protocol\nmath\nmathematics\ncalculator\nmath-calculator\nmath-server\nai\nai-agent\nllm\nlm-studio\nnodejs\njavascript\nstatistics\nalgebra\ngeometry\ntrigonometry\nlogarithm\nquadratic\nprime-factors\nfractions\npermutations\ncombinations\n```\n","readmeFilename":"README.md","_rev":"1-b23f37bde75af703fa9a98fb4b211700"}