Servidor MCP de Bitcoin SV

⚠️ AVISO: Trabajo experimental en progreso
Este proyecto se encuentra en una fase experimental inicial. Las características pueden cambiar y la API aún no es estable. ¡Agradecemos sus contribuciones, comentarios e informes de errores! No dude en abrir incidencias o enviar solicitudes de incorporación de cambios.

Una colección de herramientas de Bitcoin SV (BSV) para el marco del Protocolo de Contexto de Modelo (MCP). Esta biblioteca proporciona funciones de billetera, ordinales y utilidades para la interacción con la blockchain de BSV.

Conexión a clientes MCP

Este servidor implementa el Protocolo de Contexto de Modelo (MCP), lo que permite a los asistentes de IA utilizar las funcionalidades de Bitcoin SV. Puede conectar este servidor a varios clientes compatibles con MCP.

Cursor

Para utilizar el servidor BSV MCP con Cursor :

Instala Cursor si aún no lo has hecho
Clone este repositorio y ejecute bun install en el directorio del proyecto
Abra Cursor y navegue a Configuración → Extensiones → Protocolo de contexto de modelo
Haga clic en "Agregar un nuevo servidor MCP global"
Introduzca la siguiente configuración en formato JSON:

  {
    "mcpServers": {
      "Bitcoin SV": {
        "command": "bunx",
        "args": [
          "bsv-mcp@latest"
        ],
        "env": {
          "PRIVATE_KEY_WIF": "<your_private_key_wif>"
        }
      }
    }
  }

Reemplace <your_private_key_wif> con su clave privada WIF real (¡manténgala segura!)
Haga clic en "Guardar"

Las herramientas BSV ahora estarán disponibles para el asistente de inteligencia artificial de Cursor bajo el espacio de nombres "Bitcoin SV".

Claude para escritorio

Para conectar este servidor a Claude for Desktop:

Asegúrese de tener Claude for Desktop instalado y actualizado a la última versión
Clone este repositorio y ejecute bun install en el directorio del proyecto
Abra el archivo de configuración de Claude for Desktop:
# macOS/Linux code ~/Library/Application\ Support/Claude/claude_desktop_config.json # Windows code %APPDATA%\Claude\claude_desktop_config.json
Agregue el servidor BSV MCP a su configuración (cree el archivo si no existe):
{ "mcpServers": { "Bitcoin SV": { "command": "bunx", "args": [ "bsv-mcp@latest" ], "env": { "PRIVATE_KEY_WIF": "<your_private_key_wif>" } } } }
Reemplace <your_private_key_wif> con su clave privada WIF real
Guarde el archivo y reinicie Claude for Desktop
Las herramientas BSV aparecerán cuando haga clic en el ícono de herramientas (martillo) en Claude para escritorio

Herramientas disponibles

El kit de herramientas está organizado en varias categorías:

Herramientas de billetera

Las herramientas de billetera proporcionan la funcionalidad principal de la billetera BSV:

Nombre de la herramienta	Descripción	Ejemplo de salida
`wallet_getPublicKey`	Recupera una clave pública para un protocolo y un ID de clave específicos	`{"publicKey":"032d0c73eb9270e9e009fd1f9dd77e19cf764fbad5f799560c4e8fd414e40d6fc2"}`
`wallet_createSignature`	Crea una firma criptográfica para los datos proporcionados	`{"signature":[144,124,85,193,226,45,140,249,9,177,11,167,33,215,209,38,...]}`
`wallet_verifySignature`	Verifica una firma criptográfica con los datos proporcionados	`{"isValid":true}`
`wallet_encryption`	Herramienta combinada para cifrar y descifrar datos mediante las claves criptográficas de la billetera. Ejemplos: 1. Cifrar texto: `"Encrypt this message: Hello World"` 2. Descifrar datos: `"Decrypt this data that was previously encrypted for me"`	Cifrar: `{"ciphertext":[89,32,155,38,125,22,49,226,26,...]}` Descifrar: `{"plaintext":"hello world"}`
`wallet_getAddress`	Devuelve una dirección BSV para la billetera actual o una ruta derivada	`{"address":"1ExampleBsvAddressXXXXXXXXXXXXXXXXX","status":"ok"}`
`wallet_sendToAddress`	Envía BSV a una dirección específica (admite montos en BSV o USD)	`{"status":"success","txid":"a1b2c3d4e5f6...","satoshis":1000000}`
`wallet_purchaseListing`	Compra NFT o tokens BSV-20/BSV-21 de los listados del mercado	`{"status":"success","txid":"a1b2c3d4e5f6...","type":"nft","origin":"abcdef123456..."}`
`wallet_createOrdinals`	Crea e inscribe ordinales en la cadena de bloques BSV	`{"txid":"a1b2c3d4e5f6...","inscriptionAddress":"1ExampleAddress...","contentType":"image/png"}`

