> For the complete documentation index, see [llms.txt](https://gotts.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://gotts.gitbook.io/docs/gotts-safe-mcp-server/mcp-server/12-milestones.md).

# Milestones and Metrics

> **Package**: `packages/safe/` | **Prerequisites**: [01-overview.md](/docs/gotts-safe-mcp-server/mcp-server/01-overview.md)

***

## Milestones and Phases

### Phase 1: Foundation (Weeks 1-4)

**Goal**: Ship a working MCP server with read-only data tools, basic safety infrastructure, and evaluation framework scaffolding.

**Deliverables**:

* [ ] Project scaffolding as Turborepo workspace package (`packages/safe`)
* [ ] MCP server skeleton with stdio and HTTP transports
* [ ] Chain provider layer (viem PublicClient per chain, configurable RPC)
* [ ] Token resolution (symbol to address, token list integration)
* [ ] **Data tools**: `get_token_price`, `get_pool_info`, `get_pools_by_token_pair`, `get_pools_by_token`, `search_tokens`
* [ ] **Intelligence tools**: `discover_token` (multi-source token discovery with risk scoring)
* [ ] **Utility tools**: `get_supported_chains`, `get_gas_price`
* [ ] x402 outbound client infrastructure (`src/x402/client.ts`, spending tracker)
* [ ] CoinGecko x402 provider setup (`src/providers/coingecko.ts`)
* [ ] Configuration system (env vars + config file, including x402 outbound config)
* [ ] Error handling framework
* [ ] Caching layer (including x402 response caching)
* [ ] Evaluation framework scaffolding (vitest test structure for all tools)
* [ ] Unit tests for all data tools
* [ ] Integration tests against forked mainnet (Anvil)

**Exit criteria**: An LLM connected via MCP can query Uniswap pool data, token prices, and chain info across all 11 chains. Token discovery returns multi-source risk scoring. Evaluation framework is operational.

**Quality gate**: 100% tool unit tests pass, integration test framework operational.

### Phase 2: Trading and Deployment (Weeks 5-8)

**Goal**: Add swap execution with full safety pipeline, trading intelligence, and production deployment infrastructure.

**Deliverables**:

* [ ] Wallet abstraction layer (local key + generic viem Account)
* [ ] Safety middleware pipeline (all 7 layers)
* [ ] **Trading tools**: `get_quote`, `execute_swap`
* [ ] **Intelligence tools**: `assess_mev_risk`, `compare_venues`, `generate_cca_supply_schedule`
* [ ] **Approval tools**: `check_allowance`, `approve_token`, `sign_permit2`
* [ ] **Safety tools**: `simulate_transaction`, `validate_token`, `check_safety_status`
* [ ] **Deployment tool**: `provision_wallet` (programmatic wallet creation via Privy)
* [ ] **Utility tools**: `get_agent_balance`
* [ ] Nonce manager
* [ ] Spending limit tracker
* [ ] Token allowlist (strict mode + Uniswap default list)
* [ ] **Production deployment infrastructure**:
  * [ ] `scripts/setup-production.ts` CLI (interactive setup: wallet creation, .env generation, deployment, health check)
  * [ ] Fly.io deployment template (`fly.toml`) with auto-stop/start and secret injection
  * [ ] Docker production build optimization (multi-stage, minimal runtime image)
  * [ ] Bearer token authentication for Streamable HTTP transport
  * [ ] Pino structured logging with secret redaction rules
  * [ ] Deployment documentation ([14-deployment.md](/docs/gotts-safe-mcp-server/mcp-server/14-deployment.md))
* [ ] Integration tests for full swap pipeline (quote, simulate, execute on Anvil fork)
* [ ] Documentation: setup guide, configuration reference, deployment guide

**Exit criteria**: An agent can execute a swap with full safety checks on a forked mainnet. MEV risk assessment and venue comparison are functional. All safety layers are tested with adversarial inputs (wrong addresses, excessive amounts, duplicate calls). An operator can deploy Gotts Safe to Fly.io in under 10 minutes via `pnpm setup:production`. `provision_wallet` creates wallets programmatically via Privy.

**Quality gate**: Swap pipeline integration test passes on Anvil fork, safety pipeline rejects adversarial inputs, `setup-production.ts` completes end-to-end on a clean machine, `provision_wallet` creates a wallet and returns a valid address.

### Phase 3: Liquidity (Weeks 9-12)

**Goal**: Add LP management for V3 and V4 with IL calculation.

**Deliverables**:

* [ ] **Data tools**: `get_position`, `get_positions_by_owner`, `get_tick_data`, `get_new_pools`, `get_pool_health_score`
* [ ] **Liquidity tools**: `add_liquidity`, `remove_liquidity`, `collect_fees`, `increase_liquidity`, `rebalance_position`
* [ ] **LP Optimization tools**: `optimize_lp_range`, `recommend_fee_tier`, `backtest_lp_strategy`
* [ ] **Intelligence tools**: `calculate_il` (V3 concentrated liquidity IL formula with backtest mode), `simulate_price_impact`
* [ ] **Approval tools**: `batch_permit2`
* [ ] V4 PositionManager integration
* [ ] Range strategy helpers (narrow, medium, wide, full)
* [ ] Integration tests for full LP lifecycle on Anvil fork
* [ ] Documentation: LP management guide

**Exit criteria**: An agent can add liquidity to a V3 pool, monitor the position, collect fees, and rebalance -- all with safety checks. IL calculator validated against known examples. LP optimizer produces Monte Carlo range projections.

**Quality gate**: LP lifecycle integration test passes, IL calculator validated against known examples, LP optimizer backtested against historical data.

### Phase 4: Advanced (Weeks 13-16)

**Goal**: UniswapX, ERC-7683 cross-chain intents, Privy/Safe wallet support, x402 external data tools, and agent revenue tracking.

**Deliverables**:

* [ ] **Trading tools**: `submit_uniswapx_order`, `get_uniswapx_order_status`, `submit_cross_chain_intent`
* [ ] **Intelligence tools**: `get_agent_revenue`
* [ ] **External data tools (x402 -- CoinGecko)**: `get_onchain_token_data`, `get_trending_pools`, `search_coingecko_pools`
* [ ] **External data tools (x402 -- Elsa)**: `get_wallet_portfolio`, `get_wallet_analysis`, `get_wallet_pnl`, `get_yield_opportunities`, `get_elsa_swap_quote`
* [ ] Elsa x402 provider setup (`src/providers/elsa.ts`)
* [ ] Privy server wallet integration
* [ ] Safe smart account integration
* [ ] V2 support (swap and LP)
* [ ] npm publish as `@gotts.ai/safe`
* [ ] Comprehensive README and API documentation
* [ ] Performance benchmarks
* [ ] End-to-end tests for all tools

**Exit criteria**: The server is published to npm. All wallet types work. UniswapX and cross-chain intents are functional. x402 outbound is operational with CoinGecko and Elsa integrations. Agent revenue tracking works. Elsa portfolio and wallet analysis return valid data.

**Quality gate**: x402 outbound tests pass, CoinGecko integration verified, Elsa integration verified, cross-chain intent test passes.

### Phase 5: Hardening (Weeks 17-20)

**Goal**: Production hardening, prompt injection defense, reputation-gated access, and launch.

**Deliverables**:

* [ ] Security audit of safety middleware
* [ ] **Prompt injection defense**: Input sanitization pipeline, dual-LLM verification (CaMeL), context integrity monitoring
* [ ] **Reputation-gated tool access**: ERC-8004 tier enforcement middleware, tool access matrix
* [ ] Fuzzing / adversarial testing (hallucinated inputs, concurrent calls, edge cases)
* [ ] Monitoring and observability (structured logs, error reporting)
* [ ] Rate limiting for HTTP transport (DDoS protection)
* [ ] AI config registration (agents in `packages/safe/agents/`, skills in `packages/safe/skills/`)
* [ ] Companion skills updated (swap-integration skill points to MCP server)
* [ ] Public announcement and documentation site
* [ ] Example agent configurations (Claude Code, ElizaOS, GOAT, Vercel AI SDK)
* [ ] AgentSkills packaging for OpenClaw/ClawHub ecosystem (dual delivery)
* [ ] Golden output snapshots established for all tools
* [ ] Regression detection suite operational

**Exit criteria**: The server is production-ready. Prompt injection defense and reputation-gated access are functional. External agent builders are using it successfully.

**Quality gate**: All tools have unit tests, golden output snapshots established, regression suite operational.

### Phase 6: CCA, am-AMM, and Token Launch (Weeks 21-24)

**Goal**: Add CCA participation, Liquidity Launcher, and am-AMM pool management tools.

**Deliverables**:

* [ ] **CCA tools**: `get_cca_state`, `submit_cca_bid`, `exit_cca_bid`, `claim_cca_tokens`
* [ ] **Liquidity Launcher tools**: `launch_token`
* [ ] **am-AMM tools**: `get_amamm_state`, `submit_amamm_bid`, `get_amamm_bid_status`
* [ ] V4 zero-delta fee collection pattern for all LP tools
* [ ] Streamable HTTP transport (MCP spec 2025-11-25)
* [ ] x402 payment integration with tiered pricing
* [ ] Integration tests for CCA and am-AMM on Anvil fork
* [ ] Coordination with vault PRD phases (vault Phase 1-2 depends on core MCP tools)

**Exit criteria**: Agents can participate in CCA auctions, launch tokens via Liquidity Launcher, and bid on am-AMM pool management. x402 micropayments are functional.

**Quality gate**: CCA pipeline integration test passes, am-AMM bidding verified.

### Phase 7: Intelligence and DX (Weeks 25-28)

**Goal**: Add remaining intelligence tools, smart account support, and developer experience tools.

**Deliverables**:

* [ ] **Intelligence tools**: `generate_uniswap_link`, `simulate_pool_scenario`, `estimate_revert_risk`, `advise_gas_optimization`, `discover_agents`, `get_market_intelligence`, `calculate_fee_switch_impact`
* [ ] **DeFi Context tools**: `get_protocol_tvl` (DefiLlama, free), `get_funding_rates` (Hyperliquid, free)
* [ ] **Hook tools**: `v4_dynamic_fee_monitor`
* [ ] **Safety tools**: `audit_approvals`, `detect_honeypot`
* [ ] **Portfolio tools**: `stress_test_portfolio`
* [ ] **Smart account tools**: `detect_account_type`, `submit_user_operation`
* [ ] ERC-4337 bundler integration (Pimlico, Alchemy, Stackup)
* [ ] Pool scenario simulation engine
* [ ] Venue comparison validated against live quotes
* [ ] Integration tests for all intelligence tools
* [ ] Documentation: intelligence tools guide

**Exit criteria**: All 97 tools are operational. Smart account execution path works. Pool simulation produces accurate backtests. DefiLlama and Hyperliquid integrations return live data. Honeypot detection catches known honeypot tokens. Approval audit surfaces stale approvals.

**Quality gate**: All intelligence tools tested with mock data, venue comparison validated against live quotes, stress test scenarios validated against historical events, honeypot detection tested against known honeypot contracts.

### Phase Coordination with Vault PRD

The vault package (`packages/vault/`) has its own 5-phase timeline (see [vault milestones](https://github.com/wpank/gotts.ai-monorepo/blob/main/prd/mcp-server/vault/14-milestones.md)). Key coordination points:

| Vault Phase | Depends On (MCP Server) | Coordination                                            |
| ----------- | ----------------------- | ------------------------------------------------------- |
| Phase 1-2   | Phase 1-3 (data + LP)   | Vault strategy engine needs pool data and LP tools      |
| Phase 3     | Phase 2 (safety)        | Vault imports `runSafetyPipeline` as optional peer dep  |
| Phase 4     | Phase 4 (ERC-8004)      | Vault reputation engine extends ERC-8004 identity reads |
| Phase 5     | Phase 5 (hardening)     | Shared audit scope for safety middleware                |

***

## Success Metrics

### Adoption Metrics

| Metric                                      | Target (3 months post-launch) | Target (6 months) |
| ------------------------------------------- | ----------------------------- | ----------------- |
| npm weekly downloads                        | 500                           | 2,000             |
| GitHub stars                                | 200                           | 1,000             |
| Unique agent installations (via MCP config) | 100                           | 500               |
| Transactions executed through the server    | 1,000                         | 10,000            |

### Quality Metrics

| Metric                                                        | Target |
| ------------------------------------------------------------- | ------ |
| Safety incident rate (fund loss from LLM error)               | 0      |
| Tool success rate (non-error responses)                       | > 95%  |
| Read operation p95 latency                                    | < 2s   |
| Write operation p95 latency                                   | < 10s  |
| Simulation accuracy (sim output vs. actual output divergence) | < 1%   |
| Test coverage (line)                                          | > 90%  |

### Ecosystem Metrics

| Metric                                   | Target                                                |
| ---------------------------------------- | ----------------------------------------------------- |
| Agent frameworks with example configs    | 5+ (Claude Code, ElizaOS, GOAT, LangChain, Vercel AI) |
| Community-contributed wallet providers   | 2+                                                    |
| Community PRs / issues                   | 50+ in first 6 months                                 |
| Replaces community MCP servers (kukapay) | Users migrate to official server                      |
| x402 payment transactions processed      | 10,000+ in first 3 months                             |
| ERC-8004 verified agents connected       | 100+ in first 6 months                                |
| Agent token pools created via MCP        | 1,000+ in first 6 months                              |

### Safety Metrics (Critical)

| Metric                                    | Target                 | Measurement                   |
| ----------------------------------------- | ---------------------- | ----------------------------- |
| Hallucinated address blocked              | 100%                   | Fuzzing with random addresses |
| Spending limit bypass                     | 0%                     | Adversarial concurrent calls  |
| Simulation-to-execution divergence > 5%   | < 0.1% of transactions | Post-trade verification       |
| Duplicate transaction from retry          | 0%                     | Nonce manager testing         |
| Circuit breaker activation on low balance | 100%                   | Balance drain simulation      |

***

## Evaluation and Quality Framework

Quality is enforced through a three-tier testing strategy that covers every layer of Gotts Safe.

### Tool-Level Testing (vitest)

Every MCP tool gets unit tests verifying:

* **Input validation:** Invalid parameters (wrong types, missing required fields, out-of-range values) produce structured error responses, not crashes
* **Error handling:** Each documented error case (e.g., `TOKEN_NOT_FOUND`, `CHAIN_NOT_SUPPORTED`) is exercised by at least one test
* **Output format:** Response shape matches the documented JSON schema (validated with zod)
* **Caching behavior:** Verify cache hits, misses, and TTL expiration behave correctly

Test structure: `packages/safe/src/tools/__tests__/<tool-name>.test.ts`

**Pass criteria:** 100% of tool tests must pass on every PR.

### Integration Testing (Anvil Fork)

Write operations get end-to-end tests against a forked mainnet (Anvil):

* **Swap pipeline:** quote -> simulate -> approve -> execute -> verify receipt
* **LP pipeline:** add\_liquidity -> verify position -> collect\_fees -> remove\_liquidity
* **Safety pipeline:** Verify that spending limits, token allowlists, rate limits, and simulation all reject bad inputs
* **x402 outbound:** Mock x402 endpoint to verify payment flow and spending tracker
* **Cross-chain:** Verify intent submission and status polling (mocked filler)

Test structure: `packages/safe/src/__tests__/integration/`

**Pass criteria:** All integration tests pass on the CI Anvil fork before merge to main.

### Regression Detection (P2)

Automated checks that code or model changes don't break tool behavior:

* **Golden output snapshots:** For each tool, maintain a set of "golden" outputs from known-good runs. After code changes, re-run and diff against golden outputs. Acceptable delta thresholds are configured per tool (e.g., price tools allow +/- 5% price drift; format-sensitive tools allow 0% drift).
* **Behavioral assertions:** Beyond output matching, verify behavioral properties:
  * `execute_swap` always calls `simulate_transaction` internally before broadcast
  * `discover_token` queries at least 2 data sources
  * `assess_mev_risk` always returns a `mitigations` array
* **CI alert pipeline:** Regression detection runs nightly. Failures create GitHub issues with diffs.

### Quality Gates per Milestone Phase

Every milestone phase (Section 13) has quality gates that must pass before moving to the next phase:

| Phase                    | Quality Gate                                                                                                                                                                           |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1 (Foundation)           | 100% tool unit tests pass, integration test framework operational                                                                                                                      |
| 2 (Trading + Deployment) | Swap pipeline integration test passes on Anvil fork, safety pipeline rejects adversarial inputs, `setup-production.ts` completes end-to-end, `provision_wallet` creates a valid wallet |
| 3 (Liquidity)            | LP lifecycle integration test passes, IL calculator validated against known examples                                                                                                   |
| 4 (Advanced)             | x402 outbound tests pass, CoinGecko integration verified, Elsa integration verified, cross-chain intent test passes                                                                    |
| 5 (Hardening)            | All tools have unit tests, golden output snapshots established, regression suite operational                                                                                           |
| 6 (CCA)                  | CCA pipeline integration test passes, am-AMM bidding verified                                                                                                                          |
| 7 (Intelligence)         | All intelligence tools tested with mock data, venue comparison validated against live quotes                                                                                           |

***