MCP Hats

🚀 Hats协议MCP服务器

Hats协议MCP服务器是一个全面的模型上下文协议（MCP）服务器，用于管理Hats协议操作，包括角色管理、权限检查、组织结构管理以及跨多个区块链网络的分析功能。

🚀 快速开始

本MCP服务器可以与Claude Code集成使用，也可以手动运行。与Claude Code集成是最便捷的使用方式，安装服务器后，将其添加到Claude配置中即可。若你更喜欢手动运行服务器，可在开发或独立使用时选择此方式。

✨ 主要特性

• 帽子管理：创建、铸造、销毁和转移帽子。
• 树结构操作：管理分层组织结构。
• 权限检查：验证佩戴者、状态和资格。
• 元数据操作：更新帽子详细信息和属性。
• 查询工具：使用GraphQL子图搜索和过滤帽子。
• 分析功能：生成报告并跟踪活动。
• 多链支持：支持所有Hats协议网络。
• 外部签名：准备交易以供硬件钱包签名。

📦 安装指南

# 克隆仓库
git clone <repository-url>
cd mcp-hats-protocol-server

# 安装依赖
npm install

# 构建项目
npm run build

📚 详细文档

配置

环境变量

将 .env.template 复制到 .env 并进行配置：

# RPC 提供商 API 密钥（可选 - 若未提供则使用公共端点）
ALCHEMY_API_KEY=your_key_here
INFURA_API_KEY=your_key_here

# 区块浏览器 API 密钥（合约验证必需）
ETHERSCAN_API_KEY=your_key_here
POLYGONSCAN_API_KEY=your_key_here
# ... 其他浏览器密钥

API 密钥管理

你也可以使用MCP工具设置API密钥：

{
  "tool": "set-api-key",
  "args": {
    "keyName": "ALCHEMY_API_KEY",
    "value": "your_key_here"
  }
}

使用方法

与Claude Code集成

快速设置

# 克隆并安装服务器
git clone https://github.com/your-username/mcp-hats
cd mcp-hats
npm install
npm run build

# 添加到Claude Code（可选择提供API密钥以获得更好性能）
claude mcp add hats-protocol --env ALCHEMY_API_KEY=your_key_here -- node dist/index.js

其他设置方法

选项1：本地开发（无需构建）

claude mcp add hats-protocol --env ALCHEMY_API_KEY=your_key_here -- npx tsx src/index.ts

选项2：全局NPM安装（若已发布）

claude mcp add hats-protocol --env ALCHEMY_API_KEY=your_key_here -- npx mcp-hats-protocol

选项3：团队/项目配置

# 通过 .mcp.json 进行团队共享
claude mcp add --scope project hats-protocol --env ALCHEMY_API_KEY=your_key_here -- node dist/index.js

# 用户级访问，适用于所有项目
claude mcp add --scope user hats-protocol --env ALCHEMY_API_KEY=your_key_here -- node dist/index.js

管理集成

# 列出所有MCP服务器
claude mcp list

# 查看服务器详情
claude mcp get hats-protocol

# 移除服务器
claude mcp remove hats-protocol

Claude Code中的环境变量

添加服务器时可以设置API密钥：

claude mcp add hats-protocol \
  --env ALCHEMY_API_KEY=your_alchemy_key \
  --env ETHERSCAN_API_KEY=your_etherscan_key \
  -- node dist/index.js

手动服务器使用

若你更喜欢手动运行服务器（用于开发或独立使用）：

# 开发模式
npm run dev

# 生产模式
npm start

与Claude Code配合使用

集成后，你可以在与Claude的对话中直接使用Hats协议工具：

• 示例：检查某人是否拥有某个角色

Check if address 0x742C3cF9Af45f91B109a81EfEaf11535ECDe9571 is wearing hat 0x0000000100010000000000000000000000000000000000000000000000000000 on Ethereum

• 示例：创建一个新组织

Help me create a new DAO called "TechCollective" on Base Sepolia with myself (0x742C3cF9Af45f91B109a81EfEaf11535ECDe9571) as the founder

• 示例：分析组织结构

Show me the organizational structure for tree 0x00000001 on Base and visualize it as an ASCII tree

• 示例：获取角色分配指导

I need to assign the CTO role to a new team member. Can you guide me through the process and prepare the transaction?

Claude将自动使用适当的Hats协议工具，并通过内置提示和资源提供智能指导。

可用工具

• 帽子管理
  • create-hat - 在层级结构中创建一个新帽子
  • mint-hat - 将帽子分配给佩戴者
  • burn-hat - 从佩戴者处移除帽子
  • transfer-hat - 在佩戴者之间转移帽子
• 权限检查
  • check-hat-wearer - 验证某个地址是否佩戴特定帽子
  • check-hat-standing - 检查佩戴者是否处于良好状态
• 查询工具
  • get-hat-details - 获取帽子的详细信息
  • query-hats-by-wearer - 获取某个地址佩戴的所有帽子
  • get-tree-structure - 获取层级树结构
• 网络工具
  • list-networks - 列出所有支持的网络
  • set-api-key - 配置API密钥

示例命令

• 创建帽子

{
  "tool": "create-hat",
  "args": {
    "networkName": "ethereum",
    "admin": "0x0000000100000000000000000000000000000000000000000000000000000000",
    "details": "Engineering Team Lead",
    "maxSupply": 1,
    "eligibility": "0x0000000000000000000000000000000000000000",
    "toggle": "0x0000000000000000000000000000000000000000",
    "mutable": true,
    "imageURI": "https://example.com/hat-image.png"
  }
}

• 检查帽子佩戴者

{
  "tool": "check-hat-wearer",
  "args": {
    "networkName": "ethereum",
    "wearer": "0x742C3cF9Af45f91B109a81EfEaf11535ECDe9571",
    "hatId": "0x0000000100010000000000000000000000000000000000000000000000000000"
  }
}

开发

项目结构

src/
├── index.ts           # 入口点
├── server.ts          # MCP服务器设置
├── types/             # TypeScript定义
├── utils/             # 实用函数
├── networks/          # 网络配置
├── clients/           # Hats SDK和子图客户端
├── tools/             # MCP工具实现
└── resources/         # MCP资源

test/
├── unit/              # 单元测试
├── integration/       # 集成测试
└── e2e/              # 端到端测试

运行测试

# 运行所有测试
npm test

# 运行并生成覆盖率报告
npm run test:coverage

# 运行特定测试套件
npm run test:unit
npm run test:integration
npm run test:e2e

代码质量

# 类型检查
npm run typecheck

# 代码检查
npm run lint

# 代码格式化
npm run format

架构

核心组件

1. MCP服务器：处理工具注册和请求路由
2. Hats客户端：Hats协议SDK的包装器
3. 子图客户端：用于查询索引数据的GraphQL客户端
4. 网络管理器：多链配置和RPC管理
5. 工具实现：用于特定操作的各个工具

数据流

1. MCP客户端发送工具请求 → MCP服务器
2. 服务器使用Zod模式验证输入
3. 工具实现调用相应的客户端方法
4. 客户端与区块链或子图进行交互
5. 响应格式化并返回给MCP客户端

支持的网络

主网

• 以太坊
• Polygon
• Arbitrum One
• Optimism
• Base
• Gnosis链

测试网

• Sepolia
• Base Sepolia

资源

• Hats协议文档
• SDK文档
• 子图文档
• MCP规范

贡献

1. 创建功能分支
2. 为新功能编写测试
3. 确保所有测试通过
4. 提交包含详细描述的拉取请求

📄 许可证

本项目采用MIT许可证。