OrdiscanMCP v1

Servidor MCP para interagir com a API Ordiscan e consultar ordinais e inscrições do Bitcoin. Requer uma chave de API Ordiscan.

GitHubExperimente este MCPPatrocinado

Documentação

OrdiscanMCP v1

Uma implementação de servidor HTTP do framework MCP com integração com a API Ordiscan.

License: MIT

Recursos

  • Transporte HTTP Stream na porta 1337
  • Modo de resposta em stream para comunicação em tempo real
  • Integração abrangente com a API Ordiscan (29 ferramentas)
  • Implementação em TypeScript com validação de esquema Zod
  • Tratamento detalhado de erros e formatação de respostas
  • Conexão direta com a API (sem necessidade de proxy)
  • Autenticação por token Bearer
  • Limitação de taxa gerenciada pela API Ordiscan

Conexão com a API e Autenticação

Conexão Direta

Todas as ferramentas conectam-se diretamente à API Ordiscan (api.ordiscan.com) sem necessidade de proxy. Isso garante:

  • Tempos de resposta mais rápidos
  • Latência reduzida
  • Nenhuma configuração adicional necessária
  • Tratamento direto de erros
  • Limitação de taxa automática pela API Ordiscan

Autenticação

Toda ferramenta exige autenticação usando um token Bearer:

  • A chave da API deve ser fornecida de uma das seguintes formas:
    1. Como parâmetro em cada chamada de ferramenta (parâmetro apiKey)
    2. Através da variável de ambiente ORDISCAN_API_KEY
  • A autenticação usa o formato de token Bearer
  • Todas as requisições incluem o cabeçalho Authorization: Bearer <your-api-key>
  • Chaves de API inválidas ou ausentes resultarão em erros de autenticação

Configuração

  1. Instale as dependências:
npm install
  1. Compile o projeto:
npm run build
  1. Configure seu 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. Inicie o servidor:
npm start

Para desenvolvimento com recarga automática:

npm run dev

Envie a chave com uma requisição uma única vez, e está pronto para uso.

Estrutura do Projeto

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

Tratamento de Parâmetros

Todas as ferramentas usam utilitários robustos de tratamento de parâmetros de ordiscan-utils.ts:

Tratamento Flexível de Números

  • flexibleNumber(): Aceita entradas tanto em formato string quanto número para parâmetros numéricos
    • Converte automaticamente strings numéricas em inteiros
    • Valida faixas numéricas quando aplicável
    • Usado para paginação, números ordinais e alturas de blocos

Tratamento Flexível de Enums

  • flexibleEnum(): Valida entradas string contra valores predefinidos
    • Usado para ordens de classificação ('newest'/'oldest')
    • Usado para filtros de tipo e outros valores enumerados
    • Fornece mensagens de erro claras para entradas inválidas

Esses utilitários garantem tratamento consistente de parâmetros em todas as ferramentas, mantendo segurança de tipos e validação.

Ferramentas Disponíveis (29 no Total)

1. Ferramenta Principal

  • ordiscan_main: Ferramenta de propósito geral para informações e status de runas

2. Ferramentas de Endereço (6)

  • Ferramenta UTXO: Obter todos os UTXOs pertencentes a um endereço Bitcoin
  • Ferramentas de Inscrição Básica e Detalhada: Obter informações de inscrições para um endereço
  • Ferramenta de Saldo de Runas: Obter saldos de runas para um endereço
  • Ferramenta de Saldo BRC-20: Obter saldos de tokens BRC-20 para um endereço
  • Ferramenta de Sats Raros: Obter sats raros pertencentes a um endereço

3. Ferramentas de Atividade (3)

  • Ferramenta de Atividade de Inscrições: Rastrear transferências de inscrições para um endereço
  • Ferramenta de Atividade de Runas: Rastrear transferências de runas para um endereço
  • Ferramenta de Atividade BRC-20: Rastrear transferências de tokens BRC-20 para um endereço

4. Ferramentas de Transação (4)

  • Ferramenta de Informações de Transação: Obter informações detalhadas de transações
  • Ferramenta de Inscrições em Transação: Obter inscrições em uma transação
  • Ferramenta de Transferências de Inscrições em Transação: Rastrear transferências de inscrições em uma transação
  • Ferramenta de Runas em Transação: Rastrear transferências de runas em uma transação

