Epic: StarkZap Execution Parity (SDK -> MCP -> CLI)

[omarespejel]

PR #21 proved the model: thin MCP wrappers over StarkZap SDK calls with strong validation and write gating.
Now SDK surface has grown, and MCP/CLI are behind.

This epic closes that gap and makes StarkZap the canonical execution surface for both developers and agents.

Current status

• MCP baseline shipped in feat: add MCP server for AI agent integration #21: account, balance, transfer, execute (gated), deploy, staking, estimate-fee.
• Additional hardening/improvements landed in feat: support read-only address queries for balance and staking position #61 (read-only address queries).
• This epic is parity expansion, not a fresh MCP start.
• In review: starkzap_get_balances, starkzap_get_quote, starkzap_swap, starkzap_build_swap_calls in feat(mcp): add swap + batched balances tools with hardening #81.
• In review: starkzap_build_calls in feat(mcp): add hardened starkzap_build_calls tool #83.
• Next MCP slice: lending read tools first, then lending writes after the read path is reviewed and smoke-tested.

Decision boundary

• starkzap owns execution (SDK + MCP + CLI).
• starknet-agentic owns policy/safety and agent-runtime context (session lifecycle, ERC-8004 identity/metadata, attestation/provenance, x402 policy/preflight, plus Cairo coding skills/knowledge packs for agent development workflows).

Scope (parity targets)

P0 MCP parity

• starkzap_get_balances (in review: feat(mcp): add swap + batched balances tools with hardening #81)
• starkzap_get_quote (in review: feat(mcp): add swap + batched balances tools with hardening #81)
• starkzap_swap (in review: feat(mcp): add swap + batched balances tools with hardening #81)
• starkzap_build_swap_calls (in review: feat(mcp): add swap + batched balances tools with hardening #81)
• starkzap_build_calls (in review: feat(mcp): add hardened starkzap_build_calls tool #83)
• starkzap_lending_markets
• starkzap_lending_positions
• starkzap_lending_position
• starkzap_lending_health
• starkzap_lending_max_borrow
• starkzap_lending_quote_health
• starkzap_lending_deposit
• starkzap_lending_withdraw
• starkzap_lending_withdraw_max
• starkzap_lending_borrow
• starkzap_lending_repay

P1 MCP parity

• starkzap_get_allowance
• starkzap_approve_exact
• starkzap_approve_if_needed
• starkzap_revoke_approval
• Bridge tools once bridge SDK module is merged:
  • starkzap_bridge_quote
  • starkzap_bridge_execute
  • starkzap_bridge_status
  • starkzap_bridge_routes

CLI parity (same core, no duplicate logic)

• Add starkzap-cli commands for all P0 MCP tools.
• CLI and MCP must call the same shared action handlers + schemas.
• CLI should follow after the MCP surface stabilizes unless a PR already touches the same shared action layer.

PR slicing policy

• Keep reviewable PRs small.
• MCP read tools can land separately from write tools.
• Write tools require extra review for amount caps, write gating, tx tracking, sponsored mode, and retry/reconciliation behavior.
• Avoid broad CLI/action-layer refactors in the same PR as new state-changing tools unless the refactor is required for safety.

Implementation rules

• No business logic in MCP/CLI adapters.
• Shared action layer: parse/validate -> SDK call -> normalized output.
• MCP tool names must use the starkzap_ namespace prefix to avoid collisions with other MCP servers.
• Keep existing safety rails:
  • --enable-write
  • --enable-execute
  • amount caps
  • batch caps
  • rate limits
  • strict address/token validation
• Read-only tools must still validate provider ids, token ids, addresses, and SDK response shape before returning output to the agent.

Drift prevention (required)

• Add conformance test in CI:
  • execution action manifest -> MCP tool registry (must match)
  • execution action manifest -> CLI commands (must match)

Migration note

• During migration window, starknet-agentic can keep compatibility aliases for moved execution tools.
• New execution capability should land in StarkZap first.

Acceptance criteria

• All P0 tools implemented in MCP with tests.
• Matching CLI commands implemented with tests.
• Conformance test active in CI and failing on parity drift.
• README/docs updated with tool/command matrix and examples.
• No breaking changes to existing MCP tool names in starkzap-mcp.

[ahmetenesdur]

Hey @omarespejel

We've been building StarkFi on top of Starkzap SDK — a CLI + MCP server + Agent Skills toolkit for Starknet DeFi. The execution parity model described here is very close to what we've shipped, so it might be useful as a reference.

P0 mapping

StarkFi wraps Starkzap SDK through a shared service layer, then exposes that as both MCP tools and CLI commands.

This Epic	StarkFi MCP Tool	Notes
starkzap_get_balances	get_balance, get_portfolio	Includes USD valuations
starkzap_get_quote	get_swap_quote, get_multi_swap_quote	Fibrous, AVNU, Ekubo
starkzap_swap	swap_tokens, multi_swap	Single + multi-pair
starkzap_build_swap_calls	Part of batch_execute	⚠️ Builds + executes atomically; no standalone "build only" tool
starkzap_build_calls	Part of batch_execute	⚠️ Same — could be split out if needed
starkzap_lending_markets	list_lending_pools	Vesu V2 with APY rates
starkzap_lending_deposit	supply_assets
starkzap_lending_withdraw	withdraw_assets
starkzap_lending_withdraw_max	close_position	Atomic repay + withdraw
starkzap_lending_borrow	borrow_assets	Supports --use-supplied for existing earn positions
starkzap_lending_repay	repay_debt
starkzap_lending_position	get_lending_position
starkzap_lending_health	monitor_lending_position	4-level risk: SAFE / WARNING / DANGER / CRITICAL
starkzap_lending_quote_health	lending_quote_health	"What-if" health simulation

12/14 are direct matches. build_swap_calls and build_calls are merged into batch_execute — we opted for atomic build-and-execute rather than exposing raw Call[] arrays as a separate tool.

Additional surface on Starkzap SDK

Beyond P0, StarkFi ships 42 MCP tools and 42+ CLI commands total:

• Staking (8 tools) — stake, unstake, claim, compound across STRK, WBTC, tBTC, SolvBTC, LBTC
• DCA (4 tools) — recurring buy orders via AVNU / Ekubo
• Confidential Transfers (7 tools) — ZK-based private transfers via Tongo Cash
• Lending extras — auto-rebalance unhealthy positions, health simulation
• Portfolio — rebalancing to target allocations via batch swaps
• Gas abstraction — gasless (ERC-20 payment) and gasfree (developer-sponsored) via AVNU Paymaster
• 12 Agent Skills — npx skills add ahmetenesdur/starkfi
• Telegram Bot — BYOAI (OpenAI / Claude / Gemini)

Architecture

Starkzap SDK  →  Service Layer (shared)  →  MCP Tools (42) + CLI Commands (42+)

No business logic in MCP or CLI adapters. All transactional tools support --simulate for dry-run.

Links

• starkfi.app · npm · docs · MCP Tools · Agent Skills · MCP.md

Happy to collaborate — especially on the conformance test idea (we've hit parity drift ourselves). The P1 bridge tools are on our radar too; the bridge module already exists in Starkzap SDK, we just haven't wrapped it on the StarkFi side yet.