MIST.cash MCP Server

# 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](https://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:** ```bash 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. ```bash 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:** ```bash cd mcp-mistcash npm install ``` 2. **Configurar variables de entorno:** Crea un archivo `.env` basado en el ejemplo: ```bash cp .env.example .env ``` Edita `.env` con tu configuración (ejemplo para Madara Appchain): ```env 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:** ```bash 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) ```json { "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) ```json { "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: ```json { "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**