Servidor MCP para MIST.cash SDK

Un servidor del Protocolo de Contexto de Modelo (MCP) que expone la funcionalidad de pagos privados de MIST.cash en Starknet. Este servidor permite a los agentes de IA interactuar con el protocolo de pagos preservadores de privacidad de MIST.cash a través de una interfaz estandarizada.

🌟 Características

• 5 Herramientas MCP para operaciones de transacción
• 2 Recursos MCP para información de contratos y transacciones
• Privacidad Primero: Aprovecha el sistema de pruebas de conocimiento cero de MIST.cash
• Soporte Multi-Token: ETH, USDC, USDT, DAI en Starknet
• Listo para Producción: Lógica de reintento, tiempos de espera (timeouts) y manejo integral de errores

📋 Requisitos Previos

• Node.js 20 o superior (si se ejecuta localmente)
• Docker (recomendado para equipos)
• Acceso a un proveedor RPC de Starknet (o Appchain compatible)

🚀 Instalación y Configuración

Opción 1: Docker (Recomendado para el Equipo)

Esta es la forma más sencilla de asegurar que todos en el equipo tengan el mismo entorno.

1. Construir la imagen:

   docker build -t mcp-mistcash .
   

2. Ejecutar con Docker:

   Para usarlo con clientes MCP (como Claude Desktop), usarás el comando docker run. Nota la bandera -i que es requerida para la comunicación stdio.

   docker run -i --rm \
     -e STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz \
     -e STARKNET_NETWORK=mainnet \
     -e CHAMBER_CONTRACT_ADDRESS=0xTuDireccionDeContrato \
     mcp-mistcash
   

Opción 2: Desarrollo Local (Node.js)

1. Clonar e instalar dependencias:

   cd mcp-mistcash
   npm install
   

2. Configurar variables de entorno:

   Crea un archivo .env basado en el ejemplo:

   cp .env.example .env
   

   Edita .env con tu configuración (ejemplo para Madara Appchain):

   STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz
   STARKNET_NETWORK=mainnet
   MCP_LOG_LEVEL=info
   # Opcional: Dirección del contrato Chamber (Requerido para Madara si no usas Mainnet)
   # CHAMBER_CONTRACT_ADDRESS=0x...
   

3. Construir el proyecto:

   npm run build
   

🔌 Integración con Clientes de IA

Para que tu equipo pueda usar estas herramientas en su día a día, deben configurar su cliente de IA preferido.

Claude Desktop

Añade lo siguiente a tu archivo de configuración claude_desktop_config.json:

Ruta del archivo de configuración:

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

Configuración con Docker (Recomendada)

{
  "mcpServers": {
    "mist-cash": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz",
        "-e", "STARKNET_NETWORK=mainnet",
        "mcp-mistcash"
      ]
    }
  }
}

Configuración Local (Alternativa)

{
  "mcpServers": {
    "mist-cash": {
      "command": "node",
      "args": ["/ruta/absoluta/a/mcp-mistcash/dist/index.js"],
      "env": {
        "STARKNET_RPC_URL": "https://ztarknet-madara.d.karnot.xyz",
        "STARKNET_NETWORK": "mainnet"
      }
    }
  }
}

Cursor IDE

Añade esto a tus configuraciones de MCP en Cursor:

{
  "mist-cash": {
    "command": "docker",
    "args": [
        "run",
        "-i",
        "--rm",
        "-e", "STARKNET_RPC_URL=https://ztarknet-madara.d.karnot.xyz",
        "-e", "STARKNET_NETWORK=mainnet",
        "mcp-mistcash"
    ]
  }
}

🛠️ Herramientas Disponibles

1. generar_secreto_transaccion

Genera un secreto criptográfico para una transacción privada.

Parámetros:

• claiming_key (string, requerido): Clave de reclamación para la transacción
• recipient_address (string, requerido): Dirección Starknet (0x...)

2. obtener_assets_transaccion

Obtiene los activos de una transacción.

⚠️ ADVERTENCIA: Esta función muestra activos incluso si ya han sido gastados. Usa verificar_existencia_transaccion para una verificación precisa.

Parámetros:

• transaction_key (string, requerido): Clave de la transacción a consultar
• recipient_address (string, requerido): Dirección Starknet del receptor
• provider_rpc_url (string, opcional): URL RPC personalizada

3. verificar_existencia_transaccion

Verifica si existe una transacción con activos específicos. Ideal para transacciones completamente privadas.

Parámetros:

• claiming_key (string, requerido): Clave de reclamación
• recipient (string, requerido): Dirección del receptor
• token_address (string, requerido): Dirección del contrato del token
• amount (string, requerido): Cantidad en unidades base (wei)

4. calcular_hash_transaccion

Calcula el hash único de una transacción.

Parámetros:

• transaction_key (string, requerido): Clave de la transacción
• recipient_address (string, requerido): Dirección del receptor
• token_address (string, requerido): Dirección del token
• amount (string, requerido): Cantidad en unidades base

5. obtener_configuracion_chamber

Obtiene la configuración del contrato Chamber y los tokens soportados.

Parámetros:

• network (enum, opcional): "mainnet" o "sepolia" (por defecto: "mainnet")

📚 Recursos Disponibles

chamber://contract-info

Información estática sobre el contrato Chamber de MIST.cash, incluyendo ABI, direcciones y características.

chamber://tx/{txHash}

Detalles para una transacción específica por hash.

🔒 Consideraciones de Seguridad

✅ Prácticas Seguras

• Sin Claves Privadas: Solo se manejan claves de reclamación (públicas)
• Validación de Direcciones: Todas las direcciones Starknet son validadas
• Logging Seguro: Los secretos de las transacciones nunca se registran en los logs
• Validación de Entrada: Esquemas Zod validan todas las entradas

⚠️ Advertencias Importantes

1. Transacciones Gastadas: obtener_assets_transaccion no detecta activos gastados
2. Costos RPC: Monitorea el uso del RPC para evitar costos inesperados
3. Retrasos de Red: Timeout de 30 segundos en todas las llamadas al contrato

🏗️ Estructura del Proyecto

mcp-mistcash/
├── src/
│   ├── index.ts                 # Servidor MCP principal
│   ├── types.ts                 # Definiciones de tipos TypeScript
│   ├── tools/                   # Implementación de herramientas
│   ├── resources/               # Recursos MCP
│   └── utils/                   # Utilidades (provider, validación)
├── Dockerfile                   # Configuración para construir la imagen Docker
├── package.json
├── tsconfig.json
├── .env.example
└── README.md

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor asegúrate de:

1. Que todas las herramientas tengan manejo de errores adecuado
2. Los esquemas Zod validen las entradas
3. El código siga las mejores prácticas de TypeScript
4. La documentación esté actualizada

📄 Licencia

MIT

---

Construido con ❤️ para las comunidades de Starknet y MCP