Servidor MCP Stampchain

Um servidor Model Context Protocol (MCP) para interagir com Bitcoin Stamps e dados de tokens SRC-20 por meio da API Stampchain. Este servidor fornece ferramentas compatíveis com MCP para clientes consultarem Bitcoin Stamps, coleções e tokens SRC-20.

Recursos

Ferramentas de Bitcoin Stamps: Obtenha detalhes de stamps, pesquise stamps e recupere stamps recentes
Coleções de Stamps: Consulte coleções e pesquise dados de coleções
Tokens SRC-20: Obtenha informações de tokens e pesquise tokens SRC-20
Type-safe: Construído com TypeScript e validação Zod
Testes Abrangentes: Cobertura completa de testes com validação CI
Configurável: Opções de configuração flexíveis para diferentes ambientes
Multiplataforma: Funciona em Ubuntu, Windows e macOS com Node.js 18+

Início Rápido

Pré-requisitos

Node.js 18+
npm ou yarn

Instalação

Clone o repositório:

git clone https://github.com/stampchain-io/stampchain-mcp.git
cd stampchain-mcp

Instale as dependências:
```
npm install
```
Compile o projeto:
```
npm run build
```
Teste a instalação:
```
npm run start
```

Integração com Cliente MCP

Claude Desktop

Para usar com Claude Desktop, adicione o seguinte ao seu claude_desktop_config.json:

{
  "mcpServers": {
    "stampchain": {
      "command": "node",
      "args": ["/path/to/stampchain-mcp/dist/index.js"],
      "cwd": "/path/to/stampchain-mcp"
    }
  }
}

Alternativa: Usando npx (recomendado)

Para configuração mais fácil sem instalação local:

{
  "mcpServers": {
    "stampchain": {
      "command": "npx",
      "args": ["-y", "stampchain-mcp"]
    }
  }
}

Nota: Substitua /path/to/stampchain-mcp pelo caminho real do seu diretório de instalação.

Outros Clientes MCP

Este servidor implementa o protocolo MCP padrão e pode ser usado com qualquer cliente compatível com MCP. Consulte a documentação do seu cliente para instruções específicas de configuração. O servidor aceita conexões via transporte stdio.

Ferramentas Disponíveis

Bitcoin Stamps

get_stamp - Obtenha informações detalhadas sobre um stamp específico por ID
search_stamps - Pesquise stamps com vários filtros (criador, coleção, etc.)
get_recent_stamps - Obtenha os stamps criados mais recentemente

Coleções de Stamps

get_collection - Obtenha informações detalhadas sobre uma coleção específica
search_collections - Pesquise coleções com filtros

Tokens SRC-20

get_token_info - Obtenha informações detalhadas sobre um token SRC-20 específico
search_tokens - Pesquise tokens SRC-20 com vários filtros

Configuração

O servidor pode ser configurado por meio de:

Arquivo de configuração (formato JSON)
Variáveis de ambiente
Argumentos de linha de comando

Exemplo de Arquivo de Configuração

{
  "api": {
    "baseUrl": "https://stampchain.io/api",
    "timeout": 30000,
    "retries": 3
  },
  "logging": {
    "level": "info"
  },
  "registry": {
    "maxTools": 1000,
    "validateOnRegister": true
  }
}

Variáveis de Ambiente

