纳米_MCP_服务器

Name: 纳米_MCP_服务器
Author: dhyabi2

作者：dhyabi22 星标更新：2025-11-22

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

项目介绍

NANO MCP Server - AI Agent 集成指南

针对AI代理: 该服务器专为自主代理设计。所有错误都具有逐步指导，并自动生成文档。无需外部文档。

🌐 生产服务器地址

使用此URL: https://nano-mcp.replit.app

所有请求发送到: https://nano-mcp.replit.app (使用JSON-RPC 2.0格式的POST请求)

快速示例:

curl -X POST https://nano-mcp.replit.app \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

🤖 AI代理快速入门

生产服务器（推荐）

服务器地址: https://nano-mcp.replit.app

无需安装！ 服务器已经运行，只需开始发送请求即可。

第一步：测试连接

POST https://nano-mcp.replit.app
{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {},
    "id": 1
}

第二步：准备就绪！

服务器会返回所有可用的方法。立即开始使用它们。

🔍 JSON模式自动发现（新功能！）

零样本集成对于AI代理

🎯 不需要阅读文档！ 获取完整的JSON模式并自动生成客户端代码：

# 获取包含所有16个工具的完整JSON模式
GET https://nano-mcp.replit.app/schema

# 获取TypeScript定义
GET https://nano-mcp.replit.app/schema/typescript

# 获取OpenAPI 3.0规范（兼容Swagger）
GET https://nano-mcp.replit.app/openapi.json

模式特性

✅ 输入/输出模式 - 具有验证模式的完整JSON模式
✅ 即用示例 - 每个工具的复制粘贴示例
✅ 类型定义 - TypeScript .d.ts用于类型安全客户端
✅ 参数验证 - 地址、密钥、金额的正则表达式模式
✅ 错误模式 - 所有29个错误代码及其处理指导
✅ 性能提示 - 预期持续时间和超时建议
✅ 前提条件 - 每个操作的依赖信息

快速模式使用

# 获取特定工具的模式
GET https://nano-mcp.replit.app/schema/tools/sendTransaction

# 获取工具的示例
GET https://nano-mcp.replit.app/schema/examples/generateWallet

# 发送前验证参数
POST https://nano-mcp.replit.app/schema/validate/sendTransaction
{ "fromAddress": "...", "toAddress": "...", "amountRaw": "...", "privateKey": "..." }

# 按类别获取工具（查询、事务、实用程序等）
GET https://nano-mcp.replit.app/schema/category/transaction

# 获取所有错误代码
GET https://nano-mcp.replit.app/schema/errors

代码生成示例

// 1. 下载TypeScript定义
// curl https://nano-mcp.replit.app/schema/typescript > nano-mcp.d.ts

// 2. 导入类型
import type { SendTransactionParams, SendTransactionResult } from './nano-mcp';

// 3. 使用全类型安全性
const params: SendTransactionParams = {
  fromAddress: "nano_...",
  toAddress: "nano_...",
  amountRaw: "1000000000000000000000000000",
  privateKey: "..."
};  // TypeScript验证所有字段！

📖 完整指南: 查看docs/JSON_SCHEMA_AI_AGENT_GUIDE.md以了解详细的模式集成模式。

⏱️ 预计集成时间: 5分钟（与数小时的文档阅读相比）

本地开发（可选）

如果需要在本地运行进行开发：

cd NANO_MCP_SERVER
npm install
npm start

本地服务器运行于: http://localhost:8080

⚡ 最快集成路径（AI代理：从这里开始）

整个工作流程在5-6次调用，30-60秒内完成：

// 步骤1：设置测试钱包（1次调用，< 1秒）
POST https://nano-mcp.replit.app
{"jsonrpc":"2.0","method":"setupTestWallets","params":{},"id":1}
→ 返回: 钱包地址 + 私钥

// 步骤2：人类资金两个地址（等待30-60秒）
// → 向每个地址发送0.1+ NANO

// 步骤3：并行检查两个钱包（2次调用，4-6秒）
POST https://nano-mcp.replit.app
{"jsonrpc":"2.0","method":"getAccountStatus","params":{"address":"wallet1_address"},"id":1}
{"jsonrpc":"2.0","method":"getAccountStatus","params":{"address":"wallet2_address"},"id":2}
→ 返回: 余额，待处理区块，需要操作

