eggsact 1.2.7

Deterministic MCP and in-process utility tools for coding agents
Documentation

eggsact

Crates.io Downloads License: MIT

Deterministic MCP and in-process utility tools for coding agents. 86 tools across 23 categories: math, text, JSON, regex, path, shell, config, patch, dependency, analysis, network, encoding, temporal, and more. Includes a natural language math evaluator that parses expressions like "thirty plus five" or "30m + 100ft".

Installation

The latest release is v1.2.6. The verified binary installer is the recommended path for supported hosts:

curl --proto '=https' --tlsv1.2 -fsSL \
  https://github.com/eggstack/eggsact/releases/latest/download/install.sh \
  | bash -s -- --version 1.2.6

On Windows, run the published PowerShell installer:

irm https://github.com/eggstack/eggsact/releases/latest/download/install.ps1 | iex

Pin the Windows installer with -Version 1.2.6. Both installers verify the downloaded binary's checksum and reported version. Cargo remains available as the fallback for unsupported hosts and source builds:

cargo install eggsact

See Installation for the target matrix, fallback, and validation contract.

Maintainers can reproduce the release-mode performance evidence matrix with cargo bench --locked --bench performance; it is non-gating and intended for same-host baseline/candidate comparisons. See Performance for the measured contracts and hot-path invariants.

Or from source:

git clone https://github.com/eggstack/eggsact
cd eggsact
cargo install --path .

Minimum Rust version: 1.89.0.

Quick Start

CLI

# Natural language
eggsact "thirty plus five"            # 35

# Standard math
eggsact "2 ** 10"                     # 1024

# Unit conversions
eggsact "30m to ft"                   # 98.425...

# MCP server mode (stdio JSON-RPC, connection-pinned dual-era: 2026-07-28 + 2025-11-25/2024-11-05 legacy; one process serves one era)
eggsact --mcp
# Low-context discovery surface (pinned front doors + tool_search/tool_invoke)
eggsact --mcp --mcp-surface discovery

Each stdio process is pinned to one protocol era by its first classifiable message: an enveloped modern claim selects 2026-07-28; initialize or any claim-less opening selects the legacy path. The official SDK's automatic modern probe is enveloped and runs in a disposable sibling process. A claim-less server/discover is therefore legacy traffic, not an era-neutral probe. Cross-era requests return -32022 Unsupported protocol version, while mismatched notifications are dropped before side effects.

Discovery is an explicit low-context presentation option, not a capability reduction: full/Model direct definitions are 77 tools / 111,911 serialized bytes, while discovery advertises 7 / 6,088 bytes (5.44%). Deterministic retrieval and policy-containment gates live in tests/mcp/test_discovery.rs (76 stable Model tools at 100% semantic coverage with 88 task intents, top-1 >=90% / top-3 >=98% / top-5 100%, zero Model-audience leaks; 48 Model task scenarios plus 4 containment cases). Paired provider/client traces can be scored offline with scripts/score-discovery-traces.py --pair direct.json discovery.json (plural expected_tools contract, 2pp noninferiority gates); see tests/fixtures/discovery_traces/README.md. External OpenAI/Anthropic evidence is still pending, so generated integrations stay on direct while discovery remains explicitly selectable.

MCP client setup

Render a read-only, absolute-path registration instruction for a client-owned stdio process:

eggsact integrate list
eggsact integrate detect
eggsact integrate codex    # zed, claude, cursor, vscode, or opencode

Update an installed binary with eggsact update. It verifies the crates.io stable version, GitHub asset checksum, and candidate --version before replacement. The updater is self-contained (in-process HTTP/1 + TLS via eggfetch-core; no external curl required after install). Bootstrap installers still use curl/PowerShell because they run before Eggsact exists. Existing MCP sessions continue until their owning client reconnects. Eggsact does not install a daemon or edit client configuration.

Library

use eggsact::{run, evaluate};

// Natural language
let (result, _typ) = run("thirty plus five").unwrap();
assert_eq!(result, "35");

// Direct math
let (result, _typ) = evaluate("2 ** 10").unwrap();
assert_eq!(result, "1024");

In-Process Agent API

use eggsact::agent::{ToolRegistry, ExecutionContext, Profile, ToolAudience};

let registry = ToolRegistry::default();
let ctx = ExecutionContext::agent_default(Profile::Full, ToolAudience::Model);
let response = registry.call_json_with_execution_context(
    "math_eval",
    serde_json::json!({"expression": "2 + 3"}),
    &ctx,
).unwrap();
assert!(response.ok);

Typed Preflight Wrappers

use eggsact::preflight::{DependencyPreflight, DependencyPreflightInput};

let input = DependencyPreflightInput {
    file_path: "Cargo.toml".to_string(),
    old_text: "[dependencies]\n".to_string(),
    new_text: "[dependencies]\nserde = \"1\"\n".to_string(),
    ..Default::default()
};
let output = DependencyPreflight::run(&input).unwrap();
assert!(!output.machine_code.is_empty());

For new Rust integrations prefer calc/root functions, then typed text primitives, then ToolRegistry, then typed preflight wrappers — raw tools::* handlers are adapter internals kept pub for 1.x compatibility. See docs/library-api.md for the full hierarchy.

Supported Platforms

Tier Platform Status
1 Ubuntu latest (x86_64) Full CI gate
2 Windows latest (x86_64) Compile check
2 macOS latest (ARM64) Compile check

Documentation

Topic Link
CLI usage docs/cli.md
Installation, updates, and client setup docs/installation.md
Library API docs/library-api.md
MCP tool reference (86 tools) docs/mcp-tools.md
Math features, functions, constants, units docs/math-features.md
Architecture overview architecture/overview.md
Calculator core architecture/calculator.md
MCP server internals architecture/mcp-server.md
Agent API deep dive architecture/agent-api.md
Preflight wrappers architecture/preflight.md
Machine codes architecture/machine-codes.md
Profiles and audiences architecture/registry-profiles.md
Text processing library architecture/text-library.md
Budget and concurrency architecture/budget-concurrency.md
Performance evidence architecture/performance.md
Compatibility policy docs/compatibility-policy.md
Verification doctrine docs/verification.md
Testing patterns architecture/testing.md
Contributing docs/contributing.md
Fuzzing docs/fuzzing.md
Release process docs/release.md

Key Gotchas

  • ^ is XOR, not exponentiation. Use ** for power. Matches Python.
  • g means gram in unit expressions. Use gravity for standard gravity.
  • serde_json uses preserve_order — key order is intentional in serialized JSON.
  • Network, encoding, datetime, and cron utilities are deterministic and use no system/network state; temporal conversions accept fixed offsets only. IPv6 CIDR counts are exact decimal powers of two, mapped-IPv6 metadata is limited to ::ffff:0:0/96, and cron DOM/DOW matching follows Vixie/Cronie star syntax (either field starting with *, including */n steps, requires both fields to match; otherwise either may match; explicit full ranges are not star syntax).

Relationship to Python eggcalc

eggsact is a Rust reimplementation of the Python eggcalc project. The two projects are functionally equivalent for core math, unit conversion, and text processing operations. See docs/parity.md for known differences.

License

MIT -- see LICENSE for details.