OSIR Domain Name MCP Server

OSIR Agent Platform

适用于 OSIR 域名注册商的 AI 集成服务。将 Claude、ChatGPT 或任何 AI 助手连接到真实的域名、DNS、VPS、账单和账户操作——既可以使用独立工具（MCP），也可以使用能解决任务的专业 Agent（A2A）。

两个服务，共用一个后端客户端库：

服务	端口	协议	为 AI 提供的能力
MCP Server	8081	Model Context Protocol（SSE + Streamable HTTP）	103 个精细化工具（checkDomainAvailability、registerDomain、createDnsRecord、createMailbox、osirSitePublish 等）+ 11 个引导式提示词
A2A Server	8082	Google Agent-to-Agent（JSON-RPC 2.0）	9 个专业 Agent，具备 89 项技能，并配有一个用于多步骤工作流的编排器

当一个助手需要调用单项操作时，使用 MCP。当你想把完整任务（“为 example.com 配置 DNS 并查询我的余额”）交给协同完成工作的 Agent 时，使用 A2A。

---

什么是 MCP？

MCP（Model Context Protocol）是一种开放标准，可将 AI 助手连接到外部工具和数据。MCP 服务会发布一组可调用的工具；任何 MCP 客户端——Claude Desktop、Cursor、Copilot 或自定义 Agent——都可以发现并调用这些工具。OSIR 实现了专为域名和基础设施管理打造的 MCP 服务，因此它是 AI 原生的域名注册商，而不是在传统注册商上额外加个聊天框。

将 OSIR 连接到 Claude

在 Claude 中，打开 Settings → Connectors → Add custom connector，然后选择以下两种设置之一：

	选项 A：无需登录（推荐）	选项 B：OAuth
服务 URL	https://be.osir.com/mcp/http	https://be.osir.com/mcp/oauth
身份验证	No sign-in	Sign in now
OAuth 客户端	—	Use your own OAuth client，Client ID 为 mcp-client，密钥留空
登录方式	在聊天中登录，每次对话单独进行（见下文）	添加连接器时通过浏览器登录；连接器会保持登录状态

对于选项 B，不要选择“Use Claude's published identity”或“Register automatically”。OSIR 不支持这两种方式。

选项 A：在对话中登录。 助手首次需要调用需身份验证的工具时，会启动设备登录流程：你会收到一个指向 auth.osir.com 的链接和一个短代码，在浏览器中批准后，助手会继续使用仅限于该对话的会话。会话有效期有意设置得较短（不活动约 30 分钟后过期，最长 8 小时），并且你说“log me out”后会立即结束——因此，已连接的聊天不会持续保有对你的域名、服务器和账单的访问权限。

同一个 URL 可用于任何支持远程（streamable HTTP）服务并能在聊天中完成设备登录的 MCP 客户端。

自托管说明： /mcp/oauth 始终要求 OAuth：它会返回带有 RFC 9728 挑战的 401 响应。仅通过 URL 使用的 /mcp/http 需要设置 MCP_OAUTH_CHALLENGE_ENABLED=false。如果保留默认值（true），则所有 MCP 路径都需要 OAuth。会话时长可通过 MCP_SESSION_IDLE_MINUTES 和 MCP_SESSION_MAX_HOURS 调整。

助手可以执行哪些操作

能力	请求示例
查询可用性	“coolstartup.io 可以注册吗？费用是多少？”
注册域名	“注册两年，并启用 WHOIS 隐私保护。”
管理 DNS	“将它指向 192.0.2.10，并添加我的电子邮件记录。”
续费和转移	“续费未来 30 天内到期的所有域名。”
配置 VPS	“在法兰克福启动一台运行 Ubuntu 的 2 vCPU 服务器。”
托管电子邮件	“为 example.com 启用电子邮件，并创建一个 10 GB 邮箱 info@。”

---

自行运行服务

想要托管自己的实例或基于代码进行开发？需要 Java 21；Gradle 已通过 wrapper 打包。

# Run the MCP server (port 8081)
./gradlew :mcp-server:quarkusDev

# Run the A2A server (port 8082)
./gradlew :a2a-server:quarkusDev

将 .env.example 复制为 .env，如果要连接自己的后端/KeyCloak，请进行相应调整。 所有配置默认使用公共 OSIR 端点，因此服务开箱即用。

连接 MCP 客户端（Claude Desktop / Claude Code）

将以下内容添加到客户端的 MCP 配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "osir": { "url": "http://localhost:8081/mcp/sse" }
  }
}

重启客户端后，OSIR 工具就会出现。然后只需询问：

“pizzashqip.al 是否可用？如果不可用，请推荐其他选项。” “列出我的所有域名，并指出哪些将在未来 30 天内到期。” “添加一条指向 203.0.113.10 的 example.al A 记录，以及一条 www 的 CNAME 记录。”

