Use it to perform dimensional calculation and unit conversion via MCP with reproducible evidence.
Call the quantity_execute MCP tool with an operations array.
Multiply quantities with units (op: mul, using a and b).
Convert a quantity to a target unit (op: convert, using to).
Chain multi-step calculations by referencing previous operands (a: {ref: ...}).
Control precision with precision.mode (HALF_EVEN/HALF_UP) and precision.scale.
Receive an exactness result, an error_bound when approximate, and a full_evidence_hash for replay.
Failures are reported as structured taxonomy codes (e.g., UNKNOWN_UNIT or DIMENSION_MISMATCH_UNBRIDGEABLE).
An MCP (Model Context Protocol) server that performs dimensional calculation and unit conversion with evidence and reproducibility.
Solves silent unit errors in LLM agent chains. 5 kg × 9.81 m/s^2 returns 49.05 N with evidence, not a plausible-looking wrong number.
The server exposes one MCP tool: quantity_execute. It runs over stdio and follows the MCP protocol via the official Python SDK (mcp).
Register with any MCP client.
claude_desktop_config.json:
{
"mcpServers": {
"quantity-engine": {
"command": "python",
"args": ["/absolute/path/to/mcp_server.py"]
}
}
}Same shape — command, args, no env required.
pip install -r requirements.txt
python mcp_server.pyThe server listens on stdio. Ctrl+C to stop.
Related MCP server: SharkMath MCP
tool.json defines quantity_execute with input and output schemas. The MCP server registers this tool and forwards calls to the engine unchanged — no interpretation, no fallback.
Example call:
{
"operations": [
{"id": "s0", "op": "mul",
"a": {"value": 5, "unit": "kg"},
"b": {"value": 9.81, "unit": "m/s^2"}},
{"id": "s1", "op": "convert",
"a": {"ref": "s0", "as": "N"}, "to": "N"}
]
}Returns 49.05 N with exactness, error_bound if approximated, and full_evidence_hash for replay of the evidence.
Example addition:
{
"operations": [
{"id": "s0", "op": "add",
"a": {"value": 5, "unit": "N"},
"b": {"value": 3, "unit": "N"}}
]
}Returns 8 N (EXACT).
Example division:
{
"operations": [
{"id": "s0", "op": "div",
"a": {"value": 10, "unit": "N"},
"b": {"value": 2, "unit": "s"}}
]
}Returns 5 N/s. Dimension is derived from operand exponents (M·L·T⁻³).
Closed quantity algebra: mul, add, sub, div, convert
Exact rational arithmetic (no float drift)
Explicit precision policy (EXACT vs APPROXIMATED with error_bound)
Provenance hash (full_evidence_hash) for replay of the evidence
Structured failure taxonomy (MISSING_UNIT_DECLARATION, UNKNOWN_UNIT, INVALID_UNIT_NOTATION, INVALID_UNIT_CAST, UNKNOWN_OP, DIVISION_BY_ZERO, DIMENSION_MISMATCH_UNBRIDGEABLE, NEEDS_CLARIFICATION, NEEDS_REFERENCE_DATA)
No automatic reduction of compound units (N*m is reported as N*m, not J)
Money as separate domain with temporal context (stub)
Evidence is not correctness. The hash proves what inputs, versions, and reference data were used, and allows the same operation to be replayed against the same evidence. Mathematical correctness rests on the dimensional model, the engine rules, and the test suite — not on the hash.
quantities.py engine (zero external dependencies)
tool.json MCP tool contract
mcp_server.py MCP stdio transport (uses mcp, jsonschema)
requirements.txt mcp, jsonschema — only needed for the MCP transport
Dockerfile container for MCP deploymentMVP. 14 tests passing (python quantities.py). Not production. FX rates are stub.
Algebra is closed over the current dimensional model. cm, km, h, J, W are not in the registry — they require an explicit registry extension, not a code change.
Apache 2.0.
Execute dimensional calculation and unit conversion with audit evidence. Input: sequence of typed operations (mul, add, sub, div, convert). Output: result value with unit, precision metadata, and reproducibility hash, or a structured failure.
| Name | Required | Description | Default |
|---|---|---|---|
| precision | No | ||
| operations | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose the return shape (value with unit, precision metadata, reproducibility hash, or structured failure) and implies deterministic behavior via the hash. It omits whether the operation is pure/read-only, how failures are triggered, and any validation rules, leaving notable behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the purpose followed by a compact input/output summary; no filler. Slightly terse given the nested schema, but structurally clean.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, and the description does cover return values, which is a plus. However, for a tool with a nested operations array and an undocumented operand $ref, the description leaves the caller without enough detail on how to assemble operations correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% at the top level and the tool has a nested operations array plus a precision object, so the description should compensate more. It names the operation types (mul/add/sub/div/convert) and references precision metadata, but does not explain operand structure, the precision.mode/scale fields, or the 'to'/'at' semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (Execute) and resource (dimensional calculation and unit conversion) with the audit-evidence angle, and enumerates the operation types. No siblings exist to differentiate, but the purpose itself is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to choose this tool, prerequisites, or exclusions; the 'Input/Output' phrasing describes the contract rather than usage conditions. An agent learns what to send, not when this is the right call.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.1quantity_execute2 fields changedInput schema / properties / operations / items / properties / b / descriptionPrevious value: -"Required for mul"New value: +"Required for mul, add, sub, div"Input schema / properties / operations / items / properties / op / enumPrevious value: -[
- "mul",
- "convert"
-]New value: +[
+ "mul",
+ "add",
+ "sub",
+ "div",
+ "convert"
+]v0.1.0quantity_executeScored across 1 tool
With only one tool in the set, there is no possibility of choosing the wrong tool or confusing overlapping purposes. The single tool's scope (a sequence of typed arithmetic/conversion operations) is clearly bounded and self-contained.
The lone name `quantity_execute` uses a noun_verb pattern that is prefixed consistently with the server name (quantity-engine) and is unambiguous. It is readable and predictable, though a pure verb_noun convention (e.g. execute_quantity) would be more idiomatic.
A single batch-style execute tool is a defensible design for a calculation engine, since operations are passed as a sequence rather than as separate endpoints. However, one tool is thin for the apparent domain and forces everything—including discovery and validation—through the same opaque entry point.
Core arithmetic (mul, add, sub, div) and unit conversion with precision metadata and failure reporting cover the main lifecycle of a dimensional calculation. Gaps remain: no unit/introspection operation to discover valid units, and no support for common operations like exponentiation, roots, rounding, or comparison.
60+ units, live FX, timezones, and date arithmetic for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server exposing the Backtest360 engine API as tools for AI agents.