NANO MCP Server

NANO MCP サーバー - AI エージェント統合ガイド

AI エージェント向け：このサーバーは自律型エージェント専用に設計されています。すべてのエラーには、手順を追ったガイダンスが記載されています。外部ドキュメントは不要です。

---

🌐 本番サーバー URL

この 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 エージェント向けクイックスタート

本番サーバー（推奨）

サーバー URL： https://nano-mcp.replit.app

インストールは不要です！ サーバーはすでに稼働しています。リクエストを送信するだけで利用できます。

手順 1：接続をテストする

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

手順 2：準備完了です！

サーバーは利用可能なすべてのメソッドを返します。すぐに利用を開始できます。

---

🔍 JSON Schema の自動検出（新機能！）

AI エージェント向けゼロショット統合

🎯 ドキュメントを読む必要はありません！ 完全な JSON Schema を取得して、クライアントコードを自動生成できます。

# Get complete JSON Schema with all 16 tools
GET https://nano-mcp.replit.app/schema

# Get TypeScript definitions
GET https://nano-mcp.replit.app/schema/typescript

# Get OpenAPI 3.0 spec (Swagger compatible)
GET https://nano-mcp.replit.app/openapi.json

Schema の機能

• ✅ 入力／出力 Schema - 検証パターンを含む完全な JSON Schema
• ✅ すぐに使える例 - 各ツールのコピー＆ペースト可能な例
• ✅ 型定義 - 型安全なクライアント向け TypeScript .d.ts
• ✅ パラメーター検証 - アドレス、キー、金額の正規表現パターン
• ✅ エラー Schema - 対応方法のガイダンス付き、全 29 種類のエラーコード
• ✅ パフォーマンスに関する注意事項 - 想定実行時間と推奨タイムアウト
• ✅ 前提条件 - 各操作の依存関係情報

Schema の簡単な使い方

# Get schema for specific tool
GET https://nano-mcp.replit.app/schema/tools/sendTransaction

# Get examples for a tool
GET https://nano-mcp.replit.app/schema/examples/generateWallet

# Validate parameters before sending
POST https://nano-mcp.replit.app/schema/validate/sendTransaction
{ "fromAddress": "...", "toAddress": "...", "amountRaw": "...", "privateKey": "..." }

# Get tools by category (query, transaction, utility, etc.)
GET https://nano-mcp.replit.app/schema/category/transaction

# Get all error codes
GET https://nano-mcp.replit.app/schema/errors

コード生成の例

// 1. Download TypeScript definitions
// curl https://nano-mcp.replit.app/schema/typescript > nano-mcp.d.ts

// 2. Import types
import type { SendTransactionParams, SendTransactionResult } from './nano-mcp';

// 3. Use with full type safety
const params: SendTransactionParams = {
  fromAddress: "nano_...",
  toAddress: "nano_...",
  amountRaw: "1000000000000000000000000000",
  privateKey: "..."
};  // TypeScript validates all fields!

📖 完全ガイド： 詳細な Schema 統合パターンについては、docs/JSON_SCHEMA_AI_AGENT_GUIDE.md を参照してください。

⏱️ 統合にかかる推定時間： 5 分（ドキュメントを読む場合は数時間）

---

ローカル開発（任意）

開発のためにローカルで実行する必要がある場合：

cd NANO_MCP_SERVER
npm install
npm start

ローカルサーバーは http://localhost:8080 で稼働します。

---

⚡ 最速の統合手順（AI エージェント：ここから開始）

5～6 回の呼び出し、30～60 秒でワークフロー全体を完了できます：

// STEP 1: Setup test wallets (1 call, < 1s)
POST https://nano-mcp.replit.app
{"jsonrpc":"2.0","method":"setupTestWallets","params":{},"id":1}
→ Returns: wallet addresses + private keys

// STEP 2: Human funds both addresses (30-60s wait)
// → Send 0.1+ NANO to each address

// STEP 3: Check BOTH wallets in parallel (2 calls, 4-6s)
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}
→ Returns: balance, pending blocks, needsAction

// STEP 4: Follow needsAction automatically (2 calls, 16-24s)
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}
→ Returns: initialized confirmation

// STEP 5: Send transaction (1 call, 10-15s)
POST https://nano-mcp.replit.app
{"jsonrpc":"2.0","method":"sendTransaction","params":{
  "fromAddress":"wallet1",
  "toAddress":"wallet2",
  "amountRaw":"50000000000000000000000000",
  "privateKey":"key1"
},"id":1}
→ Returns: transaction hash

// DONE! ✅ Total: 6 calls, ~60 seconds (including human wait)

⏱️ 想定応答時間

