eggsact
Deterministic MCP and in-process utility tools for coding agents. 80 tools across 20 categories: math, text, JSON, regex, path, shell, config, patch, dependency, analysis, and more. Includes a natural language math evaluator that parses expressions like "thirty plus five" or "30m + 100ft".
Supported Platforms
| Tier | Platform | Status |
|---|---|---|
| 1 | Ubuntu latest (x86_64) | Full CI gate (fmt, clippy, tests) |
| 2 | Windows latest (x86_64) | Compile check (scheduled) |
| 2 | macOS latest (ARM64) | Compile check (scheduled) |
MSRV: Rust 1.89.0 (declared in Cargo.toml, tested weekly in scheduled CI).
Key Features
- MCP server with 80 registered tools for AI agents to reduce hallucinations
- In-process agent API for direct tool calls without MCP overhead
- Typed preflight wrappers for edit, command, config, and patch workflows
- Natural language math: "two to the power of ten" evaluates to 1024
- Unit conversions: "30m to ft", "100C in F"
- Physical and mathematical constants:
pi,c,planck,avogadro,gravity - High-performance Rust implementation with zero required external services
- 12 fuzz targets via cargo-fuzz covering parser-heavy surfaces
- 55 property tests verifying round-trip, idempotence, determinism, and symmetry invariants
Installation
From crates.io
From source
Minimum Rust version: 1.89.0. Earlier versions may compile the library but fail tests due to temporary lifetime rules in test code.
Quick Start
CLI
# Natural language
# 35
# Standard math
# 11
# Unit conversions
# 98.4251968503937
# Power
# 1024
# Help and version
# Diagnostics (text output)
# Diagnostics (JSON output)
# MCP server mode (stdio JSON-RPC)
Library
use ;
// Natural language — returns (result, type)
let = run.unwrap;
assert_eq!;
// Direct math evaluation
let = evaluate.unwrap;
assert_eq!;
// Unit conversion
let = run.unwrap;
// result ≈ "98.42519685039369 ft"
MCP Server
Start the server and connect via JSON-RPC 2.0 over stdio. The server supports MCP protocol versions 2025-11-25 (preferred) and 2024-11-05 (legacy).
Lifecycle: Clients must complete the initialization handshake before calling tools:
→
←
→
→
←
The server dispatches requests concurrently. Responses may arrive out of request order. Clients must correlate responses to requests by JSON-RPC id, not by arrival position. See architecture/mcp-server.md for the full concurrency and response-ordering contract.
Response Contract
Every MCP tool response includes a machine_code field (when non-OK) for programmatic routing and classification. Machine codes are defined in src/mcp/machine_codes.rs. See architecture/machine-codes.md for the full code table and finding helpers.
MCP Tools
80 tools across 20 categories. See architecture/mcp-server.md for the full reference.
Math (4)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
math_eval |
0 | default | stable | mod | default, full, human_math |
unit_convert |
2 | contextual | stable | cheap | full, human_math |
unit_info |
2 | contextual | stable | cheap | full, human_math |
constant_lookup |
2 | contextual | stable | cheap | full, human_math |
Text (18)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
text_measure |
0 | default | stable | cheap | default, full |
text_equal |
0 | default | stable | cheap | codegg_core, default, full |
text_diff_explain |
1 | default | stable | mod | codegg_core, codegg_patch, default, full |
text_inspect |
1 | default | stable | mod | codegg_core, codegg_unicode_security, default, full |
text_count |
0 | default | stable | cheap | default, full |
text_truncate |
3 | expert | stable | cheap | full |
text_transform |
2 | contextual | stable | mod | codegg_unicode_security, full |
text_position |
2 | contextual | stable | cheap | codegg_unicode_security, full |
text_hash |
2 | contextual | stable | mod | full |
escape_text |
1 | default | stable | cheap | default, full |
unescape_text |
1 | default | stable | cheap | default, full |
text_window |
1 | default | stable | cheap | default, full |
text_fingerprint |
0 | default | stable | cheap | codegg_core, codegg_repo_audit, default, full |
text_replace_check |
1 | default | stable | cheap | codegg_core, codegg_core_min, codegg_patch, default, full |
line_range_extract |
1 | default | stable | cheap | codegg_patch, default, full |
line_range_compare |
2 | contextual | stable | mod | codegg_patch, full |
prompt_input_inspect |
2 | harness | stable | mod | codegg_preflight, codegg_unicode_security, full |
text_security_inspect |
1 | default | stable | heavy | codegg_core, codegg_core_min, codegg_preflight, codegg_unicode_security, full |
Json (6)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
json_extract |
2 | contextual | stable | mod | codegg_config, full |
json_compare |
1 | default | stable | mod | codegg_config, default, full |
json_shape |
3 | expert | stable | mod | codegg_repo_audit, full |
json_canonicalize |
1 | default | stable | mod | codegg_config, default, full |
json_query |
1 | contextual | deprecated | mod | full |
structured_data_compare |
2 | contextual | stable | heavy | codegg_config, codegg_core, full |
Regex (3)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
validate_regex |
1 | default | stable | mod | default, full |
regex_finditer |
1 | default | stable | mod | default, full |
regex_safety_check |
1 | default | stable | cheap | codegg_shell, default, full |
Validation (4)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
validate_brackets |
1 | default | stable | cheap | default, full |
validate_json |
0 | default | stable | cheap | codegg_config, codegg_core, codegg_core_min, default, full |
validate_toml |
1 | default | stable | cheap | codegg_config, codegg_core, default, full |
validate_schema_light |
3 | contextual | stable | mod | codegg_config, full |
List (3)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
list_compare |
2 | contextual | stable | mod | full |
list_dedupe |
1 | default | stable | cheap | default, full |
list_sort |
1 | default | stable | cheap | default, full |
Path (6)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
path_normalize |
0 | default | stable | cheap | codegg_core, default, full |
path_analyze |
2 | contextual | stable | cheap | full |
path_compare |
2 | contextual | stable | cheap | full |
path_scope_check |
2 | harness | stable | cheap | codegg_preflight, full |
glob_match |
1 | default | stable | cheap | default, full |
path_batch_scope_check |
2 | harness | stable | cheap | codegg_patch, codegg_preflight, full |
Shell (4)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
shell_split |
2 | harness | stable | cheap | codegg_preflight, codegg_shell, full |
shell_quote_join |
2 | contextual | stable | cheap | codegg_shell, full |
argv_compare |
2 | contextual | stable | cheap | codegg_shell, full |
command_preflight |
1 | default | stable | heavy | codegg_core, codegg_core_min, codegg_preflight, codegg_shell, full |
Markdown (2)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
markdown_structure |
2 | contextual | stable | mod | codegg_repo_audit, full |
code_fence_extract |
2 | contextual | stable | mod | codegg_repo_audit, full |
Config (3)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
dotenv_validate |
2 | contextual | stable | cheap | codegg_config, full |
ini_validate |
2 | contextual | stable | cheap | codegg_config, full |
config_preflight |
1 | default | stable | heavy | codegg_config, codegg_core, codegg_core_min, codegg_preflight, full |
Identifier (3)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
identifier_analyze |
3 | expert | stable | mod | full |
identifier_inspect |
1 | default | stable | mod | codegg_core, codegg_unicode_security, default, full |
identifier_table_inspect |
3 | expert | stable | mod | codegg_repo_audit, full |
Unicode (2)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
unicode_policy_check |
2 | harness | stable | mod | codegg_preflight, codegg_unicode_security, full |
canonicalize_text |
2 | contextual | stable | mod | codegg_unicode_security, full |
Version (2)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
version_compare |
2 | contextual | stable | cheap | codegg_config, full |
version_constraint_check |
3 | expert | stable | cheap | full |
Toml (1)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
toml_shape |
2 | contextual | stable | mod | codegg_config, full |
Patch (5)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
patch_apply_check |
2 | harness | stable | mod | codegg_patch, codegg_preflight, full |
patch_summary |
2 | contextual | stable | mod | codegg_patch, full |
edit_preflight |
1 | default | stable | heavy | codegg_core, codegg_core_min, codegg_patch, codegg_preflight, full |
patch_contract_check |
2 | contextual | stable | mod | codegg_patch, codegg_preflight, codegg_repo_audit, full |
diff_risk_classify |
2 | contextual | stable | mod | codegg_patch, codegg_repo_audit, full |
Cargo (1)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
cargo_toml_inspect |
3 | expert | stable | mod | codegg_core, codegg_repo_audit, full |
Dependency (1)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
dependency_edit_preflight |
2 | contextual | stable | mod | codegg_config, codegg_preflight, codegg_repo_audit, full |
Repo (5)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
repo_manifest_inspect |
2 | contextual | stable | cheap | codegg_repo_audit, full |
config_file_inspect |
2 | contextual | stable | mod | codegg_config, codegg_repo_audit, full |
test_command_suggest |
2 | contextual | stable | cheap | codegg_core, codegg_repo_audit, codegg_shell, full |
repo_language_detect |
2 | contextual | stable | cheap | codegg_core, codegg_repo_audit, full |
repo_tree_summarize |
2 | contextual | stable | mod | codegg_repo_audit, full |
Analysis (4)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
import_export_inspect |
2 | contextual | stable | cheap | codegg_core, codegg_repo_audit, full |
code_block_map |
2 | contextual | stable | cheap | codegg_core, codegg_repo_audit, full |
symbol_name_diff |
2 | contextual | stable | cheap | codegg_patch, codegg_repo_audit, full |
lockfile_inspect |
2 | contextual | stable | mod | codegg_patch, codegg_preflight, codegg_repo_audit, full |
Diagnostics (3)
| Tool | Tier | Exposure | Stability | Cost | Profiles |
|---|---|---|---|---|---|
runtime_diagnostics |
3 | harness | stable | cheap | full |
profile_inspect |
3 | harness | stable | cheap | full |
tool_availability_explain |
3 | harness | stable | cheap | full |
Math Features
Operations
- Basic arithmetic:
+,-,*,/,% - Power:
**,^(e.g.,2 ** 10= 1024) - Parentheses for grouping
Functions
- Trigonometric:
sin,cos,tan,asin,acos,atan,sinh,cosh,tanh - Logarithmic:
log,ln,log10,log2,exp - Other:
sqrt,cbrt,abs,floor,ceil,round,trunc,sign,factorial
Constants
- Mathematical:
pi,e,tau,phi - Physical:
c,h,hbar,k,G,na,R,qe,me,mp,mn,epsilon0,mu0,gravity,atm
g is parsed as the gram unit in unit expressions. Use gravity or standardgravity for standard gravity.
Statistical
sum,mean/average,median,std/stddev,variance,min,max,product
Number Theory
gcd,lcm,factorial
Units
| Category | Units |
|---|---|
| Length | m, km, cm, mm, in, ft, yd, mi, ly, au, pc |
| Mass | kg, g, mg, ug, ng, lb, oz, ton, stone |
| Time | s, ms, us, ns, min, h, d, wk, yr |
| Volume | L, mL, gal, qt, pt, cup, floz, tbsp, tsp |
| Temperature | C, F, K |
| Data | B, KB, MB, GB, TB |
| Pressure | Pa, kPa, MPa, GPa, bar, atm, psi |
| Energy | J, kJ, cal, kcal, Wh, kWh, BTU, eV |
| Power | W, kW, MW, GW, hp |
| Force | N, kN, dyne, lbf |
| Voltage | V, kV, mV |
| Current | A, mA |
| Angle | rad, deg |
| Speed | m/s, km/h, mph, kn, mach |
| Frequency | Hz, kHz, MHz, GHz, THz |
Temperature conversions use offset math, not multiplicative factors. Prefixed units like kN, mV, mA are supported.
Library API
run
Evaluate a natural language or unit-expression string. Handles NL parsing, normalization, and unit conversion.
use run;
let = run.unwrap;
assert_eq!;
assert_eq!;
let = run.unwrap;
// result ≈ "60.480000000000004 m", typ = "float"
let = run.unwrap;
assert_eq!;
evaluate
Evaluate a direct math expression. Expects valid Python/Rust syntax (no natural language).
use evaluate;
let = evaluate.unwrap;
assert_eq!;
let = evaluate.unwrap;
assert_eq!;
split_at_operators
Split a math expression string at operator boundaries.
use split_at_operators;
let tokens = split_at_operators;
assert_eq!;
When to use which
| Input type | Use |
|---|---|
"five plus three" |
run() |
"30m + 100ft" |
run() |
"5 + 3" |
evaluate() or run() |
"sqrt(144)" |
evaluate() or run() |
"1km in m" |
run() only |
In-Process Agent API
Call eggsact tools directly from Rust without starting an MCP server. The ToolRegistry provides a typed, synchronous API with profile filtering, argument validation, and tool execution.
Calling tools by name
use ;
let registry = default;
// Simple call
let response = registry.call_json.unwrap;
assert!;
// Context-aware call (recommended for new code — immutable, clones eval_ctx)
let ctx = agent_default;
let response = registry.call_json_with_execution_context.unwrap;
assert!;
Profile selection
Profiles control which subset of tools is available. Profile::from_str_opt is
strict — it returns None for unknown names. Use Profile::custom(name) for
custom profiles.
use ;
// Model-facing codegg session
let registry = with_profile_and_audience;
let tools = registry.available_tools_model_safe;
assert!;
// Harness preflight checks
let harness_registry = with_profile_and_audience;
Audience is enforced at dispatch time: call_json rejects harness-only tools
when the registry uses Model audience, and rejects hidden tools for all audiences.
Typed preflight wrappers
For common workflows, use the typed wrappers in eggsact::preflight:
use ;
let input = ConfigPreflightInput ;
let output = run.unwrap;
assert!;
assert!;
Available preflight wrappers: EditPreflight, CommandPreflight, ConfigPreflight,
PatchApplyCheck, TextSecurityInspect.
All wrappers return Result<Output, PreflightError> where PreflightError
distinguishes three failure modes:
ToolCall— registry rejected the call before executionToolRejected— tool executed but returnedok: falseContractViolation— tool returnedok: truebut response shape violated the typed contract (missing mandatory field)
Missing mandatory fields are hard failures — wrappers will not silently
default machine_code, verdict, or other route-critical fields.
Architecture
eggsact/
├── src/
│ ├── main.rs # CLI entry point, argument parsing
│ ├── lib.rs # Public API exports
│ ├── calc/ # Calculator core
│ │ ├── mod.rs # Module re-exports
│ │ ├── normalize.rs # Natural language tokenization, number words
│ │ ├── evaluator.rs # AST-based expression evaluation
│ │ └── units.rs # Unit definitions and conversion factors
│ ├── mcp/ # MCP server
│ │ ├── mod.rs # Module re-exports
│ │ ├── server.rs # stdio JSON-RPC 2.0 server, protocol orchestration
│ │ ├── registry/ # Tool registration (ToolSpec declarations, single source of truth)
│ │ │ ├── mod.rs # Re-exports, tests
│ │ │ ├── types.rs # ToolDefinition, ToolSpec, enums
│ │ │ ├── all_tools.rs # ALL_TOOLS constant, PROFILE_NAMES
│ │ │ └── listing.rs # Filtering, audience, schema compaction, suggestions
│ │ ├── protocol.rs # JSON-RPC types (Request, Response, Error, InitializeResult)
│ │ ├── response.rs # ToolResponse, error sanitization, finding() helpers, with_verdict, preflight builders
│ │ ├── runtime.rs # Rate limiter, active request tracking, constants, profile management
│ │ ├── schema_validation.rs # MCP argument validation against tool schemas
│ │ └── schemas/ # JSON-schema builders per tool category
│ │ ├── mod.rs # Module declarations + re-exports
│ │ └── ... # One submodule per tool category
│ ├── tools/ # MCP tool implementations (by category)
│ │ ├── mod.rs # Module re-exports
│ │ ├── helpers.rs # Shared constants, utilities, helper functions
│ │ ├── math.rs # math_eval, unit_convert, unit_info, constant_lookup
│ │ ├── text.rs # text_measure, text_equal, text_diff_explain, etc. (18 tools)
│ │ ├── json.rs # json_extract, json_compare, json_canonicalize, etc. (6 tools)
│ │ ├── regex.rs # validate_regex, regex_safety_check, regex_finditer
│ │ ├── validation.rs # validate_json, validate_brackets, validate_toml, validate_schema_light
│ │ ├── path.rs # path_normalize, path_analyze, path_compare, glob_match, path_batch_scope_check
│ │ ├── shell.rs # shell_split, shell_quote_join, argv_compare, command_preflight
│ │ ├── list.rs # list_compare, list_dedupe, list_sort
│ │ ├── markdown.rs # markdown_structure, code_fence_extract
│ │ ├── patch.rs # patch_apply_check, patch_summary, edit_preflight, diff_risk_classify, patch_contract_check
│ │ ├── config.rs # dotenv_validate, ini_validate, config_preflight, toml_shape_tool
│ │ ├── identifier.rs # identifier_analyze, identifier_inspect, identifier_table_inspect
│ │ ├── unicode.rs # unicode_policy_check, canonicalize_text
│ │ ├── version.rs # version_compare, version_constraint_check
│ │ ├── cargo.rs # cargo_toml_inspect
│ │ ├── dependency.rs # dependency_edit_preflight
│ │ ├── diagnostics.rs # runtime_diagnostics, profile_inspect, tool_availability_explain
│ │ └── repo.rs # repo_manifest_inspect, config_file_inspect, repo_tree_summarize, test_command_suggest, repo_language_detect
│ └── text/ # Text processing library (25 modules)
│ ├── mod.rs # Module re-exports
│ ├── primitives.rs # UTF-8 encoding, codepoint iteration
│ ├── confusables.rs # Unicode confusable character lookup
│ ├── diff.rs # String diffing, Levenshtein distance
│ ├── measure.rs # Text metrics (words, lines, bytes)
│ ├── validate.rs # Bracket, JSON, regex validation
│ ├── transform.rs # Text transforms, hashing, fingerprinting
│ ├── position.rs # Byte/line/column position conversion
│ ├── regex_safety.rs # ReDoS detection
│ ├── replace.rs # Text replacement with preview
│ ├── path.rs # Path analysis and normalization
│ ├── identifier.rs # Identifier naming classification
│ ├── shell.rs # Shell command parsing and quoting
│ ├── markdown.rs # Markdown structure analysis
│ ├── glob.rs # Glob pattern matching
│ ├── config.rs # .env and INI validation
│ ├── toml.rs # TOML validation and shape analysis
│ ├── patch.rs # Unified diff parsing and application
│ ├── line_range.rs # Line range extraction and comparison
│ ├── unicode_policy.rs # Unicode safety policies
│ ├── unicode_tools.rs # Mixed-script, invisible char detection
│ ├── inspect_prompt.rs # Prompt injection detection
│ ├── synthesis.rs # Composite tool orchestration
│ ├── cargo.rs # Cargo.toml inspection
│ ├── version.rs # Semver constraint checking
│ └── confusables_generated.rs # Generated confusables data (data file)
├── tests/ # Integration and unit tests (70+ files)
├── fuzz/ # Fuzz targets and corpus (cargo-fuzz + libFuzzer)
├── docs/ # Detailed documentation
├── architecture/ # Architecture documentation (15 files)
├── .opencode/skills/ # Agent task skills (5 skills)
├── .agents/skills/ # Agent task skills (symlinks to .opencode/skills/)
├── Cargo.toml
└── README.md
Development
Build
Test
Run
# Single expression
# MCP server mode
Generated Unicode data
Confusable mappings are checked into the repository as generated static data.
Maintainers regenerate them from the pinned Unicode Security 17.0.0 source
(https://www.unicode.org/Public/17.0.0/security/confusables.txt); the script
verifies the source checksum and header before writing. Builds, CI, and the
local release gate use the checked-in data and do not download Unicode data.
Relationship to Python eggcalc
eggsact is a Rust reimplementation of the Python eggcalc project. The Python version uses AST parsing of expressions and a plugin-based MCP server. eggsact reimplements the same normalization pipeline, evaluation engine, and all MCP tools in Rust for higher performance and easier distribution as a single binary.
The two projects are functionally equivalent for core math, unit conversion, and text processing operations.
License
MIT -- see LICENSE for details.