MCP-Inscription Server

Interaja com Inscrições Ordinals e exiba conteúdo de transações.

GitHub
4
Experimente este MCPPatrocinado

Documentação

MseeP.ai Security Assessment Badge

MCP-Inscription Server

smithery badge

Visão Geral

Um servidor Model Context Protocol (MCP) que permite que modelos de IA interajam com Inscriptions Ordinals, permitindo que eles exibam conteúdo de uma transação.

🎮 Demonstração

Demonstração Goose Vídeo
Goose screenshot

💼 Sumário

🔧 Recursos

  • Detecção de Ordinals: Detecta e analisa automaticamente transações Bitcoin em ordinals, suportando formatos de inscriptions baseados em texto, imagens, json e outros.

🦆 Integração com Goose

Goose é um framework de agente de IA de código aberto da Block que suporta extensões via Model Context Protocol. Você pode integrar o servidor MCP-Inscription como uma extensão do Goose para permitir que o Goose interaja com Inscriptions Ordinals. O Goose suporta dois modos de integração para servidores MCP: executar o servidor como um processo local (STDIO) ou conectar-se a ele como um serviço remoto via Server-Sent Events (SSE). Abaixo estão as instruções para ambos os métodos:

Usando STDIO (Extensão Local)

Este método executa o servidor MCP-Inscription localmente como um subprocesso do Goose, comunicando-se por meio de entrada/saída padrão.

  1. Clone e compile o repositório MCP-Inscription (se ainda não o fez):

    git clone https://github.com/Laz1mov/mcp-inscription
cd mcp-inscription
npm install
npm run build

    Anote o caminho absoluto completo para o repositório, pois você precisará dele na próxima etapa.

  2. Adicione uma nova extensão no Goose: Abra a interface de configuração do Goose. Você pode fazer isso pela linha de comando executando goose configure, ou no aplicativo Goose Desktop indo em Configurações > Extensões. No menu, escolha "Adicionar Extensão" (Usando Extensões | goose)

  3. Escolha o tipo de extensão – Extensão de Linha de Comando: Quando solicitado o tipo de extensão, selecione Extensão de Linha de Comando (no menu CLI ou na interface) para que o Goose saiba que deve iniciar um comando local (Usando Extensões | goose) (em vez de uma extensão integrada ou remota).

  4. Insira os detalhes da extensão: Forneça um nome e comando para o servidor MCP-Inscription:

    • ID: mcp-inscription

    • Nome: Você pode chamá-lo de "mcp-inscription", ou qualquer identificador (será assim que você se referirá à extensão).

    • Comando: Especifique o caminho completo para o script CLI compilado. Por exemplo:

      node /absolute/path/to/mcp-inscription/build/cli.js

      Substitua /absolute/path/to/mcp-inscription pelo caminho real onde você clonou o repositório.

    • Normalmente você não precisa adicionar argumentos além do caminho do script (a menos que seu servidor exija flags especiais).

  5. Finalize e habilite: Complete a adição da extensão. O Goose adicionará esta nova extensão à sua configuração (geralmente ~/.config/goose/config.yaml). Certifique-se de que a extensão esteja habilitada (se estiver usando o assistente CLI, ela deve estar habilitada por padrão após a adição; no aplicativo Goose Desktop, você pode verificar a lista de Extensões e ativá-la se ainda não estiver (Usando Extensões | goose) (Usando Extensões | goose)).

  6. Inicie uma sessão Goose com a nova extensão: Agora você pode usar a extensão no Goose. Se estiver executando o Goose via CLI, inicie uma sessão que inclua a extensão executando:

    goose session --with-extension "mcp-inscription"

substituindo "ordinals" pelo nome que você deu à extensão (Usando Extensões | goose). (Isso garante que a sessão carregue a extensão. Alternativamente, se a extensão estiver habilitada globalmente, o Goose Desktop ou CLI a terá automaticamente disponível em todas as sessões.)

Usando SSE (Extensão Remota)

Este método conecta o Goose a um servidor MCP já em execução via um stream HTTP SSE. Use isto se quiser executar o servidor MCP-Inscription como um serviço independente (possivelmente em outra máquina ou apenas independente do Goose).

  1. Inicie o servidor MCP como um serviço independente: Execute o servidor MCP-Inscription no modo SSE para escutar conexões:

    # Navigate to your mcp-inscription directory
