Neo N3 MCP 服务器

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

📚 文档

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

🚀 功能

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

🔄 v1.0.8 中的新功能

增强的 RPC 可靠性：对两个网络使用安全的 HTTPS 端点：
- 主网： https://mainnet1.neo.coz.io:443 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）
NEO_NETWORK_MODE ：网络模式：'mainnet_only'、'testnet_only' 或 'both'（默认值：both）
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）

用法

网络配置工具

服务器提供了在运行时获取和设置网络模式的工具：

获取网络模式

获取当前网络模式配置。

{
  "name": "get_network_mode",
  "arguments": {}
}

设置网络模式

设置主动网络模式。

{
  "name": "set_network_mode",
  "arguments": {
    "mode": "testnet_only"
  }
}

区块链工具

所有工具都支持可选的network参数来指定要使用的网络（“主网”或“测试网”）。

获取区块链信息

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

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

获取块

通过高度或哈希值获取区块详细信息。

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

获取交易

通过哈希获取交易详情。

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

获取余额

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

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

转移资产

在地址之间转移资产。

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

调用合约

调用智能合约方法。

{
  "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"
  }
}

创建钱包

创建一个新的钱包。

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

导入钱包

从 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 all Jest tests
npm test

# Run specific test files
npx jest tests/utils/validation.test.ts
npx jest tests/contracts/contract-service.test.ts

该测试套件包括以下测试：

核心服务：
- Neo 服务（区块链交互）
- 合约服务（智能合约交互）
实用程序：
- 验证（输入参数验证）
- 错误处理（标准化错误响应）
- 缓存（带 TTL 的内存缓存）
- 速率限制（请求节流）
网站组件：
- 主页功能
- 文档页面导航
- API 游乐场交互
- 区块浏览器功能
- 聊天界面

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

简化的 JavaScript 测试运行器也可用于快速测试：

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

# Run network test
node tests/network-test.js

# Run transaction status test
node tests/transaction-status-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 服务器由几个关键组件构成：

MCP 接口：在src/index.ts中实现 - 处理 MCP 协议通信
Neo 服务：在src/services/neo-service.ts中实现 - 核心 Neo N3 区块链交互
验证：在src/utils/validation.ts中实现 - 参数验证
错误处理：在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 许可证。详情请参阅许可证文件。

著名的 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_stake ：在 Flamingo 上质押 FLM 代币
flamingo_unstake ：从 Flamingo 中取消质押的 FLM 代币
flamingo_get_balance ：获取 FLM 代币余额

NeoCompound 工具

neocompound_deposit ：将资产存入 NeoCompound
neocompound_withdraw ：从 NeoCompound 提取资产
neocompound_get_balance ：获取 NeoCompound 中存入资产的余额

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'
});

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

Integrations