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.

Construir la imagen:
```
docker build -t mcp-mistcash .
```

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)

Clonar e instalar dependencias:
```
cd mcp-mistcash
npm install
```

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...

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

Transacciones Gastadas: obtener_assets_transaccion no detecta activos gastados
Costos RPC: Monitorea el uso del RPC para evitar costos inesperados
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:

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

📄 Licencia

MIT

Construido con ❤️ para las comunidades de Starknet y MCP

Servidor MCP para MIST.cash SDK

🌟 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.

Construir la imagen:
```
docker build -t mcp-mistcash .
```

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)

Clonar e instalar dependencias:
```
cd mcp-mistcash
npm install
```

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...

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

Transacciones Gastadas: obtener_assets_transaccion no detecta activos gastados
Costos RPC: Monitorea el uso del RPC para evitar costos inesperados
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:

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

📄 Licencia

MIT

Construido con ❤️ para las comunidades de Starknet y MCP

MIST.cash MCP Server

Servidor MCP para MIST.cash SDK

🌟 Características

📋 Requisitos Previos

🚀 Instalación y Configuración

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

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

🔌 Integración con Clientes de IA

Claude Desktop

Configuración con Docker (Recomendada)

Configuración Local (Alternativa)

Cursor IDE

🛠️ Herramientas Disponibles

1. generar_secreto_transaccion

2. obtener_assets_transaccion

3. verificar_existencia_transaccion

4. calcular_hash_transaccion

5. obtener_configuracion_chamber

📚 Recursos Disponibles

chamber://contract-info

chamber://tx/{txHash}

🔒 Consideraciones de Seguridad

✅ Prácticas Seguras

⚠️ Advertencias Importantes

🏗️ Estructura del Proyecto

🤝 Contribuciones

📄 Licencia

Servidor MCP para MIST.cash SDK

🌟 Características

📋 Requisitos Previos

🚀 Instalación y Configuración

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

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

🔌 Integración con Clientes de IA

Claude Desktop

Configuración con Docker (Recomendada)

Configuración Local (Alternativa)

Cursor IDE

🛠️ Herramientas Disponibles

1. generar_secreto_transaccion

2. obtener_assets_transaccion

3. verificar_existencia_transaccion

4. calcular_hash_transaccion

5. obtener_configuracion_chamber

📚 Recursos Disponibles

chamber://contract-info

chamber://tx/{txHash}

🔒 Consideraciones de Seguridad

✅ Prácticas Seguras

⚠️ Advertencias Importantes

🏗️ Estructura del Proyecto

🤝 Contribuciones

📄 Licencia

1. `generar_secreto_transaccion`

2. `obtener_assets_transaccion`

3. `verificar_existencia_transaccion`

4. `calcular_hash_transaccion`

5. `obtener_configuracion_chamber`

`chamber://contract-info`

`chamber://tx/{txHash}`

1. `generar_secreto_transaccion`

2. `obtener_assets_transaccion`

3. `verificar_existencia_transaccion`

4. `calcular_hash_transaccion`

5. `obtener_configuracion_chamber`

`chamber://contract-info`

`chamber://tx/{txHash}`