内容
# 罗马协议开发命令行工具 + MCP 服务器
`rome` 为构建者（人类或 AI 代理）提供 **可靠的链上事实** 和 **正确的构建模式**，适用于罗马协议，通过两个对齐的接口：
- **`rome <组> <命令>`** — 适用于人类和 AI 代理的外壳命令。
- **`rome mcp`** — 适用于 MCP 原生代理的相同功能，作为 MCP 服务器。
两个接口暴露 **相同的** 功能，具有相同的名称 — 代理学习一个思维模型，不会产生任何差异，因为只有一个实现。
两个问题阻碍了代理在罗马协议上的构建：**虚构的事实**（错误的 ID、地址、选择器）和 **不知道模式**（如何使用 CPI，哪个示例可复制）。`rome` 从实时注册表和 SDK 中读取并回答这两个问题。
**文档：** [`docs/GUIDES.md`](docs/GUIDES.md) — 实际使用方法 + 如何将其集成到代理、 shell 脚本或 CI 中 · [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) — 构建方式、每个功能、安全模型和 CLI 与 MCP。
## 安装
仓库优先（待发布到 npm）：
```bash
# 一次性安装，无需安装：
npx github:rome-protocol/rome-cli facts chain hadrian
# 持久安装 — 克隆 + 链接（普通的 `npm install -g github:...` 失败：npm
# 在没有自己的 node_modules 的情况下准备此包的 github: 依赖项）：
git clone https://github.com/rome-protocol/rome-cli
cd rome-cli && npm install && npm install -g .
```
固定一个标签（例如 `github:rome-protocol/rome-cli#v0.8.0`）以实现可复制的运行。
## 命令行界面
```bash
rome facts chain hadrian # 链 ID、RPC、浏览器、程序 ID、gas 代币
rome facts tokens 200010 # 代币列表（地址、铸造、符号、十进制）
rome facts contracts hadrian # 已部署的合约地址
rome facts gas hadrian # 当前 gas 价格 + 预估与收费警告
rome facts balance hadrian 0x… # 地址的原生（gas 代币）余额
rome facts programs devnet # 网络的 Solana 程序 ID
rome cookbook cpi-recipe # CPI 账户规则 + SDK 编码器（可靠的地址）
rome cookbook patterns lending # 哪个示例仓库 + 指南适合目标
rome cookbook errors "Custom(1)" # 解码罗马失败 → 原因 + 修复（错误分类）
rome preset foundry hadrian # 适用于 foundry / hardhat 的预设罗马网络配置 + 特殊情况
rome call hadrian 0x… "balanceOf(address) returns (uint256)" 0x… # 读取合约（无需密钥）
rome doctor hadrian --address 0x… # 预检：链上线？RPC 可达？程序设置？钱包资助？
rome tx hadrian 0x… # 诊断交易：EVM 收据 + Solana 结算交易（s）+ Via 链接
# 操作 — 在链上签名，需要 ROME_EVM_KEY （从不作为标志/日志/MCP）：
rome deploy hadrian ./out/Store.json # 部署编译后的工件
rome send hadrian 0x… "set(uint256)" 42 # 通过 submitRomeTx 进行写入
rome fund hadrian --from base-sepolia --amount 1 # 桥接 USDC → 罗马 gas（CCTP，“从家”）
rome bridge hadrian --from base-sepolia --amount 1 --intent wrapper # USDC → 罗马上的 wUSDC
rome verify hadrian --path solidity # 双通道工作门（需要 ROME_EVM_KEY + ROME_SOLANA_KEY）
```
链通过 ID、名称或 slug 解析（`200010`、`hadrian`、`200010-hadrian`）。输出为 JSON — 将其管道传输到 `jq` 或在代理中读取：
```console
$ rome facts chain hadrian
{
"chainId": 200010,
"name": "Rome Hadrian",
"rpcUrl": "https://hadrian.testnet.romeprotocol.xyz/",
"romeEvmProgramId": "RPTWwELXAY4KC9ZPHhaxp7Sq1hHtU3HNEgLbSegCcWf",
"nativeCurrency": { "symbol": "USDC", "decimals": 18 }, …
}
# 通过共享铸造将 gas 代币与其包装器配对，一行代码：
$ rome facts tokens hadrian | jq -r '.tokens[] | select(.symbol=="wUSDC") | .address'
0xd4cc34b67c805d472b5a709a22a1037f6b16ef28
```
更多配方 — 代理（MCP）、shell 和 CI 集成 — 见 [`docs/GUIDES.md`](docs/GUIDES.md)。
## MCP 服务器
**您无需运行或托管任何内容。** `rome mcp` 是一个 **stdio** 服务器（不是网络守护进程），由您的 MCP 客户端为您启动。注册它一次：
```json
{
"mcpServers": {
"rome": { "command": "rome", "args": ["mcp"] }
}
}
```
客户端（Claude Code / Claude Desktop / Cursor / …）根据需求启动 `rome mcp` 作为子进程，通过 stdin/stdout 与其通信，并在会话结束时关闭它 — 无需端口，无需托管，无需进程管理器。它将每个功能公开为工具（`facts_chain`、`facts_gas`、`cookbook_cpi_recipe`，…），**只读且不持有密钥** — 可以安全地连接到任何代理；它永远不会签署交易或泄露机密。您的应用程序始终通过 [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts) 进行签名。有关生命周期，请参见 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#running-it--cli-vs-mcp-server)。
## 它是什么 — 两层
- **基础 — 只读，适用于 CLI + MCP**：`facts` + `cookbook` + `call`。消除幻觉，引导至正确的模式，读取合约。不持有密钥 — 可以安全地连接到任何代理。
- **操作 — 仅 CLI，密钥保护，MCP 上从不**：`deploy` / `send`（合约）和 `fund` / `bridge`（“从家”上桥：桥接 USDC 为 gas 或 wUSDC via CCTP）。这些签名，因此从环境中读取密钥（`ROME_EVM_KEY`）— 从不作为标志，从不记录，从不通过 MCP 服务器。每个操作都会打印其执行内容；资助预览使用 `--dry-run`。
一切都源自 [`@rome-protocol/registry`](https://github.com/rome-protocol/rome-registry) + 链的 RPC + SDK 的 [`@rome-protocol/sdk/bridge`](https://github.com/rome-protocol/rome-sdk-ts) — 没有硬编码的特定于链的内容。
仍然是编排，而不是替换：大型合约构建保留在 Foundry / Hardhat 中；脚手架使用 [`create-rome-app`](https://github.com/rome-protocol/create-rome-app)；库写入使用 [`@rome-protocol/sdk`](https://github.com/rome-protocol/rome-sdk-ts)。
## 开发
```bash
npm install
npm run build
npm test # 单元测试，包括 CLI↔MCP 对齐不变性
node scripts/mcp-smoke.mjs # 端到端：真正的 MCP 客户端通过 stdio 驱动 `rome mcp`
```
## 许可证
MIT — 见 [LICENSE](LICENSE)。