大多数操作都需要身份验证——请让助手“通过设备流程登录 OSIR”，它会引导你完成基于浏览器的 OAuth 流程（KeyCloak，RFC 8628）。

调用 A2A 服务

# Discover the agents
curl http://localhost:8082/.well-known/agents | jq '.[].name'

# Send a task (the platform routes it to the right specialist)
curl -X POST http://localhost:8082/a2a \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -d '{
    "jsonrpc": "2.0", "id": "1", "method": "tasks/send",
    "params": { "message": { "role": "user",
      "parts": [{"type": "text", "text": "Check if example.com is available"}] } }
  }'

任务通过 POST /a2a/stream（SSE）进行流式传输，支持多轮 input-required 流程；编排器会将复杂请求分解给多个 Agent（最多 15 个步骤）。

---

可以做什么

域名 — 可用性、注册、续费、转移、锁定/解锁、自动续费、WHOIS 隐私、名称服务器、AI 驱动的名称建议。 DNS — 列出/创建/更新/删除记录。 VPS — 浏览套餐和位置、下单、管理、面板登录。 账单 — 余额、发票、付款、费用预览、域名定价。 联系人、转移、主机、审计日志、账户资料和摘要。

完整的工具/技能目录、对话示例和端到端演练请参见 GUIDE.md。

工具

106 个工具，已通过实时服务器验证（https://be.osir.com/mcp/http 上的 tools/list）。

