MCP Mistcash

🚀 MIST.cash SDK的MCP服务器

这是一个模型上下文协议（MCP）服务器，它在Starknet上展示了 MIST.cash 的私有支付功能。该服务器允许人工智能代理通过标准化接口与MIST.cash的隐私保护支付协议进行交互。

✨ 主要特性

• 5个MCP工具：用于交易操作。
• 2个MCP资源：提供合约和交易信息。
• 隐私优先：利用MIST.cash的零知识证明系统。
• 多代币支持：支持Starknet上的ETH、USDC、USDT和DAI。
• 可用于生产环境：具备重试逻辑、超时处理和全面的错误处理机制。

📦 安装指南

前置要求

• Node.js 20或更高版本（本地运行时需要）
• Docker（推荐团队使用）
• 访问Starknet的RPC提供商（或兼容的Appchain）

安装步骤

选项1：使用Docker（推荐团队使用）

这是确保团队成员拥有相同环境的最简单方法。

1. 构建镜像：

docker build -t mcp-mistcash .

2. 使用Docker运行： 若要与MCP客户端（如Claude Desktop）配合使用，需使用 docker run 命令。注意，-i 标志是进行标准输入输出通信所必需的。

docker run -i --rm \
  -e STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz \
  -e STARKNET_NETWORK=mainnet \
  -e CHAMBER_CONTRACT_ADDRESS=0xTuDireccionDeContrato \
  mcp-mistcash

选项2：本地开发（使用Node.js）

1. 克隆项目并安装依赖：

cd mcp-mistcash
npm install

2. 配置环境变量： 基于示例文件创建 .env 文件：

cp .env.example .env

编辑 .env 文件，填入你的配置信息（以下是Madara Appchain的示例）：

STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz
STARKNET_NETWORK=mainnet
MCP_LOG_LEVEL=info
# 可选：Chamber合约地址（如果不使用主网，在Madara上需要此地址）
# CHAMBER_CONTRACT_ADDRESS=0x...

3. 构建项目：

npm run build

💻 使用示例

与AI客户端集成

为了让团队成员在日常工作中使用这些工具，需要配置他们首选的AI客户端。

Claude Desktop

将以下内容添加到 claude_desktop_config.json 配置文件中：

• 配置文件路径：
  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：%APPDATA%\Claude\claude_desktop_config.json

使用Docker配置（推荐）

{
  "mcpServers": {
    "mist-cash": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz",
        "-e", "STARKNET_NETWORK=mainnet",
        "mcp-mistcash"
      ]
    }
  }
}

本地配置（备用）

{
  "mcpServers": {
    "mist-cash": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp-mistcash/dist/index.js"],
      "env": {
        "STARKNET_RPC_URL": "https://ztarknet-madara.d.karnot.xyz",
        "STARKNET_NETWORK": "mainnet"
      }
    }
  }
}

Cursor IDE

将以下内容添加到Cursor的MCP配置中：

{
  "mist-cash": {
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "-e", "STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz",
        "-e", "STARKNET_NETWORK=mainnet",
        "mcp-mistcash"
    ]
  }
}

📚 详细文档

可用工具

1. generar_secreto_transaccion

为私有交易生成加密密钥。 参数：

• claiming_key（字符串，必需）：交易的认领密钥。
• recipient_address（字符串，必需）：Starknet地址（以 0x 开头）。

2. obtener_assets_transaccion

获取交易的资产信息。

⚠️ 重要提示

此函数会显示已花费的资产。请使用 verificar_existencia_transaccion 进行准确验证。

参数：

• transaction_key（字符串，必需）：要查询的交易密钥。
• recipient_address（字符串，必需）：接收方的Starknet地址。
• provider_rpc_url（字符串，可选）：自定义RPC URL。

3. verificar_existencia_transaccion

验证特定资产的交易是否存在。适用于完全私有的交易。 参数：

• claiming_key（字符串，必需）：认领密钥。
• recipient（字符串，必需）：接收方地址。
• token_address（字符串，必需）：代币合约地址。
• amount（字符串，必需）：以基本单位（wei）表示的数量。

4. calcular_hash_transaccion

计算交易的唯一哈希值。 参数：

• transaction_key（字符串，必需）：交易密钥。
• recipient_address（字符串，必需）：接收方地址。
• token_address（字符串，必需）：代币地址。
• amount（字符串，必需）：以基本单位表示的数量。

5. obtener_configuracion_chamber

获取Chamber合约的配置和支持的代币信息。 参数：

• network（枚举，可选）："mainnet" 或 "sepolia"（默认值："mainnet"）。

可用资源

chamber://contract-info

提供MIST.cash的Chamber合约的静态信息，包括ABI、地址和特性。

chamber://tx/{txHash}

按哈希值提供特定交易的详细信息。

🔧 技术细节

安全实践

• 不处理私钥：仅处理（公开的）认领密钥。
• 地址验证：所有Starknet地址都会进行验证。
• 安全日志记录：交易密钥不会记录在日志中。
• 输入验证：所有输入都通过Zod模式进行验证。

重要警告

1. 已花费的交易：obtener_assets_transaccion 无法检测已花费的资产。
2. RPC成本：监控RPC使用情况，避免产生意外成本。
3. 网络延迟：所有合约调用的超时时间为30秒。

项目结构

mcp-mistcash/
├── src/
│   ├── index.ts                 # 主MCP服务器
│   ├── types.ts                 # TypeScript类型定义
│   ├── tools/                   # 工具实现
│   ├── resources/               # MCP资源
│   └── utils/                   # 实用工具（提供者、验证）
├── Dockerfile                   # 构建Docker镜像的配置
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

🤝 贡献说明

欢迎贡献代码。请确保：

1. 所有工具都有适当的错误处理。
2. 使用Zod模式验证输入。
3. 代码遵循TypeScript最佳实践。
4. 文档保持最新。

📄 许可证

本项目采用MIT许可证。

为Starknet和MCP社区用心打造 ❤️