AI Agent如何通过MCP协议安全调用Zcash隐私区块链工具

相太阳

410人浏览 · 2026-04-30 15:53:08

相太阳 · 2026-04-30 15:53:08 发布

1. 项目概述：当AI遇见隐私区块链

最近在折腾AI Agent的生态，发现一个挺有意思的趋势：AI模型正在从单纯的文本生成器，演变成能够调用外部工具、执行实际任务的“智能体”。在这个过程中，MCP（Model Context Protocol）逐渐成为了连接AI与外部世界的标准协议。简单来说，MCP就像给AI装上了一套标准化的USB接口，让它能即插即用地使用各种工具。

而今天要聊的这个项目—— zcash-mcp ，就是这套“USB接口”中一个非常特殊的工具。它让AI Agent能够直接与Zcash这条以隐私保护著称的区块链进行交互。想象一下，你的AI助手不仅能帮你查资料、写代码，还能在完全保护你隐私的前提下，帮你查询加密资产余额、验证链上凭证，甚至发起一笔受隐私保护的转账。这听起来有点科幻，但 zcash-mcp 正在让这件事变成现实。

这个由Frontier Compute开源的MCP服务器，本质上是一个“翻译器”。它把AI模型能理解的MCP协议指令，翻译成Zcash区块链（特别是其上的ZAP1协议）能理解的操作。目前它提供了22个工具，覆盖了从基础的链上数据查询（如区块高度、交易详情），到高级的隐私功能（如创建屏蔽交易、解码加密备忘录），再到更前沿的跨链交换和基于多方计算的钱包管理。

对于开发者而言，这意味着你可以为你的AI应用轻松集成Zcash的隐私支付和凭证能力，而无需从零开始研究复杂的Zcash协议细节。对于普通用户，通过Claude Desktop、Cursor等支持MCP的客户端，你就能让AI帮你安全地处理一些链上操作。接下来，我会带你深入拆解这个项目的设计思路、核心工具的实现，以及如何将它集成到你的工作流中。

2. 核心架构与设计思路拆解

2.1 为什么是MCP + Zcash？

要理解 zcash-mcp 的价值，得先看清它要解决的两个核心问题。

第一，AI工具调用的标准化难题。 在MCP出现之前，每个AI平台（如OpenAI的GPTs、Anthropic的Claude）都有自己的一套工具调用方式。开发者如果想让自己开发的功能被多个AI平台使用，就得为每个平台写一遍适配代码，维护成本很高。MCP的诞生，就是为了统一这个“接口”。它定义了一套基于JSON-RPC over stdio（标准输入输出）的通信协议，任何实现了MCP Server的程序，都能被任何支持MCP的客户端（Claude Desktop、Cursor、OpenClaw等）调用。 zcash-mcp 选择基于MCP构建，就意味着它一次开发，就能服务整个生态，这是技术选型上非常聪明的一点。

第二，区块链交互的复杂性与隐私需求。 直接让AI去调用区块链节点RPC接口是不现实的。首先，RPC接口往往很底层，返回的数据需要大量解析；其次，涉及私钥签名的操作极其危险，绝不能将私钥暴露给AI模型；最后，像Zcash这样的隐私币，其核心的“屏蔽交易”（Shielded Transaction）涉及复杂的密码学（如zk-SNARKs），使用门槛很高。 zcash-mcp 扮演了一个“安全中介”和“简化层”的角色。它将复杂的链上操作封装成一个个语义清晰的工具（如 send_shielded ），并确保所有需要私钥的操作（通过后续会讲到的Ika MPC方案）都不会让AI模型触碰到私钥本身。

2.2 项目整体架构解析

zcash-mcp 的架构可以清晰地分为三层：协议层、业务逻辑层和依赖服务层。

协议层（MCP Adapter） ：这是项目的“外壳”，负责与MCP客户端通信。它基于 @modelcontextprotocol/sdk 开发，监听标准输入（stdin），解析客户端发来的JSON-RPC请求，调用对应的工具函数，再将结果封装成MCP格式通过标准输出（stdout）返回。这一层的代码相对固定，是任何MCP Server的模板。

