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
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:
- Como parámetro en cada llamada de herramienta (parámetro
apiKey ) - 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
- Instalar dependencias:
- Construir el proyecto:
- Configure su cliente MCP:
{
"mcpServers": {
"ordiscanmcpv1": {
"command": "npx",
"args": [
"mcp-remote",
"https://your-deployed-server.com/mcp"
]
}
}
}
URL: ( http://localhost:1337/mcp )
- Iniciar el servidor:
Para desarrollo con recarga en caliente:
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
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"
}
}
}
Obtenga información detallada sobre un token BRC-20.
Nombre de la herramienta: ordiscan_brc20_info
Parámetros:
tick (cadena): el tick único del tokenapiKey (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
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