Composer Kit MCP Server

Composer Kit MCP 服务

用于访问 Composer Kit UI 组件文档、示例和使用信息的 Model Context Protocol（MCP）服务。此服务全面支持 Composer Kit React 组件库，该库专为在 Celo 区块链上构建 web3 应用而设计。

安装

1. 克隆仓库：

git clone https://github.com/celo-org/composer-kit-mcp
cd composer-kit-mcp

2. 安装依赖：

pip install -e .

MCP 客户端设置

在 Cursor 中设置

1. 安装 MCP 服务（如果尚未安装）：

   pip install composer-kit-mcp
   

2. 配置 Cursor，将 MCP 服务添加到 Cursor 设置中：

   • 打开 Cursor 设置（Cmd/Ctrl + ,）
   • 前往“Features” → “Model Context Protocol”
   • 使用以下配置添加新的 MCP 服务：

   {
     "mcpServers": {
       "composer-kit-mcp": {
         "command": "uvx",
         "args": ["composer-kit-mcp"]
       }
     }
   }
   

3. 重启 Cursor 以加载 MCP 服务

4. 验证设置：向 Cursor 询问 Composer Kit 组件：

   • “有哪些 Composer Kit 组件可用？”
   • “演示如何使用 Wallet 组件”
   • “搜索与支付相关的组件”

在 Claude Desktop 中设置

1. 安装 MCP 服务（如果尚未安装）：

   pip install composer-kit-mcp
   

2. 找到 Claude Desktop 配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

3. 编辑配置文件以添加 MCP 服务：

   {
     "mcpServers": {
       "composer-kit-mcp": {
         "command": "uvx",
         "args": ["composer-kit-mcp"]
       }
     }
   }
   

   如果文件不存在，请使用上述内容创建文件。

4. 重启 Claude Desktop 以加载 MCP 服务

5. 验证设置：向 Claude 询问 Composer Kit：

   • 查看聊天界面中的 🔌 图标，确认 MCP 工具已可用
   • 提问：“你能帮我了解哪些 Composer Kit 组件？”
   • 试试：“演示如何使用 Payment 组件”

其他安装方式

使用 pipx（推荐用于隔离安装）

# Install pipx if you haven't already
pip install pipx

# Install composer-kit-mcp in an isolated environment
pipx install composer-kit-mcp

# The command will be available globally
composer-kit-mcp

使用虚拟环境

# Create a virtual environment
python -m venv composer-kit-mcp-env
source composer-kit-mcp-env/bin/activate  # On Windows: composer-kit-mcp-env\Scripts\activate

# Install the package
pip install composer-kit-mcp

# Use the full path in your MCP config
# e.g., /path/to/composer-kit-mcp-env/bin/composer-kit-mcp

故障排除

常见问题

1. 找不到命令：确保软件包已安装，并且命令位于 PATH 中

   which composer-kit-mcp  # Should show the path to the command
   

2. 权限错误：尝试使用 --user 标志安装，或使用 pipx

   pip install --user composer-kit-mcp
   

3. MCP 服务无法连接：检查配置中的命令路径是否正确

   composer-kit-mcp  # Should start the server (will wait for input)
   

4. Python 版本问题：确保使用 Python 3.11 或更高版本

   python --version  # Should be 3.11+
   

调试

测试 MCP 服务是否正常工作：

# Test the server directly
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | composer-kit-mcp

这应返回包含可用工具的 JSON 响应。

使用方法

运行服务

# Run the MCP server
python -m composer_kit_mcp.server

# Or use the CLI entry point
composer-kit-mcp

可用工具

组件信息

1. list_components

   • 列出所有可用的 Composer Kit 组件及其描述和类别
   • 无需参数

2. get_component

   • 获取特定组件的详细信息，包括源代码、属性和使用信息
   • 参数：component_name（例如：'button'、'wallet'、'payment'、'swap'）

3. get_component_example

   • 获取特定组件的示例用法代码，包含实际示例
   • 参数：component_name、example_type（可选：'basic'、'advanced'、'with-props'）

4. search_components

   • 按名称、描述或功能搜索组件
   • 参数：query（例如：'wallet'、'payment'、'token'、'nft'）

5. get_component_props

   • 获取特定组件属性的详细信息，包括类型、描述和要求
   • 参数：component_name

安装和设置

6. get_installation_guide

   • 获取 Composer Kit 的安装说明，包括设置步骤和配置
   • 参数：package_manager（可选：'npm'、'yarn'、'pnpm'、'bun'）

7. get_components_by_category

   • 获取特定类别中的所有组件
   • 参数：category（例如：'Core Components'、'Wallet Integration'、'Payment & Transactions'）

Celo Composer 工具

8. list_celo_composer_templates

   • 列出所有可用的 Celo Composer 模板及其描述、使用场景和功能
   • 无需参数