业务逻辑层（Tool Implementations） ：这是项目的“大脑”，包含了全部22个工具的具体实现。每个工具都是一个独立的函数，它们根据输入参数，去调用下一层的服务或本地库来完成实际工作。这一层的设计体现了良好的关注点分离。例如， get_block_height 、 lookup_transaction 这类只读的链上查询，直接调用本地的Zebra节点；而 attest_event 、 get_balance 这类与ZAP1协议相关的操作，则调用远程的ZAP1 API。

依赖服务层（External Services） ：这是项目的“手脚”，是真正干活的部分。主要依赖三个外部服务：

Zebra节点 ：Zcash的官方Rust实现全节点。 zcash-mcp 通过JSON-RPC与它通信，获取最原始的链上数据。这是所有区块链查询的基石。
ZAP1 API服务 ：由Frontier Compute维护的专有服务。ZAP1（Zcash Attestation Protocol 1）是一个在Zcash上构建应用层协议的框架。这个API处理了ZAP1特有的逻辑，如管理默克尔树、生成证明、处理凭证（Attestation）的写入与查询。它是实现高级隐私功能的关键。
Ika 2PC-MPC服务 （用于部分工具）：这是一个实现两方计算-多方计算的安全服务，用于实现 zcash_create_wallet 和 zcash_sign_mpc 等工具。它确保了在创建钱包或签名交易时，没有任何一方（用户或服务方）能单独掌握完整的私钥，从根源上消除了私钥泄漏的风险。

这种分层架构的好处是显而易见的：协议层稳定，业务逻辑层可灵活扩展新工具，依赖服务层可以独立升级或替换。例如，如果未来Zcash网络升级，只需要确保Zebra节点更新并保持RPC接口兼容， zcash-mcp 本身可能无需改动。

3. 核心工具详解与使用场景

zcash-mcp 的22个工具可以大致归为五类：基础查询、ZAP1凭证操作、支付与发票、高级钱包管理，以及跨链与验证。我们挑几个最有代表性的深入看看。

3.1 基础链上查询工具

这类工具是区块链交互的“眼睛”，让AI能“看到”链上发生了什么。

get_block_height : 获取当前Zcash网络的最新区块高度。这就像问“现在几点了？”，是许多链上操作的基准参考。实现上就是向本地Zebra节点的 getblockchaininfo RPC接口发一个最简单的查询。
lookup_transaction : 根据交易ID（txid）查询一笔交易的原始数据。返回的信息包括交易的输入、输出、手续费、所在区块等。这对于审计、追踪交易状态至关重要。在Zcash中，查询透明交易和屏蔽交易的细节不同，这个工具内部需要根据txid的特征来调用合适的RPC方法。

实操心得 ：在配置 ZEBRA_RPC_URL 时，务必确保你的Zebra节点已经完成同步，并且RPC服务已开启（默认端口8232）。对于生产环境，建议将Zebra节点运行在独立的服务器上，并通过内网或安全的反向代理来访问，避免将RPC端口直接暴露在公网。

3.2 ZAP1凭证协议工具集

这是 zcash-mcp 的“杀手锏”，赋予了AI处理链上可信声明（Attestation）的能力。ZAP1协议允许用户在Zcash区块链上写入一个经过密码学证明的、不可篡改的“小纸条”（凭证），比如“AI助手A于X年X月X日完成了Y服务”。

attest_event : 写入凭证 。这是需要API密钥的写操作。你需要提供凭证类型（type）、关联的钱包哈希（wallet_hash）、以及自定义数据（data）。工具会将这些数据构造为一个ZAP1凭证，通过ZAP1 API提交，最终被打包进一个Zcash交易中，永久上链。例如，一个AI任务平台可以用它来记录任务完成凭证。
get_balance : 查询凭证历史与状态 。输入一个钱包哈希，它可以返回这个地址所有的ZAP1凭证历史，以及当前凭证在ZAP1默克尔树中的“锚定状态”。这相当于查询一个地址的“信誉档案”。
verify_proof : 验证凭证 。给定一个凭证的叶子哈希（leaf_hash）和对应的默克尔证明（merkle_proof），这个工具可以验证该凭证是否真实存在于某个已锚定到Zcash主网的默克尔树根下。这是实现去信任验证的核心。
get_agent_status : 查询智能体状态 。输入一个ZAP1智能体ID，返回该智能体发布的所有凭证摘要。这对于管理一个由多个AI或服务组成的“智能体军团”非常有用。