// 步骤4：自动跟进需要的操作（2次调用，16-24秒）
POST https://nano-mcp.replit.app
{"jsonrpc":"2.0","method":"initializeAccount","params":{"address":"wallet1","privateKey":"key1"},"id":1}
{"jsonrpc":"2.0","method":"initializeAccount","params":{"address":"wallet2","privateKey":"key2"},"id":2}
→ 返回: 初始化确认

// 步骤5：发送交易（1次调用，10-15秒）
POST https://nano-mcp.replit.app
{"jsonrpc":"2.0","method":"sendTransaction","params":{
  "fromAddress":"wallet1",
  "toAddress":"wallet2",
  "amountRaw":"50000000000000000000000000",
  "privateKey":"key1"
},"id":1}
→ 返回: 交易哈希

// 完成！✅ 总共: 6次调用，约60秒（包括人工等待）

⏱️ 预期响应时间

功能	预期时间	推荐超时
setupTestWallets	< 1秒	5秒
getAccountStatus	1-3秒	10秒
initializeAccount	8-60秒（视情况而定）	60秒
sendTransaction	10-60秒（视情况而定）	60秒
receiveAllPending	5-60秒每块	60秒
convertBalance	< 500毫秒	5秒
generateQrCode	< 2秒	10秒

⚠️ 关键：工作生成性能

工作证明（PoW）生成时间因系统而异显著：

快速系统：10-15秒
较慢系统：30-60秒
始终设置最小60秒超时 用于事务函数（initializeAccount, sendTransaction, receiveAllPending）

如果遇到超时：

将超时增加至90-120秒
检查系统CPU可用性
不要立即重试 - 工作可能仍在处理中
超时后检查账户状态 - 交易可能已完成

❌ 不要做这些（浪费时间）

1. 不要先调用getBalance然后调用getAccountStatus

// ❌ 低效：2次调用，4-6秒
await call('getBalance', {address})         // 返回：余额，待处理
await call('getAccountStatus', {address})   // 返回：余额，待处理 + 更多

// ✅ 高效：1次调用，2-3秒
await call('getAccountStatus', {address})   // 返回：你需要的一切

2. 不要重复调用checkTestWalletsFunding

// ❌ 低效：显示0直到手动更新
await call('checkTestWalletsFunding')  // 返回：bothFunded: false
await call('checkTestWalletsFunding')  // 仍然为false（不会自动更新）

// ✅ 高效：直接检查区块链
await call('getAccountStatus', {address})  // 立即显示待处理区块

3. 不要在事务上设置短超时

// ❌ 失败：工作生成需要10-15秒
await call('sendTransaction', {...}, {timeout: 5000})  // 超时！

// ✅ 成功：适当的超时
await call('sendTransaction', {...}, {timeout: 30000})  // 成功完成

4. 不要按顺序测试独立函数

// ❌ 慢：总共6秒
await call('getAccountStatus', {address: wallet1})  // 3秒
await call('getAccountStatus', {address: wallet2})  // 3秒

// ✅ 快：总共3秒
await Promise.all([
  call('getAccountStatus', {address: wallet1}),
  call('getAccountStatus', {address: wallet2})
])  // 两者都在3秒内

💡 AI代理专业提示

使用getAccountStatus做一切 - 它替代了getBalance, getAccountInfo, getPendingBlocks
跟随needsAction数组 - 自动恢复，无需尝试和错误
批处理独立调用 - 使用Promise.all或批量请求
设置慷慨的超时 - 事务至少60秒（系统性能不同）
保存setupTestWallets响应 - 除非检索，否则不要调用getTestWallets
超时后不要重试 - 先检查账户状态，交易可能已完成
预期工作生成差异 - 根据系统负载，10-60秒不等

📊 优化影响

指标	低效	优化	改善
总调用次数	10-12	5-6	40-50% ↓
总令牌	10,000-15,000	5,000-7,000	50% ↓
总时间	60-90秒	30-60秒	40% ↓
决策点	5-6	1-2	70% ↓

结果: 更快的集成，更低的成本，更少的错误。

🎯 这个服务器做什么

NANO MCP Server 提供JSON-RPC 2.0 API用于NANO加密货币操作，包括：

✅ 自文档化错误 - 每个错误都会告诉你下一步该做什么
✅ 辅助函数 - 转换单位，自动检查账户状态
✅ 测试钱包系统 - 生成和管理测试钱包用于开发
✅ 无需外部文档 - 所有信息都在API响应中

NANO加密货币特性：

即时交易（< 1秒）
零费用
环保（能耗极小）
适合自动化AI系统

📋 可用的MCP函数（总计17个）

初始化（1个）

initialize - 获取服务器功能和所有可用函数

