OrdiscanMCP v1

Una implementación de servidor HTTP de MCP Framework con integración de API de Ordiscan.

Características

• Transporte de flujo HTTP en el puerto 1337

• Modo de respuesta de flujo para comunicación en tiempo real

• Integración completa de la API de Ordiscan (29 herramientas)

• Implementación de TypeScript con validación de esquemas Zod

• Manejo detallado de errores y formato de respuesta

• Conexión API directa (no requiere proxy)

• Autenticación de token de portador

• Limitación de velocidad gestionada por la API de Ordiscan

Related MCP server: Obsidian MCP REST Server

Conexión y autenticación de API

Conexión directa

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

• Tiempos de respuesta más rápidos

• Latencia reducida

• No se necesita configuración adicional

• Manejo directo de errores

• Limitación automática de velocidad mediante la API de Ordiscan

Autenticación

Cada herramienta requiere autenticación mediante un token Bearer:

• La clave API se debe proporcionar:

  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 de portador

• Todas las solicitudes incluyen el encabezado Authorization: Bearer <your-api-key>

• Las claves API no válidas o faltantes generarán errores de autenticación

Configuración

1. Instalar dependencias:

npm install

2. Construir el proyecto:

npm run build

3. Configure su 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 )

4. Iniciar el servidor:

npm start

Para desarrollo con recarga en caliente:

npm run dev

Pase la clave con una solicitud una sola 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 cadena y de número para parámetros numéricos

  • Convierte automáticamente números de cadena en enteros

  • Valida rangos numéricos cuando corresponda

  • Se utiliza para paginación, números ordinales y alturas de bloque.

Manejo flexible de enumeraciones

• flexibleEnum() : valida las entradas de cadena contra valores predefinidos

  • Se utiliza para ordenar por orden ('más nuevo'/'más antiguo')

  • Se utiliza para filtros de tipo y otros valores enumerados.

  • Proporciona mensajes de error claros para entradas no válidas

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

Herramientas disponibles (29 en total)

1. Herramienta principal

• ordiscan_main : Herramienta de uso general para obtener información y estado de las runas

2. Herramientas de dirección (6)

• Herramienta UTXO : Obtenga todos los UTXO propiedad de una dirección de Bitcoin

• Herramientas de inscripción básicas y detalladas : Obtenga información de inscripción para una dirección

• Herramienta de equilibrio de runas : obtenga el equilibrio de runas de una dirección

• Herramienta de saldo BRC-20 : obtenga saldos de tokens BRC-20 para una dirección

• Herramienta Sats Raros : Obtenga Sats Raros propiedad de una dirección

3. Herramientas de actividad (3)

• Herramienta de actividad de inscripciones : Realice un seguimiento de las transferencias de inscripciones de una dirección

• Herramienta de actividad de runas : seguimiento de transferencias de runas para una dirección

• Herramienta de actividad BRC-20 : Seguimiento de transferencias de tokens BRC-20 para una dirección

4. Herramientas de transacción (4)

• Herramienta de información de transacciones : obtenga información detallada de las transacciones

• Herramienta de inscripciones de transacciones : obtener inscripciones en una transacción

• Herramienta de transferencias de inscripciones de transacciones : realice un seguimiento de las transferencias de inscripciones en una transacción

• Herramienta de Runas de Transacción : Rastrear transferencias de runas en una transacción

5. Herramientas de inscripción (4)

• Herramienta de información de inscripciones : obtenga información detallada sobre una inscripción

• Herramienta de rasgos de inscripción : obtener rasgos para una inscripción

• Herramienta de lista de inscripciones : obtenga una lista paginada de todas las inscripciones

• Herramienta de transferencias de inscripciones : realice un seguimiento de las transferencias de una inscripción

6. Herramientas de recolección (3)

• Herramienta de lista de colecciones : obtenga una lista paginada de colecciones

• Herramienta de información de colección : obtenga información detallada sobre una colección

• Herramienta de inscripciones de colecciones : obtener inscripciones en una colección

7. Herramientas de runas (3)

• Herramienta de lista de runas : obtenga una lista de todas las runas

• Herramienta de información del mercado de runas : obtén información del mercado de una runa

• Herramienta de desbloqueo de nombres de runas : comprobar la disponibilidad de nombres de runas

8. Herramientas BRC-20 (2)

• Herramienta de lista BRC-20 : obtenga una lista de todos los tokens BRC-20

• Herramienta de información del token BRC-20 : obtenga información detallada sobre un token BRC-20

9. Herramientas Sat (3)

• Herramienta de información de satélite : obtenga información sobre un satélite específico

• Herramienta UTXO Rare Sats : obtenga sats raros en un UTXO

• Herramienta de rangos de saturación UTXO : obtenga rangos de saturación en un UTXO

Ejemplos de herramientas

Herramienta de información de inscripción

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

Nombre de la herramienta: ordiscan_inscription_info

Parámetros:

• id (cadena): El ID de la inscripción (por ejemplo, b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0)

• apiKey (cadena, opcional): su clave 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

Obtenga información del mercado para una runa específica.

Nombre de la herramienta: ordiscan_rune_market

Parámetros:

• name (cadena): el nombre único de la runa (sin espaciadores)

• apiKey (cadena, opcional): su clave 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

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

Nombre de la herramienta: ordiscan_brc20_info

Parámetros:

• tick (cadena): el tick único del token

• apiKey (cadena, opcional): su clave 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 un manejo integral de errores:

• Validación de clave API

• Errores de solicitud de red

• Validación de entrada no válida

• Limitación de velocidad de las respuestas desde la API de Ordiscan

• Mensajes de error detallados

Formato de respuesta

Cada herramienta proporciona respuestas tanto sin procesar como formateadas:

• Datos sin procesar en el campo data

• Datos formateados legibles por humanos en el campo formatted

• Formato de error consistente en todas las herramientas

• Formato de número adecuado y localización de fecha

Recomendaciones de seguridad

Gestión de claves API

• Nunca codifique claves API en su código

• Utilice variables de entorno para el almacenamiento de claves API

• Rotar las claves API periódicamente

• Utilice diferentes claves API para el desarrollo y la producción

Manejo de errores

El servidor implementa un manejo seguro de errores:

• No hay información confidencial en los mensajes de error

• Códigos de estado HTTP adecuados

• Respuestas de error estructuradas

• Registro de errores sin exponer los aspectos internos

Validación de entrada

Todas las herramientas utilizan una validación de entrada estricta:

• Validación del esquema Zod para todos los parámetros

• Comprobación de tipos con TypeScript

• Manejo flexible de números para entradas numéricas

• Validación de cadenas para valores enumerados

Limitación de velocidad

La limitación de velocidad la gestiona la API de Ordiscan:

• No se necesita ninguna limitación de velocidad adicional

• Límites de velocidad basados en claves API

• Respuestas de error adecuadas para el límite de velocidad excedido

• Manejo automático del límite de velocidad