使用说明

@initia/mcp

MCP服务器和CLI 开始区块链生态系统。用于跨Initia L1和L2汇总（MiniEVM、MiniMove、MiniWasm）查询链状态、管理资产和执行事务的工具。

两个接口，一个代码库：

@initia/mcp --MCP服务器（stdio传输，用于Claude Desktop/LLM代理）
initctl --CLI（用于人工和脚本）

快速开始

npm install
npm run build

CLI（initctl）

# Global install
npm install -g .
initctl chain list

# Or run directly without global install
node dist/cli.js chain list

# Or via npx (after npm install)
npx initctl chain list

克劳德桌面

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "initia": {
      "command": "npx",
      "args": ["-y", "@initia/mcp"],
      // optional — see Environment Variables below
      "env": {
        "INITIA_KEY": "your mnemonic words ...",
        "INITIA_NETWORK": "mainnet"
      }
    }
  }
}

克劳德代码

claude mcp add initia -s user -- npx -y @initia/mcp

# optional — see Environment Variables below
claude mcp add initia -s user \
  -e INITIA_KEY="your mnemonic words ..." \
  -e INITIA_NETWORK=mainnet \
  -- npx -y @initia/mcp

法典

添加 codex.json （或通过 codex --mcp-config codex.json):

{
  "mcpServers": {
    "initia": {
      "command": "npx",
      "args": ["-y", "@initia/mcp"],
      // optional — see Environment Variables below
      "env": {
        "INITIA_KEY": "your mnemonic words ...",
        "INITIA_NETWORK": "mainnet"
      }
    }
  }
}

双子星命令行工具

添加 .gemini/settings.json:

{
  "mcpServers": {
    "initia": {
      "command": "npx",
      "args": ["-y", "@initia/mcp"],
      // optional — see Environment Variables below
      "env": {
        "INITIA_KEY": "your mnemonic words ...",
        "INITIA_NETWORK": "mainnet"
      }
    }
  }
}

命令行界面

# Query
initctl chain list
initctl token search --symbol USDC
initctl move view --module-address 0x1 --module-name coin --function-name balance --args '["0x1"]'

# Transaction (interactive confirm)
initctl bank send --to init1abc... --amount 1000000 --denom uinit

# Transaction (skip confirm)
initctl bank send --to init1abc... --amount 1000000 --denom uinit --yes

# JSON output (for scripts)
initctl token search --symbol INIT --json

# Shell completion
eval "$(initctl completion bash)"   # bash
eval "$(initctl completion zsh)"    # zsh
initctl completion fish | source    # fish

环境变量

变量	必填	默认	描述
`INITIA_KEY`	否	--	助记词（12/24个单词），十六进制私钥(`0x...`)，或 `"ledger"`
`INITIA_KEY_INDEX`	没有	`0`	HD衍生指数（用于助记/分类账）
`INITIA_LEDGER_APP`	没有	`ethereum`	分类账应用程序： `ethereum` 或 `cosmos`
`INITIA_NETWORK`	没有	`mainnet`	`mainnet` 或 `testnet`
`AUTO_CONFIRM`	没有	`false`	跳过突变确认（仅MCP）
`INITIA_LOG_LEVEL`	没有	`info`	`debug`, `info`, `warn`, `error`
`INITIA_USE_SCAN_API`	没有	`false`	使用扫描API获取增强的链数据

没有签名者密钥，只读工具仍然有效。变异工具返回 SIGNER_REQUIRED.

工具（107）

链与账户（10）

工具	说明
`chain_list`	列出所有支持的链（L1+L2汇总）
`chain_capabilities`	获取链VM类型、功能和端点
`chain_gas_prices`	当前链上天然气价格（L1或L2）
`account_get`	账户信息和余额
`portfolio_get`	所有链的汇总余额
`address_validate`	验证bech32或EVM地址格式
`address_convert`	在bech32和十六进制之间转换
`delegation_get`	质押委托、奖励和无约束
`distribution_rewards`	在验证器之间等待质押奖励
`simulate_tx`	模拟交易并估算天然气

通证广；denom（7）

工具	说明
`token_search`	在所有链中按符号搜索代币
`token_list`	列出链上已注册的令牌
`token_info`	任何类型的令牌元数据（名称、符号、小数）
`token_balance`	本地、ERC20、CW20或Move-FA的代币余额
`amount_format`	用小数格式化原始金额
`denom_classify`	分类面额类型（原生、ibc、evm等）
`denom_metadata`	链上银行模块元数据

交易记录（3）

工具	说明
`tx_get`	使用VM感知解码通过哈希获取交易
`tx_search`	搜索交易（CometBFT查询语法）
`tx_by_address`	地址的最近交易记录

验证与质押（7）

工具	说明
`validator_list`	列出具有状态和投票权的验证器
`validator_get`	详细的验证器信息
`staking_pool`	网络绑定/未绑定令牌总计
`staking_annual_provisions`	当前年度代币准备金（通货膨胀）
`staking_manage`	委派、取消委派、重新委派或索取奖励
`governance_vote`	对治理提案进行投票
`proposal_list` / `proposal_get`	列出或获取治理建议

桥（14）

工具	说明
`bridge_route`	找到最佳的跨链转运路线
`bridge_execute`	通过路由器执行跨链传输
`bridge_transfer_status`	跟踪跨链转移进度
`bridge_list_chains`	列出可桥接的L2链
`bridge_routable_assets`	列出可用于路由的资产
`bridge_deposit` / `bridge_withdraw`	直接L1↔L2 OP单位存款/取款
`bridge_withdrawals` / `bridge_withdrawal_status`	查询提款状态
`opbridge_list` / `opbridge_get`	OPUnit网桥配置
`opbridge_token_pairs`	L1↔L2令牌对映射
`opbridge_token_pair_by_l1_denom` / `opbridge_token_pair_by_l2_denom`	令牌对查找

