OrdiscanMCP v1

Servidor MCP para interactuar con la API de Ordiscan y consultar ordinales e inscripciones de Bitcoin. Requiere una clave de API de Ordiscan.

GitHubPrueba este MCPPatrocinado

Documentación

OrdiscanMCP v1

Una implementación de servidor HTTP del framework MCP con integración de la API de Ordiscan.

License: MIT

Características

  • Transporte HTTP Stream en el puerto 1337
  • Modo de respuesta Stream para comunicación en tiempo real
  • Integración integral de la API de Ordiscan (29 herramientas)
  • Implementación en TypeScript con validación de esquemas Zod
  • Manejo detallado de errores y formato de respuestas
  • Conexión directa a la API (sin necesidad de proxy)
  • Autenticación mediante token Bearer
  • Límite de velocidad gestionado por la API de Ordiscan

Conexión y Autenticación de la API

Conexión Directa

Todas las herramientas se conectan directamente a la API de Ordiscan (api.ordiscan.com) sin requerir ningún proxy. Esto garantiza:

  • Tiempos de respuesta más rápidos
  • Latencia reducida
  • Sin necesidad de configuración adicional
  • Manejo directo de errores
  • Límite de velocidad automático por la API de Ordiscan

Autenticación

Cada herramienta requiere autenticación mediante un token Bearer:

  • La clave de API debe proporcionarse de una de las siguientes formas:
    1. Como parámetro en cada llamada de herramienta (parámetro apiKey)
    2. A través de la variable de entorno ORDISCAN_API_KEY
  • La autenticación utiliza el formato de token Bearer
  • Todas las solicitudes incluyen el encabezado Authorization: Bearer <your-api-key>
  • Las claves de API inválidas o faltantes resultarán en errores de autenticación

Configuración

  1. Instalar dependencias:
npm install
  1. Compilar el proyecto:
npm run build
  1. Configurar tu cliente MCP:
{
  "mcpServers": {
    "ordiscanmcpv1": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-deployed-server.com/mcp"  
      ]
    }
  }
}

