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社區用心打造 ❤️