Herramientas BSV

Herramientas para interactuar con la cadena de bloques y la red BSV:

Nombre de la herramienta	Descripción	Ejemplo de salida
`bsv_getPrice`	Obtiene el precio actual de BSV desde una API de intercambio	`Current BSV price: $38.75 USD`
`bsv_decodeTransaction`	Decodifica una transacción BSV y devuelve información detallada	`{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,"inputs":[...],"outputs":[...]}`
`bsv_explore`	Herramienta integral de exploración de blockchain que accede a los puntos finales de la API de WhatsOnChain	`{"chain_info":{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"0000000000..."}}`

Herramientas de ordinales

Herramientas para trabajar con ordinales (NFT) en BSV:

Nombre de la herramienta	Descripción	Ejemplo de salida
`ordinals_getInscription`	Recupera información detallada sobre una inscripción específica	`{"id":"a1b2c3d4e5f6...","origin":"a1b2c3d4e5f6...","contentType":"image/png","content":"iVBORw0KGgoAAA..."}`
`ordinals_searchInscriptions`	Búsquedas de inscripciones basadas en diversos criterios	`{"results":[{"id":"a1b2c3...","contentType":"image/png","owner":"1Example..."},...]}`
`ordinals_marketListings`	Recupera listados de mercado para tokens NFT, BSV-20 y BSV-21 con una interfaz unificada	`{"results":[{"txid":"a1b2c3...","price":9990000,"tick":"PEPE","listing":true},...]}`
`ordinals_marketSales`	Obtiene información sobre las ventas en el mercado de tokens BSV-20 y BSV-21	`{"results":[{"txid":"a1b2c3...","price":34710050,"tick":"$BTC","sale":true},...]}`
`ordinals_getTokenByIdOrTicker`	Recupera detalles sobre un token BSV20 específico por ID	`{"tick":"PEPE","max":"21000000","lim":"1000","dec":"2"}`

Herramientas de utilidad

Funciones de utilidad de propósito general:

Nombre de la herramienta	Descripción	Ejemplo de salida
`utils_convertData`	Convierte datos entre diferentes formatos de codificación (utf8, hex, base64, binario). Parámetros: - `data` (obligatorio): La cadena a convertir- `from` (obligatorio): Formato de codificación de origen (utf8, hexadecimal, base64 o binario)- `to` (obligatorio): Formato de codificación de destino (utf8, hexadecimal, base64 o binario) Ejemplos: - UTF-8 a hexadecimal: `{"data": "hello world", "from": "utf8", "to": "hex"}` → `68656c6c6f20776f726c64` - UTF-8 a base64: `{"data": "Hello World", "from": "utf8", "to": "base64"}` → `SGVsbG8gV29ybGQ=` - base64 a UTF-8: `{"data": "SGVsbG8gV29ybGQ=", "from": "base64", "to": "utf8"}` → `Hello World` - Hex a base64: `{"data": "68656c6c6f20776f726c64", "from": "hex", "to": "base64"}` → `aGVsbG8gd29ybGQ=` Notas: - Todos los parámetros son obligatorios. - La herramienta devuelve los datos convertidos como una cadena. - Para la conversión binaria, los datos se representan como una matriz de valores de bytes.	`"SGVsbG8gV29ybGQ="` (UTF-8 "Hola Mundo" convertido a base64)