cd /path/to/mcp-inscription

# If you havent built it yet
npm install
npm run build

# Run in SSE mode on port 3000 (default)
SERVER_MODE=sse node build/cli.js

# Alternatively, specify a different port
SERVER_MODE=sse PORT=9000 node build/cli.js

    Isso iniciará o servidor no modo SSE, disponibilizando-o em http://localhost:3000 (ou na porta especificada).

  2. Adicione uma nova extensão no Goose (Remota): Como antes, execute goose configure ou use a interface do Goose para Adicionar Extensão (Usando Extensões | goose). Desta vez, escolha Extensão Remota quando solicitado o tipo de extensão (Usando Extensões | goose). Isso informa ao Goose que ele se conectará a um servidor externo via SSE.

  3. Insira os detalhes da extensão remota: Dê um nome à extensão (ex.: "ordinals") e forneça a URL do servidor. Para a URL, insira o endereço base onde o servidor MCP está rodando. Por exemplo, se seu servidor estiver escutando na porta 9000 na sua máquina local, você pode inserir http://localhost:9000. O Goose tentará se conectar ao endpoint SSE do servidor MCP nesse endereço. (O Goose usa o caminho SSE padrão do MCP, que por convenção está sob a rota /mcp/sse no servidor; normalmente você só precisa fornecer o host e a porta, e o Goose cuida do resto.)

  4. Habilite a extensão: Após adicionar a extensão remota, certifique-se de que ela esteja habilitada nas configurações do Goose (assim como no caso STDIO). Apenas uma das extensões STDIO ou SSE (com as mesmas ferramentas) precisa estar habilitada – se você acidentalmente habilitar tanto uma versão local quanto remota do mesmo servidor, talvez queira desabilitar uma para evitar confusão.

Usando a extensão MCP-Inscription no Goose: Uma vez que a extensão esteja configurada (por qualquer um dos métodos acima) e habilitada, você pode interagir com o Goose e consultar dados ord através dela. Em um novo chat ou sessão do Goose, simplesmente faça perguntas como faria normalmente. O Goose reconhecerá quando usar as ferramentas MCP-Inscription para atender sua solicitação. Por exemplo:

  • "Mostre-me Ordinals: 0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389?"

Quando você fizer essas perguntas, o Goose invocará as ferramentas do servidor MCP-Inscription e retornará a resposta (ex.: a informação do bloco Bitcoin mais recente). Você deve ver o Goose respondendo com informações atualizadas obtidas da blockchain Bitcoin via o servidor MCP-Inscription.

Se o Goose não parecer usar a extensão (por exemplo, se responder que não consegue encontrar a informação), certifique-se de que a extensão está habilitada e que o servidor está rodando (no modo SSE para remoto). Você também pode executar o CLI do Goose com logging detalhado para ver se ele tentou chamar a extensão. Geralmente, se configurado corretamente, o Goose descobrirá automaticamente as capacidades do servidor MCP-Inscription e as usará quando relevante.

Recursos Adicionais: Para mais detalhes sobre extensões do Goose e o MCP, consulte a documentação oficial do Goose (Usando Extensões | goose). A documentação inclui uma lista de extensões integradas e da comunidade e explica como servidores MCP se integram ao Goose. Você também pode encontrar um diretório de servidores MCP disponíveis e dicas adicionais de configuração na documentação do Goose e na documentação do Model Context Protocol. Isso pode ajudar se você quiser explorar mais extensões ou desenvolver as suas próprias.

🔑 Integração com Claude Desktop

Para usar o servidor MCP-Inscription com o Claude Desktop (aplicativo desktop da Anthropic para Claude), siga estes passos:

  1. Baixe e instale o Claude Desktop: Visite a página oficial de downloads do Claude Desktop e obtenha o aplicativo para seu sistema operacional (macOS ou Windows) (Instalando Claude para Desktop | Central de Ajuda Anthropic). Instale o aplicativo e certifique-se de estar usando a versão mais recente (você pode verificar atualizações no menu do aplicativo).

  2. Clone e compile o repositório MCP-Inscription:

    git clone https://github.com/Laz1mov/mcp-inscription
