cultureic/celo-mcp-setup-guide

Celo MCP Server Setup Guide

Guía completa de instalación del Celo Composer Kit MCP Server en macOS

Esta guía documenta el proceso completo de instalación del servidor MCP de Celo Composer Kit, incluyendo todos los problemas encontrados y sus soluciones.

Requisitos Previos

• macOS 12+ (funciona con versiones anteriores pero sin soporte oficial de Homebrew)
• Python 3.11+ (verificamos con Python 3.13.7)
• Homebrew (para algunas instalaciones)
• Conocimientos básicos de terminal y línea de comandos

Problemas Identificados y Soluciones

1. Falta del comando realpath

Problema: El comando realpath no está disponible por defecto en macOS, pero es requerido por uvx.

Error típico:

realpath: command not found

Solución: Crear un script personalizado de realpath usando Python:

# Crear el script
cat > ~/.local/bin/realpath << 'EOF'
#!/usr/bin/env python3
import os
import sys

if len(sys.argv) < 2:
    print(f"Usage: {sys.argv[0]} <path>", file=sys.stderr)
    sys.exit(1)

# Handle the -- argument properly
args = sys.argv[1:]
if args and args[0] == '--':
    args = args[1:]

if not args:
    print(f"Usage: {sys.argv[0]} <path>", file=sys.stderr)
    sys.exit(1)

try:
    print(os.path.realpath(args[0]))
except Exception as e:
    print(f"realpath: {e}", file=sys.stderr)
    sys.exit(1)
EOF

# Dar permisos de ejecución
chmod +x ~/.local/bin/realpath

2. Problema con UV y paths relativos

Problema: uvx generaba scripts que buscaban Python en directorios relativos incorrectos.

Error típico:

/path/to/current/directory/python: No such file or directory

Solución: UV se instaló correctamente y funciona, solo necesitaba el realpath personalizado.

Guía de Instalación Paso a Paso

Paso 1: Verificar Python

python3 --version
# Debería mostrar Python 3.11 o superior

Paso 2: Instalar UV (Fast Python Package Manager)

curl -LsSf https://astral.sh/uv/install.sh | sh

Paso 3: Configurar PATH para UV

export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

Paso 4: Instalar pipx

brew install pipx

Paso 5: Crear script realpath personalizado

mkdir -p ~/.local/bin
cat > ~/.local/bin/realpath << 'EOF'
#!/usr/bin/env python3
import os
import sys

if len(sys.argv) < 2:
    print(f"Usage: {sys.argv[0]} <path>", file=sys.stderr)
    sys.exit(1)

# Handle the -- argument properly
args = sys.argv[1:]
if args and args[0] == '--':
    args = args[1:]

if not args:
    print(f"Usage: {sys.argv[0]} <path>", file=sys.stderr)
    sys.exit(1)

try:
    print(os.path.realpath(args[0]))
except Exception as e:
    print(f"realpath: {e}", file=sys.stderr)
    sys.exit(1)
EOF

chmod +x ~/.local/bin/realpath

Paso 6: Instalar Composer Kit MCP

pipx install composer-kit-mcp

Paso 7: Verificar la instalación

# Probar con pipx (método recomendado para uso continuo)
composer-kit-mcp &
ps aux | grep composer-kit-mcp | grep -v grep
kill %1  # Para detener el proceso

# Probar con uvx (para uso ocasional)
export PATH="$HOME/.local/bin:$PATH"
uvx --force-reinstall composer-kit-mcp
# Ctrl+C para interrumpir

Métodos de Ejecución

Usando pipx (Recomendado para uso continuo)

composer-kit-mcp

Usando uvx (Para ejecución ocasional)

export PATH="$HOME/.local/bin:$PATH"
uvx composer-kit-mcp

Configuración de Clientes MCP

Para Cursor IDE

1. Instalar el servidor MCP:

pipx install composer-kit-mcp

2. Configurar Cursor:
   • Abrir Cursor Settings (Cmd/Ctrl + ,)
   • Navegar a "Features" → "Model Context Protocol"
   • Agregar servidor MCP:

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

3. Reiniciar Cursor y verificar preguntando:
   • "What Composer Kit components are available?"
   • "Show me how to use the Wallet component"

Para Claude Desktop

1. Instalar el servidor MCP:

pipx install composer-kit-mcp

2. Localizar el archivo de configuración:

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

3. Editar el archivo de configuración:

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

4. Reiniciar Claude Desktop y buscar el ícono 🔌

Herramientas MCP Disponibles

Una vez configurado, tendrás acceso a estas herramientas:

Descubrimiento de Componentes

• list_components: Listar todos los componentes disponibles
• get_component: Información detallada de un componente específico
• search_components: Buscar componentes por funcionalidad

Integración con Celo Composer

• get_celo_composer_cli_info: Información del CLI de Celo Composer
• get_component_example: Ejemplos de uso de componentes
• get_installation_guide: Guías de instalación

Categorías de Componentes

• Core Components: Componentes UI esenciales
• Wallet Integration: Conexión de billeteras
• Payment & Transactions: Flujos de pago
• Token Management: Gestión de tokens
• NFT Components: Componentes NFT
• Identity Components: Características de identidad

Verificación de Estado

Para verificar que todo está funcionando correctamente:

# Verificar Python
python3 --version

# Verificar UV
which uv

# Verificar pipx
which pipx

# Verificar realpath personalizado
which realpath
realpath .

# Verificar composer-kit-mcp
composer-kit-mcp --version 2>/dev/null || echo "MCP server installed correctly"

Troubleshooting

Error: "realpath: command not found"

Solución: Asegúrate de que el script personalizado de realpath esté instalado y en tu PATH.

Error: "python: No such file or directory"

Solución: Verifica que UV esté usando el PATH correcto y que realpath funcione.

Error: "externally-managed-environment"

Solución: Usa pipx en lugar de pip para instalaciones globales.

Problemas con macOS 12 o anterior

Solución: Los warnings de Homebrew son normales. Las instalaciones funcionarán pero sin soporte oficial.

Comandos de Ejemplo

Una vez configurado en tu IDE, puedes probar:

"What Composer Kit components are available?"
"Show me how to create a payment component"
"Search for wallet-related components"
"Get installation guide for npm"
"Show me examples of the Balance component"

Recursos Adicionales

• Documentación oficial de Celo MCP
• Repositorio de Composer Kit MCP
• Documentación de UV
• Model Context Protocol

Contribuciones

Si encuentras problemas adicionales o tienes mejoras para esta guía, por favor abre un issue o envía un pull request.

Fecha de creación: Agosto 2025
Probado en: macOS 12 (Monterey) con Python 3.13.7