# 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**