tax-ledger (Autonomous MVP build)

Rust workspace for a local-first, Excel-first tax ledger system.

Agent Guide

See AGENTS.md for agent-facing purpose, capability boundaries, operating expectations, and persistent session-learning rules. See docs/mcp-capability-contract.md for the concrete MCP tool matrix, API relationships, and contrived end-to-end usage.

Current scope

• Contract-first filename preflight (VENDOR--ACCOUNT--YYYY-MM--DOCTYPE)
• Session manifest parsing and account listing
• Workbook initialization with required sheet names
• Git-friendly plain-text ingest output via Beancount journal entries (rustledger-compatible)
• Idiomatic turbo MCP interface surface for list_accounts and ingest_statement_rows

Prerequisites

Tool	Install	Purpose
Rust 1.88+	curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh	Build toolchain
just	cargo install just	Task runner (all just * recipes)
cocogitto	cargo install cocogitto	Conventional commits + version bumps
cross	cargo install cross --locked	Cross-compilation for musl/macOS release bundles
mcp-publisher	See registry releases	MCP Registry submission (just publish-registry)

Optional: Docker or Podman for container builds.

Quickstart

# Run the full test suite
cargo test --workspace --all-features

# Or via just (also runs mcp-outcome-test)
just test

# Start the MCP server (stdio transport)
just mcp-start

Install in Claude Code

Windows (PowerShell)

Invoke-WebRequest "https://github.com/PromptExecution/l3dg3rr/releases/latest/download/ledgerr-mcp-x86_64-pc-windows-msvc.mcpb" -OutFile "$env:TEMP\ledgerr-mcp.mcpb"
claude mcp add ledgerr "$env:TEMP\ledgerr-mcp.mcpb"

macOS (Apple Silicon)

curl -fsSL "https://github.com/PromptExecution/l3dg3rr/releases/latest/download/ledgerr-mcp-aarch64-apple-darwin.mcpb" -o /tmp/ledgerr-mcp.mcpb
claude mcp add ledgerr /tmp/ledgerr-mcp.mcpb

macOS (Intel) / Linux

# Intel Mac
curl -fsSL "https://github.com/PromptExecution/l3dg3rr/releases/latest/download/ledgerr-mcp-x86_64-apple-darwin.mcpb" -o /tmp/ledgerr-mcp.mcpb
# Linux x86_64
curl -fsSL "https://github.com/PromptExecution/l3dg3rr/releases/latest/download/ledgerr-mcp-x86_64-unknown-linux-musl.mcpb" -o /tmp/ledgerr-mcp.mcpb

claude mcp add ledgerr /tmp/ledgerr-mcp.mcpb

After adding, restart Claude Code. The l3dg3rr_* tools will appear automatically.

Docker

The container runs the ledgerr-mcp-server binary (stdio MCP transport). Mount /data for the workbook and PDF inbox.

docker build -t tax-ledger:dev .
docker run --rm -i \
  -v "$PWD/data:/data" \
  tax-ledger:dev

Release

just release           # patch release (default)
just release major   # major release
just release minor  # minor release

# Or trigger via GitHub: Actions > Release > Run workflow

Uses cocogitto for conventional commit versioning. Releases trigger on CI success or manual dispatch.

Behavior-Driven MVP E2E

./scripts/e2e_mvp.sh

This validates the full ingest -> classify -> audit -> schedule summary flow.

Claude Cowork Plugin Marketplace

• Approach and operator workflow: docs/claude-cowork-plugin-marketplace.md
• Marketplace catalog: .claude-plugin/marketplace.json
• MCP runtime helpers: Justfile (just mcp-start, just mcp-stop, just mcp-e2e)

CI/CD Publish Targets

• Workflow: .github/workflows/publish.yml
• Trigger: GitHub Release published (or manual workflow_dispatch)
• Targets:
  • GHCR image: ghcr.io/promptexecution/l3dg3rr
  • crates.io crates: ledger-core, ledgerr-mcp (requires CRATES_IO_TOKEN)
  • PyPI package: l3dg3rr-mcp-launcher (requires PYPI_API_TOKEN)