注意事项 ： attest_event 操作会产生真实的Zcash网络交易手续费。虽然凭证数据本身很小，但它需要被包含在一笔标准的交易中。在测试时，可以使用测试网API或确保有足额的测试网ZEC。生产环境使用则需要谨慎评估成本。

3.3 隐私支付与发票工具

让AI处理支付，隐私和安全是首要考虑。 zcash-mcp 通过Zcash的屏蔽池和ZIP 321支付协议来实现。

send_shielded : 生成屏蔽支付URI 。这是最常用的支付工具。你只需要提供接收方的屏蔽地址（z-addr）和支付金额，它会生成一个符合ZIP 321标准的 zcash: 支付URI。用户在任何支持此标准的钱包（如ZecWallet）中打开这个链接，就会自动填充收款地址和金额，并且资金是从用户的屏蔽池发送到接收方的屏蔽池，全程交易金额和地址对区块链观察者都是加密的。
zcash_create_invoice & zcash_watch_payment : 创建并监控支付发票 。这是一套组合拳，常用于商业场景。 create_invoice 会生成一个带有唯一ID的发票，返回支付地址、金额、URI和过期时间。你可以将这个发票发给付款方。与此同时，或之后，你可以启动 watch_payment 工具，传入发票ID，它会持续轮询区块链，直到检测到有一笔支付发送到了该发票的地址，然后返回交易详情。这实现了简单的“支付确认”自动化。

技术细节补充 ：Zcash的屏蔽地址（z-addr）和透明地址（t-addr）有本质区别。透明地址的交易像比特币一样公开可查。而屏蔽地址的交易利用zk-SNARKs技术，验证者只能证明“这笔交易是合法的”，但无法知道具体谁转给了谁、转了多少钱。 send_shielded 工具强制使用屏蔽地址，正是为了继承Zcash最强的隐私特性。

3.4 高级钱包管理与MPC签名

这是面向高级用户和开发者的工具集，引入了Ika 2PC-MPC（两方计算-多方计算）方案，解决了私钥管理的终极难题。

zcash_create_wallet : 创建分片密钥钱包 。传统的钱包，私钥要么由用户自己保管（容易丢失），要么托管在第三方（有跑路风险）。MPC钱包将私钥“切分”成多个分片，由不同方持有。 zcash-mcp 集成的Ika方案采用2PC-MPC，意味着私钥被分成两片，一片由用户端（通过本地生成的助记词）控制，另一片由Ika服务端控制。 任何一笔交易都需要双方合作才能签名，任何一方都无法单独盗取资产。 这个工具会引导你完成钱包创建流程，并返回一个钱包ID。
zcash_sign_mpc : MPC协作签名 。当需要从上述MPC钱包发起交易时，调用此工具。你提供钱包ID和需要签名的交易哈希，它会与远端的Ika服务进行一轮或多轮密码学交互，最终合力产生一个有效的签名，而全程你的私钥分片不会离开你的设备，Ika服务也看不到完整的私钥。
zcash_shield : 将MPC托管的透明ZEC转入屏蔽池 。MPC钱包初始创建的是透明地址（t-addr）。如果你希望获得更强的隐私保护，可以使用这个工具，将透明地址中的ZEC，通过一笔屏蔽交易，转移到属于你自己的屏蔽地址（z-addr）中。此后，这些资产就完全由你的屏蔽钱包私钥控制了。

安全警告 ：MPC方案虽然安全，但引入了依赖。Ika服务的安全性、可用性变得至关重要。务必使用官方或极度可信的Ika服务提供商。同时，妥善保管好你在创建钱包时生成的本地助记词分片，这是你资产的最终保障。

3.5 跨链交换与链上验证

这些工具展示了Zcash生态与其他区块链互操作的探索。

