Neo N3 MCP Server

](https://mseep.ai/app/r3e-network-neo-n3-mcp)

Neo N3 MCP服务器

用于Neo N3区块链集成的MCP服务器 |版本2.0.0

  ](https://www.npmjs.com/package/@r3e/neo-n3-mcp)

一个生产就绪的MCP服务器，提供Neo N3区块链集成，包括27个工具、3个固定资源和一个参数化块资源，用于钱包管理、交易生命周期跟踪、资产转移、合同部署、合同交互和区块链查询。

🚀 快速开始

从NPM安装

# Install globally
npm install -g @r3e/neo-n3-mcp

# Or install locally
npm install @r3e/neo-n3-mcp

基本用法

# Run with default configuration
npx @r3e/neo-n3-mcp

# Or if installed globally
neo-n3-mcp

⚙️ 配置

1.环境变量

MCP stdio服务器从环境变量中读取配置。

NEO_NETWORK=both \
NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443 \
NEO_TESTNET_RPC=http://seed1t5.neo.org:20332 \
N3INDEX_API_BASE_URL=https://api.n3index.dev \
LOG_LEVEL=info \
LOG_FILE=./logs/neo-n3-mcp.log \
npx @r3e/neo-n3-mcp

也接受向后兼容的别名：

• NEO_MAINNET_RPC_URL
• NEO_TESTNET_RPC_URL
• NEO_NETWORK_MODE

当 NEO_NETWORK=both，stdio工具调用主网时没有明确的网络默认值。HTTP入口点需要 NEO_NETWORK=mainnet 或 NEO_NETWORK=testnet.

当合约引用是一个普通名称并且不在本地著名合约注册表中时，服务器可以回退到 https://api.n3index.dev 用于在链上验证合约之前进行名称到哈希的解析。

2.MCP客户端配置

Claude/Cursor配置示例：

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": ["-y", "@r3e/neo-n3-mcp"],
      "disabled": false,
      "env": {
        "NEO_NETWORK": "testnet",
        "NEO_TESTNET_RPC": "http://seed1t5.neo.org:20332",
        "LOG_LEVEL": "info"
      }
    }
  }
}

3.Docker配置

使用Docker Hub镜像

# Basic run
docker run -p 3000:3000 \
  -e NEO_NETWORK=mainnet \
  -e LOG_CONSOLE=false \
  -e LOG_FILE=/app/logs/neo-n3-mcp.log \
  r3enetwork/neo-n3-mcp:2.0.0

# With environment variables
docker run -p 3000:3000 \
  -e NEO_NETWORK=mainnet \
  -e NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443 \
  -e NEO_TESTNET_RPC=http://seed1t5.neo.org:20332 \
  -e LOG_LEVEL=info \
  r3enetwork/neo-n3-mcp:2.0.0

# With volume for persistent data
docker run -p 3000:3000 \
  -v $(pwd)/wallets:/app/wallets \
  -v $(pwd)/logs:/app/logs \
  -e NEO_NETWORK=testnet \
  r3enetwork/neo-n3-mcp:2.0.0

Docker Compose

创建一个 docker-compose.yml:

version: '3.8'
services:
  neo-mcp:
    image: r3enetwork/neo-n3-mcp:2.0.0
    ports:
      - "3000:3000"
    environment:
      - NEO_NETWORK=mainnet
      - NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443
      - NEO_TESTNET_RPC=http://seed1t5.neo.org:20332
      - LOG_LEVEL=info
      - LOG_FILE=/app/logs/neo-n3-mcp.log
    volumes:
      - ./wallets:/app/wallets
      - ./logs:/app/logs
      - ./config:/app/config
    restart: unless-stopped

运行方式：

docker-compose up -d

🐳 Docker快速入门

# Quick start with Docker Compose
git clone https://github.com/r3e-network/neo-n3-mcp.git
cd neo-n3-mcp
docker-compose -f docker/docker-compose.yml up -d

# Or build and run manually
npm run docker:build
npm run docker:run

# Development mode
npm run docker:up:dev

生产Docker设置

# Build production image
./scripts/docker-build.sh --tag v2.0.0

# Run with custom configuration
docker run -d \
  --name neo-mcp-prod \
  -p 3000:3000 \
  -e NEO_NETWORK=mainnet \
  -v neo-mcp-logs:/app/logs \
  neo-n3-mcp:v2.0.0

开发Docker设置

# Build development image
./scripts/docker-build.sh --dev

# Run with hot reload and debugging
docker-compose -f docker/docker-compose.dev.yml up -d

