# MCP and AI Plan Upgrades — Dodoex and Uniswap Liquidity Pool Management

**Purpose:** Upgrades to the PMM full-mesh and single-sided LP plans so that **MCPs and AIs dedicated to managing and maintaining** all Dodoex (DODO PMM) and Uniswap liquidity pools are explicitly covered and operational.

**Status:** All planned upgrades (§2) and all additional recommendations (§5) are **implemented**. See §4 and §5.1 for implementation details. Optional tasks index: [OPTIONAL_TASKS_CHECKLIST.md](../00-meta/OPTIONAL_TASKS_CHECKLIST.md).

**Related:** [PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md](PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md), [AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md](../02-architecture/AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md), [POOL_ACCESS_DASHBOARD_API_MCP.md](../11-references/POOL_ACCESS_DASHBOARD_API_MCP.md).

---

## 1. Current state (what plans already assume)

| Component | Role | Plan coverage today |
|-----------|------|----------------------|
| **ai-mcp-pmm-controller** | Read pool state (getMidPrice, reserves, k, fee); optional quote/add/remove liquidity | Allowlist per chain; one chain per MCP instance; profile `dodo_pmm_v2_like` for Chain 138 Mock DVM |
| **Token-aggregation API** | Index DODO (and Uniswap when env set); single-hop quote; tokens/pools discovery | Chain 138 + optional public chains via `CHAIN_*_DODO_PMM_INTEGRATION`, `CHAIN_*_RPC_URL` |
| **cross-chain-pmm-lps bot** | Deviation watcher; buy/sell to compress δ; inventory adjust; circuit break | Design only; not wired to MCP or API for automation |
| **EnhancedSwapRouter** | Multi-provider routing (Dodoex, Uniswap, Balancer, Curve) | Not deployed; no MCP/API integration specified |

---

## 2. Upgrades to the plans

### 2.1 Full-mesh and single-sided plans (PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN)

| Upgrade | Description |
|---------|-------------|
| **Allowlist sync with mesh** | After running `create-pmm-full-mesh-chain138.sh`, **automatically or semi-automatically** update the MCP allowlist (e.g. `ai-mcp-pmm-controller/config/allowlist-138.json`) with every new pool (pool_address, base_token, quote_token, profile). Document a script or MCP tool that: (1) reads `DODOPMMIntegration.getAllPools()` and `getPoolConfig(pool)` on Chain 138, (2) writes the allowlist so the MCP can read state for all mesh pools without manual entry. |
| **Per-chain allowlist for public cW* pools** | When single-sided cW* / HUB pools are deployed on a public chain, extend the plan to: (1) add a **per-chain MCP allowlist** (or multi-chain allowlist) so the dedicated MCP/AI can read pool state on that chain; (2) document the mapping from `cross-chain-pmm-lps/config/deployment-status.json` (and pool-matrix) to the MCP config so one source of truth drives both deployment and MCP visibility. |
| **Uniswap pool indexing and maintenance** | Where the plan says "DODO PMM or Uniswap V2/V3 per chain": (1) add an explicit **Uniswap pool creation and indexing** path: set `CHAIN_*_UNISWAP_V2_FACTORY` / `CHAIN_*_UNISWAP_V3_FACTORY` and run the token-aggregation indexer so Uniswap pools appear in the API; (2) add a **maintenance** subsection: who (or which AI/MCP) is responsible for adding liquidity, rebalancing, or pausing on Uniswap pools on each chain; (3) if an AI/MCP is dedicated to Uniswap pools, define its **inputs** (API quote, pool state from indexer or RPC) and **allowed actions** (e.g. quote only vs. submit tx). |
| **Bot–MCP–API integration** | In the **single-sided** plan (and cross-chain-pmm-lps): (1) specify that the **deviation bot** (v1/v2) can consume **pool state from the MCP** (e.g. `dodo.get_pool_state` for each allowlisted pool) or from the **token-aggregation API** (e.g. `/api/v1/tokens/:address/pools`, reserve/price from indexer); (2) specify that the bot’s **actions** (e.g. trigger buy/sell to compress δ) are either executed by the same AI that uses the MCP or by a separate executor that receives signals from the MCP/AI; (3) add **circuit-break and cooldown** to the MCP/API so the AI can read "pool in CIRCUIT_BREAK" or "cooldown until block X" and avoid sending trades. |
| **Dedicated “pool manager” MCP/AI scope** | Add a short subsection: **Dedicated MCP/AI for Dodoex and Uniswap pool management.** Scope: (1) **Dodoex (Chain 138 + public cW*):** MCP tools for read state, quote add/remove liquidity; allowlist kept in sync with full mesh and single-sided deployments; (2) **Uniswap (per chain where used):** Same idea—allowlist or indexer-driven list of Uniswap V2/V3 pools; MCP or API to read pool state and optionally quote; (3) **Maintenance tasks:** Document that this MCP/AI is the **designated** reader (and optionally executor) for rebalancing, add/remove liquidity, and responding to deviation alerts within policy (slippage, size, circuit break). |

