新核-n3-mcp

Name: 新核-n3-mcp
Author: r3e-network

作者：r3e-network4 星标更新：2025-07-07

安装使用来源：spider==github.com

项目介绍

Neo N3 MCP 服务器

Neo N3 区块链集成的 MCP 服务器 | 版本 1.6.0

一个生产就绪的 MCP 服务器，提供与 Neo N3 区块链的集成，包括 34 个工具和 9 个资源，用于钱包管理、资产转移、合约交互和区块链查询。

🚀 快速开始

从 NPM 安装

# 全局安装
npm install -g @r3e/neo-n3-mcp

# 或者本地安装
npm install @r3e/neo-n3-mcp

基本用法

# 使用默认配置运行
npx @r3e/neo-n3-mcp

# 或者如果全局安装了
neo-n3-mcp

⚙️ 配置

1. 命令行配置

# 指定网络
neo-n3-mcp --network testnet

# 自定义 RPC 端点
neo-n3-mcp --mainnet-rpc https://mainnet1.neo.coz.io:443 --testnet-rpc https://testnet1.neo.coz.io:443

# 启用日志
neo-n3-mcp --log-level info --log-file ./neo-mcp.log

# 完整示例
neo-n3-mcp \
  --network mainnet \
  --mainnet-rpc https://mainnet1.neo.coz.io:443 \
  --testnet-rpc https://testnet1.neo.coz.io:443 \
  --log-level debug \
  --log-file ./logs/neo-mcp.log

2. JSON 配置

创建一个 neo-mcp-config.json 文件：

{
  "network": "mainnet",
  "rpc": {
    "mainnet": "https://mainnet1.neo.coz.io:443",
    "testnet": "https://testnet1.neo.coz.io:443"
  },
  "logging": {
    "level": "info",
    "file": "./logs/neo-mcp.log",
    "console": true
  },
  "server": {
    "name": "neo-n3-mcp-server",
    "version": "1.6.0"
  },
  "wallets": {
    "directory": "./wallets"
  }
}

使用配置文件运行：

neo-n3-mcp --config ./neo-mcp-config.json

3. Docker 配置

使用 Docker Hub 镜像

# 基础运行
docker run -p 3000:3000 r3enetwork/neo-n3-mcp:1.6.0

# 使用环境变量
docker run -p 3000:3000 \
  -e NEO_NETWORK=mainnet \
  -e NEO_MAINNET_RPC=https://mainnet1.neo.coz.io:443 \
  -e NEO_TESTNET_RPC=https://testnet1.neo.coz.io:443 \
  -e LOG_LEVEL=info \
  r3enetwork/neo-n3-mcp:1.6.0

# 使用卷保存持久数据
docker run -p 3000:3000 \
  -v $(pwd)/wallets:/app/wallets \
  -v $(pwd)/logs:/app/logs \
  -e NEO_NETWORK=testnet \
  r3enetwork/neo-n3-mcp:1.6.0

Docker Compose

创建一个 docker-compose.yml 文件：

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

运行：

docker-compose up -d

🐳 Docker 快速开始

# 使用 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

# 或手动构建和运行
npm run docker:build
npm run docker:run

# 开发模式
npm run docker:up:dev

生产 Docker 设置

# 构建生产镜像
./scripts/docker-build.sh --tag v1.6.0

# 使用自定义配置运行
docker run -d \
  --name neo-mcp-prod \
  -p 3000:3000 \
  -e NEO_NETWORK=mainnet \
  -v neo-mcp-logs:/app/logs \
  neo-n3-mcp:v1.6.0

开发 Docker 设置

# 构建开发镜像
./scripts/docker-build.sh --dev

# 运行带有热重载和调试
docker-compose -f docker/docker-compose.dev.yml up -d

🔧 配置选项

环境变量

变量	描述	默认值
`NEO_NETWORK`	默认网络（主网/测试网）	`testnet`
`NEO_MAINNET_RPC`	主网 RPC 端点	`https://mainnet1.neo.coz.io:443`
`NEO_TESTNET_RPC`	测试网 RPC 端点	`https://testnet1.neo.coz.io:443`
`LOG_LEVEL`	日志级别（debug/info/warn/error）	`info`
`LOG_FILE`	日志文件路径	`./logs/neo-mcp.log`
`WALLET_DIR`	钱包存储目录	`./wallets`

命令行选项

选项	描述
`--network`	设置默认网络
`--mainnet-rpc`	主网 RPC URL
`--testnet-rpc`	测试网 RPC URL
`--log-level`	设置日志级别
`--log-file`	设置日志文件路径
`--config`	从 JSON 文件加载配置
`--help`	显示帮助信息

🛠️ MCP 客户端集成

Claude Desktop

添加到你的 Claude Desktop 配置中（~/.cursor/mcp.json 或类似文件）：

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": [
        "-y",
        "@r3e/neo-n3-mcp",
        "--network",
        "testnet"
      ],
      "disabled": false,
      "env": {
        "NEO_NETWORK": "testnet",
        "LOG_LEVEL": "info"
      }
    }
  }
}

对于主网配置：

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": [
        "-y",
        "@r3e/neo-n3-mcp",
        "--network",
        "mainnet"
      ],
      "disabled": false,

      "env": {
        "NEO_NETWORK": "mainnet",
        "NEO_MAINNET_RPC": "https://mainnet1.neo.coz.io:443",
        "NEO_TESTNET_RPC": "https://testnet1.neo.coz.io:443",
        "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: ['@r3e/neo-n3-mcp', '--network', 'mainnet']
});

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

await client.connect(transport);

📊 可用工具及资源

🛠️ 工具（34 个可用）