zcash_crosschain_swap : 跨链交换意图 。目前支持将透明的ZEC交换为BTC、USDC或USDT。其原理并非在 zcash-mcp 内完成原子交换，而是 生成一个符合Ika或NEAR协议标准的交换意图对象 。你需要将这个意图提交到相应的跨链桥或去中心化交易所来完成实际交换。这个工具的价值在于，AI可以帮你规划和构造复杂的跨链资产转换请求。
zcash_verify_evm : 在EVM链上验证ZAP1证明 。这是将Zcash的信任传递到其他区块链（如以太坊、Base、Arbitrum）的关键。你可以将一个在Zcash上生成的ZAP1默克尔证明，通过这个工具，生成一个在指定EVM链上智能合约的调用参数。在该EVM链上部署的验证合约可以据此确认某个ZAP1凭证的真实性，从而触发链上的其他逻辑（如发放NFT、解锁权限）。这为构建跨链信誉系统打开了大门。

4. 从零开始：配置与集成实战

了解了工具能做什么，接下来我们一步步把它用起来。这里以在Claude Desktop上集成为例，其他MCP客户端（如Cursor）配置类似。

4.1 环境准备与依赖安装

首先，你需要一个运行中的Zebra节点。这是大多数读操作的基础。

# 1. 克隆并编译Zebra (需要Rust环境)
git clone https://github.com/ZcashFoundation/zebra.git
cd zebra
cargo build --release

# 2. 运行Zebra节点 (主网)
./target/release/zebra start

# 或者使用Docker (更简单)
docker run -d -p 8232:8232 --name zebra zcashfoundation/zebra:latest

运行后，Zebra会开始同步区块，这可能需要几个小时甚至更久（取决于网络和硬盘速度）。你可以通过访问 http://127.0.0.1:8232 来测试RPC是否就绪（会返回一个405错误，这是正常的，因为需要POST请求）。

接下来，安装 zcash-mcp 服务器。全局安装更方便：

npm install -g @frontiercompute/zcash-mcp

安装后，你可以直接运行 zcash-mcp 来测试服务器是否正常启动（它会等待stdio输入，按Ctrl+C退出）。

4.2 配置Claude Desktop

Claude Desktop的MCP服务器配置是一个JSON文件，位置因操作系统而异：

macOS : ~/Library/Application Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

如果文件不存在，就创建一个。然后添加 zcash-mcp 的配置：

{
  "mcpServers": {
    "zcash": {
      "command": "npx",
      "args": ["@frontiercompute/zcash-mcp"],
      "env": {
        "ZEBRA_RPC_URL": "http://127.0.0.1:8232",
        "ZAP1_API_KEY": "your_trial_key_here"
      }
    }
  }
}

配置参数详解 ：

command : 这里用的是 npx ，它会自动下载并运行最新版本的 @frontiercompute/zcash-mcp 包。你也可以指向全局安装的 zcash-mcp 命令（如果 npm install -g 了）。
args : 传递给命令的参数，这里就是包名。
env : 设置环境变量。 ZEBRA_RPC_URL 指向你的本地节点。 ZAP1_API_KEY 对于读操作不是必须的，但如果你想使用 attest_event 等写操作，就需要申请一个。

获取试用API Key ：正如项目README提到的，你可以通过一个简单的curl命令获取试用密钥：

curl -s -X POST https://frontiercompute.cash/api/trial-key

将返回的key填入配置文件的 ZAP1_API_KEY 字段。

保存配置文件后， 必须完全重启Claude Desktop应用 （不仅仅是关闭窗口，要从任务管理器/活动监视器彻底退出再重启），配置才会生效。

4.3 首次交互测试

重启Claude Desktop后，打开一个新对话。你可以直接问它：“What is the current Zcash block height?”（当前Zcash区块高度是多少？）。

如果一切配置正确，Claude会识别到可用的 zcash 工具，并调用 get_block_height 。你会在回复中看到它调用了工具，并返回一个数字（例如 2,500,123 ）。这意味着集成成功了！

你可以继续尝试其他只读工具，比如：

“Look up transaction with txid: [一个真实的Zcash交易ID]”
“Get the ZAP1 anchor status.”
“Decode this shielded memo: [一段Base64编码的备忘录]”

