- Rust toolchain (stable, minimum 1.89.0) --
rustupis recommended for installation. - Python 3.x -- required for parity tests only. Install
eggcalcdependencies from the repo root.
Verify your setup:
rustc --version
python --version
cargo --versioncargo build # debug build
cargo build --release # optimized release buildThe debug binary lands in target/debug/eggsact. The parity test suite expects this
path, so run cargo build before running parity tests.
cargo fmt --all -- --check # formatting gate (CI-equivalent)
cargo clippy --locked --all-targets --all-features -- -D warnings
cargo test --locked --all-features -- --skip parity --test-threads=4 # CI-equivalent test run
cargo run --locked --features dev-tools --bin generate-docs -- --check # generated docs freshness
cargo package --locked --verbose # crates.io package verification
cargo test --locked --lib # unit tests within src/ only
cargo test --locked --test lib parity # parity tests against Python
cargo test --locked --doc # doc tests
cargo deny check advisories bans licenses sources # supply-chain auditUnit tests live inside src/ files as #[cfg(test)] modules. Integration and parity
tests live in tests/. The parity test entry point is tests/lib.rs, which declares
the parity module.
eggsact/
src/
main.rs # CLI entry point, argument parsing
lib.rs # Library root, re-exports run()/evaluate()
calc/ # Calculator core (5 files)
mod.rs
evaluator.rs # AST-based expression evaluation
normalize.rs # Natural language normalization
units.rs # Unit definitions and conversion
context.rs # Per-evaluation mutable state (EvalContext)
mcp/ # MCP server protocol, runtime, registry, validation
server.rs # Protocol orchestration, stdio loop, dispatch
compat.rs # CompatibilityMode enum
registry/ # Tool registration (ToolSpec declarations, single source of truth)
mod.rs # Re-exports, tests
types.rs # ToolDefinition, ToolSpec, enums
all_tools.rs # ALL_TOOLS aggregation from specs/
listing.rs # Filtering, audience, schema compaction
specs/ # ToolSpec declarations per tool category
mod.rs # Re-exports all category slices
math.rs # MATH_TOOLS
text.rs # TEXT_TOOLS
... # One file per category
protocol.rs # JSON-RPC types
response.rs # ToolResponse, error sanitization, finding helpers
runtime.rs # Rate limiter, constants, profile management
schema_validation.rs
machine_codes.rs # Machine-readable response codes
budget.rs # Per-tool budgets, composite sub-budgets
schemas/ # JSON-schema builders per tool category
mod.rs
...
tools/ # MCP tool implementations (by category)
helpers.rs # Shared constants, utilities
math.rs # Math & unit tools
text.rs # Text processing tools (18)
json.rs # JSON tools (6)
regex.rs # Regex tools (3)
validation.rs # Validation tools (4)
path.rs # Path tools (6)
shell.rs # Shell tools (4)
list.rs # List tools (3)
markdown.rs # Markdown tools (2)
patch.rs # Patch tools (5)
config.rs # Config tools (3) + TOML shape tool (toml category handler lives here)
identifier.rs # Identifier tools (3)
unicode.rs # Unicode tools (2)
version.rs # Version tools (2)
cargo.rs # Cargo tool (1)
dependency.rs # Dependency tool (1)
diagnostics.rs # Diagnostics tools (3)
repo.rs # Repo tools (5)
analysis.rs # Analysis tools (4)
network.rs # Network literal tools (2)
encoding.rs # Codec and radix tools (2)
temporal.rs # Datetime and cron tools (2)
agent/ # In-process agent API (ToolRegistry, Profile, call_json)
preflight/ # Typed preflight wrappers
services/ # Typed composite services (RepoFacts, PatchAnalysis, SecurityInspection, ...)
temporal/ # Fixed-offset datetime/cron cores (leaf, like text/)
text/ # Text processing library (27 modules)
integrate.rs # Read-only per-client MCP setup renderers
update.rs # Verified binary self-update
tests/
lib.rs # Test entry point
parity/ # Python/Rust comparison tests
mcp/ # MCP protocol tests
calc/ # Calculator tests
text/ # Text processing tests
-
Implement the function in
src/tools/<category>.rs. Follow the existing pattern: take&Value, validate arguments at the boundary, call a library function when one exists, and returnToolResponse. -
Add a
ToolSpecentry insrc/mcp/specs/<category>.rs. This is the single source of truth for tool registration. It defines the handler, category, tier, tags, profiles, input schema, and output schema all in one place. Each category exports apub const <CATEGORY>_TOOLS: &[ToolSpec]slice, whichall_tools.rsaggregates into the combinedALL_TOOLS. -
Run the invariant test to verify sync:
cargo test --locked tool_registration_tables_are_in_sync -- --nocapture -
Regenerate docs from the registry:
cargo run --locked --features dev-tools --bin generate-docs
This updates the profile reference block in
architecture/mcp-server.md, theGenerated Registry Factsblock inarchitecture/overview.md, andgenerated/tool-cards.md.README.mdanddocs/are hand-maintained and not touched. -
Prefer reusable library code under
src/text/orsrc/calc/for business logic. Keepsrc/tools/*.rswrappers thin so the same behavior is testable without going through JSON-RPC. -
Add tests at the right layer:
- Library behavior:
tests/text/ortests/calc/. - MCP request/response behavior:
tests/mcp/. - Python reference compatibility:
tests/parity/usingcompare_tool_parity().
- Library behavior:
-
Add the implementation in the appropriate module under
src/text/. Match the existing code style for that module. -
Re-export from
src/text/mod.rsif the function is part of the public API. Add apub useline and update thepub modlist if you created a new module. -
Add unit tests in the same file as
#[cfg(test)]module, or in a separate file undertests/text/for integration-level coverage. -
Add an MCP tool wrapper if the function should be exposed to MCP clients. Create a thin wrapper in
src/tools/<category>.rsthat parses input, calls your function, and returns the result as aToolResponse. Add aToolSpecentry insrc/mcp/specs/<category>.rsand runcargo run --features dev-tools --bin generate-docsto regenerate docs.
- Use type annotations on all public functions and structs.
- Use
serdefor JSON serialization. DeriveSerializeandDeserializeon data structures. - Follow existing naming conventions: snake_case for functions and variables, PascalCase for types.
- Keep error types consistent with the existing set:
input_too_large,invalid_arguments,evaluation_error, etc. - Prefer
std::collections::HashMapfor hash maps (no external hash-map dependency). - Keep the crate standard-library-plus-minimal-deps. Check
Cargo.tomlbefore adding a new dependency.
The parity suite compares Rust MCP tool output against the Python eggcalc reference.
It requires Python 3.x and eggcalc at ../eggcalc (sibling directory).
cargo test --test lib parityThe Rust catalog contains 86 tools; the Python reference defines 67. The parity suite lists 39 accepted test cases across categories C1-C6, represented by 40 ignored test instances. They cover shell tokenization, prompt inspection, Unicode policy, output shape, tool ordering, and error handling. These are documented differences, not current merge-gate failures. See docs/parity.md for details.
When changing behavior, verify parity tests for the affected tools still pass. If your
change introduces a valid behavioral difference from Python, update the parity test to
accept the new behavior and document the divergence in docs/parity.md.
Before making breaking changes, review docs/compatibility-policy.md for
stability guarantees, deprecation timelines, and what constitutes a breaking
change across the Rust API, MCP tools, input/output schemas, machine codes,
and profiles.
The project uses cargo-deny (configured in deny.toml) for
dependency hygiene:
cargo deny check advisories bans licenses sources # license, advisory, ban, and source checksAllowed licenses (deny.toml): MIT, Apache-2.0, Apache-2.0 WITH LLVM-exception,
Unlicense, Unicode-DFS-2016, Unicode-3.0, Zlib, ISC, BSD-3-Clause,
CDLA-Permissive-2.0. The last three cover the TLS stack behind in-process
self-update (rustls/ring/webpki-roots): all OSI-approved or standard
trust-root-data licenses. All are permissive and compatible with the project's
MIT license.
The canonical release process is documented in docs/release.md. Key points: GitHub CI verifies merge correctness but does not publish; the maintainer runs scripts/release-check.sh locally, publishes manually with cargo publish --locked, and creates the version tag after successful publication. See docs/verification.md for the full verification doctrine.