Stellar MCP

Interactúa con la blockchain de Stellar, gestiona cuentas y ejecuta contratos inteligentes en Stellar Classic y Soroban.

GitHub

Prueba este MCPPatrocinado

Documentación

🌟 Stellar MCP

Un servidor de Model Context Protocol que proporciona capacidades de interacción con la blockchain de Stellar. Este servidor permite a los LLMs interactuar tanto con Stellar Classic como con contratos inteligentes Soroban, gestionar cuentas y realizar diversas operaciones de blockchain.

🧩 Componentes

🛠️ Herramientas

💫 Operaciones de Stellar Classic

stellar_create_account
- Crear una nueva cuenta de Stellar
stellar_balance
- Obtener el saldo de una cuenta de Stellar
- Entrada: account (string): La clave pública de la cuenta para consultar el saldo
stellar_payment
- Enviar un pago a otra cuenta
- Entradas:
  - destination (string, requerido): La clave pública de la cuenta de destino
  - amount (string, requerido): La cantidad a enviar
  - secretKey (string, requerido): La clave secreta de la cuenta de origen
  - asset (object, opcional): Detalles del activo personalizado
    - code (string): El código del activo
    - issuer (string): La clave pública del emisor del activo
stellar_transactions
- Obtener el historial de transacciones de una cuenta
- Entrada: account (string): La clave pública de la cuenta para obtener las transacciones
stellar_create_asset
- Crear un nuevo activo en la red de Stellar
- Entradas:
  - code (string, requerido): El código del activo
  - issuerSecretKey (string, requerido): La clave secreta de la cuenta emisora
  - distributorSecretKey (string, requerido): La clave secreta de la cuenta distribuidora
  - totalSupply (string, requerido): El suministro total del activo
stellar_change_trust
- Cambiar la línea de confianza (trustline) de un activo
- Entradas:
  - asset (object, requerido):
    - code (string, requerido): El código del activo
    - issuer (string, requerido): La clave pública del emisor del activo
  - limit (string, requerido): El límite de confianza
  - secretKey (string, requerido): La clave secreta de la cuenta que cambia la confianza
stellar_create_claimable_balance
- Crear un saldo reclamable que puede ser reclamado por cuentas específicas bajo ciertas condiciones
- Entradas:
  - asset (object, opcional): Detalles del activo personalizado. Si no se proporciona, usa XLM nativo
    - code (string): El código del activo (p. ej., "USD", "EUR")
    - issuer (string): La clave pública del emisor del activo
  - amount (string, requerido): Cantidad a bloquear en el saldo reclamable
  - claimants (array, requerido): Lista de cuentas que pueden reclamar este saldo
    - destination (string): Clave pública de la cuenta que puede reclamar
    - predicate (object): Condiciones para reclamar
      - type (string): Uno de: "UNCONDITIONAL", "BEFORE_RELATIVE_TIME", "BEFORE_ABSOLUTE_TIME", "NOT", "AND", "OR"
      - value (number o array): Para predicados de tiempo: segundos/timestamp, para predicados compuestos: array de predicados
  - secretKey (string, requerido): Clave secreta de la cuenta que crea el saldo
stellar_claim_claimable_balance
- Reclamar un saldo reclamable usando su ID
- Entradas:
  - balanceId (string, requerido): ID del saldo reclamable a reclamar (devuelto por createClaimableBalance)
  - secretKey (string, requerido): Clave secreta de la cuenta que reclama (debe ser uno de los reclamantes)
stellar_fund_account
- Financiar una cuenta de prueba usando Friendbot (solo testnet)
- Entrada: publicKey (string): La clave pública de la cuenta a financiar

📝 Operaciones de Contratos Inteligentes Soroban

soroban_build_and_optimize
- Compilar y optimizar contratos inteligentes Soroban
- Entradas:
  - contractPath (string, opcional): La ruta al directorio del contrato. Por defecto, el directorio de trabajo actual
- Salidas:
  - Registros de compilación y estado de compilación
  - Lista de archivos WASM optimizados
  - Resultados de optimización para cada contrato
- Características:
  - Compila automáticamente contratos usando stellar contract build
  - Encuentra todos los archivos WASM en el directorio de destino
  - Optimiza cada archivo WASM usando stellar contract optimize
  - Proporciona registros detallados de todo el proceso