踩坑记录 ：最常见的问题是Claude Desktop没有正确加载配置。确保：1. 配置文件路径和名称绝对正确。2. JSON格式合法，没有多余的逗号。3. 重启是“彻底”的。在macOS上，可以打开“活动监视器”搜索“Claude”并强制退出。在Windows上，使用任务管理器结束所有Claude相关进程。

4.4 进阶：在自定义AI应用中使用

除了预置客户端，你也可以在自己的Node.js项目中直接集成 zcash-mcp 作为子进程调用，或者使用MCP客户端SDK。

方法一：作为子进程调用

import { spawn } from 'child_process';
import { StdioServer } from '@modelcontextprotocol/sdk/server/stdio.js';

const serverProcess = spawn('npx', ['@frontiercompute/zcash-mcp'], {
  stdio: ['pipe', 'pipe', 'inherit'], // 继承stderr以便调试
  env: { ...process.env, ZEBRA_RPC_URL: 'http://localhost:8232' }
});

// 接下来你需要实现MCP客户端，通过stdin/stdout与serverProcess通信
// 这涉及到MCP协议的握手、请求/响应循环，比较复杂。

方法二：使用MCP客户端SDK（推荐） 社区有像 @modelcontextprotocol/sdk 这样的库，但更简单的是直接使用已经支持MCP的AI应用开发框架，或等待更上层的客户端库成熟。对于大多数用户，通过Claude Desktop或Cursor来使用是目前最平滑的路径。

5. 实战案例：构建一个AI驱动的链上凭证系统

理论说再多，不如看一个实际的应用场景。假设我们想构建一个“AI任务完成公证系统”：用户发布任务，AI（或AI辅助的工人）完成任务后，将完成凭证永久记录在Zcash区块链上，任何人都可以公开验证。

5.1 系统设计与流程

角色定义 ：
- 任务发布者 ：拥有一个Zcash屏蔽地址（z-addr）。
- AI执行者 ：一个具有唯一 agent_id 的AI Agent，集成了 zcash-mcp 。
- 验证者 ：任何想验证任务是否完成的人。
核心流程 ：
- 步骤1（发布） ：任务发布者创建一个任务，并生成一个唯一的 task_id 。
- 步骤2（执行与公证） ：AI执行者完成任务后，调用 attest_event 工具，凭证类型（type）设为 TASK_COMPLETION ，数据（data）中包含 task_id 、完成时间戳等，钱包哈希（wallet_hash）使用发布者的z-addr派生出的一个哈希（用于隐私保护，不直接暴露地址）。
- 步骤3（锚定） ：该凭证被ZAP1网络处理，并最终被锚定（Anchor）到Zcash主网的一个区块中，获得一个默克尔根（Merkle Root）和证明（Proof）。
- 步骤4（验证） ：验证者获得 task_id 和对应的叶子哈希（leaf_hash），调用 verify_proof 工具，传入证明和默克尔根信息，即可独立验证该完成凭证是否真实存在且未被篡改。

5.2 关键代码逻辑模拟

虽然 zcash-mcp 本身是服务器，但我们可以模拟AI Agent调用它的逻辑。假设我们在一个Node.js脚本中模拟AI执行者：

// 模拟环境：假设我们通过某种方式直接调用了zcash-mcp的工具函数
// 在实际中，这是通过MCP协议与zcash-mcp服务器进程通信完成的

async function attestTaskCompletion(taskId, publisherZAddr, zap1ApiKey) {
  // 1. 从发布者的z-addr生成一个钱包哈希 (实际中可能通过特定算法)
  // 这里仅为示例，ZAP1协议可能有标准的派生方法
  const walletHash = deriveWalletHash(publisherZAddr); 

  // 2. 构造凭证数据
  const attestationData = {
    type: 'TASK_COMPLETION_V1',
    wallet_hash: walletHash,
    data: {
      task_id: taskId,
      completed_at: new Date().toISOString(),
      agent_id: 'my_ai_agent_001',
      // ... 其他元数据
    }
  };

  // 3. 调用 atttest_event 工具 (通过MCP调用)
  // 伪代码，实际是发送一个MCP JSON-RPC请求
  const result = await callMcpTool('attest_event', {
    attestation: attestationData
  }, { ZAP1_API_KEY: zap1ApiKey });

  if (result.success) {
    console.log(`任务 ${taskId} 完成凭证已提交！`);
    console.log(`交易ID: ${result.txid}`);
    console.log(`叶子哈希 (leaf_hash): ${result.leaf_hash}`); // 保存此哈希供后续验证
    return result.leaf_hash;
  } else {
    throw new Error(`凭证提交失败: ${result.error}`);
  }
}