関数	想定時間	推奨タイムアウト
setupTestWallets	< 1s	5s
getAccountStatus	1-3s	10s
initializeAccount	8-60s（変動あり）	60s
sendTransaction	10-60s（変動あり）	60s
receiveAllPending	ブロックごとに 5-60s	60s
convertBalance	< 500ms	5s
generateQrCode	< 2s	10s

⚠️ 重要：ワーク生成のパフォーマンス

Proof-of-Work（PoW）の生成時間はシステムによって大きく異なります：

• 高速なシステム：10～15 秒
• 低速なシステム：30～60 秒
• トランザクション関数（initializeAccount、sendTransaction、receiveAllPending）には、必ず 60 秒以上のタイムアウトを設定してください

タイムアウトが発生した場合：

1. タイムアウトを 90～120 秒に延長する
2. システムで利用可能な CPU を確認する
3. すぐに再試行しない - ワークの処理が続いている可能性があります
4. タイムアウト後にアカウントの状態を確認する - トランザクションが完了している可能性があります

❌ 避けるべきこと（時間の浪費）

1. getBalance の後に getAccountStatus を呼び出さない

// ❌ INEFFICIENT: 2 calls, 4-6s
await call('getBalance', {address})         // Returns: balance, pending
await call('getAccountStatus', {address})   // Returns: balance, pending + more

// ✅ EFFICIENT: 1 call, 2-3s
await call('getAccountStatus', {address})   // Returns: everything you need

2. checkTestWalletsFunding を繰り返し呼び出さない

// ❌ INEFFICIENT: Shows 0 until manually updated
await call('checkTestWalletsFunding')  // Returns: bothFunded: false
await call('checkTestWalletsFunding')  // Still false (not auto-updating)

// ✅ EFFICIENT: Check blockchain directly
await call('getAccountStatus', {address})  // Shows pending blocks immediately

3. トランザクションに短いタイムアウトを設定しない

// ❌ FAILS: Work generation takes 10-15 seconds
await call('sendTransaction', {...}, {timeout: 5000})  // Times out!

// ✅ WORKS: Proper timeout
await call('sendTransaction', {...}, {timeout: 30000})  // Completes successfully

4. 独立して実行できる関数を順番にテストしない

// ❌ SLOW: 6 seconds total
await call('getAccountStatus', {address: wallet1})  // 3s
await call('getAccountStatus', {address: wallet2})  // 3s

// ✅ FAST: 3 seconds total
await Promise.all([
  call('getAccountStatus', {address: wallet1}),
  call('getAccountStatus', {address: wallet2})
])  // Both in 3s

💡 AI エージェント向けのヒント

1. すべてに getAccountStatus を使用する - getBalance、getAccountInfo、getPendingBlocks の代わりになります
2. needsAction 配列に従う - 試行錯誤せずに自動復旧できます
3. 独立した呼び出しをまとめる - Promise.all またはバッチリクエストを使用します
4. 余裕のあるタイムアウトを設定する - トランザクションには最低 60 秒（システムの性能によって異なります）
5. setupTestWallets の応答を保存する - ウォレット情報を取得する場合を除き、getTestWallets を呼び出さないでください
6. タイムアウト時に再試行しない - まずアカウントの状態を確認してください。トランザクションが完了している可能性があります
7. ワーク生成時間にはばらつきがある - システム負荷に応じて 10～60 秒かかります

📊 最適化の効果

指標	非効率	最適化後	改善率
呼び出し総数	10-12	5-6	40-50% ↓
トークン総数	10,000-15,000	5,000-7,000	50% ↓
合計時間	60-90s	30-60s	40% ↓
判断ポイント	5-6	1-2	70% ↓

結果： 統合の高速化、コストの削減、エラーの減少。

---

🎯 このサーバーの機能

NANO MCP Server は、NANO 暗号通貨の操作に対応する JSON-RPC 2.0 API を提供します。

• ✅ 自己説明型のエラー - 各エラーで次に行うべきことが明確にわかります
• ✅ ヘルパー関数 - 単位を変換し、アカウントの状態を自動で確認します
• ✅ テストウォレットシステム - 開発用のテストウォレットを生成・管理します
• ✅ 外部ドキュメント不要 - 情報はすべて API レスポンスに含まれています

NANO 暗号通貨の特長：

• 即時取引（1 秒未満）
• 手数料無料
• 環境にやさしい（エネルギー消費が最小限）
• 自動化された AI システムに最適

---

📋 利用可能な MCP 関数（合計 17 個）

初期化（1 個）

1. initialize - サーバーの機能と利用可能なすべての関数を取得

コア関数（8 個）

2. generateWallet - 新しい NANO ウォレットを作成
3. getBalance - アカウント残高を確認
4. getAccountInfo - アカウントの詳細データを取得
5. getPendingBlocks - 保留中のトランザクションを一覧表示
6. initializeAccount - 新しいアカウントを開設・有効化
7. sendTransaction - NANO を送金（エラー処理を強化）
8. receiveAllPending - 保留中のすべてのブロックを受け取る
9. generateQrCode - base64 PNG 形式の決済用 QR コードを作成

