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 开发打造，将安全性、性能和合规性作为首要任务。