Spaceship Mcp

spaceship-mcp

由社区构建的 Model Context Protocol（MCP）服务，用于调用 Spaceship API。通过任何兼容 MCP 的 AI 客户端，以自然语言管理域名、DNS 记录、联系人、市场列表等。

注意： 这是一个非官方、由社区维护的项目，与 Spaceship 无关联，也未获其认可。

添加到编辑器

CLI 单行命令——最快的入门方式。选择你的工具：

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

通过 ~/.gemini/settings.json 分别设置环境变量 SPACESHIP_API_KEY 和 SPACESHIP_API_SECRET。

VS Code（Copilot）

打开命令面板（Cmd+Shift+P / Ctrl+Shift+P）> MCP: Add Server > 选择 Command (stdio)。

也可以在项目目录下的 .vscode/mcp.json 中添加：

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

Cursor

添加到 .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）：

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

支持的客户端

此 MCP 服务适用于任何支持 Model Context Protocol 的客户端，包括：

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

• 48 个工具，分为 8 个类别，涵盖完整的 Spaceship API
• 13 种 DNS 记录类型，提供专用的类型安全创建工具（A、AAAA、ALIAS、CAA、CNAME、HTTPS、MX、NS、PTR、SRV、SVCB、TLSA、TXT）
• 完整的域名生命周期管理——注册、续费、转移和恢复域名
• SellerHub 集成——列出待售域名并生成结账链接
• DNS 对齐分析——比较预期记录与实际记录，以发现配置错误
• WHOIS 隐私和联系人管理，支持特定 TLD 的属性
• 通过每个工具上的 Zod 架构验证输入和输出，确保操作安全且可预测
• 5 个 MCP 资源，用于被动加载上下文（域名列表、域名详情、DNS 记录、联系人、SellerHub）
• 9 个 MCP 提示词——5 个引导式工作流，以及 4 个支持参数自动补全的提示词
• 资源订阅，通过轮询检测变更并自动发送通知
• 响应缓存，支持配置 TTL，并在写入时自动失效
• 速率限制处理，支持指数退避和 Retry-After 标头
• 工具集筛选，仅公开所需的工具类别
• 动态工具加载模式，适用于上下文窗口受限的 Agent
• 可操作的错误消息，提供结合上下文的恢复建议
• 支持 Docker，可进行容器化部署
• 453 个单元测试，覆盖率接近完整

配置

必填项

在 Spaceship API Manager 中生成凭据。

可选项

API 密钥设置

创建 API 密钥

1. 登录你的 Spaceship 账户
2. 前往 API Manager（直接链接）
3. 点击 New API key
4. 为密钥设置一个描述性名称（例如，“MCP Server”）
5. 选择所需的权限范围（见下文）
6. 复制 API 密钥和 API 密钥密文——密钥密文只会显示一次

可用权限范围

每个权限范围控制对 Spaceship API 特定部分的访问。创建密钥时，只启用所需的权限范围。

各功能所需的权限范围

下表显示了每组工具所需的权限范围。

推荐的权限范围预设

完全访问 — 启用所有权限，实现不受限制的使用：

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

仅管理 DNS — 仅读写 DNS 记录：

dnsrecords:read  dnsrecords:write

只读 — 浏览域名和记录，但不进行任何更改：

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

可用工具

DNS 记录

按类型创建记录

每种 DNS 记录类型都有专用工具，并提供类型安全的参数和验证。

域名管理

域名生命周期

联系人和隐私

个人名称服务器

SellerHub

分析

MCP 资源

资源提供被动上下文，客户端无需调用工具即可加载。

支持资源订阅的客户端会在数据发生变化时收到自动通知（每 30 秒轮询一次）。

MCP 提示词

提示词提供引导式工作流，客户端可将其作为斜杠命令或快捷操作呈现。

引导式工作流

自动补全提示词

这些提示词支持为域名和常用值自动补全参数：

工具集筛选

仅启用所需的工具类别，以减少上下文窗口占用。将 SPACESHIP_TOOLSETS 环境变量设为以逗号分隔的列表：

SPACESHIP_TOOLSETS=dns,domains

未设置时，将启用所有工具集。无效名称会被忽略；如果所有名称都无效，则会启用所有工具集作为回退方案。

动态工具加载

对于上下文窗口受限的 Agent，动态模式会将全部 48 个工具替换为 3 个轻量级元工具：

SPACESHIP_DYNAMIC_TOOLS=true

工作流：

1. search_tools({ query: "dns" }) — 查找相关工具
2. describe_tools({ tools: ["create_a_record"] }) — 获取完整参数架构
3. execute_tool({ tool: "create_a_record", arguments: { ... } }) — 执行

在动态模式下，资源、提示词和补全功能仍可用。

安全说明

• 信任模型： 任何获准调用此 MCP 服务的提示词或 Agent，都可以使用已配置的凭据执行 Spaceship API 操作。
• 最小权限凭据： 按环境／团队／用例使用独立的 Spaceship API 密钥，并仅启用所需的权限范围（参见可用权限范围）。
• 写入操作审批： 为会修改数据的工具启用主机端审批（register_domain、create_*、update_*、delete_*、save_*、set_* 和生命周期操作）。
• 团队配置治理： 将共享的 MCP 配置纳入版本控制；对命令、参数、环境变量和工具集筛选的变更要求审核；将机密信息保存在保险库或主机的密钥管理器中（不要存放在纯文本仓库文件中）。

使用示例

连接后，你可以使用自然语言与 Spaceship API 交互：

• “列出我的所有域名”
• “检查 example.com 是否可以注册”
• “为 api.example.com 创建一条指向 203.0.113.10 的 A 记录”
• “为 example.com 设置使用 Google Workspace 的 MX 记录”
• “为 example.com 启用 WHOIS 隐私保护”
• “检查 example.com 的 DNS 记录是否符合预期”
• “列出我在 SellerHub 上出售的域名”
• “将 example.com 转移到 Spaceship”

社区

• 支持：SUPPORT.md
• 安全问题报告：SECURITY.md
• 贡献指南：CONTRIBUTING.md
• Bug 报告和功能请求：Issues

开发

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build for production
pnpm build

# Run tests
pnpm test

# Type check
pnpm typecheck

项目结构

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

要求

• Node.js >= 20
• 拥有 Spaceship 账户和 API 凭据

许可证

MIT - 详情请参阅 LICENSE。