ヘルパー関数（3 個）- 自律型エージェント向け

10. convertBalance - NANO と raw 単位を相互変換
11. getAccountStatus - 1 回の呼び出しで残高、保留中の項目、機能、必要な操作を表示
12. nanoConverterHelp - 新機能！ Nano（XNO）の変換、形式、数値の処理に関する包括的なガイド（Nano に詳しくないクライアントに必須）

テストウォレット関数（5 個）- 開発向け

13. setupTestWallets - 2 つのテストウォレットを生成（人間による資金の入金が必要）
14. getTestWallets - テストウォレットの情報を取得
15. updateTestWalletBalance - ウォレットの残高追跡情報を更新
16. checkTestWalletsFunding - ウォレットを利用できる状態か確認
17. resetTestWallets - 削除して最初からやり直す

---

🚀 AI エージェント向けの完全なワークフロー

ワークフロー：NANO トランザクションの送信

// Step 1: Check account status first (ALWAYS DO THIS)
POST https://nano-mcp.replit.app
{
    "jsonrpc": "2.0",
    "method": "getAccountStatus",
    "params": {
        "address": "nano_your_address"
    },
    "id": 1
}

// Response shows:
// - initialized: true/false
// - balance: {raw, nano}
// - pending: {count, amount}
// - needsAction: [array of required actions]
// - readyForTesting: true/false

// Step 2: Handle any required actions
// If needsAction includes "initializeAccount":
{
    "jsonrpc": "2.0",
    "method": "initializeAccount",
    "params": {
        "address": "nano_your_address",
        "privateKey": "your_private_key"
    },
    "id": 2
}

// If needsAction includes "receiveAllPending":
{
    "jsonrpc": "2.0",
    "method": "receiveAllPending",
    "params": {
        "address": "nano_your_address",
        "privateKey": "your_private_key"
    },
    "id": 3
}

// Step 3: Convert amount to raw units
{
    "jsonrpc": "2.0",
    "method": "convertBalance",
    "params": {
        "amount": "0.1",
        "from": "nano",
        "to": "raw"
    },
    "id": 4
}
// Returns: {"converted": "100000000000000000000000000000"}

// Step 4: Send transaction
{
    "jsonrpc": "2.0",
    "method": "sendTransaction",
    "params": {
        "fromAddress": "nano_sender",
        "toAddress": "nano_recipient",
        "amountRaw": "100000000000000000000000000",
        "privateKey": "sender_private_key"
    },
    "id": 5
}

// Success: {"success": true, "hash": "..."}
// Error: Detailed error with nextSteps (see Error Handling section)

---

⚡ クイックリファレンス：一般的なタスク

タスク 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（raw）、pending（raw）

タスク 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 種類以上の具体的なエラーコード
• 詳細な入力検証 - アドレス、秘密鍵、金額、すべてのパラメーターを検証
• よくある間違いを自動検出（例：raw の代わりに NANO を使用）
• 修正案の提示 - サーバーが正しい値を計算
• 段階的な復旧手順 - エラーで行き詰まることはありません
• 外部ドキュメントが一切不要 - すべての情報がエラーレスポンスに含まれています

エラーレスポンスの構造

すべてのエラーに含まれる項目：

• errorCode - 機械可読なコード（例："INSUFFICIENT_BALANCE"）
• error - 人間が読めるメッセージ
• details - 具体的な状況（問題の内容、期待される形式など）
• nextSteps - 段階的な修正手順（配列）
• relatedFunctions - 解決に役立つ関数
• exampleRequest - コピーしてすぐに使える正しいリクエスト
• suggestedCorrection - 自動修正された値（該当する場合）

📋 エラーコード一覧

検証エラー：

• MISSING_PARAMETER - 必須パラメーターが指定されていません
• METHOD_NOT_FOUND - MCP メソッド名が無効です
• INVALID_ADDRESS_FORMAT - アドレスが指定されていないか、型が正しくありません
• INVALID_ADDRESS_PREFIX - アドレスが「nano_」または「xrb_」で始まっていません
• INVALID_ADDRESS_LENGTH - アドレスの長さが正しくありません
• INVALID_ADDRESS_CHARACTERS - アドレスに無効な文字が含まれています
• INVALID_PRIVATE_KEY_FORMAT - 秘密鍵が指定されていないか、型が正しくありません
• INVALID_PRIVATE_KEY_LENGTH - 秘密鍵が64文字ではありません
• INVALID_PRIVATE_KEY_CHARACTERS - 秘密鍵が16進数ではありません
• INVALID_AMOUNT_FORMAT - 金額が指定されていないか、型が正しくありません
• AMOUNT_WRONG_UNIT - スマート検出：raw の代わりに NANO を使用しています
• INVALID_AMOUNT_CHARACTERS - 金額に無効な文字が含まれています
• INVALID_AMOUNT_ZERO_OR_NEGATIVE - 金額は正の値である必要があります
• INVALID_AMOUNT_OVERFLOW - 金額が大きすぎます
• INVALID_CONVERSION_UNITS - 「from」または「to」の単位が無効です
• SAME_CONVERSION_UNITS - 同じ単位には変換できません
• INVALID_QR_AMOUNT_FORMAT - QR コードの金額形式が無効です