IBC（3）

工具	说明
`ibc_channels`	列出IBC通道或查找两个链之间的通道
`ibc_denom_hash`	从路径计算IBC面额哈希
`ibc_transfer`	通过IBC发送代币

用户名（4）

工具	说明
`username_resolve`	解析.init名称↔ 地址
`username_record`	完整的.init用户名记录
`username_metadata`	.init用户名的NFT元数据
`username_check`	检查用户名可用性

移动虚拟机（14）

工具	说明
`move_modules`	列出在某个地址部署的模块
`move_module_abi`	获取模块ABI（函数、结构）
`move_resources`	列出某个地址所拥有的资源
`move_resource_get`	查询特定资源
`move_view`	调用视图函数（只读）
`move_execute`	执行输入功能
`move_publish` / `move_script`	部署模块或运行脚本
`move_table_entry`	查询表条目
`move_dex_pairs`	列出DEX流动性池对
`move_denom_metadata` / `move_metadata_denom`	天龙↔ 元数据转换
`move_bcs_encode` / `move_bcs_decode`	BCS序列化实用程序

电动汽车（10）

工具	说明
`evm_call`	调用合约函数（只读）
`evm_send`	发送状态更改事务
`evm_deploy`	部署合约
`evm_get_logs`	查询事件日志
`evm_get_tx_receipt`	获取交易收据
`evm_get_block`	获取区块信息
`evm_get_code`	获取合约字节码（仅限Minievm）
`evm_get_storage_at`	读取存储插槽（仅限Minievm）
`evm_decode_revert`	解码还原原因
`evm_decode_logs`	使用ABI解码事件日志

科斯姆瓦斯姆（12）

工具	说明
`wasm_query`	查询智能合约
`wasm_execute`	执行智能合约功能
`wasm_store_code`	上传合同字节码
`wasm_instantiate`	立即签订合同
`wasm_migrate`	迁移到新的代码ID
`wasm_update_admin` / `wasm_clear_admin`	行政管理
`wasm_contract_info` / `wasm_code_info`	合同/代码元数据
`wasm_contracts_by_code`	根据代码ID列出合同
`wasm_contract_history`	迁移历史
`wasm_raw_state`	原始键值状态

贵宾（16）

工具	说明
`vip_stage_info`	当前VIP阶段和时间
`vip_positions`	锁定锁紧位置
`vip_voting_power`	衡量投票权
`vip_vesting_positions`	奖励明细表
`vip_vote_info`	每座桥的投票分配
`vip_claimable_rewards`	可申请的VIP奖励
`vip_delegate` / `vip_undelegate` / `vip_redelegate`	锁桩管理
`vip_extend_lock`	延长锁定时间
`vip_gauge_vote` / `vip_gauge_vote_by_amount`	计量投票
`vip_claim_rewards` / `vip_claim_staking_rewards`	领取奖励
`vip_provide_and_delegate`	LP+一次锁定委托
`vip_stableswap_provide_and_delegate`	Stableswap LP+锁代表

事件解析（3）

工具	说明
`event_parse_tx`	从事务中解析Cosmos事件
`event_parse_move`	解码移动模块事件
`event_parse_wasm`	解码CosmWasm合约事件

分类账（2）

工具	说明
`ledger_status`	检查分类账设备连接
`ledger_verify_address`	在设备上显示地址以供验证

银行（1）

工具	说明
`bank_send`	发送令牌（支持批量发送）

建筑

src/
├── index.ts              # MCP server entry point (stdio)
├── cli.ts                # CLI entry point (initctl)
├── tools/
│   ├── registry.ts       # ToolRegistry — shared by MCP and CLI
│   ├── groups.ts         # Group definitions (24 groups)
│   ├── index.ts          # Side-effect imports for all tool files
│   ├── tx-executor.ts    # Mutation flow (dry-run → simulate → broadcast)
│   ├── vm-guard.ts       # VM compatibility checks
│   └── *.ts              # Tool modules (registry.register() calls)
├── mcp/
│   └── adapter.ts        # Registry → McpServer binding
├── cli/
│   ├── adapter.ts        # Registry → citty commands + zodToCittyArgs
│   ├── format.ts         # TTY / JSON output formatting
│   ├── confirm.ts        # Mutation y/N prompt
│   └── completion.ts     # Shell completion (bash/zsh/fish)
├── initia/
│   └── chain-manager.ts  # Chain context creation, caching
├── config/               # Environment config, chain aliases
├── schemas/              # Shared Zod parameter schemas
├── errors.ts             # Typed error codes
├── response.ts           # Response serialization
└── logger.ts             # Structured JSON logging

工具在运输无关系统中注册一次 ToolRegistryMCP和CLI适配器独立使用相同的注册表——向 *.ts 文件会自动在两个接口中公开它。

智能默认值

按名称验证：接受验证器地址的工具也接受名字对象名称（不区分大小写，自动解析）
“我”地址：接受地址参数 "me", "self", "my"，或 "signer" 解析为配置的签名者
VM防护：合约工具强制VM兼容性--调用 move_view 在MiniEVM链上返回 WRONG_VM 建议的替代方案有误

发展

npm run dev          # Run MCP server with tsx (hot reload)
npm test             # Unit + integration tests
npm run test:smoke   # E2E tests against testnet
npm run lint         # ESLint + tsc --noEmit

许可证

阿帕奇-2.0