cd mcp-inscription
npm install
npm run build

  3. Configure o Claude Desktop para usar o servidor MCP-Inscription: Abra o arquivo de configuração do Claude Desktop (ele é criado quando você edita as configurações pela primeira vez no Claude Desktop):

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
    • Windows: %APPDATA%\Claude\claude_desktop_config.json
      Adicione uma entrada para o servidor MCP-Inscription neste JSON de configuração sob a seção "mcpServers". Por exemplo:
    {
  "mcpServers": {
    "mcp-inscription": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-inscription/build/cli.js"]
    }
  }
}

    No trecho acima, "mcp-inscription" é um identificador para o servidor (você pode nomeá-lo como quiser). Substitua /absolute/path/to/mcp-inscription pelo caminho completo real onde você clonou o repositório.

  4. Reinicie o Claude Desktop: Salve o arquivo claude_desktop_config.json e então feche e reabra o Claude Desktop. Na próxima inicialização, o Claude iniciará automaticamente o servidor MCP-Inscription conforme configurado. Se o Claude Desktop estava em execução, você precisa reiniciá-lo para que as alterações tenham efeito.

Testando a Integração com Claude Desktop

Uma vez que o Claude Desktop for reiniciado, você pode testar se o servidor MCP-Inscription está funcionando corretamente:

  • Verifique a resposta: O Claude deve retornar uma resposta detalhada (ex.: a própria inscription ou informações sobre runes) sem erros. Se você receber uma mensagem de erro ou nenhuma resposta útil, o servidor MCP pode não estar conectado corretamente.

  • Verifique os logs do Claude (se necessário): O Claude Desktop fornece arquivos de log que podem ajudar a depurar integrações MCP. Se a ferramenta não estiver respondendo, verifique os arquivos de log em:

    • macOS: ~/Library/Logs/Claude/
    • Windows: %APPDATA%\Claude\logs\
      Procure por mcp.log para mensagens gerais de conexão MCP, e um arquivo chamado mcp-server-mcp-inscription.log (ou com o nome que você usou) para a saída/erros do servidor MCP. Esses logs mostrarão se o servidor iniciou ou se houve erros (como caminho errado ou exceções no servidor). Se você vir erros, corrija a configuração ou o ambiente conforme necessário, reinicie o Claude Desktop e teste novamente.

Instalando via Smithery

Para instalar o Inscription Server para Claude Desktop automaticamente via Smithery:

npx -y @smithery/cli install @Laz1mov/mcp-inscription --client claude

📂 Estrutura do Projeto

mcp-inscription/
├── src/
│   ├── ordinals_client.ts      # Bitcoin ordinals and runestone utility functions
│   ├── servers/
│   │   ├── index.ts            # Server exports and factory functions
│   │   ├── sse.ts              # Server implementation using SSE transport
│   │   ├── stdio.ts            # Server implementation using STDIO transport
│   │   └── base.ts             # Base server implementation with shared functionality
│   ├── index.ts                # Main entry point
│   ├── cli.ts                  # CLI launcher
│   ├── mcp_inscription_types.ts # Shared types and schemas for the MCP-Inscription server
│   └── utils/
│       ├── logger.ts           # Logger setup
│       ├── cache.ts            # Caching implementation
│       ├── error_handlers.ts   # Error handling utilities
│       ├── json_utils.ts       # JSON processing utilities
│       ├── img_utils.ts        # Image processing and conversion utilities
│       └── version.ts          # Version information
├── .env.example                # Example environment configuration file
├── package.json
├── tsconfig.json
└── README.md

📦 Ferramentas Disponíveis

show_ordinals

Descrição:
Decodifica dados de inscription Ordinal a partir dos dados de testemunha (witness) de uma transação.

Esquema de Entrada:

{
  "txid": "string"
}

Exemplo de Entrada:

{
  "txid": "0169d12c4edf2026a67e219c10207438a080eb82d8f21860f6784dd66f281389"
}

Saída:
Retorna o conteúdo da inscription decodificado, que pode ser texto, JSON, HTML ou outros formatos.

🚨 Tratamento de Erros

O servidor emprega tipos de erro personalizados para lidar com operações Bitcoin e consultas à blockchain. Mensagens de erro detalhadas são registradas usando Pino e incluídas nas respostas ao cliente para facilitar a depuração.

🤝 Contribuição

Contribuições e solicitações de recursos são bem-vindas! Sinta-se à vontade para enviar pull requests ou abrir issues no GitHub.

📝 Licença

Este projeto está licenciado sob a Licença MIT.