ブロックチェーンエラー：

• INSUFFICIENT_BALANCE - 送金する NANO が不足しています
• INSUFFICIENT_WORK - [重大] Work が難易度のしきい値を満たしていません（修正済み — 再試行してください）
• ACCOUNT_NOT_INITIALIZED - アカウントは最初のトランザクションを受け取る必要があります
• ACCOUNT_NOT_INITIALIZED_NO_PENDING - アカウントに保留中のブロックがありません
• PENDING_BLOCKS_NOT_RECEIVED - 先に保留中のブロックを受け取る必要があります
• BLOCKCHAIN_INVALID_BLOCK - ブロックチェーンがブロックを拒否しました
• BLOCKCHAIN_INSUFFICIENT_BALANCE - ブロックチェーンでの残高確認に失敗しました
• BLOCKCHAIN_ERROR - ブロックチェーン操作で一般的なエラーが発生しました
• CONVERSION_ERROR - 残高の変換に失敗しました

例：残高不足エラー

リクエスト：

{
    "jsonrpc": "2.0",
    "method": "sendTransaction",
    "params": {
        "fromAddress": "nano_xxx",
        "toAddress": "nano_yyy",
        "amountRaw": "1000000000000000000000000000",
        "privateKey": "key"
    },
    "id": 1
}

エラーレスポンス：

{
    "jsonrpc": "2.0",
    "result": {
        "success": false,
        "error": "Insufficient balance",
        "errorCode": "INSUFFICIENT_BALANCE",
        "details": {
            "address": "nano_xxx",
            "currentBalance": "80000000000000000000000000",
            "currentBalanceNano": "0.00016",
            "attemptedAmount": "1000000000000000000000000000",
            "attemptedAmountNano": "0.002",
            "shortfall": "920000000000000000000000000",
            "shortfallNano": "0.00184"
        },
        "nextSteps": [
            "Step 1: Check current balance using getBalance or getAccountInfo",
            "Step 2: Either reduce send amount to maximum 0.00016 NANO or less",
            "Step 3: Or fund account with additional 0.00184 NANO minimum",
            "Step 4: After funding, use receiveAllPending to process pending blocks",
            "Step 5: Retry your send transaction"
        ],
        "relatedFunctions": ["getBalance", "getAccountInfo", "receiveAllPending"],
        "exampleRequest": {
            "jsonrpc": "2.0",
            "method": "getBalance",
            "params": {"address": "nano_xxx"},
            "id": 1
        }
    },
    "id": 1
}

🎯 スマート自動修正の例

raw の代わりに NANO を送信しましたか？サーバーが自動修正します！

不正なリクエスト（raw の代わりに NANO を使用）：

{
    "jsonrpc": "2.0",
    "method": "sendTransaction",
    "params": {
        "fromAddress": "nano_3sender...",
        "toAddress": "nano_3receiver...",
        "amountRaw": "0.1",
        "privateKey": "abc123..."
    },
    "id": 1
}

スマートエラーレスポンス：

{
    "success": false,
    "error": "amountRaw appears to be in NANO format, not raw",
    "errorCode": "AMOUNT_WRONG_UNIT",
    "details": {
        "providedValue": "0.1",
        "detectedFormat": "NANO (decimal)",
        "expectedFormat": "raw (integer string)"
    },
    "suggestedCorrection": {
        "originalValue": "0.1",
        "originalUnit": "NANO",
        "correctedValue": "100000000000000000000000000000",
        "correctedUnit": "raw"
    },
    "nextSteps": [
        "Step 1: Use the correctedValue from suggestedCorrection below",
        "Step 2: Retry your request with the raw amount"
    ],
    "exampleConversion": {
        "jsonrpc": "2.0",
        "method": "convertBalance",
        "params": { "amount": "0.1", "from": "nano", "to": "raw" },
        "id": 1
    }
}

AI エージェントのアクション：

// Extract corrected value automatically
if (response.errorCode === "AMOUNT_WRONG_UNIT") {
    const correctedAmount = response.suggestedCorrection.correctedValue;
    // Retry with corrected value: "100000000000000000000000000000"
}

エラーコード早見表