5. Ferramentas de Inscrição (4)

  • Ferramenta de Informações de Inscrição: Obter informações detalhadas sobre uma inscrição
  • Ferramenta de Características de Inscrição: Obter características de uma inscrição
  • Ferramenta de Lista de Inscrições: Obter uma lista paginada de todas as inscrições
  • Ferramenta de Transferências de Inscrição: Rastrear transferências de uma inscrição

6. Ferramentas de Coleção (3)

  • Ferramenta de Lista de Coleções: Obter uma lista paginada de coleções
  • Ferramenta de Informações de Coleção: Obter informações detalhadas sobre uma coleção
  • Ferramenta de Inscrições em Coleção: Obter inscrições em uma coleção

7. Ferramentas de Runas (3)

  • Ferramenta de Lista de Runas: Obter uma lista de todas as runas
  • Ferramenta de Informações de Mercado de Runas: Obter informações de mercado para uma runa
  • Ferramenta de Desbloqueio de Nome de Runa: Verificar disponibilidade de nome de runa

8. Ferramentas BRC-20 (2)

  • Ferramenta de Lista BRC-20: Obter uma lista de todos os tokens BRC-20
  • Ferramenta de Informações de Token BRC-20: Obter informações detalhadas sobre um token BRC-20

9. Ferramentas de Sat (3)

  • Ferramenta de Informações de Sat: Obter informações sobre um sat específico
  • Ferramenta de Sats Raros em UTXO: Obter sats raros em um UTXO
  • Ferramenta de Faixas de Sat em UTXO: Obter faixas de sats em um UTXO

Exemplos de Ferramentas

Ferramenta de Informações de Inscrição

Obtenha informações detalhadas sobre uma inscrição específica.

Nome da Ferramenta: ordiscan_inscription_info

Parâmetros:

  • id (string): O ID da inscrição (ex.: b61b0172d95e266c18aea0c624db987e971a5d6d4ebc2aaed85da4642d635735i0)
  • apiKey (string, opcional): Sua chave da API Ordiscan

Exemplo de Resposta:

{
  "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"
    }
  }
}

Ferramenta de Mercado de Runas

Obtenha informações de mercado para uma runa específica.

Nome da Ferramenta: ordiscan_rune_market

Parâmetros:

  • name (string): O nome único da runa (sem espaçadores)
  • apiKey (string, opcional): Sua chave da API Ordiscan

Exemplo de Resposta:

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

Ferramenta de Informações BRC-20

Obtenha informações detalhadas sobre um token BRC-20.

Nome da Ferramenta: ordiscan_brc20_info

Parâmetros:

  • tick (string): O tick único do token
  • apiKey (string, opcional): Sua chave da API Ordiscan

Exemplo de Resposta:

{
  "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"
    }
  }
}

Tratamento de Erros

Todas as ferramentas incluem tratamento abrangente de erros:

  • Validação de chave da API
  • Erros de requisição de rede
  • Validação de entrada inválida
  • Respostas de limitação de taxa da API Ordiscan
  • Mensagens de erro detalhadas

Formatação de Respostas

Cada ferramenta fornece respostas tanto brutas quanto formatadas:

  • Dados brutos no campo data
  • Dados formatados legíveis por humanos no campo formatted
  • Formato de erro consistente em todas as ferramentas
  • Formatação adequada de números e localização de datas

Recomendações de Segurança

Gerenciamento de Chaves da API

  • Nunca codifique chaves da API diretamente no código
  • Use variáveis de ambiente para armazenar chaves da API
  • Rotacione chaves da API periodicamente
  • Use chaves da API diferentes para desenvolvimento e produção

Tratamento de Erros

O servidor implementa tratamento seguro de erros:

  • Nenhuma informação sensível em mensagens de erro
  • Códigos de status HTTP adequados
  • Respostas de erro estruturadas
  • Registro de erros sem expor detalhes internos

Validação de Entrada

Todas as ferramentas usam validação rigorosa de entrada:

  • Validação de esquema Zod para todos os parâmetros
  • Verificação de tipos com TypeScript
  • Tratamento flexível de números para entradas numéricas
  • Validação de strings para valores enumerados

Limitação de Taxa

A limitação de taxa é gerenciada pela API Ordiscan:

  • Nenhuma limitação de taxa adicional necessária
  • Limites de taxa baseados na chave da API
  • Respostas de erro adequadas para limite de taxa excedido
  • Tratamento automático de limitação de taxa