convez.ai
MCP ServerUtilidadesAvançado
pavansgill

Just Calculate MCP

pavansgill/just-calculate-mcp

45 ferramentas matemáticas sem sobrecarregar o contexto do modelo

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP em Rust que fornece 45 ferramentas matemáticas (aritmética, trigonometria, álgebra linear, estatística, operações bitwise) com um padrão inovador de gating para evitar sobrecarga de tools. Implementa dois modelos de acesso: toggle para revelação progressiva de categorias e act para chamadas diretas sem exposição no schema.

Instalação

$npx convez-ai pavansgill/just-calculate-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
57%
Último commit
há 2 meses
Versão
—
Issues abertas
2
Contribuidores
2

Casos de uso

  • Integração de capacidades matemáticas avançadas em agentes IA sem consumir contexto
  • Demonstração de padrões de gerenciamento de tools em servidores MCP
  • Cálculos financeiros, estatísticos e científicos em fluxos automatizados

Veredito

Projeto técnico sólido que resolve um problema real de escalabilidade em MCP servers. A abordagem dual (toggle/act) é educativa e pragmática, embora o foco em matemática pura limita seu escopo de aplicação. Excelente para quem desenvolve servidores MCP complexos.

README

A tradução para o português deste README ainda está na fila.

just-calculate-mcp

CI License: Apache 2.0

A Rust Model Context Protocol server that gives an AI assistant a real calculator — 45 math tools across 17 domains, from arithmetic and trigonometry to finance, linear algebra, statistics, and bitwise ops — without drowning the client in 45 tool schemas.

That second part is the interesting bit, and the reason this repo exists as much as a demonstration of two tool-management patterns as a calculator. If you're here for the math, jump to the catalog. If you're here because your own MCP server has too many tools, read on — that problem is what this project is really about.

Licensed under Apache-2.0. Use it, fork it, ship it in your own product — commercial or not. The patent grant and "as-is, no warranty" terms are there so nobody gets patent-ambushed and nobody gets sued. It's a gift to the world; go build something with it. See the license section.


The problem: tool overload

MCP clients send every tool's schema to the model on every request. A calculator that covers "all of math" can easily hit 40+ tools, and at that point:

  • the tool list alone burns a large slice of the context window, every turn;
  • many clients degrade — selection accuracy drops as the list grows;
  • yet the model still needs to discover what's available and how to call it.

You can't win by just deleting tools (you lose capability) or by cramming everything into one mega-tool (you lose validated, self-describing schemas). So this server keeps all 45 tools and shows a tool list of only two by default. It does that with a small gating layer, and it deliberately ships two complementary ways through it so you can see both patterns side by side.


The two approaches

By default the client sees exactly two tools — toggle and act — plus one discovery resource. Everything else is hidden until asked for.

1. toggle — progressive disclosure

Reveal a whole category (or a single tool), use it with its real, validated schema, then hide it again. Revealed tools appear/disappear from the live tool list via the standard notifications/tools/list_changed event.

toggle { "target": "geometry", "on": true }   // reveals area_2d, volume_3d, … (6 tools)
toggle { "target": "area_2d",  "on": true }   // or just one tool
toggle { "target": "all",      "on": true }   // reveal everything
toggle { "target": "geometry", "on": false }  // hide again when done

Best when you'll make several related calls — you get the genuine input schema, argument validation, and client-side autocomplete, at the cost of one round-trip to turn the category on.

2. act — one-shot proxy

Call any tool by name in a single step, without revealing it. Works even while the tool is toggled off.

act { "tool": "area_2d", "args": { "shape": "circle", "a": 5 } }
// → area = 78.53981633974483

Best when you want a quick one-off — zero round-trips, zero footprint in the tool list. The trade-off is that the model leans on the guide (below) for the argument shape instead of an inline schema.

Discovery: the calc://guide resource

Neither approach is useful if the model can't find out what exists. So the server exposes an MCP resource at calc://guide — a generated catalog of every category, every tool, and how to use both meta-tools. The model reads it once and knows the whole surface area, without 45 schemas ever entering the context.

The payoff: default context drops from ~45 schemas to 2 tools + 1 on-demand resource, while the full calculator stays reachable two different ways.


Quick start

Requires a Rust toolchain.

git clone https://github.com/pavansgill/just-calculate-mcp
cd just-calculate-mcp
cargo build --release

Register it with any MCP client. For Claude Code / Claude Desktop, point at the binary (or use cargo run):

{
  "mcpServers": {
    "just-calculate": {
      "command": "/path/to/just-calculate-mcp/target/release/just-calculate-mcp"
    }
  }
}

The server speaks JSON-RPC 2.0 over stdio. On connect, the client will see toggle and act, and can read calc://guide to discover the rest.

Smoke test from the shell

The act proxy reaches any tool in one shot without toggling:

printf '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}\n{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"act","arguments":{"tool":"simple_arithmetic","args":{"number_a":10,"number_b":3,"operator":"/"}}}}\n' \
  | ./target/release/just-calculate-mcp
# → 10 / 3 = 3.3333333333333335

The catalog

45 tools across 17 categories. Read calc://guide at runtime for the live list and per-tool argument shapes.

DomainTools
arithmeticsimple_arithmetic, rounding, number_properties
powerspower_root, exponential
logarithmlogarithm
trigonometrytrigonometry, trigonometry_2arg, hyperbolic, angle_convert
statisticsdescriptive_stats, percentile, correlation, linear_regression
combinatoricscombinatorics
number_theorynumber_theory, modular_arithmetic
financepresent_future_value, interest_rate, loan, investment_return, depreciation, business_math
geometryarea_2d, perimeter_2d, volume_3d, surface_area_3d, distance_2d, coordinate_convert
programmerbase_convert, bitwise_ops, number_repr
unit_convertunit_convert
engineeringcomplex_number, electrical, decibel, interpolation
linear_algebravector_ops, matrix_ops
calculuspolynomial_calc, numerical_methods
probabilitydistribution, odds_convert
special_functionsspecial_functions
constantsmath_constant

How it's built

src/
├── main.rs           — wires Calculator to the stdio transport
├── server.rs         — Calculator struct, the #[tool_router] block, the
│                       hand-written ServerHandler, and the toggle/act gating
└── tools/
    ├── registry.rs   — category → tool-name map; the single source of truth
    │                   that drives both `toggle` and the calc://guide resource
    ├── shared.rs     — small shared helpers (gcd, lcm, factorial, …)
    └── <category>.rs — pure math logic + input struct, one file per domain

The split is deliberate: tools/ is pure logic with no MCP types, and server.rs is all the MCP wiring. The gating layer holds two routers — a toggleable visible set (everything hidden at startup except the two meta-tools) and a full set used only by act — both generated from the same #[tool_router] macro, so there's no second dispatch table to keep in sync.

Built on rmcp v1.7. The gating uses rmcp's native disable_route / enable_route and list_changed notifications — it's standard MCP, not a hack.

See CLAUDE.md for the full architecture notes and the steps to add a new math category.


Development

cargo test     # unit tests + an in-memory client/server integration test
cargo build    # verify it compiles

Adding a tool is four small steps — write the pure logic in tools/<category>.rs, add a #[tool] method in server.rs, register its name in tools/registry.rs (so toggle and the guide can see it), and add tests. Details in CLAUDE.md.


License

Copyright 2026 Pavan Singh Gill. Licensed under the Apache License, Version 2.0.

Ver o original no GitHub

Bom para

Relacionados