Herramientas MNEE

Herramientas para trabajar con tokens MNEE:

Nombre de la herramienta	Descripción	Ejemplo de salida
`mnee_getBalance`	Recupera el saldo actual del token MNEE para la billetera	`{"balance": {"amount": 2900, "decimalAmount": 0.029}}`
`mnee_sendMnee`	Envía tokens MNEE a una dirección específica. Admite cantidades de MNEE y USD.	`{"success": true, "txid": "d1ce853934964e6c1fe9f44c918a824f175c6ab466b966f49ebc0682a8318895", "rawtx": "0100000002a0be40d8942015f1...", "mneeAmount": 0.01, "usdAmount": "$0.01", "recipient": "15mNxEkyKJXPD8amic6oLUjS45zBKQQoLu"}`
`mnee_parseTx`	Analice una transacción MNEE para obtener información detallada sobre sus operaciones y montos. Todos los montos se expresan en unidades atómicas con una precisión de 5 decimales (p. ej., 1000 unidades atómicas = 0,01 MNEE).	`{"txid": "d1ce853934964e6c1fe9f44c918a824f175c6ab466b966f49ebc0682a8318895", "environment": "production", "type": "transfer", "inputs": [{"address": "18izL7Wtm2fx3ALoRY3MkY2VFSMjArP62D", "amount": 2900}], "outputs": [{"address": "15mNxEkyKJXPD8amic6oLUjS45zBKQQoLu", "amount": 1000}, {"address": "19Vq2TV8aVhFNLQkhDMdnEQ7zT96x6F3PK", "amount": 100}, {"address": "18izL7Wtm2fx3ALoRY3MkY2VFSMjArP62D", "amount": 1800}]}`

Uso de las herramientas con MCP

Una vez conectado, podrá interactuar con Bitcoin SV en lenguaje natural a través de su asistente de IA. Aquí tiene algunos ejemplos:

Operaciones de billetera

Obtener mi dirección de Bitcoin SV
"Enviar 0,01 BSV a 1ExampleBsvAddressXXXXXXXXXXXXXXXXXX"
"Envía BSV por valor de $5 USD a 1ExampleBsvAddressXXXXXXXXXXXXXXXXXX"
"Enviar 0,01 MNEE a 1ExampleBsvAddressXXXXXXXXXXXXXXXXXX"
Consultar mi saldo de MNEE
Analizar esta transacción MNEE: txid
"Cifrar este mensaje con las claves de mi billetera"
"Descifrar estos datos que previamente fueron cifrados para mí"
Compra este NFT: txid_vout
Compre este token BSV-20: txid_vout

Ordinales (NFT)

Muéstrame información sobre el NFT con el punto de salida 6a89047af2cfac96da17d51ae8eb62c5f1d982be2bc4ba0d0cd2084b7ffed325_0
Búsqueda de NFT de Pixel Zoide
"Muéstrame las listas actuales de NFT de BSV en el mercado"
Muéstrame listados de tokens BSV-20 para el ticker PEPE.
Consulta las ventas recientes de tokens BSV-20.

Operaciones de blockchain

"¿Cuál es el precio actual del BSV?"
"Decodificar esta transacción BSV: (código hexadecimal o ID de la transacción)"
Obtén la información más reciente sobre la cadena Bitcoin SV.
"Muéstrame los detalles del bloque para la altura 800000"
Explorar el historial de transacciones de la dirección 1ExampleBsvAddressXXXX
"Verificar las salidas no gastadas (UTXO) de mi dirección de billetera"
Obtener detalles de la transacción con hash a1b2c3d4e5f6

Conversión de datos

Convertir "Hola Mundo" de UTF-8 a formato hexadecimal