核心函数（8个）

generateWallet - 创建新的NANO钱包
getBalance - 检查账户余额
getAccountInfo - 获取详细的账户数据
getPendingBlocks - 列出待处理的交易
initializeAccount - 开启/激活新账户
sendTransaction - 发送NANO（增强错误）
receiveAllPending - 接收所有待处理的区块
generateQrCode - 创建支付二维码（base64 PNG）

辅助函数（3个） - 适用于自主代理

convertBalance - 转换NANO ↔ 原始单位
getAccountStatus - 一次调用显示：余额，待处理，能力，需要哪些操作
nanoConverterHelp - 新！综合指南用于Nano（XNO）转换、格式和数字处理（对不熟悉Nano的客户端至关重要）

测试钱包函数（5个） - 用于开发

setupTestWallets - 生成两个测试钱包（需要人工资助）
getTestWallets - 检索测试钱包信息
updateTestWalletBalance - 更新钱包余额跟踪
checkTestWalletsFunding - 检查钱包是否已准备好
resetTestWallets - 删除并重新开始

🚀 AI代理完整工作流程

工作流程：发送NANO交易

// 第一步：首先检查账户状态（始终这样做）
POST https://nano-mcp.replit.app
{
    "jsonrpc": "2.0",
    "method": "getAccountStatus",
    "params": {
        "address": "nano_your_address"
    },
    "id": 1
}

// 返回显示：
// - 初始化：true/false
// - 余额：{原始，nano}
// - 待处理：{数量，金额}
// - 需要操作：[所需操作的数组]
// - 测试准备就绪：true/false

// 第二步：处理任何所需的操作
// 如果需要操作包括“initializeAccount”：
{
    "jsonrpc": "2.0",
    "method": "initializeAccount",
    "params": {
        "address": "nano_your_address",
        "privateKey": "your_private_key"
    },
    "id": 2
}

// 如果需要操作包括“receiveAllPending”：
{
    "jsonrpc": "2.0",
    "method": "receiveAllPending",
    "params": {
        "address": "nano_your_address",
        "privateKey": "your_private_key"
    },
    "id": 3
}

// 第三步：将金额转换为原始单位
{
    "jsonrpc": "2.0",
    "method": "convertBalance",
    "params": {
        "amount": "0.1",
        "from": "nano",
        "to": "raw"
    },
    "id": 4
}
// 返回：{"converted": "100000000000000000000000000000"}

// 第四步：发送交易
{
    "jsonrpc": "2.0",
    "method": "sendTransaction",
    "params": {
        "fromAddress": "nano_sender",
        "toAddress": "nano_recipient",
        "amountRaw": "100000000000000000000000000",
        "privateKey": "sender_private_key"
    },
    "id": 5
}

// 成功：{"success": true, "hash": "..."}
// 错误：详细的错误和下一步（参见错误处理部分）

⚡ 常用任务快速参考

任务1：生成新钱包

{"jsonrpc": "2.0", "method": "generateWallet", "params": {}, "id": 1}

返回：address, privateKey, publicKey, seed

任务2：检查余额

{"jsonrpc": "2.0", "method": "getBalance", "params": {"address": "nano_xxx"}, "id": 1}

返回：balance（原始），pending（原始）

任务3：转换单位

{"jsonrpc": "2.0", "method": "convertBalance", "params": {"amount": "0.1", "from": "nano", "to": "raw"}, "id": 1}

返回：converted值及公式

任务4：检查账户准备情况

{"jsonrpc": "2.0", "method": "getAccountStatus", "params": {"address": "nano_xxx"}, "id": 1}

返回：完整状态 + 下一步该做什么

🧠 AI代理综合错误处理

✨ 什么使这特别

NANO MCP Server拥有最全面且适合AI代理的错误处理：

20多个特定错误代码 用于程序化处理
广泛的输入验证 - 地址、私钥、金额、所有参数
常见错误的自动检测（例如，使用NANO而不是原始）
建议的修正 - 服务器计算正确的值
逐步恢复 - 永远不会卡在一个错误上
无需外部文档 - 所有信息都在错误响应中

错误响应结构

所有错误包括：

errorCode - 机器可读代码（例如，“INSUFFICIENT_BALANCE”）
error - 人类可读消息
details - 特定上下文（出了什么问题，预期格式等）
nextSteps - 步骤式补救措施（数组）
relatedFunctions - 可以帮助解决这个问题的功能
exampleRequest - 可复制粘贴的正确请求
suggestedCorrection - 自动纠正的值（适用时