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許可證。