JinDaGe - stacks-clarity-mcp MCP Details

article

README

🚀 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：本地开发设置（当前）

克隆并安装：

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

构建项目：

npm run build

注意：这将生成包含编译后 JavaScript 的 dist/ 文件夹。在运行服务器之前必须进行构建。

配置 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 替换为实际路径！

完全重启 Cursor（退出并重新打开）
验证设置：
- 转到 Cursor → 设置 → MCP
- 查找 stacks-clarity-mcp 旁边的绿色指示器
- 在聊天中切换到代理模式
- 使用以下命令进行测试："list available stacks tools"

网络选项

mainnet - 生产 Stacks 网络
testnet - 带有免费代币的测试网络
devnet - 使用 Clarinet 进行本地开发

获取 Hiro API 密钥（可选）

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

访问 platform.hiro.so
创建账户并生成 API 密钥
将其添加到配置中的 HIRO_API_KEY

📚 详细指南：查看 integration_guides/ 文件夹，获取 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 多种改进的成本计算

开发工作流程

研究标准：使用 list_sips 和 get_sip 了解要求
生成合约：使用模板工具生成符合 SIP 的实现
安全测试：生成全面的安全测试套件
性能优化：使用 SIP-012 工具进行分析和优化
前端集成：构建具有钱包连接功能的用户界面
部署：使用 Clarinet 工具进行生产部署

生产检查清单

✅ 验证 SIP 合规性
✅ 实现强制后置条件
✅ 通过安全测试
✅ 使用 SIP-012 进行性能优化
✅ 正确集成前端
✅ 通过所有测试（单元、集成、安全）

故障排除

MCP 服务器未在 Cursor 中显示

检查 MCP 设置：
- 转到 Cursor → 设置 → Cursor 设置 → MCP
- 查找 stacks-clarity-mcp 条目
- 检查指示器是绿色（已连接）还是红色（错误）
- 点击条目查看错误详细信息
验证配置：
- 确保 .cursor/mcp.json 存在于项目根目录
- 对于本地开发，使用 server.ts 的 绝对路径
- 检查 Node.js 是否已安装：node --version
重启 Cursor：
- 完全退出 Cursor（不仅仅是关闭窗口）
- 重新打开 Cursor
- 等待 10 - 15 秒让 MCP 初始化
检查代理模式：
- 在 Cursor 聊天中，确保下拉菜单设置为代理（不是普通聊天）
- MCP 工具仅在代理模式下工作
测试 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 开发打造，将安全性、性能和合规性作为首要任务。