Neo N3 MCP 服务器

这是一个提供与 Neo N3 区块链无缝集成的 MCP 服务器，允许 Claude 与区块链数据交互、管理钱包、转移资产和调用智能合约。

📚 文档

• 网站 - 包含文档、用户指南和示例的综合网站
• API 参考 - 所有工具和资源的详细 API 文档
• 部署指南 - 综合部署选项和配置
• 测试指南 - 测试方法及验证功能的说明
• 架构 - 详细的系统架构和设计决策
• 网络架构 - 双网络支持及配置详情

🚀 功能

• 双网络支持：在单个服务器中同时与 Neo N3 主网和测试网进行交互
• 区块链信息：查询区块链高度、验证者和网络状态
• 区块与交易数据：获取关于区块和交易的详细信息
• 账户管理：检查余额、安全地创建和导入钱包
• 资产操作：在地址之间转移 NEO、GAS 和其他代币
• 智能合约交互：在 Neo N3 区块链上部署和调用智能合约
• 知名合约支持：与 NeoFS、NeoBurger、Flamingo、NeoCompound、GrandShare 和 GhostMarket 进行交互
• 交易监控：带有确认跟踪的详细交易状态检查
• Gas 费估算：在执行转账前计算预估的 Gas 费
• 弹性 RPC 通信：具有指数退避机制的自动重试机制
• 注重安全性：输入验证、安全的钱包存储和私钥保护
• Docker 支持：使用 Docker 和 Docker Compose 轻松部署
• 一键安装：简单的设置过程以实现 Claude 集成

🔄 v1.0.8 的新特性

• 增强的RPC可靠性：使用安全的HTTPS端点连接两个网络：
  • 主网：https://mainnet1.neo.coz.io:443
  • 测试网：https://testnet1.neo.coz.io:443
• 全面的网站：新网站提供详细的文档、用户指南和集成示例
• 改进的开发工具：添加了重建脚本和支持暗模式
• 更好的文档：增强了文档的组织结构和可读性

MCP配置

您可以轻松地以多种方式将Neo N3 MCP服务器添加到您的Claude MCP配置中：

使用NPM（快速启动推荐）

在您的claude_desktop_config.json或MCP设置中添加以下内容：

{
  "mcpServers": {
    "neo-n3": {
      "command": "npx",
      "args": [
        "-y",
        "@r3e/neo-n3-mcp"
      ]
    }
  }
}

这将自动下载并运行Neo N3 MCP服务器，而无需本地安装。

使用Docker

在您的claude_desktop_config.json或MCP设置中添加以下内容：

{
  "mcpServers": {
    "neo-n3": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "r3e/neo-n3-mcp"
      ]
    }
  }
}

要本地构建Docker镜像：

docker build -t r3e/neo-n3-mcp .

安装

使用Docker（推荐）

# Clone the repository
git clone https://github.com/R3E-Network/neo-n3-mcp.git
cd neo-n3-mcp

# Start the server with Docker Compose
docker-compose up -d

手动安装

# Clone the repository
git clone https://github.com/R3E-Network/neo-n3-mcp.git
cd neo-n3-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Start the server
npm start

添加到MCP设置

要将Neo N3 MCP服务器添加到您的MCP设置中，可以使用提供的脚本：

# Build the project first
npm run build

# Add to MCP settings
npm run add-to-mcp

这会自动将Neo N3 MCP服务器添加到您的Claude MCP设置文件中，使其可用于与Claude一起使用。

配置

该服务器可以通过环境变量进行配置：