soroban_deploy
- Desplegar contratos inteligentes Soroban en la red de Stellar
- Entradas:
  - wasmPath (string, requerido): Ruta al archivo WASM compilado
  - secretKey (string, requerido): Clave secreta de la cuenta que despliega
  - constructorArgs (array, opcional): Argumentos para el constructor del contrato si corresponde
    - Cada argumento debe ser un objeto con:
      - name (string): Nombre del parámetro del constructor
      - type (string): Tipo del argumento (p. ej., "Address", "String", etc.)
      - value (string): Valor del argumento
- Salidas:
  - ID del contrato (comienza con "C" seguido de 55 caracteres)
  - Mensajes de estado del despliegue
  - Detalles de la transacción
- Características:
  - Detecta automáticamente si el contrato tiene constructor
  - Valida los argumentos del constructor antes del despliegue
  - Lanza error si faltan argumentos del constructor para contratos que los requieren
  - Proporciona registros de despliegue detallados y actualizaciones de estado
  - Soporta tanto contratos simples como contratos con lógica de inicialización
- Ejemplo de uso:
```
// Deploying a contract without constructor
await soroban.deploy({
  wasmPath: 'path/to/hello_world.wasm',
  secretKey: 'S...',
});

// Deploying a contract with constructor
await soroban.deploy({
  wasmPath: 'path/to/contract_with_constructor.wasm',
  secretKey: 'S...',
  constructorArgs: [
    {
      name: 'admin',
      type: 'Address',
      value: 'G...',
    },
  ],
});
```

soroban_retrieve_contract_methods

Recuperar la interfaz completa de un contrato inteligente Soroban desplegado
Entradas:
- contractAddress (string, requerido): Dirección del contrato desplegado (comienza con "C")
- secretKey (string, requerido): Clave secreta de la cuenta que realiza la consulta
Salidas:
- Un objeto ContractInterface estructurado que contiene:
  - name: El nombre del contrato
  - methods: Array de métodos del contrato, cada uno con:
    - name: Nombre del método
    - parameters: Array de parámetros con:
      - name: Nombre del parámetro
      - type: Tipo del parámetro, que puede ser:
        
        Tipos primitivos (u32, i32, u64, i64, u128, i128, bool)
        
        Tipos Soroban (Address, String, Bytes, BytesN, Duration, Timepoint)
        
        Structs personalizados (Data, ComplexData, etc.)
        
        Colecciones (Vec, Map<K, V>)
        
        Tipos opcionales (Option)
        
        Tuplas ((T1, T2, ...))
        
        Tipos Result (Result<T, E>)
    - returnType: Tipo de retorno del método, que puede ser:
      - Void (())
      - Tipo único (T)
      - Tupla ((T1, T2, ...))
      - Result (Result<T, E>)
  - structs: Array de structs del contrato, cada uno con:
    - name: Nombre del struct
    - fields: Array de campos con nombre, tipo y visibilidad
  - enums: Array de enums del contrato, cada uno con:
    - name: Nombre del enum
    - variants: Array de variantes con:
      - name: Nombre de la variante
      - value: Valor numérico opcional (para enums estilo C)
      - dataType: Tipo de dato opcional para variantes con datos asociados
    - isError: Booleano que indica si es un enum de error
