# awesome-base-mcp

Node.js [Model Context Protocol](https://modelcontextprotocol.io) server for an autonomous agent wallet on Base. It supports native/ERC-20 payments, bounded ERC-20 allowances, Uniswap V3, Aerodrome, Aave V3, Morpho Blue, Hyperliquid, 0x and CoW Protocol.

**License: CC0 1.0 (public domain)** — see [LICENSE](./LICENSE) · **No warranty, real funds at risk** — see [DISCLAIMER](./DISCLAIMER.md)

---

## English

### Features

- **Wallet**: `wallet_get_address`, `wallet_get_balance`, `wallet_get_portfolio`, `wallet_get_allowances`, `wallet_pay`, `wallet_approve_token`, `wallet_revoke_allowance` — portfolio research plus policy-governed payments, bounded approvals, and audited allowance revocation.
- **DEX**: `uniswap_quote_v3` / `uniswap_swap_v3`, `aerodrome_quote` / `aerodrome_swap`, `zeroex_quote` / `zeroex_swap`, `cow_quote` / `cow_place_order`.
- **Lending**: Aave V3 (`aave_supply`, `aave_withdraw`, `aave_borrow`, `aave_repay`, plus account/reserve reads) and Morpho Blue (market discovery, supply/borrow/repay, collateral in/out).
- **Contract inspection**: `contract_get_code` returns all verified source files from Sourcify v2, then uses Base Blockscout as a fallback, with deployed bytecode and detected proxy implementations for independent honeypot review. It is read-only and is not a safety verdict.
- **Risk research**: `contract_risk_report`, `token_risk_report`, `token_market_snapshot`, `transaction_simulate`, and `token_simulate_trade` combine static code signals, liquidity observations, and read-only EVM simulations. Results are evidence, never a safety guarantee.
- **Position safety**: `protocol_position_health` combines Aave account health with current Morpho LLTV/oracle-based health calculations.
- **Perps**: `hyperliquid_market`, `hyperliquid_account`, `hyperliquid_place_order`, `hyperliquid_cancel_order`, `hyperliquid_set_leverage`, `hyperliquid_transfer`.
- **Policy engine**: WebUI-controlled execution switches, protocol switches, recipient/contract blacklists, per-asset caps, Hyperliquid coin/notional/leverage caps, pre-broadcast simulation, and a JSONL audit trail (`audit/events.jsonl`).

### Setup

```powershell
npm install
Copy-Item .env.example .env
# fill in AGENT_PRIVATE_KEY and BASE_RPC_URL — see comments in .env.example
```

Run over stdio (for VS Code / Claude Desktop):

```powershell
npm run start:stdio
```

Run Streamable HTTP + policy WebUI on loopback:

```powershell
$env:MCP_HTTP_BEARER_TOKEN = "replace-with-a-32-character-or-longer-random-secret"
npm run start:http
```

- MCP endpoint: `http://127.0.0.1:5201/mcp` (Bearer token required).
- WebUI: `http://127.0.0.1:5202/ui/` — configure policy, then it writes `.awesome-base-mcp.policy.json` (git-ignored).
- VS Code users: [`.vscode/mcp.json`](.vscode/mcp.json) starts the server over stdio; restart the MCP server after editing `.env`.

### Security model

- The private key is **only** read from `.env`; it is never accepted through MCP tool input and never logged.
- `.env`, the policy file and `audit/` are git-ignored. On POSIX the server enforces `0600` on sensitive files and rejects symlinked paths.
- Writes are submitted directly by the agent key — **no interactive approval step**. Use `PAYMENT_LIMITS_JSON` and the WebUI blacklists/caps to bound the blast radius.
- The bearer token is a wallet-control secret, not a user password. Keep both HTTP services on loopback; `ALLOW_REMOTE_HTTP=true` is only safe behind TLS and a trusted reverse proxy.

### Testing

Two self-service integration suites live in [`tests/`](./tests/) and run against **Base mainnet with your funded key** — start with tiny amounts.

```powershell
npm run test:read    # 24 read-only tools, costs nothing
npm run test:write   # full write cycle (swaps, Aave, Morpho, CoW fill, HL round-trip)
```

Known practical gotchas (learned while testing on mainnet):

- CoW on Base: allowance must go to the **VaultRelayer** `0xC92E8bdf79f0507f65a392b0ab4667716BFE0110` (differs from Ethereum mainnet).
- Morpho: repaying more than the outstanding debt panics — repay slightly *less* and accept dust debt; any open debt blocks withdrawing 100% of collateral.
- Aerodrome classic pools are thin — use a wide `minimumAmountOut` buffer and a long deadline.
- Free public RPCs rate-limit quickly; a free Alchemy/dRPC key is recommended.
- Hyperliquid "unified account" mode disables spot↔perp transfers (funds are shared automatically).

### License

[CC0 1.0 Universal](./LICENSE) — to the extent possible under law, the author waives all copyright and related rights. Use it, fork it, ship it.

### Disclaimer

This software is provided **as-is, without warranty of any kind**. It moves **real funds on mainnet** with no interactive confirmation. You are solely responsible for every transaction. Read [DISCLAIMER.md](./DISCLAIMER.md) before use.

---

## 中文

### 功能

- **钱包**:`wallet_get_address`、`wallet_get_balance`、`wallet_get_portfolio`、`wallet_get_allowances`、`wallet_pay`、`wallet_approve_token`、`wallet_revoke_allowance` —— 资产研究，以及受策略约束的转账、有界授权和可审计撤销授权。
- **DEX**:Uniswap V3、Aerodrome、0x、CoW Protocol 的报价与Swap工具。
- **借贷**:Aave V3(supply/withdraw/borrow/repay 及账户、储备查询)与 Morpho Blue(市场发现、供款/借款/还款、抵押进出)。
- **合约检测**:`contract_get_code` 优先返回 Sourcify v2 的全部已验证源码，未收录时回退到 Base Blockscout，并附带部署 bytecode 与识别到的代理实现，供 Agent 自行审查 honeypot 风险。该工具只读，返回结果不构成安全结论。
- **风险研究**:`contract_risk_report`、`token_risk_report`、`token_market_snapshot`、`transaction_simulate`、`token_simulate_trade` 结合静态代码信号、流动性观察和只读 EVM 模拟；结果仅供判断，不构成安全保证。
- **仓位安全**:`protocol_position_health` 汇总 Aave 健康度与基于当前 Morpho LLTV/预言机的健康度计算。
- **永续合约**:Hyperliquid 行情、账户、下单、撤单、设置杠杆、资金划转。
- **策略引擎**:WebUI 控制执行开关、协议开关、收款方/合约黑名单、单资产限额、Hyperliquid 币种/名义价值/杠杆上限、广播前模拟,以及 JSONL 审计日志(`audit/events.jsonl`)。

### 安装

```powershell
npm install
Copy-Item .env.example .env
# 填写 AGENT_PRIVATE_KEY 和 BASE_RPC_URL —— 见 .env.example 内注释
```

以 stdio 运行(VS Code / Claude Desktop):

```powershell
npm run start:stdio
```

以 Streamable HTTP + 策略 WebUI 运行(仅监听本地回环):

```powershell
$env:MCP_HTTP_BEARER_TOKEN = "替换为至少32位随机字符串"
npm run start:http
```

- MCP 端点:`http://127.0.0.1:5201/mcp`(需 Bearer token)。
- WebUI:`http://127.0.0.1:5202/ui/` —— 配置策略后写入 `.awesome-base-mcp.policy.json`(已被 git 忽略)。
- VS Code 用户:[`.vscode/mcp.json`](.vscode/mcp.json) 已配置 stdio 启动;修改 `.env` 后需重启 MCP 服务器。

### 安全模型

- 私钥**只**从 `.env` 读取;绝不通过 MCP 工具入参接收,也绝不写日志。
- `.env`、策略文件、`audit/` 均被 git 忽略。POSIX 上服务器对敏感文件强制 `0600` 权限并拒绝符号链接。
- 交易由 Agent 私钥直接广播——**没有交互式确认步骤**。请用 `PAYMENT_LIMITS_JSON` 和 WebUI 黑名单/限额控制风险敞口。
- Bearer token 是钱包控制凭据,不是用户密码。两个 HTTP 服务务必保持仅监听回环;`ALLOW_REMOTE_HTTP=true` 只有在 TLS + 可信反代之后才安全。

### 测试

两套自助集成测试在 [`tests/`](./tests/),直接跑在 **Base 主网 + 你的真实私钥**上——请从小额开始。

```powershell
npm run test:read    # 24 个只读工具,零成本
npm run test:write   # 完整写入链路(swap、Aave、Morpho、CoW 真实成交、HL 开平仓)
```

主网实测踩过的坑:

- CoW(Base):授权必须给 **VaultRelayer** `0xC92E8bdf79f0507f65a392b0ab4667716BFE0110`(与以太坊主网不同)。
- Morpho:还款超过欠款会直接 panic——要**少还一点点**并接受灰尘债;只要还有债务,就不能 100% 撤出抵押。
- Aerodrome 经典池很薄——`minimumAmountOut` 留大缓冲、deadline 给长。
- 免费公共 RPC 限流很快,建议申请免费的 Alchemy/dRPC key。
- Hyperliquid "统一账户"模式禁用现货↔合约划转(资金自动共享)。

### 许可证

[CC0 1.0 Universal](./LICENSE) —— 在法律允许的最大范围内,作者放弃所有版权及相关权利。随便用、随便改、随便发布。

### 免责声明

本软件**按原样提供,不附带任何形式的保证**。它会在主网动用**真实资金**且没有交互式确认。每一笔交易的责任都由你自己承担。使用前务必阅读 [DISCLAIMER.md](./DISCLAIMER.md)。