• addPrefixToDomain - 通过添加前缀生成域名建议。
• addSshKey - 将 SSH 公钥保存到你的账户中，以便在 VPS 安装时注入。
• addSuffixToDomain - 通过添加后缀生成域名建议。
• buildVpsInstance - 在 VPS 实例上准备操作系统安装。
• bulkDomainSuggestions - 针对一个或多个关键词，从所选 TLD 集合中生成域名建议。
• cancelTransfer - 准备取消待处理的域名转移。
• changeVpsPaymentTerm - 准备更改 VPS 实例的付款期限（计费周期）；使用 executeConfirmedAction 确认。
• checkDeviceLoginStatus - 轮询设备登录是否完成。
• checkDomainAvailability - 检查域名是否可注册及其价格。
• checkHostAvailability - 检查主机／粘合记录名称是否可创建。
• checkKeywordAvailability - 检查关键词在所有受支持的 TLD 和注册局中的可用性，并返回详细结果。
• checkKeywordAvailabilitySummary - 检查关键词可用性汇总统计，不返回详细域名结果（速度更快）。
• countMyVpsInstances - 获取已认证用户拥有的 VPS 实例总数。
• createAccount - 创建新的 OSIR 客户账户。
• createContact - 创建用于域名注册的新联系人。
• createDnsRecord - 为域名创建新的 DNS 记录。
• createHost - 创建新的主机／粘合记录（例如，用于自定义名称服务器）。
• createMailbox - 准备在启用了邮件服务的域名上创建付费邮箱。
• createPaymentSession - 准备创建 Stripe 付款结账会话，以向账户余额充值。
• deleteContact - 准备删除联系人。
• deleteDnsRecord - 准备删除 DNS 记录。
• deleteHost - 准备删除主机／粘合记录。
• deleteMailbox - 准备删除邮箱。
• deleteSshKey - 准备从账户中移除 SSH 密钥；使用 executeConfirmedAction 确认。
• deleteVpsInstance - 准备删除／取消 VPS 实例。
• enableMailDomain - 在你拥有的域名上启用邮件托管。
• executeConfirmedAction - 在用户批准后，执行之前准备的破坏性操作或财务操作。
• fundBalanceWithSharedPaymentToken - 准备通过向客户授权给 OSIR 的 Stripe Shared Payment Token 收费，为余额充值，让 Agent 无需将任何人带到结账页面即可为购买付款。
• generateDomainSuggestions - 根据关键词生成域名建议。
• getAccountBalance - 获取已认证用户当前的账户余额。
• getAccountSummary - 获取用户账户的综合摘要：个人资料、余额、域名数量、VPS 数量和待处理的转移。
• getAuthStatus - 检查当前会话是否已通过身份验证。
• getContact - 获取特定联系人的详细信息。
• getContactsForDomain - 获取分配给某个域名的所有联系人（注册人、管理员、技术联系人、账单联系人）。
• getDedicatedServerCatalog - 获取所有可用的独立服务器配置及其价格和规格。
• getDnsRecord - 获取特定 DNS 记录的详细信息。
• getDomainAuditTrail - 获取特定域名的审计记录（所有变更的历史记录）。
• getDomainExtensions - 获取所有可用的域名扩展名（TLD）及价格信息。
• getDomainInfo - 获取域名的详细信息，包括到期日期、名称服务器和状态。
• getDomainPricing - 从产品目录中获取域名扩展名的价格。
• getHostingBundle - 获取特定域名的托管选项和确切价格：推荐的 VPS 套餐（按价格从低到高排列）、邮件方案、网页转发以及应用／网站部署（构建免费；上线需运行于 VPS）。
• getHostsForDomain - 列出与某个域名关联的所有主机／粘合记录。
• getInvoiceDetails - 获取特定发票的详细信息，包括明细项。
• getInvoiceStatistics - 获取发票汇总统计：已付、待付和逾期金额。
• getMailboxQuote - 获取仅供展示的邮箱方案价格报价。
• getMailboxUsage - 获取每个邮箱的磁盘用量（以字节为单位），以便与方案的 quotaBytes 一同显示配额。
• getMailDnsRecords - 获取邮件域名所需的 DNS 记录（MX、SPF、DKIM 等）——适用于通过外部服务管理 DNS 的客户。
• getMyAuditLogs - 获取已认证用户在所有服务中的近期审计日志。
• getMyProfile - 获取已认证用户的个人资料和账户信息，包括姓名、电子邮件、组织、余额以及域名／VPS 数量。
• getPaymentTransactions - 获取已认证用户的付款交易历史记录。
• getProductCatalog - 获取完整的产品目录，包括域名扩展名、VPS 套餐和独立服务器。
• getRecentActivity - 获取用户所有域名和服务的最新活动。
• getTransferQuote - 获取域名转移的价格报价。
• getTransferStatus - 检查域名转移的当前状态。
• getVpsInstanceDetails - 获取特定 VPS 实例的详细信息，包括资源用量。
• getVpsPackageDetails - 获取特定 VPS 套餐的详细信息，包括所有价格层级。
• initializeDnsZone - 初始化（创建）域名的 DNS 区域。
• initiateTransfer - 准备从其他注册商发起域名转移。
• listCategorizedTlds - 列出 OSIR 目录中已填写类别和受众元数据的 TLD。
• listContacts - 列出已认证用户的所有联系人，可选搜索。
• listDnsRecords - 列出域名的所有 DNS 记录。
• listInvoices - 列出已认证用户的发票，可按状态筛选并分页。
• listMailboxes - 列出你的邮箱及其方案、付款期限、状态和下次续费日期。
• listMailDomains - 列出已启用邮件托管的域名，以及其状态（PENDING_DNS 或 ACTIVE）和 DNS 模式。
• listMailPlans - 列出可用的电子邮件邮箱方案及其配额和价格（按月和按年计价，单位为美分）。
• listMySshKeys - 列出账户中保存的 SSH 密钥及其 ID 和 SHA256 指纹。
• listMyVpsInstances - 列出已认证用户拥有的所有 VPS 实例。
• listPendingTransfers - 列出所有待处理的入站（接收）域名转移。
• listUserDomains - 列出已认证用户拥有的所有域名。
• listVpsLocations - 列出可用的 VPS 托管位置（城市／国家）及可用套餐。
• listVpsOsTemplates - 列出可供安装的操作系统模板。
• listVpsPackages - 列出可用的 VPS 托管套餐及其价格、规格和位置。
• lockDomain - 为域名启用注册商锁，防止未经授权的转移。
• loginToVpsPanel - 生成一次性登录 URL，以便登录 VPS 控制面板（VirtFusion）管理服务器。
• loginWithDevice - 启动设备授权登录（RFC 8628）。
• logout - 登出：立即撤销身份提供商处的会话令牌。
• orderVps - 准备订购新的 VPS 实例。
• osirAppCreateUpload - 创建上传凭证，以便将应用源代码部署到 Osir。
• osirAppDelete - 准备删除 Osir 应用。
• osirAppDeploy - 将应用部署到 Osir（免费层级）并获取可访问的 HTTPS URL；应用在隔离的 microVM 中运行。将应用迁移到用户自己的 VPS 后，重新部署会在该 VPS 上更新应用并保留其域名。
• osirAppGetSource - 获取 Osir 应用当前源代码 zip 文件的短期签名下载 URL——可用此功能编辑已部署的应用，无需用户重新附加项目：下载并修改文件，然后调用 osirAppCreateUpload（PUT 新 zip 文件）和 osirAppDeploy，并使用相同的名称；平台会重新构建，并为自有层级的应用自动将新版本部署到用户的服务器。
• osirAppList - 列出已认证用户部署的 Osir 应用及其可访问 URL 和状态。
• osirAppLogs - 获取 Osir 应用 microVM 的近期日志（“我的应用为什么无法运行？”）。
• osirAppDeployToVps - 将运行中的 Osir 应用部署到用户拥有的 VPS，迁出共享免费层级：附加已有 VPS（instanceId，不产生费用）或订购新的 VPS（packageId，受限）。平台通过自身的部署密钥部署应用——无需 SSH，也无需安装脚本。
• osirAppProvisionDatabase - 为 Osir 应用配置托管 Postgres 数据库。
• osirAppSetSecret - 为 Osir 应用设置环境密钥（例如
• osirAppStatus - 获取 Osir 应用的当前状态、可访问 URL 和运行状况（“我的应用能正常运行吗？”）。
• osirSiteDesignBrief - 使用 OSIR 设计网站的第 1 步。
• osirSitePublish - 将单页网站发布到 Osir 上可访问的 HTTPS URL（免费层级）——任何完整的 HTML 文档均可：用户自己的网站、本次聊天中设计的页面，或通过 osirSiteDesignBrief 流程生成的页面。将网站迁移到用户自己的 VPS 后，重新发布会在该 VPS 上更新网站。
• payInvoice - 准备使用账户余额支付未结清的发票。
• previewPaymentFees - 预览指定付款金额将产生的费用。
• registerDomain - 准备注册新的域名。
• renewDomain - 准备续费指定年数的域名。
• setMailboxPassword - 为邮箱设置新密码。
• spinDomainWords - 通过替换／变换词语生成域名建议。
• suggestAlternatives - 请求的域名不可用时，建议替代域名（旧版方法）。
• transferDomain - 准备将域名从其他注册商转移到 OSIR。
• unlockDomain - 准备移除域名的注册商锁，以允许转移。
• updateContact - 更新现有联系人的信息。
• updateDnsRecord - 更新现有 DNS 记录。
• updateDomainAutoRenew - 为域名启用或停用自动续费。
• updateDomainPrivacy - 为域名启用或停用 WHOIS 隐私保护。
• updateNameservers - 更新域名的名称服务器。
• validateDomainName - 验证域名格式是否正确。
• verifyAccount - 使用验证邮件中的代码验证新创建的 OSIR 账户——入门流程的第 2 步，无需身份验证。
• verifyMailDns - 检查邮件域名的 DNS 记录是否解析成功；找到所有记录后，会激活该域名的邮件服务。