async function verifyCompletion(leafHash, merkleProof) {
  // 调用 verify_proof 工具
  const verificationResult = await callMcpTool('verify_proof', {
    leaf_hash: leafHash,
    merkle_proof: merkleProof // 这个proof可以从get_balance或prove_payment等工具获取
  });

  if (verificationResult.verified) {
    console.log('✅ 凭证验证通过！该任务完成记录真实有效。');
    return true;
  } else {
    console.log('❌ 凭证验证失败。记录可能不存在或已被篡改。');
    return false;
  }
}

5.3 潜在问题与优化

成本问题 ：每次 attest_event 都是一笔链上交易，需要支付ZEC作为矿工费。对于高频、微额的任务场景，成本可能过高。
- 优化方案 ：采用“批处理”或“二层”思路。可以设计一个系统，将多个任务完成凭证先在链下聚合，定期（如每小时）将聚合后的默克尔根一次性锚定上链。单个任务的验证者可以通过链下的默克尔证明和最终的链上锚定根进行验证。ZAP1协议本身可能就支持这种批处理模式。
隐私与关联 ：虽然凭证数据本身可能加密，但钱包哈希如果直接由z-addr派生，且多次使用，可能会被关联分析。
- 优化方案 ：使用零知识证明技术，让AI执行者证明“我知道某个任务的完成凭证对应某个钱包哈希”，而不直接暴露该哈希与发布者z-addr的关联。或者，使用每次交易生成的一次性支付地址（OVK）来派生不同的钱包哈希。
AI的自主性与安全 ：让AI自动调用 attest_event 需要它持有API Key。这存在API Key泄漏或被滥用的风险。
- 优化方案 ：不要将主API Key直接交给AI。可以搭建一个代理服务，AI通过该代理服务来请求上链。代理服务可以实施速率限制、内容审核、预算控制等策略。或者，使用具有细粒度权限和过期时间的临时令牌。

6. 常见问题排查与调试技巧

在实际集成和使用 zcash-mcp 的过程中，你肯定会遇到各种问题。这里整理了一些常见坑点和解决方法。

6.1 连接与配置问题

问题1：Claude Desktop不响应，或提示“没有可用工具”。

检查点1：配置文件路径和格式 。这是最常见的问题。用JSON验证器检查你的 claude_desktop_config.json 文件。确保没有语法错误，比如最后一个条目后面多了逗号。
检查点2：彻底重启 。在macOS上，使用 Cmd+Q 退出Claude，然后在“活动监视器”中确认所有“Claude”进程都已结束，再重新启动。在Windows上，使用任务管理器。
检查点3：查看日志 。Claude Desktop有时会在其配置目录下生成日志文件。查看日志中是否有关于加载MCP服务器的错误信息。
检查点4：手动测试服务器 。打开终端，运行 npx @frontiercompute/zcash-mcp 。如果服务器无法启动（例如，缺少Node.js环境或依赖），这里会报错。确保Node.js版本在18以上。

问题2：工具调用失败，提示“Connection refused”或“ECONNREFUSED”。

原因：这通常是 ZEBRA_RPC_URL 配置错误，或者Zebra节点没有运行。
解决：
1. 在浏览器中访问 http://127.0.0.1:8232 （如果你用的是默认配置和端口）。如果看到类似“405 Method Not Allowed”的页面，说明RPC服务在运行，这是正常的。如果连接被拒绝，说明Zebra没启动或端口不对。
2. 检查Zebra进程： ps aux | grep zebra (Linux/macOS) 或查看任务管理器 (Windows)。
3. 确认Zebra的RPC端口配置。在Zebra的配置文件 zebrad.toml 中，确保有 [rpc] 部分且 listen_addr = "127.0.0.1:8232" 。