エラーコード	意味	自動修正の可否	対応
INSUFFICIENT_BALANCE	NANO が不足しています	一部対応（不足額を表示）	金額を減らすか、資金を補充します
INSUFFICIENT_WORK	PoW がしきい値を下回っています	はい（自動再試行）	リクエストを再試行してください
ACCOUNT_NOT_INITIALIZED	アカウントが開設されていません	はい（2つの解決策）	initializeAccount を呼び出します
AMOUNT_WRONG_UNIT	raw ではなく NANO を使用しています	はい（自動変換）	suggestedCorrection を使用します
INVALID_ADDRESS_*	アドレス形式が正しくありません	はい（形式を表示）	アドレス形式を修正します
INVALID_PRIVATE_KEY_*	鍵の形式が正しくありません	はい（形式を表示）	秘密鍵を修正します
MISSING_PARAMETER	パラメーターがありません	はい（例を表示）	不足しているパラメーターを追加します
METHOD_NOT_FOUND	メソッドが無効です	はい（すべてのメソッドを一覧表示）	正しいメソッドを使用します

📚 ドキュメント全文

エラー処理ガイドの詳細： docs/AI_AGENT_ERROR_HANDLING.md を参照してください

記載内容：

• 29 個のすべてのエラーコードの説明（INSUFFICIENT_WORK を含む）
• スマート自動修正の例
• エラー復旧のための判断ツリー
• AI エージェントのベストプラクティス
• セキュリティ上の考慮事項
• 100% の検証カバレッジの詳細

エラー処理の判断ツリー

Receive Error
  |
  ├─> errorCode == "INSUFFICIENT_BALANCE"
  |     ├─> Check details.shortfall
  |     ├─> Option 1: Reduce amountRaw
  |     └─> Option 2: Fund account
  |
  ├─> errorCode == "ACCOUNT_NOT_INITIALIZED"
  |     ├─> Check details.hasPendingBlocks
  |     ├─> If true: Call initializeAccount
  |     └─> If false: Send NANO to address first
  |
  ├─> errorCode == "PENDING_BLOCKS_NOT_RECEIVED"
  |     └─> Call receiveAllPending
  |
  └─> Other errors
        └─> Follow nextSteps array

---

🧪 テストウォレットシステム（開発用）

クイックセットアップ

ステップ 1：テスト用ウォレットを生成する

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

応答（これらのアドレスを保存してください！）：

{
    "jsonrpc": "2.0",
    "result": {
        "wallet1": {
            "address": "nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn",
            "privateKey": "6b84f1b17dd0a6176df2b500b40ce17c0db5bd8042ca8ac04173dd74bac303b8",
            "publicKey": "bc33249aa963b650b410c68123366ccdb6dcb9bb83f713fc11ade241578c92b8",
            "seed": "cbce4f1ec09296e245f4125b8f89930cc490599f30697491bc03e4915041c146",
            "balance": "0",
            "funded": false
        },
        "wallet2": {
            "address": "nano_39isqp67xsse8cj5igtonuiwicqy8p6txa57mbjd8bcyip7ggrai4bby1x1w",
            "privateKey": "9279a138a0000ac09477be901210b58b80e503835744f08c70690d94d57e70b9",
            "publicKey": "9e19bd885ee72c32a2383b55a6e1c82afe3589aea0659a62b3255e858ae76110",
            "seed": "bf69ae134c00c0e24aabb97ac4a0a7e1933fdd28672a1b0caf9b1c7ea193d917",
            "balance": "0",
            "funded": false
        },
        "created": "2025-11-11T15:25:23.161Z",
        "status": "awaiting_funding",
        "fundingInstructions": [
            "Send test NANO to Wallet 1: nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn",
            "Send test NANO to Wallet 2: nano_39isqp67xsse8cj5igtonuiwicqy8p6txa57mbjd8bcyip7ggrai4bby1x1w",
            "After funding, use checkFundingStatus to verify both wallets are funded",
            "Recommended test amount: 0.1 NANO or more per wallet"
        ]
    },
    "id": 1
}

⚠️ 重要 — 対応が必要です： これらのウォレットには人間が資金を入金する必要があります！

1. ウォレット 1 のアドレスをコピー： nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn
2. ウォレット 2 のアドレスをコピー： nano_39isqp67xsse8cj5igtonuiwicqy8p6txa57mbjd8bcyip7ggrai4bby1x1w
3. 両方のアドレスにテスト用 NANO を送信します（各ウォレットに 0.1 NANO を推奨）
4. テスト用の資金を送信するには、NANO のフォーセットまたはご自身のウォレットを使用します
5. 確認を待ちます（通常 5 秒未満）

ステップ 2：入金状況を確認する

{
    "jsonrpc": "2.0",
    "method": "checkTestWalletsFunding",
    "params": {},
    "id": 2
}

ステップ 3：両方に入金されたら、テストを開始します！ 準備ができると、応答に "bothFunded": true と表示されます。