Cómo funciona MCP

Cuando interactúas con un asistente de IA habilitado para MCP:

La IA analiza tu solicitud y decide qué herramientas utilizar
Con su aprobación, llama a la herramienta BSV MCP adecuada
El servidor ejecuta la operación solicitada en la cadena de bloques de Bitcoin SV
Los resultados se devuelven al asistente de IA.
El asistente presenta la información de forma natural y conversacional.

Solución de problemas

Si tiene problemas para conectarse al servidor:

Asegúrese de que las dependencias del paquete estén instaladas correctamente: bun install
Verifique que su clave privada WIF esté configurada correctamente en el entorno
Compruebe que su cliente sea compatible con MCP y esté configurado correctamente
Busque mensajes de error en la salida de la consola del cliente

Para Claude for Desktop, consulte los registros en:

tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Para Cursor, verifique los registros de MCP de Cursor en Configuración → Extensiones → Protocolo de contexto de modelo.

Actualizaciones recientes

Blockchain Explorer : Se agregó la herramienta bsv_explore para el acceso a la API de WhatsOnChain con compatibilidad con mainnet/testnet
Herramientas unificadas : wallet_encrypt y wallet_decrypt se fusionaron en una única herramienta wallet_encryption
Mercado mejorado : compatibilidad con NFT y tokens BSV-20/21 en listados, ventas y compras
Rendimiento : Se agregó almacenamiento en caché de precios y se optimizó la estructura del punto final de la API.
Validación mejorada : mejor manejo de errores para claves privadas y parámetros

Explorador de cadenas de bloques de Bitcoin SV

La herramienta bsv_explore proporciona acceso completo a la blockchain de Bitcoin SV a través de la API WhatsOnChain. Esta potente herramienta de exploración permite consultar diversos aspectos de la blockchain, incluyendo datos de la cadena, bloques, transacciones e información de direcciones.

Puntos finales disponibles

La herramienta admite las siguientes categorías de puntos finales y puntos finales específicos:

Datos de la cadena

Punto final	Descripción	Parámetros requeridos	Ejemplo de respuesta
`chain_info`	Estadísticas de red, dificultad y trabajo en cadena	Ninguno	`{"chain":"main","blocks":826458,"headers":826458,"bestblockhash":"000000000000..."}`
`chain_tips`	Consejos actuales sobre la cadena, incluidas alturas y estados	Ninguno	`[{"height":826458,"hash":"000000000000...","branchlen":0,"status":"active"}]`
`circulating_supply`	Suministro circulante actual de BSV	Ninguno	`{"bsv":21000000}`
`peer_info`	Estadísticas de pares conectados	Ninguno	`[{"addr":"1.2.3.4:8333","services":"000000000000...","lastsend":1621234567}]`

Bloquear datos

Punto final	Descripción	Parámetros requeridos	Ejemplo de respuesta
`block_by_hash`	Datos de bloque completos mediante hash	`blockHash`	`{"hash":"000000000000...","confirmations":1000,"size":1000000,...}`
`block_by_height`	Datos de bloque completos por altura	`blockHeight`	`{"hash":"000000000000...","confirmations":1000,"size":1000000,...}`
`tag_count_by_height`	Estadísticas sobre el recuento de etiquetas para un bloque específico	`blockHeight`	`{"tags":{"amp":3,"bitkey":5,"metanet":12,"planaria":7,"b":120}}`
`block_headers`	Recupera los últimos 10 encabezados de bloque	Ninguno	`[{"hash":"000000000000...","height":826458,"version":536870912,...},...]`
`block_pages`	Recupera páginas de ID de transacciones para bloques grandes	`blockHash` , opcional: `pageNumber`	`["tx1hash","tx2hash","tx3hash",...]`

Datos estadísticos