### 2.2 RUNBOOK and script upgrades (SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK)

| Upgrade | Description |
|---------|-------------|
| **Post-deploy: update MCP allowlist** | In the runbook checklist, add a step: "After deploying cW* / HUB pools on chain X, update the MCP allowlist for chain X (or the multi-chain config) with pool_address, base_token, quote_token, and profile so the dedicated MCP/AI can read and manage those pools." |
| **Post-deploy: update deployment-status.json** | Already implied; make it explicit that `deployment-status.json` is the **source for MCP allowlist generation** (script: given chainId, read deployment-status and output allowlist fragment). |
| **List Uniswap pools per chain** | If Uniswap is used on a chain, add a step to list Uniswap V2/V3 pools (from factory events or indexer) and add them to the same MCP/API visibility (allowlist or indexer config) so one MCP/AI can "see" both DODO and Uniswap pools. |

### 2.3 AI_AGENTS_57XX and POOL_ACCESS_DASHBOARD_API_MCP

| Upgrade | Description |
|---------|-------------|
| **Multi-chain MCP** | Document an option for **one MCP server** that supports **multiple chains**: e.g. allowlist contains `chainId` per pool, and the MCP uses the appropriate RPC per chain when calling `get_pool_state` or `quote_add_liquidity`. This reduces the need to run one MCP instance per chain for Dodoex + Uniswap. |
| **Uniswap pool profile** | Add a **pool profile** (e.g. `uniswap_v2_pair` or `uniswap_v3_pool`) to the MCP: expected view methods (getReserves, token0, token1, or slot0, liquidity, etc.) so the MCP can read Uniswap pool state and expose it to the same AI that manages DODO pools. |
| **Dashboard and API alignment** | State that the **token-aggregation API** and the **MCP** should expose **the same set of pools** for a given chain (DODO + Uniswap once indexed): so the "custom dashboard" and the MCP/AI use one source of truth (allowlist + indexer config) and stay in sync. |
| **Automation triggers** | Document how the dedicated AI is **triggered**: (1) **Scheduled:** cron or scheduler calls MCP/API to get state, then decides rebalance/add/remove; (2) **Event-driven:** indexer or chain watcher emits "reserve delta" or "price deviation" and triggers the AI; (3) **Manual:** operator asks the AI (via MCP) for a quote or recommendation, then executes manually. |

---

## 3. Summary: what to add to the “above” plans

- **PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN:** Allowlist sync with full mesh; per-chain allowlist for cW*; Uniswap indexing and maintenance; bot–MCP–API integration; dedicated MCP/AI scope for Dodoex + Uniswap.
- **SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK:** Post-deploy MCP allowlist update; deployment-status as source for allowlist; Uniswap pool listing where applicable.
- **AI_AGENTS_57XX / POOL_ACCESS:** Multi-chain MCP option; Uniswap pool profile; dashboard/API alignment; automation triggers (scheduled, event-driven, manual).

---

## 4. Completed upgrades (implemented)