STAMPCHAIN_API_URL - URL base da API (padrão: https://stampchain.io/api)
STAMPCHAIN_LOG_LEVEL - Nível de registro (debug, info, warn, error)
STAMPCHAIN_API_TIMEOUT - Tempo limite da API em milissegundos

Uso em Linha de Comando

# Start with default configuration
npm run start

# Start with custom config file
npm run start -- --config config.json

# Start with debug logging
npm run start -- --log-level debug

# Show available tools
npm run tools

# Show version information
npm run version

Desenvolvimento

Scripts

npm run dev - Iniciar servidor de desenvolvimento com recarga automática
npm run build - Compilar o projeto TypeScript
npm run test - Executar todos os testes
npm run test:watch - Executar testes em modo de observação
npm run test:coverage - Executar testes com relatório de cobertura
npm run typecheck - Verificação de tipos TypeScript
npm run format - Formatar código com Prettier
npm run validate - Suíte completa de validação

Testes

O projeto inclui cobertura abrangente de testes:

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode during development
npm run test:watch

Estrutura do Projeto

src/
├── api/           # API client and related utilities
├── config/        # Configuration management
├── interfaces/    # TypeScript interfaces
├── protocol/      # MCP protocol handlers
├── schemas/       # Zod validation schemas
├── tools/         # MCP tool implementations
├── utils/         # Utility functions
├── index.ts       # Main entry point
└── server.ts      # Server implementation

Referência da API

Parâmetros das Ferramentas

Todas as ferramentas aceitam vários parâmetros para filtragem e paginação:

limit - Número de resultados a retornar (padrão: 10, máximo: 100)
page - Número da página para paginação (padrão: 1)
sort - Campo e direção de ordenação (ex.: "created_desc")

Formato de Resposta

Todas as ferramentas retornam dados estruturados com:

success - Booleano indicando se a solicitação foi bem-sucedida
data - Os dados solicitados (stamps, coleções, tokens)
pagination - Informações de paginação quando aplicável
error - Detalhes do erro se a solicitação falhou

Solução de Problemas

Problemas Comuns

Erros de Compilação: Certifique-se de ter Node.js 18+ e execute npm install primeiro
Problemas de Conexão: Verifique se a API Stampchain está acessível
Integração com Cliente MCP: Verifique se o caminho no seu arquivo de configuração está correto

Depuração

Ative o registro de depuração para ver informações detalhadas:

npm run start -- --debug

Ou defina o nível de registro na sua configuração:

{
  "logging": {
    "level": "debug"
  }
}

Desenvolvimento

Cobertura de Testes

Este projeto mantém cobertura abrangente de testes em várias áreas:

✅ Testes Unitários - Utilitários principais e funções auxiliares
✅ Testes de Integração - Funcionalidade do servidor MCP
✅ Validação da API - Garante compatibilidade com a API v2.3
✅ Validação de Esquemas - Alinhamento de esquemas TypeScript e Zod
✅ Multiplataforma - Testado em Ubuntu, Windows e macOS
✅ Multi-versão - Suporte a Node.js 18.x, 20.x e 22.x
✅ Testes com API Real - Valida contra a API Stampchain v2.3 ao vivo

Comandos Detalhados de Teste

# Run specific test suites
npm run test:unit         # Unit tests for utilities and helpers
npm run test:integration  # Integration tests for MCP server
npm run test:api         # API validation tests (v2.3 compatibility)
npm run test:tools       # Tool functionality tests
npm run test:schemas     # Schema validation tests

# Advanced testing options
npm run test:ui          # Run tests in UI mode (interactive)
npm run test:ci          # CI test run (includes coverage)
npm run validate         # Full validation (schema + typecheck + format + tests)

Fluxo de Trabalho de Desenvolvimento

Instale as dependências: npm install
Inicie o servidor de desenvolvimento: npm run dev
Execute testes em modo de observação: npm run test:watch
Valide antes do commit: npm run validate

Contribuindo

Faça um fork do repositório
Crie um branch de recurso: git checkout -b feature/new-feature
Faça suas alterações
Execute os testes: npm test
Faça o commit das suas alterações: git commit -am 'Add new feature'
Envie para o branch: git push origin feature/new-feature
Envie um pull request

Estilo de Código

Use TypeScript para todo código novo
Siga as diretrizes do modo estrito do TypeScript
Escreva testes para novos recursos
Atualize a documentação conforme necessário
Execute npm run validate antes de enviar PRs

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Suporte

Problemas: GitHub Issues
Documentação: Documentação da API Stampchain
Comunidade: Telegram @BitcoinStamps

Registro de Alterações

v0.2.0

Compatibilidade com Stampchain API v2.3: Esquemas e validação atualizados para a API mais recente
Testes Aprimorados: Suíte de testes abrangente com validação CI multiplataforma
Documentação Melhorada: README profissional com badges de status e melhor organização
Desenvolvimento Simplificado: Pipeline de validação otimizado (TypeScript + Prettier)
Correções de Bugs: Problemas de CI resolvidos e melhorias na validação de esquemas

v0.1.0

Lançamento inicial
Ferramentas básicas de Bitcoin Stamps, Coleções e SRC-20
Integração com cliente MCP
Suíte de testes abrangente

Stampchain MCP Server

Documentação