🔧 配置选项

环境变量

接受旧别名：

• NEO_MAINNET_RPC_URL
• NEO_TESTNET_RPC_URL
• NEO_NETWORK_MODE

🛠️ MCP客户端集成

克劳德桌面/光标

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": ["-y", "@r3e/neo-n3-mcp"],
      "disabled": false,
      "env": {
        "NEO_NETWORK": "mainnet",
        "NEO_MAINNET_RPC": "https://mainnet1.neo.coz.io:443",
        "NEO_TESTNET_RPC": "http://seed1t5.neo.org:20332",
        "LOG_LEVEL": "info"
      }
    }
  }
}

自定义MCP客户端

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'npx',
  args: ['-y', '@r3e/neo-n3-mcp'],
  env: {
    NEO_NETWORK: 'mainnet',
    NEO_MAINNET_RPC: 'https://mainnet1.neo.coz.io:443',
    NEO_TESTNET_RPC: 'http://seed1t5.neo.org:20332',
  },
});

const client = new Client(
  { name: 'my-neo-client', version: '1.0.0' },
  { capabilities: {} }
);

await client.connect(transport);

📊 可用工具和资源

🛠️ 工具（27个可用）

• 网络: get_network_mode, set_network_mode
• 区块链: get_blockchain_info, get_block_count, get_block, get_transaction, get_application_log, wait_for_transaction
• 钱包: create_wallet, import_wallet, get_wallet
• 资产: get_balance, get_unclaimed_gas, get_nep17_transfers, get_nep11_balances, get_nep11_transfers, transfer_assets, estimate_transfer_fees
• 合同: invoke_contract, deploy_contract, list_famous_contracts, get_contract_info, get_contract_status
• NeoFS: neofs_create_container, neofs_get_containers
• 高级: claim_gas, estimate_invoke_fees

🌐 HTTP端点

• 健康与指标: /health, /metrics
• 交易: /api/transactions/:txid, /api/transactions/:txid/application-log, /api/transactions/:txid/wait
• 账户: /api/accounts/:address/balance, /api/accounts/:address/unclaimed-gas, /api/accounts/:address/nep17-transfers, /api/accounts/:address/nep11-balances, /api/accounts/:address/nep11-transfers, POST /api/accounts/claim-gas
• 积木: GET /api/blocks/:hashOrHeight
• 转账: POST /api/transfers, POST /api/transfers/estimate-fees
• 合同: GET /api/contracts/:reference, GET /api/contracts/:reference/status, POST /api/contracts/invoke, POST /api/contracts/invoke/estimate-fees, POST /api/contracts/:name/invoke, POST /api/contracts/deploy （要求 confirm=true)
• 钱包: POST /api/wallets, POST /api/wallets/import, GET /api/wallets/:address

📁 资源（3个固定+1个模板）

• 状态: neo://network/status, neo://mainnet/status, neo://testnet/status
• 参数化块: neo://block/{height}

🔐 安全

• 输入验证：所有输入都经过验证和消毒
• 需要确认：敏感操作需要明确确认
• 私钥安全：密钥加密并安全存储
• 网络隔离：主网/测试网的单独配置
• 速率限制：可配置的生产部署速率限制
• 安全日志记录：日志中没有暴露敏感数据

⚡ 性能和可靠性

• 速率限制：内置速率限制，可配置阈值
• 错误处理：使用适当的MCP错误代码进行全面的错误处理
• 网络弹性：RPC调用的自动回退机制
• 生产就绪：系统化服务配置和监控支持

🔄 版本管理和发布流程

当前版本：2.0.0

🚀 如何触发下一个版本发布

方法1：自动发布脚本（推荐）

# 1. First, do a dry run to see what will happen
./scripts/prepare-release.sh --type minor --dry-run

# 2. If everything looks good, run the actual release preparation
./scripts/prepare-release.sh --type minor

# 3. Push the changes (script will guide you)
git push

# 4. Create GitHub release (triggers full CI/CD pipeline)
gh release create v2.1.0 --generate-notes

方法2：手动NPM版本命令

# Check current version
npm run version:check

# Bump version manually
npm run version:patch   # 2.0.0 → 2.0.1 (bug fixes)
npm run version:minor   # 2.0.0 → 2.1.0 (new features)
npm run version:major   # 2.0.0 → 3.0.0 (breaking changes)

# Then commit and push
git add . && git commit -m "chore: bump version to 2.1.0"
git push

方法3：GitHub发布（直接）

# Using GitHub CLI
gh release create v2.1.0 --generate-notes