Punto final	Descripción	Parámetros requeridos	Ejemplo de respuesta
`block_stats_by_height`	Estadísticas de bloque para una altura específica	`blockHeight`	`{"size":123456,"txCount":512,"outputTotal":54.12345678,"outputTotalUsd":2345.67,...}`
`block_miner_stats`	Estadísticas de minería de bloques durante un período de tiempo	opcional: `days` (predeterminado 7)	`{"blocks":{"miner1":412,"miner2":208,...},"total":1008}`
`miner_summary_stats`	Resumen de las estadísticas mineras	opcional: `days` (predeterminado 7)	`{"totalBlocks":1008,"totalFees":1.23456789,"totalFeesUsd":53.67,...}`

Datos de la transacción

Punto final	Descripción	Parámetros requeridos	Ejemplo de respuesta
`tx_by_hash`	Datos detallados de las transacciones	`txHash`	`{"txid":"a1b2c3d4e5f6...","version":1,"locktime":0,"size":225,...}`
`tx_raw`	Datos hexadecimales de transacciones sin procesar	`txHash`	`"01000000012345abcdef..."`
`tx_receipt`	Recibo de transacción	`txHash`	`{"blockHash":"000000000000...","blockHeight":800000,"confirmations":26458}`
`bulk_tx_details`	Recuperar múltiples transacciones en una sola solicitud	`txids` (matriz)	`[{"txid":"a1b2c3d4e5f6...","version":1,...}, {"txid":"b2c3d4e5f6a7...","version":1,...}]`

Datos de dirección

Punto final	Descripción	Parámetros requeridos	Ejemplo de respuesta
`address_history`	Historial de transacciones de la dirección	`address` , opcional: `limit`	`[{"tx_hash":"a1b2c3d4e5f6...","height":800000},...]`
`address_utxos`	Salidas no utilizadas para la dirección	`address`	`[{"tx_hash":"a1b2c3d4e5f6...","tx_pos":0,"value":100000},...]`

Red

Punto final	Descripción	Parámetros requeridos	Ejemplo de respuesta
`health`	Comprobación del estado de la API	Ninguno	`{"status":"synced"}`

Ejemplos de uso

La herramienta bsv_explore se puede utilizar con indicaciones en lenguaje natural como:

"Get the current Bitcoin SV blockchain information"
"Show me block #800000 details"
"Get tag count statistics for block #800000"
"Fetch transaction history for address 1ExampleBsvAddressXXXXXXXX"
"Get unspent outputs for my wallet address"
"Check transaction details for txid a1b2c3d4e5f6..."
"What is the current BSV circulating supply?"
"Show me the latest block headers"
"Get transaction IDs for page 2 of a large block"
"Show me block statistics for height 800000"
"What are the mining statistics for the last 14 days?"
"Get a summary of mining activity over the past 30 days"
"Retrieve details for multiple transactions in a single query"

Bajo el capó, la herramienta acepta parámetros para especificar qué datos recuperar:

endpoint : el punto final específico de WhatsOnChain para consultar (por ejemplo, chain_info , tx_by_hash )
network : La red BSV a utilizar ( main o test )
Parámetros adicionales según lo requiera el punto final específico:
- blockHash : para puntos finales block_by_hash y block_pages
- blockHeight : para los puntos finales block_by_height, tag_count_by_height y block_stats_by_height
- pageNumber : Para el punto final block_pages (paginación)
- days : para los puntos finales block_miner_stats y miner_summary_stats (el valor predeterminado es 7)
- txHash : para puntos finales relacionados con transacciones (tx_by_hash, tx_raw, tx_receipt)
- txids : para el punto final bulk_tx_details (matriz de ID de transacción)
- address : para puntos finales relacionados con la dirección
- limit : límite de paginación opcional para address_history

Opciones de red

La herramienta es compatible tanto con la red principal como con la red de prueba:

main : red principal de Bitcoin SV (predeterminada)
test : red de pruebas de Bitcoin SV

Desarrollo

Ejecución del servidor

bun run index.ts

Ejecución de pruebas

bun test

Licencia

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Bitcoin SV MCP Server

Integrations