テスト用ウォレットのワークフロー

setupTestWallets
     ↓
Fund addresses (external)
     ↓
initializeAccount (both wallets)
     ↓
updateTestWalletBalance (both wallets)
     ↓
checkTestWalletsFunding
     ↓
Ready for send/receive testing!

---

💡 判断ツリー：トランザクションの全フロー

START
  |
  v
Call: getAccountStatus(address)
  |
  ├─> initialized: false
  |   |
  |   ├─> hasPendingBlocks: true
  |   |   └─> Call: initializeAccount
  |   |
  |   └─> hasPendingBlocks: false
  |       └─> STOP: Fund account first
  |
  └─> initialized: true
      |
      ├─> pendingCount > 0
      |   └─> Call: receiveAllPending
      |
      └─> canSend: true
          |
          v
      Call: convertBalance(amount, "nano", "raw")
          |
          v
      Call: sendTransaction(...)
          |
          ├─> success: true
          |   └─> DONE!
          |
          └─> success: false
              └─> Parse errorCode
                  └─> Follow nextSteps in error response

---

📊 単位変換（重要！）

NANO では 2 つの単位を使用します：

• NANO（小数、例：「0.1」）— 人間が読みやすい形式
• raw（整数の文字列）— ブロックチェーンで使用される単位

変換：

• 1 NANO = 10³⁰ raw
• amountRaw パラメーターには必ず raw を使用してください

クイックリファレンス：

NANO	Raw
0.000001	1000000000000000000000000
0.001	1000000000000000000000000000
0.01	10000000000000000000000000000
0.1	100000000000000000000000000000
1.0	1000000000000000000000000000000

convertBalance 関数を使用します：

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

---

🔧 セットアップと設定

インストール

# Clone or download
cd NANO_MCP_SERVER

# Install dependencies
npm install

# Run server
npm start

環境変数（任意）

MCP_PORT=8080                    # Server port (default: 8080)
MCP_TRANSPORT=http               # Transport type (default: http)
NANO_RPC_URL=https://...         # NANO RPC node (has default)
NANO_REPRESENTATIVE=nano_xxx     # Representative (has default)

テスト

# Run tests (21 tests for test wallet system)
npm test

---

📚 関数リファレンス

initialize

目的： MCP サーバーを初期化し、利用可能なすべての機能／関数の一覧を取得します パラメーター： なし 戻り値： サーバー情報と、説明付きの利用可能なすべての MCP ツールの一覧

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

応答に含まれる内容：

• protocolVersion — MCP プロトコルのバージョン
• serverInfo — サーバー名とバージョン
• capabilities — サーバーの機能
• tools — 説明とパラメータースキーマを含む、利用可能なすべての MCP 関数の一覧

使用例： サーバーで何ができるか、どの関数が利用できるかを確認するための最初の呼び出し

generateWallet

目的： 新しい NANO ウォレットを作成します パラメーター： なし 戻り値： address、privateKey、publicKey、seed

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

getBalance

目的： アカウント残高を確認します パラメーター： address 戻り値： balance（raw）、pending（raw）

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

getAccountInfo

目的： アカウントの詳細情報を取得します パラメーター： address 戻り値： frontier、balance、representative、block_count など

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

getPendingBlocks

目的： 保留中（未受信）のトランザクションを一覧表示します パラメーター： address 戻り値： 保留中のブロックと金額を含むオブジェクト

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

initializeAccount

目的： 新しいアカウントを開設／有効化します（初回の受信） パラメーター： address、privateKey 戻り値： initialized、blockHash、balance など

{"jsonrpc": "2.0", "method": "initializeAccount", "params": {"address": "nano_xxx", "privateKey": "key"}, "id": 1}

sendTransaction

目的： 別のアドレスに NANO を送信します パラメーター： fromAddress、toAddress、amountRaw、privateKey 戻り値： success、hash、または詳細なエラー

{"jsonrpc": "2.0", "method": "sendTransaction", "params": {"fromAddress": "nano_xxx", "toAddress": "nano_yyy", "amountRaw": "100000000000000000000000000", "privateKey": "key"}, "id": 1}

receiveAllPending

目的： 保留中のトランザクションをすべて受信します パラメーター： address、privateKey 戻り値： 受信したブロックの配列

{"jsonrpc": "2.0", "method": "receiveAllPending", "params": {"address": "nano_xxx", "privateKey": "key"}, "id": 1}

generateQrCode

目的： NANO を受け取るための決済 QR コードを生成します パラメーター：

• address（文字列、必須） - 決済の受け取り先となる NANO アドレス
• amount（文字列、任意） - NANO の金額（小数形式、例：「0.1」）

戻り値：

• qrCode（文字列） - Base64 エンコードされた PNG 画像
• paymentString（文字列） - 決済用 NANO URI（nano:address?amount=...）
• address（文字列） - NANO アドレス
• amount（文字列） - NANO の金額（指定されている場合）