• NEO_RPC_URL: Neo N3 RPC节点的默认URL (默认: https://mainnet1.neo.coz.io:443)
• NEO_MAINNET_RPC_URL: Neo N3主网RPC节点的URL (默认: 与NEO_RPC_URL相同或https://mainnet1.neo.coz.io:443)
• NEO_TESTNET_RPC_URL: Neo N3测试网RPC节点的URL (默认: https://testnet1.neo.coz.io:443)
• NEO_NETWORK: 默认网络类型: 'mainnet' 或 'testnet' (默认: mainnet)
• WALLET_PATH: 钱包文件路径 (默认: ./wallets)
• LOG_LEVEL: 日志级别: 'debug', 'info', 'warn', 'error' (默认: info)
• LOG_CONSOLE: 是否记录到控制台 (默认: true)
• LOG_FILE: 是否记录到文件 (默认: false)
• LOG_FILE_PATH: 日志文件路径 (默认: ./logs/neo-n3-mcp.log)
• MAX_REQUESTS_PER_MINUTE: 每分钟最大请求数 (默认: 60)
• REQUIRE_CONFIRMATION: 对敏感操作是否需要确认 (默认: true)

使用

工具

所有工具现在都支持一个可选的network参数来指定使用的网络('mainnet'或'testnet')。

get_blockchain_info

获取关于Neo N3区块链的一般信息。

{
  "name": "get_blockchain_info",
  "arguments": {
    "network": "testnet"
  }
}

get_block

通过高度或哈希获取区块详情。

{
  "name": "get_block",
  "arguments": {
    "hashOrHeight": 12345,
    "network": "mainnet"
  }
}

get_transaction

通过哈希获取交易详情。

{
  "name": "get_transaction",
  "arguments": {
    "txid": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890",
    "network": "testnet"
  }
}

get_balance

获取特定地址的账户余额。

{
  "name": "get_balance",
  "arguments": {
    "address": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ",
    "network": "mainnet"
  }
}

transfer_assets

在地址之间转移资产。

{
  "name": "transfer_assets",
  "arguments": {
    "fromWIF": "KwDZGCUXYAB1cUNmZKQ5RFUBAYPjwXvpavQQHvpeH1qM5pJ3zurn",
    "toAddress": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ",
    "asset": "NEO",
    "amount": "1",
    "confirm": true,
    "network": "testnet"
  }
}

invoke_contract

调用智能合约方法。

{
  "name": "invoke_contract",
  "arguments": {
    "fromWIF": "KwDZGCUXYAB1cUNmZKQ5RFUBAYPjwXvpavQQHvpeH1qM5pJ3zurn",
    "scriptHash": "0x8c23f196d8a1bfd103a9dcb1f9ccf0c611377d3b",
    "operation": "transfer",
    "args": [
      {
        "type": "Hash160",
        "value": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ"
      },
      {
        "type": "Hash160",
        "value": "NXV7ZhHiyM1aHXwvUNBLNAkCwZ6wgeKyMZ"
      },
      {
        "type": "Integer",
        "value": "1"
      },
      {
        "type": "Any",
        "value": null
      }
    ],
    "confirm": true,
    "network": "testnet"
  }
}

create_wallet

创建一个新的钱包。

{
  "name": "create_wallet",
  "arguments": {
    "password": "your-secure-password",
    "network": "mainnet"
  }
}

import_wallet

从WIF或加密密钥导入现有钱包。

{
  "name": "import_wallet",
  "arguments": {
    "key": "KwDZGCUXYAB1cUNmZKQ5RFUBAYPjwXvpavQQHvpeH1qM5pJ3zurn",
    "password": "your-secure-password",
    "network": "testnet"
  }
}

资源

Neo N3 网络状态

默认网络（基于配置）：

neo://network/status

特定网络：

neo://mainnet/status
neo://testnet/status

Neo N3 区块高度

默认网络：

neo://block/{height}

特定网络：

neo://mainnet/block/{height}
neo://testnet/block/{height}

Neo N3 地址余额

默认网络：

neo://address/{address}/balance

特定网络：

neo://mainnet/address/{address}/balance
neo://testnet/address/{address}/balance

测试

Neo N3 MCP 服务器包括全面的测试以确保其功能。有两种主要方式运行测试：

使用 Jest（TypeScript 测试）

Jest 测试提供全面的测试，并带有适当的模拟：

# Install dependencies first
npm install

# Run Jest tests
npm test

测试套件包括以下内容的测试：

• 区块链信息检索
• 区块和交易数据访问
• 账户余额查询
• 钱包创建和导入
• 资产转移
• 智能合约调用

使用简单的测试运行器（JavaScript）

还有一个简化的 JavaScript 测试运行器，用于快速测试：

# Run the simplified test
node tests/simple-test.js

这个测试涵盖了核心 API 功能，而无需 TypeScript 编译。

开发和贡献

发布

要将包发布到 NPM 和/或 Docker 注册表：

# Publish to NPM
npm run publish:npm

# Build and publish Docker image
npm run publish:docker

# Publish to both
npm run publish:all

开发设置

对于开发，请使用：

# Build with TypeScript watching
npm run dev

安全考虑

• 私钥永远不会在响应中暴露
• 敏感操作（如转账、合约调用）需要明确确认
• 对所有参数进行输入验证
• 错误消息设计为提供信息而不暴露敏感信息

技术细节

服务架构

Neo N3 MCP 服务器围绕几个关键组件构建：

1. MCP 接口：实现在 src/index.ts - 处理 MCP 协议通信
2. Neo 服务：实现在 src/services/neo-service.ts - 核心 Neo N3 区块链交互
3. 验证：实现在 src/utils/validation.ts - 参数验证
4. 错误处理：实现在 src/utils/error-handler.ts - 标准化错误响应

错误处理

通过 handleError 函数标准化错误，该函数：

• 将 Neo N3 特定的错误转换为用户友好的消息
• 隐藏敏感信息
• 向用户提供清晰的操作信息

网络

服务器在连接到 Neo N3 区块链网络时自动处理网络重试和错误。可以通过环境变量配置连接参数，如超时时间和重试次数。

项目结构

项目组织如下：

neo-n3-mcp/
├── src/
│   ├── services/
│   │   └── neo-service.ts       # Core Neo N3 blockchain interaction
│   ├── utils/
│   │   ├── validation.ts        # Input validation
│   │   └── error-handler.ts     # Error handling and responses
│   ├── config.ts                # Configuration settings
│   └── index.ts                 # MCP server and tool definitions
├── tests/
│   ├── neo-service.test.ts      # Jest tests for NeoService
│   └── simple-test.js           # Simple JavaScript test runner
├── scripts/
│   ├── add-to-mcp-settings.js   # Script to add to MCP settings
│   ├── publish-npm.js           # Script to publish to NPM
│   └── publish-docker.sh        # Script to build and publish Docker image
├── wallets/                     # Wallet storage directory
├── dist/                        # Compiled TypeScript output
├── docker-compose.yml           # Docker Compose configuration
├── Dockerfile                   # Docker container definition
├── package.json                 # Node.js package definition
└── tsconfig.json                # TypeScript configuration

致谢

如果没有以下支持，本项目是不可能完成的：

• @cityofzion/neon-js - Neo N3 区块链的官方 JavaScript SDK，提供了与 Neo N3 网络交互的核心功能。特别感谢 City of Zion 团队对这一重要库的持续开发和维护。
• MCP 协议 - 为 AI 系统提供与外部工具和资源交互的标准协议。

许可证

此 MCP 服务器根据 MIT 许可证发布。详情请参阅 LICENSE 文件。

著名的 Neo N3 合约支持

Neo N3 MCP 服务器现在包括与以下著名 Neo N3 合约交互的支持：

• NeoFS: 基于 Neo N3 区块链的去中心化存储系统
• NeoBurger: Neo N3 质押服务
• Flamingo (FLM): Neo N3 DeFi 平台
• NeoCompound: Neo N3 上的自动收益耕作协议
• GrandShare: Neo N3 上的利润分享协议
• GhostMarket: Neo N3 上的 NFT 市场

合约工具

列表和信息

• list_famous_contracts: 列出所有支持的著名 Neo N3 合约
• get_contract_info: 获取特定著名合约的详细信息

NeoFS 工具

• neofs_create_container: 在 NeoFS 中创建一个存储容器
• neofs_get_containers: 获取地址拥有的容器

NeoBurger 工具

• neoburger_deposit: 存入 NEO 到 NeoBurger 以获得 bNEO 代币
• neoburger_withdraw: 通过返还 bNEO 代币从 NeoBurger 提取 NEO
• neoburger_get_balance: 获取账户的 bNEO 余额
• neoburger_claim_gas: 从 NeoBurger 领取累积的 GAS 奖励

Flamingo 工具

• flamingo_stake: 在 Flamingo 上质押 FLM 代币
• flamingo_unstake: 从 Flamingo 解除质押 FLM 代币
• flamingo_get_balance: 获取 FLM 代币余额

NeoCompound 工具

• neocompound_deposit: 将资产存入 NeoCompound
• neocompound_withdraw: 从 NeoCompound 提取资产
• neocompound_get_balance: 获取在 NeoCompound 中存款资产的余额

GrandShare 工具

• grandshare_deposit: 将资产存入 GrandShare 池
• grandshare_withdraw: 从 GrandShare 池中提取资产
• grandshare_get_pool_details: 获取 GrandShare 池的详细信息

GhostMarket 工具

• ghostmarket_create_nft: 在 GhostMarket 上创建一个新的 NFT
• ghostmarket_list_nft: 在 GhostMarket 上列出待售的 NFT
• ghostmarket_buy_nft: 在 GhostMarket 上购买已列出的 NFT
• ghostmarket_get_token_info: 获取 GhostMarket 上 NFT 的信息

示例

获取著名合约列表

const result = await callTool('list_famous_contracts', {
  network: 'mainnet'
});

获取合约信息

const result = await callTool('get_contract_info', {
  contractName: 'flamingo',
  network: 'mainnet'
});

存款到 NeoBurger

const result = await callTool('neoburger_deposit', {
  fromWIF: 'your-private-key-wif-format',
  confirm: true,
  network: 'mainnet'
});

在 Flamingo 上质押

const result = await callTool('flamingo_stake', {
  fromWIF: 'your-private-key-wif-format',
  amount: '100',
  confirm: true,
  network: 'mainnet'
});

存款到 NeoCompound

const result = await callTool('neocompound_deposit', {
  walletPath: '/path/to/wallet.json',
  walletPassword: 'your-password',
  assetId: '0xd2a4cff31913016155e38e474a2c06d08be276cf',
  amount: '100',
  network: 'mainnet'
});

在 GhostMarket 上创建 NFT

const result = await callTool('ghostmarket_create_nft', {
  walletPath: '/path/to/wallet.json',
  walletPassword: 'your-password',
  tokenURI: 'https://example.com/nft/metadata.json',
  properties: [
    { key: "artist", value: "ExampleArtist" },
    { key: "edition", value: "1/1" }
  ],
  network: 'mainnet'
});

获取 GrandShare 池详细信息

const result = await callTool('grandshare_get_pool_details', {
  poolId: 1,
  network: 'mainnet'
});