# Or manually through GitHub web interface:
# 1. Go to https://github.com/r3e-network/neo-n3-mcp/releases
# 2. Click "Create a new release"
# 3. Tag: v2.1.0, Title: "Release v2.1.0"
# 4. Auto-generate release notes
# 5. Publish release

🔄 创建发布时会发生什么

自动化的CI/CD管道会触发以下工作流程：

第一阶段：测试与验证 ⚡

• ✅ 多版本测试：ubuntu上最新的Node.js 18.x、20.x、22.x
• ✅ 代码质量：过梁和类型检查
• ✅ 单元测试：核心功能验证
• ✅ 覆盖率报告：自动上传到Codecov

第二阶段：构建和Docker 🔨

• ✅ TypeScript编译：构建验证
• ✅ Docker构建：开发和生产图像
• ✅ 集装箱测试：Docker功能验证
• ✅ 编写验证：配置测试

第三阶段：安全与审计 🔒

• ✅ 安全审计：npm漏洞审计
• ✅ 依赖性检查：安全问题审计ci
• ✅ 程序包更新：检查过时的依赖关系

第四阶段：出版 📦 （仅在发布时）

• 🚀 NPM出版：自动将包发布到npm注册表
• 🐳 Docker发布：将多标签映像发布到Docker Hub
• 📋 版本化标签：具有适当标记的语义版本控制

第五阶段：部署 🌐 （仅在发布时）

• 🎯 生产部署：自动部署通知
• 📊 发布跟踪：版本监控和验证

📋 释放类型

🎯 快速释放命令

# For next minor release (recommended for new features)
./scripts/prepare-release.sh --type minor

# For patch release (bug fixes)
./scripts/prepare-release.sh --type patch

# For major release (breaking changes)
./scripts/prepare-release.sh --type major

# Test what would happen (dry run)
./scripts/prepare-release.sh --type minor --dry-run

📊 最新更改（v2.0.0）

• ✅ npm依赖：将供应商提供的neon js 3.x替换为 @cityofzion/neon-js@5.x 来自npm——不再捆绑供应商代码
• ✅ 全类型安全：零 any 生产代码中的类型——正确的neonjs类型贯穿整个代码库
• ✅ 强制限速：速率限制现在已集成到HTTP和MCP请求管道中（已定义但从未调用）
• ✅ 配置验证：服务器在启动时验证环境变量，并快速失败，出现描述性错误
• ✅ 日志轮转：日志以10MB的速度轮换，最多保留3个轮换文件
• ✅ 清洁包装表面：只有dist/、README.md和LICENSE在npm tarball中提供

📚 发布文件

• 更改日志.md -完整的版本历史记录
• 版本_管理.md -详细的发布流程
• 工作流.md -CI/CD管道文件

🔐 所需密钥（已配置）

• ✅ NPM_TOKEN -用于NPM注册表发布
• ✅ DOCKER_USERNAME -Docker Hub用户名
• ✅ DOCKER_PASSWORD -Docker Hub访问令牌

📚 文档

• api参考 -完整的API文件
• 建筑 -系统设计和组件
• 例子 -实际使用示例和最佳实践
• **** -全面的Docker部署指南
• 生产清单 -生产部署指南
• 部署 -部署配置
• 测试 -测试和验证
• 网络 -网络配置详细信息
• 版本管理 -发布流程和版本控制
• 发布指南 -触发发布的快速参考
• 工作流程指南 -CI/CD管道文件
• 更新日志 -版本历史和更改
• 迁移指南 -从v1.x升级到v2.0

故障排除

安装问题

• neon js安装失败：确保你的Node.js>=18。跑 npm cache clean --force 然后重试。
• TypeScript错误：此包附带类型定义。确保您的 @types/node 版本与您的Node.js版本匹配。

运行时问题

• “超出费率限制”：服务器强制执行速率限制（默认值：60 req/min）。配置为 MAX_REQUESTS_PER_MINUTE 或禁用 RATE_LIMITING_ENABLED=false.
• “配置无效”：服务器在启动时验证配置。检查哪个值错误的错误消息。
• RPC连接错误：验证您的RPC URL是否可访问。默认主网： https://mainnet1.neo.coz.io:443

📄 许可证

MIT许可证-请参阅 许可证 文件以获取详细信息。

🔗 链接

• NPM包: https://www.npmjs.com/package/@r3e/neo-n3-mcp
• Neo N3文档: https://docs.neo.org/
• MCP协议: https://modelcontextprotocol.io/