リクエスト例：

{
    "jsonrpc": "2.0",
    "method": "generateQrCode",
    "params": {
        "address": "nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn",
        "amount": "0.1"
    },
    "id": 1
}

レスポンス例：

{
    "jsonrpc": "2.0",
    "result": {
        "qrCode": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...[long base64 string]",
        "paymentString": "nano:nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn?amount=100000000000000000000000000000",
        "address": "nano_3h3m6kfckrxpc4t33jn36eu8smfpukwuq1zq4hy35dh4a7drs6ormhwhkncn",
        "amount": "0.1"
    },
    "id": 1
}

使用例：

• 決済の受け付け用に、Web／モバイルアプリに QR コードを表示する
• 請求書用の決済リンクを生成する
• 共有可能な決済リクエストを作成する
• qrCode は HTML に直接埋め込めます：<img src="data:image/png;base64,..." />
• paymentString は、NANO ウォレット用のクリック可能なリンクやディープリンクとして使用できます

convertBalance（ヘルパー）

目的： NANO と raw 単位を相互変換します パラメーター： amount、from（"nano"/"raw"）、to（"nano"/"raw"） 戻り値： converted、formula

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

getAccountStatus（ヘルパー）

目的： アカウントの準備状況を包括的に確認します パラメーター： address 戻り値： initialized、balance、pending、capabilities、needsAction、recommendations

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

nanoConverterHelp（ヘルパー） - 新機能！

目的： Nano（XNO）の変換ユーティリティと数値形式に関する包括的なヘルプを取得します パラメーター： なし 戻り値： 変換式、例、よくある間違い、ベストプラクティス、ユーティリティ関数のドキュメント

⚠️ 重要：Nano に詳しくないクライアントに必須です！

このツールがある理由： ほとんどの暗号資産クライアントでは、Bitcoin や Ethereum のような単純な小数形式の数値が想定されています。しかし、Nano は小数点以下 30 桁（10^30 raw 単位 = 1 XNO）を使用するため、精度エラーを防ぐには特別な処理が必要です。

リクエスト例：

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

レスポンス例（一部抜粋）：

{
  "jsonrpc": "2.0",
  "result": {
    "description": "Nano (XNO) uses raw units for all on-chain operations. 1 XNO = 10^30 raw. This ensures exact precision without floating-point errors.",
    "formula": "raw = XNO × 10^30",
    "reverseFormula": "XNO = raw ÷ 10^30",
    "decimalPlaces": 30,
    "examples": {
      "0.1_XNO": "100000000000000000000000000000",
      "1_XNO": "1000000000000000000000000000000"
    },
    "commonMistakes": [
      "Using XNO value instead of raw in amountRaw parameter",
      "Using floating-point arithmetic which causes rounding errors"
    ],
    "utilityFunctions": {
      "xnoToRaw": {
        "description": "Convert XNO amount to raw units (use this for all transaction amounts)",
        "example": "xnoToRaw(1) => '1000000000000000000000000000000'",
        "usage": "Always use this before sending transactions"
      }
    },
    "exampleWorkflow": [
      "Step 1: Get user input in XNO (e.g., '0.1')",
      "Step 2: Convert to raw using NanoConverter.xnoToRaw('0.1')",
      "Step 3: Validate address using NanoConverter.isValidNanoAddress(address)",
      "Step 4: Use raw amount in sendTransaction"
    ],
    "warning": "IMPORTANT: Most clients don't know Nano uses 30 decimal places. Always educate users that 1 XNO = 10^30 raw units."
  },
  "id": 1
}

使用例：

1. 初回の統合： Nano のトランザクションを実装する前にこのメソッドを呼び出し、数値形式を理解します
2. 変換エラーのデバッグ： 「AMOUNT_WRONG_UNIT」エラーが発生した場合、正しい形式を確認できます
3. クライアントへの説明： 返される情報を使って、エンドユーザーに Nano の精度について説明します
4. リファレンスドキュメント： 実装時の参照資料として、このレスポンスを保存します

setupTestWallets（テストウォレット）

目的： すべての認証情報を含む 2 つのテストウォレットを生成します パラメーター： なし 戻り値： wallet1、wallet2（アドレス、秘密鍵、公開鍵、シードを含む）、fundingInstructions ⚠️ 要対応： 人間が両方のウォレットアドレスにテスト用 NANO を送金する必要があります

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

レスポンスに含まれる内容：

• 2 つの完全なウォレット認証情報（アドレス、秘密鍵、公開鍵、シード）
• 送金先の正確なアドレスを記載した送金手順
• 「awaiting_funding」を示すステータス
• 推奨テスト金額（ウォレット 1 つあたり 0.1 NANO）

getTestWallets（テストウォレット）