url: (http://localhost:1337/mcp) Remoto: (https://ordiscan-mcp-v1.onrender.com/mcp)

  1. Iniciar el servidor:
npm start

Para desarrollo con recarga automática:

npm run dev

Pasa la clave con una solicitud una vez, y listo.

Estructura del Proyecto

ordiscanmcpv1/
├── src/
│   ├── tools/
│   │   ├── ordiscan-utils.ts
│   │   ├── ordiscan.ts            # Main Ordiscan Tool
│   │   │
│   │   ├── # Address Tools
│   │   ├── ordiscan-utxo.ts
│   │   ├── ordiscan-inscriptions.ts
│   │   ├── ordiscan-inscriptions-detail.ts
│   │   ├── ordiscan-runes-balance.ts
│   │   ├── ordiscan-brc20-balance.ts
│   │   ├── ordiscan-rare-sats.ts
│   │   │
│   │   ├── # Activity Tools
│   │   ├── ordiscan-inscriptions-activity.ts
│   │   ├── ordiscan-runes-activity.ts
│   │   ├── ordiscan-brc20-activity.ts
│   │   │
│   │   ├── # Transaction Tools
│   │   ├── ordiscan-tx-info.ts
│   │   ├── ordiscan-tx-inscriptions.ts
│   │   ├── ordiscan-tx-inscription-transfers.ts
│   │   ├── ordiscan-tx-runes.ts
│   │   │
│   │   ├── # Inscription Tools
│   │   ├── ordiscan-inscription-info.ts
│   │   ├── ordiscan-inscription-traits.ts
│   │   ├── ordiscan-inscriptions-list.ts
│   │   ├── ordiscan-inscriptions-detail.ts
│   │   │
│   │   ├── # Collection Tools
│   │   ├── ordiscan-collections-list.ts
│   │   ├── ordiscan-collection-info.ts
│   │   ├── ordiscan-collection-inscriptions.ts
│   │   │
│   │   ├── # Rune Tools
│   │   ├── ordiscan-runes-list.ts
│   │   ├── ordiscan-rune-market.ts
│   │   ├── ordiscan-rune-name-unlock.ts
│   │   │
│   │   ├── # BRC-20 Tools
│   │   ├── ordiscan-brc20-list.ts
│   │   ├── ordiscan-brc20-info.ts
│   │   │
│   │   ├── # Sat Tools
│   │   ├── ordiscan-sat-info.ts
│   │   ├── ordiscan-utxo-rare-sats.ts
│   │   └── ordiscan-utxo-sat-ranges.ts
│   │
│   └── index.ts
├── package.json
├── tsconfig.json
└── README.md

Manejo de Parámetros

Todas las herramientas utilizan utilidades robustas de manejo de parámetros de ordiscan-utils.ts:

Manejo Flexible de Números

  • flexibleNumber(): Acepta entradas de tipo string y number para parámetros numéricos
    • Convierte automáticamente números en formato string a enteros
    • Valida rangos numéricos cuando corresponde
    • Se utiliza para paginación, números ordinales y alturas de bloque

Manejo Flexible de Enumeraciones

  • flexibleEnum(): Valida entradas de tipo string contra valores predefinidos
    • Se utiliza para órdenes de clasificación ('newest'/'oldest')
    • Se utiliza para filtros de tipo y otros valores enumerados
    • Proporciona mensajes de error claros para entradas inválidas

Estas utilidades garantizan un manejo consistente de parámetros en todas las herramientas, manteniendo la seguridad de tipos y la validación.

Herramientas Disponibles (29 en Total)

1. Herramienta Principal

  • ordiscan_main: Herramienta de propósito general para información y estado de runas

2. Herramientas de Dirección (6)

  • Herramienta UTXO: Obtener todos los UTXOs propiedad de una dirección de Bitcoin
  • Herramientas de Inscripciones Básicas y Detalladas: Obtener información de inscripciones para una dirección
  • Herramienta de Saldo de Runas: Obtener saldos de runas para una dirección
  • Herramienta de Saldo BRC-20: Obtener saldos de tokens BRC-20 para una dirección
  • Herramienta de Sats Raros: Obtener sats raros propiedad de una dirección

3. Herramientas de Actividad (3)

  • Herramienta de Actividad de Inscripciones: Rastrear transferencias de inscripciones para una dirección
  • Herramienta de Actividad de Runas: Rastrear transferencias de runas para una dirección
  • Herramienta de Actividad BRC-20: Rastrear transferencias de tokens BRC-20 para una dirección

4. Herramientas de Transacciones (4)

  • Herramienta de Información de Transacción: Obtener información detallada de una transacción
  • Herramienta de Inscripciones en Transacción: Obtener inscripciones en una transacción
  • Herramienta de Transferencias de Inscripciones en Transacción: Rastrear transferencias de inscripciones en una transacción
  • Herramienta de Runas en Transacción: Rastrear transferencias de runas en una transacción

5. Herramientas de Inscripciones (4)

  • Herramienta de Información de Inscripción: Obtener información detallada sobre una inscripción
  • Herramienta de Rasgos de Inscripción: Obtener rasgos de una inscripción
  • Herramienta de Lista de Inscripciones: Obtener una lista paginada de todas las inscripciones
  • Herramienta de Transferencias de Inscripción: Rastrear transferencias de una inscripción

6. Herramientas de Colecciones (3)

  • Herramienta de Lista de Colecciones: Obtener una lista paginada de colecciones
  • Herramienta de Información de Colección: Obtener información detallada sobre una colección
  • Herramienta de Inscripciones de Colección: Obtener inscripciones en una colección

7. Herramientas de Runas (3)

  • Herramienta de Lista de Runas: Obtener una lista de todas las runas
  • Herramienta de Información de Mercado de Runas: Obtener información de mercado para una runa
  • Herramienta de Desbloqueo de Nombre de Runa: Verificar disponibilidad de nombre de runa

8. Herramientas BRC-20 (2)

  • Herramienta de Lista BRC-20: Obtener una lista de todos los tokens BRC-20
  • Herramienta de Información de Token BRC-20: Obtener información detallada sobre un token BRC-20

9. Herramientas de Sats (3)

  • Herramienta de Información de Sat: Obtener información sobre un sat específico
  • Herramienta de Sats Raros en UTXO: Obtener sats raros en un UTXO
  • Herramienta de Rangos de Sats en UTXO: Obtener rangos de sats en un UTXO

Ejemplos de Herramientas

Herramienta de Información de Inscripción

Obtener información detallada sobre una inscripción específica.

Nombre de la Herramienta: ordiscan_inscription_info

Parámetros:

  • id (string): El ID de la inscripción (ej. b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0)
  • apiKey (string, opcional): Tu clave de API de Ordiscan

Ejemplo de Respuesta:

{
  "success": true,
  "formatted": {
    "id": "b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0",
    "number": 123456,
    "type": "image/png",
    "timestamp": "2024-01-01 12:00:00",
    "sat": "1,234,567",
    "content_url": "https://ordinals.com/content/...",
    "collection": "example-collection",
    "owner": {
      "address": "bc1...",
      "output": "txid:vout"
    },
    "genesis": {
      "address": "bc1...",
      "output": "txid:vout"
    }
  }
}

Herramienta de Mercado de Runas

Obtener información de mercado para una runa específica.

Nombre de la Herramienta: ordiscan_rune_market

Parámetros:

  • name (string): El nombre único de la runa (sin separadores)
  • apiKey (string, opcional): Tu clave de API de Ordiscan

Ejemplo de Respuesta:

{
  "success": true,
  "formatted": {
    "price": {
      "sats": "1,234.56",
      "usd": "$0.50"
    },
    "market_cap": {
      "btc": "12.3456",
      "usd": "$500,000"
    }
  }
}

Herramienta de Información BRC-20

Obtener información detallada sobre un token BRC-20.

Nombre de la Herramienta: ordiscan_brc20_info

Parámetros:

  • tick (string): El tick único del token
  • apiKey (string, opcional): Tu clave de API de Ordiscan

Ejemplo de Respuesta:

{
  "success": true,
  "formatted": {
    "tick": "ORDI",
    "supply": {
      "max": "21,000,000",
      "minted": "15,000,000",
      "remaining": "6,000,000",
      "percent_minted": "71.43%"
    },
    "market": {
      "price_usd": "$1.23",
      "market_cap_usd": "$18,450,000",
      "fully_diluted_market_cap_usd": "$25,830,000"
    }
  }
}

Manejo de Errores

Todas las herramientas incluyen manejo integral de errores:

  • Validación de clave de API
  • Errores de solicitudes de red
  • Validación de entradas inválidas
  • Respuestas de límite de velocidad de la API de Ordiscan
  • Mensajes de error detallados

Formato de Respuestas

Cada herramienta proporciona respuestas tanto en formato crudo como formateado:

  • Datos crudos en el campo data
  • Datos formateados legibles para humanos en el campo formatted
  • Formato de error consistente en todas las herramientas
  • Formato de números adecuado y localización de fechas

Recomendaciones de Seguridad

Gestión de Claves de API

  • Nunca codifiques claves de API en tu código
  • Utiliza variables de entorno para almacenar claves de API
  • Rota las claves de API periódicamente
  • Utiliza claves de API diferentes para desarrollo y producción

Manejo de Errores

El servidor implementa manejo seguro de errores:

  • Sin información sensible en mensajes de error
  • Códigos de estado HTTP adecuados
  • Respuestas de error estructuradas
  • Registro de errores sin exponer detalles internos

Validación de Entradas

Todas las herramientas utilizan validación estricta de entradas:

  • Validación de esquemas Zod para todos los parámetros
  • Verificación de tipos con TypeScript
  • Manejo flexible de números para entradas numéricas
  • Validación de strings para valores enumerados

Límite de Velocidad

El límite de velocidad es gestionado por la API de Ordiscan:

  • Sin necesidad de límite de velocidad adicional
  • Límites de velocidad basados en clave de API
  • Respuestas de error adecuadas al exceder el límite
  • Manejo automático del límite de velocidad