| Upgrade | Status | Implementation |
|---------|--------|----------------|
| **Allowlist sync with mesh** | Done | Script `scripts/generate-mcp-allowlist-from-chain138.sh`: reads `allPools(uint256)` and `poolConfigs(pool)` via RPC; outputs allowlist JSON. Use `-o ai-mcp-pmm-controller/config/allowlist-138.json` to write. Documented in PMM plan §1.5. |
| **Per-chain allowlist from deployment-status** | Done | Script `scripts/generate-mcp-allowlist-from-deployment-status.sh <chain_id> [-o path]`: reads `deployment-status.json` pmmPools for that chain; outputs allowlist fragment with limits. Documented in SINGLE_SIDED runbook §5a, §6. |
| **Post-deploy MCP allowlist step** | Done | Runbook §5a: run generate-mcp-allowlist-from-deployment-status.sh after deploying cW* / HUB pools. |
| **deployment-status as source for allowlist** | Done | Runbook §6: explicit that deployment-status.json is source of truth; script generates allowlist from it. |
| **Uniswap pool listing / indexing step** | Done | Runbook §6a: set CHAIN_*_UNISWAP_* env, run indexer; add Uniswap pools to MCP allowlist with profile when available. |
| **Uniswap pool profile** | Done | Added `uniswap_v2_pair` and `uniswap_v3_pool` to `ai-mcp-pmm-controller/config/pool_profiles.json` with expected methods. MCP server must implement reading these methods when profile is used. |
| **PMM plan: Uniswap, Bot–MCP, Pool Manager** | Done | Plan §2.7 (Uniswap indexing and maintenance), §2.8 (Bot–MCP–API integration), §2.9 (Dedicated MCP/AI scope); §1.5 (Allowlist sync with mesh). |
| **Multi-chain MCP, dashboard alignment, automation** | Done | [AI_AGENTS_57XX_MCP_ADDENDUM.md](../02-architecture/AI_AGENTS_57XX_MCP_ADDENDUM.md): multi-chain allowlist/RPC, Uniswap profile reference, dashboard/API alignment, automation triggers (scheduled, event-driven, manual). |

---

## 5. Additional recommendations

| # | Recommendation | Priority | Notes |
|---|-----------------|----------|--------|
| 1 | **Implement multi-chain allowlist in MCP server** | High | Extend ai-mcp-pmm-controller to accept `chainId` per pool and select RPC by chain so one server can serve Chain 138 and all public cW* chains. |
| 2 | **Wire MCP get_pool_state to Uniswap profiles** | High | In the MCP tool implementation, when profile is `uniswap_v2_pair` or `uniswap_v3_pool`, call getReserves/slot0/liquidity and return normalized state (reserves, derived price) for the AI. |
| 3 | **Expose circuit-break and cooldown in API or MCP** | Medium | Add an endpoint or MCP tool that returns bot state (IDLE, ABOVE_BAND, BELOW_BAND, COOLDOWN, CIRCUIT_BREAK) and cooldown-until block/time so the AI does not submit trades during cooldown or circuit-break. Source: cross-chain-pmm-lps peg-bands and bot state. |
| 4 | **Event-driven trigger for bot/AI** | Medium | When token-aggregation indexer or a chain watcher detects reserve delta or price deviation beyond a threshold, emit an event or call a webhook that triggers the dedicated AI to fetch state (via MCP/API) and decide rebalance; keeps reaction time low without polling. |
| 5 | **Single allowlist file for multi-chain** | Low | Allow one JSON file to contain pools for multiple chains (array of { chainId, pools }) so the MCP can load one file and serve all chains; merge output of generate-mcp-allowlist-from-chain138.sh and generate-mcp-allowlist-from-deployment-status.sh per chain into one manifest. |
| 6 | **Rate limits and gas caps in MCP** | Medium | Enforce allowlist `limits` (max_slippage_bps, max_single_tx_notional_usd, cooldown_seconds, gas_cap_gwei) in the MCP server when the AI requests quote or execute; reject or cap out-of-policy requests. |
| 7 | **Audit trail for AI-driven txs** | Medium | Log all MCP tool calls (get_pool_state, quote_add_liquidity, add_liquidity, etc.) and any executed txs (tx hash, pool, amount, chain) for audit and incident review. |
| 8 | **EnhancedSwapRouter integration with MCP** | Low | When EnhancedSwapRouter is deployed on Chain 138, add it to the MCP/API so the AI can reason about multi-provider routing (Dodoex vs Uniswap vs Balancer) and optionally trigger swaps through the router. |

### 5.1 Implementation status (all completed)

