Stacks Clarity MCP

🚀 Stacks Clarity MCP 服務器（非官方）

這是一個全面的 MCP（模型上下文協議）服務器，專為 Stacks 區塊鏈開發打造，提供 30 多種針對 Clarity 智能合約、SIP 合規性、安全性和性能優化的專業工具。

由以下團隊帶來

💡 初次接觸 MCP？ 查看我們的 集成指南，獲取 Cursor、Claude Code 或 本地開發 的分步設置說明。

🚀 快速開始

本全面的 MCP 服務器提供了完整的 Stacks 開發工具包，以安全優先的模式和 SIP 合規性實現了專業 Stacks dApp 開發的一級和二級優先級。

✨ 主要特性

• 🏗️ 完整的 SIP 標準訪問 - 提供 30 多種 SIP 標準及完整的 Clarity 代碼。
• 🔐 安全優先的開發 - 所有代幣轉移都有強制後置條件。
• ⚡ SIP-012 性能優化 - 數據庫容量提升 2 倍，支持動態存儲。
• 🎨 代幣標準 - 完整實現 SIP-009（NFT）和 SIP-010（FT）。
• 🧪 全面測試 - 生成單元、集成和安全測試。
• 🔧 Clarinet 集成 - 提供完整的項目設置和管理工具。
• 💰 賬戶管理 - 支持 STX 餘額、交易歷史和驗證。
• 📚 完整文檔 - 包含 Clarity 手冊、SIP 標準和集成指南。

📦 安裝指南

前提條件

• Node.js 和 npm（npm ≥ 5.2.0）
• Clarinet CLI（用於合約開發）
• Stacks 錢包（用於前端集成）
• Cursor IDE 或 Claude Code（用於 MCP 集成）

Cursor/Claude Code 的快速設置

選項 1：使用已發佈的包（如果可用）

一旦發佈到 npm，在項目中創建 .cursor/mcp.json：

{
  "mcpServers": {
    "stacks-clarity-mcp": {
      "command": "npx",
      "args": ["-y", "@stacks/stacks-clarity-mcp"],
      "env": {
        "HIRO_API_KEY": "",
        "STACKS_NETWORK": "testnet"
      }
    }
  }
}

選項 2：本地開發設置（當前）

1. 克隆並安裝：

git clone https://github.com/YOUR_USERNAME/stacks-clarity-mcp.git
cd stacks-clarity-mcp
npm install

2. 構建項目：

npm run build

注意：這將生成包含編譯後 JavaScript 的 dist/ 文件夾。在運行服務器之前必須進行構建。

3. 配置 Cursor - 在項目根目錄創建 .cursor/mcp.json：

{
  "mcpServers": {
    "stacks-clarity-mcp": {
      "command": "npx",
      "args": ["-y", "tsx", "/absolute/path/to/stacks-clarity-mcp/src/server.ts"],
      "env": {
        "HIRO_API_KEY": "",
        "STACKS_NETWORK": "testnet"
      }
    }
  }
}

重要：將 /absolute/path/to/stacks-clarity-mcp 替換為實際路徑！

4. 完全重啟 Cursor（退出並重新打開）
5. 驗證設置：
   • 轉到 Cursor → 設置 → MCP
   • 查找 stacks-clarity-mcp 旁邊的綠色指示器
   • 在聊天中切換到 代理 模式
   • 使用以下命令進行測試："list available stacks tools"

網絡選項

• mainnet - 生產 Stacks 網絡
• testnet - 帶有免費代幣的測試網絡
• devnet - 使用 Clarinet 進行本地開發

獲取 Hiro API 密鑰（可選）

要使用增強功能和更高的速率限制：

1. 訪問 platform.hiro.so
2. 創建賬戶並生成 API 密鑰
3. 將其添加到配置中的 HIRO_API_KEY

📚 詳細指南：查看 文件夾，獲取 Cursor、Claude Code 和 開發 設置的指南。

💻 使用示例

基礎用法

快速開始指南

1. 探索可用標準

// 發現所有 SIP 標準
use tool: list_sips

// 獲取特定代幣標準
use tool: get_token_standards

// 訪問完整的 Clarity 參考
use tool: get_clarity_book

2. 構建 SIP-010 代幣

// 生成合規的代幣合約
use tool: generate_sip010_template
params: {
  tokenName: "MyToken",
  symbol: "MTK",
  decimals: 6,
  features: ["minting", "burning"]
}

// 創建安全轉移
use tool: generate_sip010_transfer
params: {
  contractId: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.my-token",
  amount: 1000000,
  sender: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R",
  recipient: "ST2CY5V39NHDPWSXMW9QDT3HC3GD6Q6XX4CFRK9AG",
  memo: "Secure transfer with post-conditions"
}

3. 設置開發環境

// 初始化 Clarinet 項目
use tool: generate_clarinet_project
params: {
  projectName: "my-stacks-project",
  template: "fungible-token"
}

// 生成全面測試
use tool: generate_contract_tests
params: {
  contractName: "my-token",
  testType: "security",
  scenarios: ["post-conditions", "authorization"]
}

高級用法

性能優化

// 分析合約性能
use tool: analyze_contract_performance
params: {
  contractCode: "...", // 你的 Clarity 合約
  optimizationLevel: "advanced"
}