Características:
- Soporta todos los tipos de datos Soroban (primitivos, structs, structs anidados, enums)
- Proporciona la interfaz completa del contrato incluyendo métodos, structs y enums
- Maneja tipos de datos complejos y estructuras anidadas
- Devuelve una representación JSON estructurada de la interfaz del contrato
- Filtra automáticamente el parámetro env de las firmas de métodos (proporcionado por la blockchain de Soroban)
- Soporta varios tipos de enums:
  - Enums simples (sin datos asociados)
  - Enums estilo C (con valores numéricos)
  - Enums con un solo tipo de dato
  - Enums con tipos de datos de tupla
  - Enums de error (marcados con #[contracterror])

Ejemplo de uso:

const result = await soroban.retrieveContractMethods({
  contractAddress:
    'CACLOQNDBVG2Q7VRQGOKC4THZ34FHW2PUYQQOAVBSLJEV6VHEF3ZCIPO',
});

// Example response:
[
  {
    type: 'text',
    text: '🚀 Retrieving contract methods for address: CACLOQNDBVG2Q7VRQGOKC4THZ34FHW2PUYQQOAVBSLJEV6VHEF3ZCIPO',
  },
  {
    type: 'text',
    text: 'Interface retrieved successfully',
  },
  {
    type: 'text',
    text: 'Contract Interface',
  },
  {
    type: 'text',
    text: JSON.stringify(
      {
        name: 'Contract',
        methods: [
          {
            name: 'set_admin',
            parameters: [{ name: 'admin', type: 'Address' }],
            returnType: '()',
          },
          {
            name: 'get_admin',
            parameters: [],
            returnType: 'Address',
          },
          {
            name: 'method_with_args',
            parameters: [
              { name: 'arg1', type: 'u32' },
              { name: 'arg2', type: 'u32' },
            ],
            returnType: '(u32, u32)',
          },
          {
            name: 'handle_integers',
            parameters: [
              { name: 'i32_val', type: 'i32' },
              { name: 'i64_val', type: 'i64' },
              { name: 'i128_val', type: 'i128' },
              { name: 'i256_val', type: 'I256' },
              { name: 'u32_val', type: 'u32' },
              { name: 'u64_val', type: 'u64' },
              { name: 'u128_val', type: 'u128' },
              { name: 'u256_val', type: 'U256' },
            ],
            returnType: '(i32, u32)',
          },
          {
            name: 'handle_strings',
            parameters: [
              { name: 'str_val', type: 'String' },
              { name: 'bytes_val', type: 'Bytes' },
              { name: 'bytes_n_val', type: 'BytesN<32>' },
            ],
            returnType: 'String',
          },
          {
            name: 'handle_collections',
            parameters: [
              { name: 'map', type: 'Map<String, u32>' },
              { name: 'vec', type: 'Vec<u32>' },
            ],
            returnType: '(Map<String, u32>, Vec<u32>)',
          },
          {
            name: 'handle_custom_types',
            parameters: [
              { name: 'data', type: 'Data' },
              { name: 'complex_data', type: 'ComplexData' },
            ],
            returnType: '(Data, ComplexData)',
          },
          {
            name: 'handle_optionals',
            parameters: [
              { name: 'maybe_u32', type: 'Option<u32>' },
              { name: 'maybe_address', type: 'Option<Address>' },
            ],
            returnType: 'OptionalData',
          },
          {
            name: 'get_admin_from_storage',
            parameters: [],
            returnType: 'Result<Address, ContractError>',
          },
        ],
        structs: [
          {
            name: 'Data',
            fields: [
              { name: 'admin', type: 'Address', visibility: 'pub' },
              { name: 'counter', type: 'u32', visibility: 'pub' },
              { name: 'message', type: 'String', visibility: 'pub' },
            ],
          },
          {
            name: 'ComplexData',
            fields: [
              { name: 'admin', type: 'Address', visibility: 'pub' },
              { name: 'data', type: 'Data', visibility: 'pub' },
              { name: 'bytes', type: 'Bytes', visibility: 'pub' },
              { name: 'bytes_n', type: 'BytesN<32>', visibility: 'pub' },
              { name: 'duration', type: 'Duration', visibility: 'pub' },
              { name: 'map', type: 'Map<String, u32>', visibility: 'pub' },
              { name: 'symbol', type: 'Symbol', visibility: 'pub' },
              { name: 'timepoint', type: 'Timepoint', visibility: 'pub' },
              { name: 'vec', type: 'Vec<u32>', visibility: 'pub' },
            ],
          },
          {
            name: 'OptionalData',
            fields: [
              { name: 'maybe_u32', type: 'Option<u32>', visibility: 'pub' },
              {
                name: 'maybe_address',
                type: 'Option<Address>',
                visibility: 'pub',
              },
            ],
          },
        ],
        enums: [
          {
            name: 'DataKey',
            variants: [
              { name: 'Admin' },
              { name: 'Counter' },
              { name: 'Data' },
              { name: 'Account', dataType: 'Address' },
              { name: 'Contract', dataType: '(Address, u64)' },
            ],
            isError: false,
          },
          {
            name: 'ContractError',
            variants: [
              { name: 'AdminNotFound', value: 1 },
              { name: 'InvalidValue', value: 2 },
              { name: 'OptionNotFound', value: 3 },
            ],
            isError: true,
          },
        ],
      },
      null,
      2,
    ),
  },
];

Tipos de Parámetros de Métodos

El analizador soporta varios tipos de parámetros y retorno. Ten en cuenta que el parámetro env se filtra automáticamente de la interfaz, ya que es proporcionado por el entorno de la blockchain de Soroban.

Tipos Primitivos

fn handle_primitives(value: u32, flag: bool) -> u64;

Analizado como:

{
  "name": "handle_primitives",
  "parameters": [
    { "name": "value", "type": "u32" },
    { "name": "flag", "type": "bool" }
  ],
  "returnType": "u64"
}

Tipos de Struct Personalizados

fn handle_struct(data: Data) -> Data;

Analizado como:

{
  "name": "handle_struct",
  "parameters": [{ "name": "data", "type": "Data" }],
  "returnType": "Data"
}

Colecciones

fn handle_collections(map: Map<String, u32>, vec: Vec<u32>) -> (Map<String, u32>, Vec<u32>);

Analizado como:

{
  "name": "handle_collections",
  "parameters": [
    { "name": "map", "type": "Map<String, u32>" },
    { "name": "vec", "type": "Vec<u32>" }
  ],
  "returnType": "(Map<String, u32>, Vec<u32>)"
}

Tipos Opcionales

fn handle_optionals(maybe_u32: Option<u32>, maybe_address: Option<Address>) -> OptionalData;

Analizado como:

{
  "name": "handle_optionals",
  "parameters": [
    { "name": "maybe_u32", "type": "Option<u32>" },
    { "name": "maybe_address", "type": "Option<Address>" }
  ],
  "returnType": "OptionalData"
}

Tipos Result

fn handle_result() -> Result<Address, ContractError>;

Analizado como:

{
  "name": "handle_result",
  "parameters": [],
  "returnType": "Result<Address, ContractError>"
}

Tipos Complejos

fn handle_complex(data: ComplexData) -> (Data, ComplexData);

Analizado como:

{
  "name": "handle_complex",
  "parameters": [{ "name": "data", "type": "ComplexData" }],
  "returnType": "(Data, ComplexData)"
}

Nota sobre el Parámetro Env

Todos los métodos de contratos en Soroban reciben un parámetro env que proporciona acceso al entorno de la blockchain. Este parámetro es proporcionado automáticamente por la blockchain de Soroban y se filtra de la interfaz. Por ejemplo, un método definido como:

fn set_admin(env: Env, admin: Address) -> ();

Aparecerá en la interfaz como:

{
  "name": "set_admin",
  "parameters": [{ "name": "admin", "type": "Address" }],
  "returnType": "()"
}

⭐ Características Principales

👤 Gestión de cuentas (creación, financiación, verificación de saldo)
🪙 Operaciones de activos (creación, líneas de confianza)
💸 Procesamiento de pagos
📝 Recuperación del historial de transacciones
📱 Despliegue e interacción con contratos inteligentes
🌐 Soporte tanto para Stellar Classic como para Soroban

⚙️ Configuración

🔑 Variables de Entorno

Crea un archivo .env con la siguiente configuración:

STELLAR_SERVER_URL=

🔧 Configuración para usar el Servidor Stellar MCP

Aquí está la configuración para usar el servidor Stellar MCP en Cursor, Windsurf y Claude Desktop:

💻 Local

{
  "mcpServers": {
    "stellar-mcp": {
      "command": "node",
      "args": ["your/path/stellar-mcp/dist/index.js"]
    }
  }
}

📦 NPX

{
  "mcpServers": {
    "stellar-mcp": {
      "command": "npx",
      "args": ["-y", "stellar-mcp"]
    }
  }
}

🐳 Docker

{
  "mcpServers": {
    "stellar": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "STELLAR_SERVER_URL=<STELLAR_URL_VALUE>",
        "stellar-mcp"
      ]
    }
  }
}