---

构建、测试、部署

./gradlew build        # build all modules + run tests
./gradlew test         # tests only

docker-compose up -d   # run both servers in containers

提供的 docker-compose.yml、build-and-deploy.bat 和 CI 工作流引用了一个占位容器注册表（registry.example.com）——请将它们指向你自己的注册表。 生产环境检查清单（PostgreSQL、TLS、扩缩容）请参阅 DEPLOYMENT.md。

配置

所有设置均为环境变量，并设有合理的默认值——不会提交任何机密信息。

变量	默认值	描述
OSIR_BACKEND_URL	https://be.osir.com	后端 API
KEYCLOAK_URL	https://auth.osir.com	KeyCloak 身份验证服务
KEYCLOAK_REALM	osir	KeyCloak Realm
KEYCLOAK_CLIENT_ID	osir-cli	OAuth 客户端 ID
CORS_ORIGINS	https://osir.com,…	允许的 CORS 来源
A2A_SIGNING_SECRET	(empty)	可选的 HMAC-SHA256 请求签名
SENTRY_DSN	(empty)	可选的崩溃报告，发送到 Sentry 协议端点（GlitchTip）；为空 = 关闭
SENTRY_ENVIRONMENT	production	已报告事件的环境标签

完整列表请参阅 .env.example。

项目布局

common/      Shared library — 12 services, 9 REST clients, ~174 models
mcp-server/  Quarkus MCP server — 106 tools, 11 prompts, 2 resources
a2a-server/  Quarkus A2A server — 9 agents, 89 skills, JSON-RPC, JPA task persistence

两个服务端都依赖于 common，因此后端操作只需实现一次，即可通过两种方式提供。

文档

• GUIDE.md — 完整使用指南、工具参考和演练
• WEBSITE-DESIGN.md — AI 网站设计：客户指南、用例、前端集成
• DEVELOPING.md — 仓库布局、构建和运行命令、架构说明
• VPS-OS-BUILD.md — 订购带操作系统的 VPS、SSH 密钥、重装以及 OSIR APP DEPLOY 流程。操作 VPS 工具前请先阅读：订购和构建是 VirtFusion 中两个独立的步骤，而 orderVps 单独执行时只会交付一台未安装操作系统的服务器。
• A2A-API-REFERENCE.md — A2A 协议规范（方法、错误、Agent）
• A2A-ARCHITECTURE.md — A2A 设计文档
• A2A-CONFIRMATION-GATE-SPEC.md — 通过 executeConfirmedAction 将破坏性操作置于暂存阶段
• DEPLOYMENT.md — 生产环境部署检查清单

许可证

Apache License 2.0。