Abacus

CI PyPI Python 3.10+ License: GPLv3 Sponsor Ruff Checked with mypy Last commit

A calculator for the artificial minds — because we know their needs are different.

People reach for a calculator to get a number. A language model reaches for one to get a number it can trust and reason about: Was this exact, or rounded? At what scale? Would a wider type have held more digits? Does this overflow the way the production code will? A floating-point answer that merely looks precise is worse than no answer — it launders a rounding error into a confident claim.

mcp-abacus is built for that caller. It does type-faithful calculation: you pick a numeric type/mode (fixed-point, IEEE-754 double, exact rational, complex) and the whole expression behaves exactly as that type would in real code — it rounds where the type rounds, stays exact where the type is exact, and carries the result onward bit-for-bit. Every answer comes back labelled with its own precision verdict (exact vs inexact, rounded to N decimals), so the model never has to guess whether a result is the true value. It does not approximate a type; it calculates using that type.

What it gives you

• calculate — evaluate one expression in one numeric type. Modes:

  • fixed-point (default) — exact scaled integer; money / ERC-20-safe
  • floating-point — IEEE-754 double (aliases float64, double)
  • rational — exact numerator/denominator; no silent rounding
  • complex — a + b*i over two fixed-point parts; write the imaginary unit as 1i (e.g. 3+4i, 2.5i). Exact + - * ((3+4i)*(1+2i) → -5+10i, sqrt(-1) → 1i), rounds / and the transcendentals onto the grid; no ordering, bitwise, integer (gcd/factorial), or solver support

  A vector literal [a, b, …] builds a one-dimensional list of values in the chosen mode (e.g. [1, 2, 3], the empty [], or [1+1, 2*3] → [2, 6]); it is an internal container, not a selectable mode. The whole stats family reduces over a single vector's elements — min/max/avg/median/variance/stddev/sumsq/geomean/harmean (avg([1, 2, 3]) → 2, sumsq([1, 2, 3]) → 14, geomean([4, 9]) → 6), as do the integer reducers gcd/lcm (gcd([54, 24, 6]) → 6). The order statistics take a leading point then the data (a run or one vector): quantile(q, …) for q in [0, 1] and percentile(p, …) for p in [0, 100] read the value at that rank (type-7 linear interpolation), generalising median — percentile(50, [1, 2, 3, 4]) is the median. And covariance(x, y)/correlation(x, y) take two equal-length vectors (covariance([1, 2, 3], [4, 5, 6]), Pearson correlation(...) in [-1, 1]). Going the other way, factor(n) PRODUCES a vector — the prime factors of a positive integer, ascending with multiplicity (factor(12) → [2, 2, 3], factor(1) → []). Otherwise vectors only construct and render — other operators and functions refuse one, there is no indexing (b[i]), and nesting ([[1,2],[3,4]]) is rejected.

• analyze — evaluate an expression and return its whole parse tree, each node annotated with the value it computed, so you can see where a surprising answer rounded or overflowed (e.g. (1 + 1/2) * 3 is 3 in fixed-point — the tree shows the 1/2 = 0 leaf that explains it)

• solver — find the value(s) of one or more variables that drive an expression to a target over a bracket: find-root (x**2 - 2 over [0, 2] → √2) or find-minimum / find-maximum, in the same numeric type and expression language (constants come from name = expr assignment lines). One unknown uses golden-section search (or Brent parabolic via algorithm="brent-parabolic", usually faster on smooth extrema); pass variables (a name → [lower, upper] map) with algorithm="nelder-mead" to solve several jointly with a Nelder-Mead simplex

• curve_fit — fit known curve forms to paired (x, y) observations and report each fitted equation with its error. Hand over the data and it estimates, for the straight line, quadratic, cubic, power law a*x**b, exponential a*exp(b*x), exp-reciprocal (Arrhenius) a*exp(b/x), logarithm a + b*ln(x), square root a*sqrt(x) + b, reciprocal a/x + b, sinusoid a*sin(b*x + c) + d, gaussian a*exp(-(x-b)**2/(2*c**2)), saturation x/(a*x + b) (Michaelis-Menten), hyperbolic 1/(a*x + b), Laurent a + b*x + c/x, Hoerl a*b**x*x**c, Weibull CDF 1 - exp(-(x/a)**b), logistic a/(1 + exp(-(b*x + c))) (with a data-fixed ceiling a), generalized hyperbolic 1/(a*x**2 + b*x + c) and Lorentzian peak a/(1 + ((x-b)/c)**2), the parameters that best match in the least-squares sense — polynomials and the affine forms in closed form via the normal equations, the power, exponential and exp-reciprocal laws by a log-linearisation, the gaussian and Hoerl by fitting a log-space basis (Caruana's method for the gaussian), the Weibull by the double-log Weibull plot, the logistic by the logit once its ceiling is fixed, the saturation and hyperbolic by a reciprocal-line transform (the generalized hyperbolic and Lorentzian by a reciprocal-quadratic), and the sinusoid (the lone form with no closed form) by an iterative frequency search — then ranks them by residual error and returns the best three (e.g. x=[1,1.5,2], y=[2,5.8,8.9] → 6.9*x - 4.78…). The whole fit runs in the chosen numeric type, so the parameters and error carry the usual precision verdict

• help — the grammar and type reference, on tap for the model

• info — server version and environment

Each calculate result is self-describing: a rendered value string with its precision verdict baked in, plus structured exact / precision fields. An inexact fixed-point result even previews what a few more decimals would reveal, so the caller is steered toward more precision rather than toward a misleading float.

Install and register for Claude Code

Install the server as a uv tool from this checkout:

uv tool install .

This puts an mcp-abacus executable on your PATH. Register it with Claude Code (user scope, so it's available in every project):

claude mcp add abacus -- mcp-abacus

Then start (or /mcp reconnect) a Claude Code session — the abacus tools will be available. Verify the server is up with:

claude mcp list

Upgrading from source: the version is pinned, so a plain reinstall can reuse a cached wheel and silently install stale code. Force a clean rebuild:

uv cache clean mcp-abacus
uv tool install --force --no-cache .

A long-lived Claude session keeps the old server subprocess until you /mcp reconnect or start a fresh session.

Development

uv sync
uv run pytest

Sponsoring

mcp-abacus is free, open-source software developed in my spare time. Sponsorships are what keep the project alive and actively maintained — they fund new numeric modes, bug fixes, and ongoing support, and they're a direct signal that the work is worth continuing.

If the project is useful to you, please consider sponsoring it through GitHub Sponsors. Click the Sponsor button at the top of the repository, or visit the link directly, and pick a one-time or recurring tier. Every contribution, large or small, is hugely appreciated and goes straight back into keeping mcp-abacus healthy.

License

GNU General Public License v3.0 or later (GPL-3.0-or-later). See LICENSE.