9. get_celo_composer_template

   • 获取特定 Celo Composer 模板的详细信息
   • 参数：template_name

10. list_celo_composer_frameworks

    • 列出 Celo Composer 支持的框架（React/Next.js、Hardhat）
    • 无需参数

11. get_celo_composer_commands

    • 获取可用的 Celo Composer CLI 命令、标志和用法示例
    • 无需参数

12. get_celo_composer_guide

    • 获取各类 Celo Composer 任务的分步指南
    • 参数：guide_type（'quick-start'、'smart-contract-deployment'、'local-development'、'ui-components'、'deployment'）

13. get_integration_guide

    • 获取有关在 Celo Composer 项目中集成 Composer Kit 的综合指南
    • 无需参数

14. create_celo_composer_project

    • 生成用于创建新 Celo Composer 项目的完整命令
    • 参数：project_name、owner、template、include_hardhat（可选，默认为 true）
    • 返回：完整的 CLI 命令，以及后续步骤和模板信息

可用组件

核心组件

• Address：显示 Ethereum 地址，支持截断和复制功能
• Balance：显示和管理代币余额，并控制精度
• Identity：显示用户信息，包括地址、名称、余额和社交链接

钱包集成

• Wallet：钱包连接和用户信息显示
• Connect：支持回调的钱包连接按钮

支付与交易

• Payment：通过内置对话框和错误处理发送付款
• Transaction：执行区块链交易并跟踪状态
• Swap：代币兑换界面，可选择要交换的代币

代币管理

• TokenSelect：通过筛选从列表中搜索并选择代币

NFT 组件

• NFT：显示 NFT 详情并提供铸造界面
• NFTCard：用于显示 NFT 的卡片布局
• NFTImage：NFT 图片显示组件
• NFTMeta：NFT 元数据展示
• NFTMint：NFT 铸造界面

主要功能

组件文档

• 完整 API 参考：所有组件的详细属性信息
• 用法示例：每个组件的真实代码示例
• 安装指南：分步设置说明
• 分类整理：按功能对组件进行分类

Celo Composer 集成

• 模板管理：访问所有 Celo Composer 模板
• 项目创建：生成新项目的完整 CLI 命令
• 框架支持：React/Next.js 和 Hardhat 集成信息
• 分步指南：有关项目设置、部署和开发的综合指南
• 集成文档：如何将 Composer Kit 组件与 Celo Composer 项目结合使用

搜索与发现

• 语义搜索：按功能或使用场景查找组件
• 分类筛选：按类别浏览组件
• 属性文档：详细的类型信息和要求

代码示例

• 基本用法：简单的实现示例
• 高级模式：复杂的用法场景
• 最佳实践：推荐的实现模式

Celo Composer 模板

Minipay 模板

• 用途：为在 Celo 上构建迷你支付 dApp 预先配置
• 使用场景：移动优先的支付应用、微交易、P2P 付款
• 功能：针对移动设备优化的 UI、支付流程组件、Celo 集成、PWA 支持

Valora 模板

• 用途：旨在轻松集成 Valora 钱包
• 使用场景：Valora 钱包集成、社交支付、DeFi 应用
• 功能：Valora 钱包连接、社交功能、DeFi 组件、多代币支持

集成工作流

1. 选择模板：根据使用场景选择 Minipay 或 Valora
2. 创建项目：使用 create_celo_composer_project 工具生成设置命令
3. 安装依赖项：使用生成的命令设置项目
4. 添加 Composer Kit：安装 Composer Kit 组件以增强 UI
5. 开发：使用分步指南进行部署和开发设置

架构

该服务提供对硬编码的 Composer Kit 组件数据和 Celo Composer 信息的访问：

src/composer_kit_mcp/
├── components/         # Component data and models
│   ├── data.py        # Hardcoded component and Celo Composer information
│   └── models.py      # Pydantic models for components and Celo Composer
├── server.py          # Main MCP server with Composer Kit and Celo Composer tools
└── __init__.py        # Package initialization

数据结构

• Composer Kit 组件：完整的组件库，包含 props、示例和用法信息
• Celo Composer 模板：包含使用场景和功能的模板配置
• Celo Composer 指南：常见任务的分步说明
• 集成文档：如何结合这两个工具快速开发 dApp

组件类别

核心组件

实现基本功能所需的 UI 组件

钱包集成

用于钱包连接和用户管理的组件

支付与交易

用于处理支付和区块链交易的组件

代币管理

用于代币选择和管理的组件

NFT 组件

用于 NFT 展示和交互的组件

开发

运行测试

pytest

代码格式化

black .
ruff check .

类型检查

mypy .

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

参与贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 如适用，添加测试
5. 提交 pull request

支持

如有问题或疑问：

• GitHub Issues：composer-kit-mcp/issues
• 文档：Composer Kit 文档