📥 Instalación

npm install

🔨 Compilación

npm run build

🚀 Ejecución

Desarrollo:

npm run start:dev

Producción:

npm run start:prod

📚 Ejemplo Básico de Uso

[Video pendiente]

🔍 Depuración con MCP Inspector

Para depurar el servidor Stellar MCP y monitorear todas las interacciones entre el LLM y la red de Stellar, puedes usar el MCP Inspector. Esta herramienta proporciona una vista en tiempo real de todas las solicitudes y respuestas.

Ejecución con MCP Inspector

Usa el siguiente comando para iniciar el servidor con el inspector:

npm run start:prod

npx @modelcontextprotocol/inspector node <your/path>/stellar-mcp npm run start:prod

Esto iniciará el MCP Inspector en el puerto 9229. Luego puedes abrir tu navegador y navegar a:

http://localhost:5173

El inspector te mostrará:

Todas las solicitudes entrantes del LLM
Respuestas salientes y errores
Interacciones en tiempo real con la red de Stellar
Información detallada de transacciones

Esto es particularmente útil cuando:

Se depuran interacciones con Stellar
Se monitorean flujos de transacciones
Se solucionan operaciones fallidas
Se entiende la secuencia de llamadas API

📄 Licencia

Este servidor MCP está licenciado bajo la Licencia MIT. Esto significa que eres libre de usar, modificar y distribuir el software, sujeto a los términos y condiciones de la Licencia MIT. Para más detalles, consulta el archivo LICENSE en el repositorio del proyecto.