Spaceship MCP

spaceship-mcp

Um servidor Model Context Protocol (MCP) construído pela comunidade para a API do Spaceship. Gerencie domínios, registros DNS, contatos, anúncios no marketplace e muito mais — tudo por meio de linguagem natural através de qualquer cliente de IA compatível com MCP.

Nota: Este é um projeto não oficial, mantido pela comunidade, e não é afiliado ou endossado pela Spaceship.

Adicionar ao Seu Editor

Comandos de uma linha — a forma mais rápida de começar. Escolha sua ferramenta:

Claude Code

claude mcp add --scope user spaceship-mcp \
  --env SPACESHIP_API_KEY=your-key \
  --env SPACESHIP_API_SECRET=your-secret \
  -- npx -y spaceship-mcp

Codex CLI (OpenAI)

codex mcp add spaceship-mcp \
  --env SPACESHIP_API_KEY=your-key \
  --env SPACESHIP_API_SECRET=your-secret \
  -- npx -y spaceship-mcp

Gemini CLI (Google)

gemini mcp add spaceship-mcp -- npx -y spaceship-mcp

Defina as variáveis de ambiente SPACESHIP_API_KEY e SPACESHIP_API_SECRET separadamente via ~/.gemini/settings.json.

VS Code (Copilot)

Abra a Paleta de Comandos (Cmd+Shift+P / Ctrl+Shift+P) > MCP: Add Server > selecione Command (stdio).

Ou adicione ao .vscode/mcp.json no diretório do seu projeto:

{
  "servers": {
    "spaceship-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

Cursor

Adicione ao .cursor/mcp.json (nível do projeto) ou ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "spaceship-mcp": {
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

Clientes Suportados

Este servidor MCP funciona com qualquer cliente que suporte o Model Context Protocol, incluindo:

{
  "mcpServers": {
    "spaceship-mcp": {
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

{
  "mcpServers": {
    "spaceship-mcp": {
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

{
  "context_servers": {
    "spaceship-mcp": {
      "command": "npx",
      "args": ["-y", "spaceship-mcp"],
      "env": {
        "SPACESHIP_API_KEY": "your-key",
        "SPACESHIP_API_SECRET": "your-secret"
      }
    }
  }
}

docker run -i --rm \
  -e SPACESHIP_API_KEY=your-key \
  -e SPACESHIP_API_SECRET=your-secret \
  ghcr.io/bartwaardenburg/spaceship-mcp

[mcp_servers.spaceship-mcp]
command = "npx"
args = ["-y", "spaceship-mcp"]
env = { "SPACESHIP_API_KEY" = "your-key", "SPACESHIP_API_SECRET" = "your-secret" }

Recursos

• 48 ferramentas em 8 categorias cobrindo toda a API do Spaceship
• 13 tipos de registros DNS com ferramentas de criação dedicadas e type-safe (A, AAAA, ALIAS, CAA, CNAME, HTTPS, MX, NS, PTR, SRV, SVCB, TLSA, TXT)
• Ciclo de vida completo do domínio — registrar, renovar, transferir e restaurar domínios
• Integração com SellerHub — listar domínios para venda e gerar links de checkout
• Análise de alinhamento DNS — comparar registros esperados vs. reais para detectar configurações incorretas
• Privacidade WHOIS e gerenciamento de contatos com suporte a atributos específicos por TLD
• Validação de entrada e saída via esquemas Zod em todas as ferramentas para operações seguras e previsíveis
• 5 Recursos MCP para carregamento passivo de contexto (lista de domínios, detalhes do domínio, registros DNS, contatos, SellerHub)
• 9 Prompts MCP — 5 fluxos de trabalho guiados e 4 com preenchimento automático de argumentos
• Assinaturas de recursos com detecção de alterações baseada em polling e notificações automáticas
• Cache de respostas com TTL configurável e invalidação automática em gravações
• Tratamento de limite de taxa com backoff exponencial e suporte ao cabeçalho Retry-After
• Filtragem de conjuntos de ferramentas para expor apenas as categorias de ferramentas que você precisa
• Modo de carregamento dinâmico de ferramentas para agentes com janelas de contexto limitadas
• Mensagens de erro acionáveis com sugestões de recuperação sensíveis ao contexto
• Suporte a Docker para implantação em contêineres
• 453 testes unitários com cobertura quase completa

Configuração

Obrigatório

Gere suas credenciais no Gerenciador de API do Spaceship.

Opcional

Configuração da Chave de API

Criando Sua Chave de API

1. Faça login na sua conta Spaceship
2. Navegue até o Gerenciador de API (link direto)
3. Clique em Nova chave de API
4. Dê um nome descritivo à chave (ex.: "Servidor MCP")
5. Selecione os escopos que você precisa (veja abaixo)
6. Copie tanto a chave de API quanto o segredo de API — o segredo é mostrado apenas uma vez

Escopos Disponíveis

Cada escopo controla o acesso a uma parte específica da API do Spaceship. Ao criar sua chave, habilite apenas os escopos que você precisa.

Escopos por Recurso

A tabela abaixo mostra quais escopos são necessários para cada grupo de ferramentas.

Presets de Escopo Recomendados

Acesso total — habilite tudo para uso irrestrito:

domains:read  domains:write  domains:billing  domains:transfer
contacts:read  contacts:write
dnsrecords:read  dnsrecords:write
sellerhub:read  sellerhub:write
asyncoperations:read

Somente gerenciamento de DNS — apenas leitura/gravação de registros DNS:

dnsrecords:read  dnsrecords:write

Somente leitura — navegue por domínios e registros sem fazer alterações:

domains:read  contacts:read  dnsrecords:read  sellerhub:read  asyncoperations:read

Ferramentas Disponíveis

Registros DNS

Criação de Registros Específicos por Tipo

Cada tipo de registro DNS possui uma ferramenta dedicada com parâmetros type-safe e validação.

Gerenciamento de Domínios

Ciclo de Vida do Domínio

Contatos e Privacidade

Nameservers Pessoais

SellerHub

Análise

Recursos MCP

Recursos fornecem contexto passivo que os clientes podem carregar sem chamar ferramentas.

Clientes que suportam assinaturas de recursos receberão notificações automáticas quando os dados mudarem (verificação a cada 30 segundos).

Prompts MCP

Prompts fornecem fluxos de trabalho guiados que os clientes podem apresentar como comandos de barra ou ações rápidas.

Fluxos de Trabalho Guiados

Prompts de Auto-Completar

Estes prompts suportam auto-completar de argumentos para nomes de domínio e valores comuns:

Filtragem de Conjuntos de Ferramentas

Reduza o uso da janela de contexto habilitando apenas as categorias de ferramentas necessárias. Defina a variável de ambiente SPACESHIP_TOOLSETS como uma lista separada por vírgulas:

SPACESHIP_TOOLSETS=dns,domains

Quando não definido, todos os conjuntos de ferramentas são habilitados. Nomes inválidos são ignorados; se todos os nomes forem inválidos, todos os conjuntos de ferramentas são habilitados como fallback.

Carregamento Dinâmico de Ferramentas

Para agentes com janelas de contexto limitadas, o modo dinâmico substitui todas as 48 ferramentas por 3 meta-ferramentas leves:

SPACESHIP_DYNAMIC_TOOLS=true

Fluxo de trabalho:

1. search_tools({ query: "dns" }) — descobrir ferramentas relevantes
2. describe_tools({ tools: ["create_a_record"] }) — obter o esquema completo de parâmetros
3. execute_tool({ tool: "create_a_record", arguments: { ... } }) — executar

Recursos, prompts e complementos permanecem disponíveis no modo dinâmico.

Notas de Segurança

• Modelo de confiança: Qualquer prompt ou agente autorizado a chamar este servidor MCP pode executar ações da API Spaceship com as credenciais configuradas.
• Credenciais de privilégio mínimo: Use chaves de API Spaceship separadas por ambiente/equipe/caso de uso e habilite apenas os escopos necessários (veja Escopos disponíveis).
• Aprovações para ações de escrita: Habilite aprovações no host para ferramentas de mutação (register_domain, create_*, update_*, delete_*, save_*, set_* e operações de ciclo de vida).
• Governança de configuração da equipe: Mantenha a configuração MCP compartilhada em controle de versão, exija revisão para alterações em comando/args/env/filtragem de conjuntos de ferramentas e mantenha segredos em um cofre ou gerenciador de segredos do host (não em arquivos de texto simples no repositório).

Exemplo de Uso

Uma vez conectado, você pode interagir com a API Spaceship usando linguagem natural:

• "Listar todos os meus domínios"
• "Verificar se example.com está disponível para registro"
• "Criar um registro A para api.example.com apontando para 203.0.113.10"
• "Configurar registros MX para example.com usando Google Workspace"
• "Ativar privacidade WHOIS em example.com"
• "Verificar se meus registros DNS para example.com correspondem ao esperado"
• "Listar meus domínios à venda no SellerHub"
• "Transferir example.com para a Spaceship"

Comunidade

• Suporte: SUPPORT.md
• Relato de segurança: SECURITY.md
• Diretrizes de contribuição: CONTRIBUTING.md
• Relatos de bugs e solicitações de recursos: Issues

Desenvolvimento

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

Estrutura do Projeto

src/
  index.ts                    # Entry point (stdio transport)
  server.ts                   # MCP server setup, toolset filtering, feature registration
  spaceship-client.ts         # Spaceship API HTTP client with caching and retry
  cache.ts                    # TTL-based in-memory response cache
  schemas.ts                  # Shared Zod validation schemas
  output-schemas.ts           # Zod output schemas for all 48 tools
  types.ts                    # TypeScript interfaces
  tool-result.ts              # Error formatting with recovery suggestions
  resources.ts                # MCP Resources (5 resources)
  resource-subscriptions.ts   # Polling-based resource change notifications
  prompts.ts                  # MCP Prompts (5 guided workflows)
  completions.ts              # MCP Prompts with argument auto-complete (4 prompts)
  dynamic-tools.ts            # Dynamic tool loading meta-tools
  dns-utils.ts                # DNS record formatting utilities
  update-checker.ts           # NPM update notifications
  tools/
    dns-records.ts            # List, save, delete DNS records
    dns-record-creators.ts    # 13 type-specific DNS record creation tools
    domain-management.ts      # Domain listing, settings, nameservers
    domain-lifecycle.ts       # Registration, renewal, transfer, restore
    contacts-privacy.ts       # Contact profiles and WHOIS privacy
    personal-nameservers.ts   # Vanity/glue nameserver management
    sellerhub.ts              # Marketplace listing and checkout tools
    analysis.ts               # DNS alignment analysis

Requisitos

• Node.js >= 20
• Uma conta Spaceship com credenciais de API

Licença

MIT - veja LICENSE para detalhes.