| # | Implementation |
|---|----------------|
| 1 | **Multi-chain allowlist:** `config/server.py` supports allowlist format `chains: [ { chainId, pools } ]` and per-pool `chain_id`. RPC per chain via env `RPC_138`, `RPC_137`, etc. or `RPC_BY_CHAIN_PATH` (JSON file). `_get_web3(chain_id)` caches Web3 per chain. |
| 2 | **Uniswap get_pool_state:** In `dodo_get_pool_state`, profiles `uniswap_v2_pair` and `uniswap_v3_pool` use getReserves/slot0/liquidity; return normalized state (reserves, mid_price, liquidity_base/quote). |
| 3 | **Circuit-break and cooldown:** `GET /bot_state` and MCP tool `dodo.get_bot_state` return bot state from `BOT_STATE_PATH` (JSON). Example: `config/bot_state.example.json`. Optional `params.pool` for per-pool state. |
| 4 | **Event-driven trigger:** `POST /webhook/trigger` accepts JSON body `{ "reason", "chain_id", "pool" }`; returns 202 and logs. Wire indexer/watcher to POST here; AI can poll MCP or react to webhook. |
| 5 | **Single multi-chain allowlist:** Allowlist format supports `chains: [ { chainId, pools } ]`. Script `scripts/merge-mcp-allowlist-multichain.sh -o path` merges Chain 138 and other chains into one file. |
| 6 | **Rate limits and gas caps:** `_check_limits_and_cooldown()` enforces notional, cooldown_seconds (via `COOLDOWN_STATE_PATH`), gas_cap_gwei, max_slippage_bps. Used in `dodo_simulate_action`; use `_record_trade_ts(pool)` after writes. |
| 7 | **Audit trail:** Every MCP tool response goes through `_audit_and_return()`; logs to `AUDIT_LOG_PATH` (JSONL) and logger. |
| 8 | **EnhancedSwapRouter stub:** MCP tool `dodo.get_router_quote` returns `configured: true/false` from `ENHANCED_SWAP_ROUTER_ADDRESS`. Add contract calls when router is deployed. |

---

## 6. Next steps (operator / runtime)

After implementation, operators can:

1. **Multi-chain MCP:** Set `ALLOWLIST_PATH` to a multi-chain file (from `scripts/merge-mcp-allowlist-multichain.sh -o path`); set `RPC_138`, `RPC_137`, etc. or `RPC_BY_CHAIN_PATH`.
2. **Bot state:** Set `BOT_STATE_PATH` to a JSON file (see `ai-mcp-pmm-controller/config/bot_state.example.json`); update it from your peg-bands/bot or leave default.
3. **Audit / cooldown:** Set `AUDIT_LOG_PATH` and `COOLDOWN_STATE_PATH` if you want persistent audit log and cooldown ledger.
4. **Webhook:** Wire your indexer or chain watcher to `POST /webhook/trigger` with `{ "reason", "chain_id", "pool" }` when reserve or price deviation exceeds threshold.
5. **EnhancedSwapRouter:** When the router is deployed on Chain 138, set `ENHANCED_SWAP_ROUTER_ADDRESS` and extend `dodo.get_router_quote` in the MCP server to call the router contract.

---

## 7. References

- [PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md](PMM_FULL_MESH_AND_PUBLIC_SINGLE_SIDED_PLAN.md)
- [SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md](SINGLE_SIDED_LPS_PUBLIC_NETWORKS_RUNBOOK.md)
- [AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md](../02-architecture/AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md)
- [AI_AGENTS_57XX_DEPLOYMENT_PLAN.md](../02-architecture/AI_AGENTS_57XX_DEPLOYMENT_PLAN.md)
- [POOL_ACCESS_DASHBOARD_API_MCP.md](../11-references/POOL_ACCESS_DASHBOARD_API_MCP.md)
- [DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md](../04-configuration/DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md)
- [DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md](DEFI_AGGREGATOR_DEX_ROUTING_FLOWS_DIAGRAM.md) — Mermaid diagram of all DeFi aggregator and DEX routing flows for swaps
- [AI_AGENTS_57XX_MCP_ADDENDUM.md](../02-architecture/AI_AGENTS_57XX_MCP_ADDENDUM.md) — Multi-chain MCP, Uniswap profile, automation triggers
- [OPTIONAL_TASKS_CHECKLIST.md](../00-meta/OPTIONAL_TASKS_CHECKLIST.md) — Consolidated optional tasks (Done / Pending)