目的： 現在のテストウォレット情報を取得します パラメーター： なし 戻り値： wallet1、wallet2（アドレス、残高、送金状況を含む）

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

使用例： ウォレットの生成後に認証情報を取得する、または現在の状態を確認する

updateTestWalletBalance（テストウォレット）

目的： テストウォレットの追跡対象残高を更新します パラメーター： walletName（"wallet1" または "wallet2"）、balance（raw）、funded（ブール値） 戻り値： 更新されたウォレット情報

{"jsonrpc": "2.0", "method": "updateTestWalletBalance", "params": {"walletName": "wallet1", "balance": "100000000000000000000000000000", "funded": true}, "id": 1}

使用例： 残高の変化を手動で追跡する、またはウォレットを送金済みとしてマークする

checkTestWalletsFunding（テストウォレット）

目的： 両方のテストウォレットに入金されているか（残高が 0 より大きいか）を確認します パラメーター： なし 戻り値： wallet1（残高、送金済み）、wallet2（残高、送金済み）、bothFunded、status

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

使用例： 人間による送金後、ウォレットがテスト可能な状態かを確認する

resetTestWallets（テストウォレット）

目的： テストウォレットを削除して新しく作成します パラメーター： なし 戻り値： 確認メッセージ

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

使用例： クリーンアップして、新しいテストウォレットを生成する

---

🎓 AI エージェントのベストプラクティス

✅ すること：

1. まず getAccountStatus でアカウントの状態を必ず確認します
2. トランザクションの前に convertBalance で金額を変換します
3. プログラムでエラーを処理するため、errorCode を解析します
4. エラーレスポンスの nextSteps 配列に従います
5. トランザクションを送信する前に、保留中のブロックを受信します

❌ しないこと：

1. アカウントの状態確認を省略する
2. amountRaw に NANO の値をそのまま使用する（raw 単位で指定する必要があります）
3. エラーの nextSteps を無視する ― 復旧の手順を示します
4. アカウントの準備ができていると思い込む ― 必ず確認します
5. エラーメッセージ文字列を解析する（代わりに errorCode を使用します）

---

🔒 セキュリティに関する注意事項

1. 秘密鍵：秘密鍵を記録したり、公開したりしないでください
2. テスト用と本番用：開発にはテスト用ウォレットを使用してください
3. RPC ノード：レート制限付きのデフォルトのパブリックノードが提供されています
4. 検証：すべての入力はサーバーによって検証されます

---

📖 追加ドキュメント

NANO_MCP_SERVER/ にあります：

• AUTONOMOUS_AGENT_INTEGRATION_GUIDE.md - 統合ガイドの完全版
• TEST_WALLET_INTEGRATION.md - テスト用ウォレットのドキュメント
• AUTONOMOUS_AGENT_ERROR_ENHANCEMENT.md - エラー処理の詳細
• examples/test-wallet-usage.json - リクエストの例

---

🎉 このサーバーが AI エージェントに使いやすい理由

✅ 自己文書化 - すべてのエラーが内容を説明します ✅ ヘルパー関数 - 変換と状態確認の機能を内蔵 ✅ 構造化レスポンス - JSON を簡単に解析できます ✅ 機械可読コード - プログラムによる処理のためのエラーコード ✅ 実行可能なガイダンス - すべてのエラーに nextSteps が含まれます ✅ 外部ドキュメント不要 - 必要な情報はすべてレスポンスに含まれます ✅ 迅速な統合 - 最初のトランザクションまで 5～10 分

---

🚀 統合にかかる時間

タスク	所要時間
インストールして実行	2 分
最初のトランザクション	5～10 分
統合の完了	30 分未満

従来の NANO 統合と比較：最低 1～2 時間

---

⚡ クイックテスト（コピーして貼り付け）

本番サーバー（セットアップ不要）：

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

# You should see list of all 16 available methods

ローカル開発（任意）：

# 1. Start local server
cd NANO_MCP_SERVER && npm start

# 2. In another terminal, test:
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{},"id":1}'

---

📞 サポート

AI エージェント向け：

• すべてのエラーに修正手順が含まれます
• getAccountStatus を使用して問題を診断します
• 特定の問題を確認するには errorCode をチェックします
• エラーレスポンスの nextSteps に従います

開発者向け：

• GitHub Issues：課題を作成
• ドキュメント：NANO_MCP_SERVER/docs/ 内のファイルを参照してください

---

🎊 さあ、始めましょう！

必要なものはすべてそろっています。サーバーは自己文書化されたエラーで、あらゆる手順を案内します。

最初に実行するコマンド：

cd NANO_MCP_SERVER && npm start

サーバーの準備が整う URL： http://localhost:8080

次の内容から開始します： {"jsonrpc":"2.0","method":"initialize","params":{},"id":1}

NANO の統合がうまくいきますように！ 🚀