// 獲取優化建議
use tool: generate_optimization_recommendations
params: {
  contractPattern: "token-contract",
  currentIssues: ["high gas costs", "multiple map operations"]
}

集成示例

React 前端與 @stacks/connect

// 獲取完整的前端指南
use tool: build_stacks_frontend

// 生成錢包連接代碼
// 帶有後置條件的交易簽名
// 錯誤處理和用戶體驗

DeFi 協議開發

// 性能優化的 DeFi 合約
use tool: generate_clarity_contract
params: {
  contractName: "amm-pool",
  contractType: "custom",
  features: ["governance", "staking"]
}

// 安全測試
use tool: generate_contract_tests
params: {
  contractName: "amm-pool",
  testType: "security",
  scenarios: ["reentrancy", "authorization", "post-conditions"]
}

NFT 市場

// 符合 SIP-009 的 NFT 集合
use tool: generate_sip009_template
params: {
  collectionName: "Art Collection",
  symbol: "ART",
  features: ["metadata", "royalties"]
}

// 帶有託管的市場合約
use tool: generate_clarity_contract
params: {
  contractName: "nft-marketplace",
  contractType: "custom",
  features: ["escrow", "royalties"]
}

📚 詳細文檔

可訪問完整的 Stacks 開發資源：

• 34000 多行 的 Clarity 手冊文檔
• 30 多種 SIP 標準 及完整實現
• 安全模式 和最佳實踐
• 性能優化 指南
• 前端集成 示例

🔧 技術細節

安全特性

強制後置條件

所有代幣轉移 必須 包含後置條件。MCP 服務器強制執行此規則：

// ✅ 正確：帶有後置條件的轉移
use tool: generate_fungible_post_condition
params: {
  address: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R",
  contractId: "ST1H1733V5MZ3SZ9XRW9FKYGEZT0JDGEB8Y634C7R.token",
  amount: 1000000,
  condition: "equal"
}

// 始終使用 PostConditionMode.Deny 以實現最大安全性

SIP 合規性強制執行

• 自動檢查 SIP-009 和 SIP-010 合規性
• 原生資產函數使用（ft-transfer?，nft-transfer?）
• 正確的錯誤處理和授權模式

SIP-012 性能優化

• 數據庫操作增加 2 倍：每個塊的讀寫限制增加
• 動態列表存儲：僅為實際數據大小付費
• 優化成本函數：100 多種改進的成本計算

開發工作流程

1. 研究標準：使用 list_sips 和 get_sip 瞭解要求
2. 生成合約：使用模板工具生成符合 SIP 的實現
3. 安全測試：生成全面的安全測試套件
4. 性能優化：使用 SIP-012 工具進行分析和優化
5. 前端集成：構建具有錢包連接功能的用戶界面
6. 部署：使用 Clarinet 工具進行生產部署

生產檢查清單

• ✅ 驗證 SIP 合規性
• ✅ 實現強制後置條件
• ✅ 通過安全測試
• ✅ 使用 SIP-012 進行性能優化
• ✅ 正確集成前端
• ✅ 通過所有測試（單元、集成、安全）

故障排除

MCP 服務器未在 Cursor 中顯示

1. 檢查 MCP 設置：
   • 轉到 Cursor → 設置 → Cursor 設置 → MCP
   • 查找 stacks-clarity-mcp 條目
   • 檢查指示器是綠色（已連接）還是紅色（錯誤）
   • 點擊條目查看錯誤詳細信息
2. 驗證配置：
   • 確保 .cursor/mcp.json 存在於項目根目錄
   • 對於本地開發，使用 server.ts 的 絕對路徑
   • 檢查 Node.js 是否已安裝：node --version
3. 重啟 Cursor：
   • 完全退出 Cursor（不僅僅是關閉窗口）
   • 重新打開 Cursor
   • 等待 10 - 15 秒讓 MCP 初始化
4. 檢查代理模式：
   • 在 Cursor 聊天中，確保下拉菜單設置為 代理（不是普通聊天）
   • MCP 工具僅在代理模式下工作
5. 測試 MCP 連接：

# 直接測試服務器
npx tsx /path/to/server.ts

# 或使用 MCP 檢查器
npx @modelcontextprotocol/inspector

常見問題

• “命令未找到”：確保使用 npx tsx 而不僅僅是 tsx
• “模塊未找到”：在 MCP 服務器目錄中運行 npm install
• 構建錯誤：對於本地開發，使用 tsx 從源代碼運行（跳過構建步驟）
• 工具不可見：確保處於 代理模式 且 MCP 顯示綠色指示器

獲取幫助

• 查看 集成指南 以獲取詳細設置
• 查看 development_usage.md 以進行本地開發
• 使用 MCP 檢查器測試工具：npx @modelcontextprotocol/inspector

🤝 貢獻

此 MCP 服務器實現了完整的 Stacks 開發棧。貢獻應遵循以下原則：

• 安全優先原則
• SIP 標準合規性
• 注重性能優化
• 提供全面文檔

📄 許可證

本項目採用 Apache 2.0 許可證。

🔗 資源

• Stacks 文檔
• Clarity 語言參考
• SIP 標準
• Clarinet CLI
• Stacks.js

專為專業 Stacks 開發打造，將安全性、性能和合規性作為首要任務。