问题3：调用 attest_event 等写操作时，提示“API key required”或“Unauthorized”。

原因：没有设置有效的 ZAP1_API_KEY 环境变量，或者试用密钥已过期。
解决：
1. 确认配置文件中 env 字段里的 ZAP1_API_KEY 值正确无误。
2. 重新申请一个试用密钥： curl -s -X POST https://frontiercompute.cash/api/trial-key 。
3. 如果用于生产，可能需要联系Frontier Compute获取正式API密钥。

6.2 工具使用与数据问题

问题4： decode_memo 工具解码出来的中文是乱码。

原因：Zcash的备忘录（Memo）字段是512字节的任意数据。不同钱包和协议（如ZIP 302、ZAP1 typed memo）对文本的编码方式可能不同，常见的有UTF-8和UTF-16LE。
解决： decode_memo 工具内部已经尝试了多种解码方式。如果仍然乱码，可能是数据本身不是文本，或者是自定义的二进制格式。你需要根据写入备忘录的源头协议来确认其编码方式。对于ZAP1 typed memo，其文本字段通常是UTF-8。

问题5： get_balance 返回的数据中，某个凭证的 anchored 状态一直是 false 。

原因：ZAP1协议为了效率，不会将每一个凭证（叶子）都单独上链，而是将一批凭证构建成一棵默克尔树，定期将树的根（Merkle Root）锚定到Zcash链上。你的凭证可能已经提交到ZAP1网络，但还在等待被包含进下一批次的锚定交易中。
解决：这是正常现象。你可以通过 get_anchor_status 工具查看下一批锚定的推荐时间或当前未锚定叶子的数量。通常锚定是定期进行的（例如每小时或每达到一定数量叶子后）。

问题6：使用 zcash_create_wallet 创建的MPC钱包，如何备份？

关键：MPC钱包的备份至关重要。在创建流程中， Ika服务会提示你在本地生成并安全保存一份“恢复分片”或“助记词” 。 这个分片绝不能丢失！ Ika服务方持有另一分片，但他们无法用单独的分片恢复你的钱包。
操作：严格按照创建钱包时客户端的指引，将助记词写在纸上，存放在多个物理安全的地方。 切勿截图存放在联网设备或云盘上 。

6.3 性能与高级调试

问题7：工具调用响应慢。

可能原因1 ：Zebra节点还在同步区块。初始同步期间，RPC响应会变慢。可以等待同步完成，或使用轻量级客户端模式（如果支持）。
可能原因2 ：ZAP1 API服务器网络延迟。该服务部署在云端，受网络状况影响。可以尝试 ping 或 curl 测试其延迟。
可能原因3 ：复杂的工具（如 verify_proof 涉及密码学运算）本身就需要一定计算时间。

问题8：如何查看 zcash-mcp 服务器的详细日志进行调试？

方法：在Claude Desktop配置中，无法直接查看stdio日志。但你可以通过命令行手动启动服务器并测试，这样所有日志都会输出到控制台。
1. 打开终端，设置环境变量：
```
export ZEBRA_RPC_URL=http://127.0.0.1:8232
export ZAP1_API_KEY=your_key
```
2. 运行服务器：
```
npx @frontiercompute/zcash-mcp
```
3. 服务器启动后，它会等待stdin输入。此时，你可以手动构造MCP JSON-RPC请求（比较复杂）。更简单的测试方法是运行项目自带的测试套件： npm run test:live （需要配置好所有环境变量），它会模拟客户端调用所有工具并打印详细输出。

问题9：我想扩展 zcash-mcp ，添加自定义工具，怎么办？

路径： zcash-mcp 是开源项目。你可以Fork其GitHub仓库，在 src/tools/ 目录下参考现有工具添加新的工具函数，然后在 src/index.ts 中注册它，最后重新构建（ npm run build ）。这要求你对TypeScript、MCP协议和Zcash相关操作有较深的理解。