网络：get_network_mode, set_network_mode
区块链：get_blockchain_info, get_block_count, get_block, get_transaction
钱包：create_wallet, import_wallet
资产：get_balance, transfer_assets, estimate_transfer_fees
合约：invoke_contract, list_famous_contracts, get_contract_info
高级：claim_gas, estimate_invoke_fees

📁 资源（9 个可用）

网络状态：neo://network/status, neo://mainnet/status, neo://testnet/status
区块链数据：neo://mainnet/blockchain, neo://testnet/blockchain
合约注册表：neo://mainnet/contracts, neo://testnet/contracts
资产信息：neo://mainnet/assets, neo://testnet/assets

🔐 安全性

输入验证：所有输入均经过验证和清理
确认要求：敏感操作需要明确确认
私钥安全：密钥加密并安全存储
网络隔离：为主网和测试网分别配置
速率限制：生产部署可配置的速率限制
安全日志：日志中不暴露敏感数据

⚡ 性能与可靠性

速率限制：内置速率限制，具有可配置阈值
错误处理：全面的错误处理，带有适当的 MCP 错误码
网络弹性：RPC 调用的自动回退机制
生产就绪：支持 systemd 服务配置和监控

🔄 版本管理和发布流程

当前版本：1.6.0

此项目遵循语义化版本控制并通过自动化 CI/CD 管道进行发布。详情请参阅我们的版本管理指南。

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

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

# 1. 首先，执行一次干跑以查看会发生什么
./scripts/prepare-release.sh --type minor --dry-run

# 2. 如果一切看起来都很好，执行实际的发布准备
./scripts/prepare-release.sh --type minor

# 3. 推送更改（脚本会引导你完成）
git push

# 4. 创建 GitHub 发布（触发完整的 CI/CD 管道）
gh release create v1.7.0 --generate-notes

方法 2：手动 NPM 版本命令

# 查看当前版本
npm run version:check

# 手动更新版本
npm run version:patch   # 1.6.0 → 1.6.1 （修复错误）
npm run version:minor   # 1.6.0 → 1.7.0 （新功能）
npm run version:major   # 1.6.0 → 2.0.0 （重大变更）

# 然后提交并推送
git add . && git commit -m "chore: bump version to 1.7.0"
git push

方法 3：GitHub 发布（直接）

# 使用 GitHub CLI
gh release create v1.7.0 --generate-notes

# 或通过 GitHub Web 界面手动创建：
# 1. 访问 https://github.com/r3e-network/neo-n3-mcp/releases
# 2. 点击“创建新发布”
# 3. 标签：v1.7.0，标题：“发布 v1.7.0”
# 4. 自动生成发布说明
# 5. 发布

🔄 创建发布时会发生什么

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

阶段 1：测试与验证 ⚡

✅ 多版本测试：Node.js 18.x, 20.x, 22.x 在 ubuntu-latest 上
✅ 代码质量：代码检查和类型检查
✅ 单元测试：核心功能验证
✅ 覆盖率报告：自动上传至 Codecov

阶段 2：构建与 Docker 🔨

✅ TypeScript 编译：构建验证
✅ Docker 构建：开发和生产镜像
✅ 容器测试：Docker 功能验证
✅ 组合验证：配置测试

阶段 3：安全与审计 🔒

✅ 安全审计：npm audit 检查漏洞
✅ 依赖检查：audit-ci 检查安全问题
✅ 包更新：检查过时的依赖项

阶段 4：发布 📦（仅在发布时）

🚀 NPM 发布：自动发布到 npm 注册表
🐳 Docker 发布：多标签镜像发布到 Docker Hub
📋 版本标签：语义化版本控制，正确打标签

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

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

📋 发布类型

类型	版本变化	使用场景	示例
补丁	1.6.0 → 1.6.1	修复错误，安全补丁	`./scripts/prepare-release.sh --type patch`
次要	1.6.0 → 1.7.0	新功能，增强	`./scripts/prepare-release.sh --type minor`
主要	1.6.0 → 2.0.0	重大变更	`./scripts/prepare-release.sh --type major`

🎯 快速发布命令

# 对于下一个次要版本（推荐用于新功能）
./scripts/prepare-release.sh --type minor

# 对于补丁版本（修复错误）
./scripts/prepare-release.sh --type patch

# 对于主要版本（重大变更）
./scripts/prepare-release.sh --type major

# 测试会发生什么（干跑）
./scripts/prepare-release.sh --type minor --dry-run

📊 最新变更（v1.6.0）

✨ 企业 CI/CD 管道：完整的 GitHub Actions 工作流
🐳 Docker 基础设施：生产和开发环境
📁 项目组织：结构化的文件夹（docker/, docs/, scripts/）
🔧 自动化发布：NPM 和 Docker Hub 集成
📚 全面文档：所有部署场景的指南
🔄 版本管理：自动化发布准备和验证

📚 发布文档

CHANGELOG.md - 完整版本历史
VERSION_MANAGEMENT.md - 详细的发布过程
WORKFLOW.md - CI/CD 管道文档

🔐 必要的秘密（已配置）

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

📚 文档

API 参考 - 完整的 API 文档
架构 - 系统设计和组件
示例 - 实用用法示例和最佳实践
Docker 指南 - 综合的 Docker 部署指南
生产检查清单 - 生产部署指南
部署 - 部署配置
测试 - 测试和验证
网络 - 网络配置细节
版本管理 - 发布过程和版本控制
发布指南 - 触发发布的快速参考
工作流指南 - CI/CD 管道文档
变更日志 - 版本历史和变更

📄 许可证

MIT 许可证 - 详情见 LICENSE 文件。