Neo N3 MCP 服务器

<p align="center"> <img src="logo/logo.png" alt="Neo N3 Logo" width="100"/> </p>

一个 MCP 服务器，提供与 Neo N3 区块链的无缝集成，允许 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（推荐）

# 克隆存储库
git clone https://github.com/R3E-Network/neo-n3-mcp.git
cd neo-n3-mcp

# 使用 Docker Compose 启动服务器
docker-compose up -d

手动安装

# 克隆存储库
git clone https://github.com/R3E-Network/neo-n3-mcp.git
cd neo-n3-mcp

# 安装依赖项
npm install

# 构建项目
npm run build

# 启动服务器
npm start

添加到 MCP 设置

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

# 首先构建项目
npm run build

# 添加到 MCP 设置
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 测试提供全面的测试和适当的模拟：

# 首先安装依赖项
npm install

# 运行 Jest 测试
npm test

测试套件包括以下测试：

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

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

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

# 运行简化的测试
node tests/simple-test.js

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

开发和贡献

发布

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

# 发布到 NPM
npm run publish:npm

# 构建和发布 Docker 镜像
npm run publish:docker

# 发布到两者
npm run publish:all

开发设置

对于开发，请使用：

# 使用 TypeScript 监视进行构建
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       # 核心 Neo N3 区块链交互
│   ├── utils/
│   │   ├── validation.ts        # 输入验证
│   │   └── error-handler.ts     # 错误处理和响应
│   ├── config.ts                # 配置设置
│   └── index.ts                 # MCP 服务器和工具定义
├── tests/
│   ├── neo-service.test.ts      # NeoService 的 Jest 测试
│   └── simple-test.js           # 简单的 JavaScript 测试运行器
├── scripts/
│   ├── add-to-mcp-settings.js   # 用于添加到 MCP 设置的脚本
│   ├── publish-npm.js           # 用于发布到 NPM 的脚本
│   └── publish-docker.sh        # 用于构建和发布 Docker 镜像的脚本
├── wallets/                     # 钱包存储目录
├── dist/                        # 编译的 TypeScript 输出
├── docker-compose.yml           # Docker Compose 配置
├── Dockerfile                   # Docker 容器定义
├── package.json                 # Node.js 包定义
└── tsconfig.json                # TypeScript 配置

致谢

如果没有以下内容，这个项目是不可能实现的：

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