Hope Domain MCP Server

一个模型上下文协议（MCP）服务器，提供 Hope Domain API 服务，包括域名 WHOIS 查询和 AI 驱动的域名推荐。

✨ 特性

🔍 域名 WHOIS 查询

• 单个域名 WHOIS 查询（免费）
• 批量域名 WHOIS 查询（最多1000个域名，≤50个免费）

🤖 AI 域名推荐

• 基于项目描述的 AI 驱动域名建议
• 每次请求生成1-50个域名推荐

💰 积分管理

• 查看当前积分余额和账户状态
• 追踪使用情况和充值历史

🚀 完全无警告

• 使用 Node.js 原生 fetch API
• 零依赖警告，清洁的安装体验

📦 安装方式

⚡ 方式一：一键安装（Cursor 用户推荐）

🎯 特点：

• ⚡ 零配置 - 点击即用，无需手动设置
• 🔄 自动更新 - 始终使用最新版本
• 🚀 即时部署 - 无需本地安装
• ✨ 完全无警告 - 清洁的运行环境

⚙️ 方式二：标准配置（通用）

NPX 方式（推荐）

{
  "mcpServers": {
    "hopedomain-mcp": {
      "command": "npx",
      "args": ["hopedomain-mcp@latest"],
      "env": {
        "HOPE_DOMAIN_API_KEY": "sk-your_api_key_here"
      }
    }
  }
}

🎯 特点：

• 📦 无需安装 - 通过 npx 直接运行
• 🔄 自动更新 - @latest 确保最新版本
• 🌐 跨平台兼容 - 支持所有 MCP 客户端
• ⚡ 轻量快速 - 仅需 API 密钥配置
• ✨ 零警告输出 - 完全清洁的运行体验

本地开发安装

1. Clone the repository:

   git clone https://github.com/HopeDomain/whois-mcp.git
   cd whois-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

📁 配置文件模板

我们提供了多种预配置模板，位于 configs/ 目录：

• 📄 configs/claude-desktop.json - Claude Desktop 标准配置
• 📄 configs/cursor-mcp.json - Cursor MCP 配置
• 📄 configs/local-dev.json - 本地开发配置

直接复制相应的配置到您的 MCP 客户端配置文件中即可！

🚀 快速开始

🎯 第一步：选择安装方式

• Cursor 用户 → 点击一键安装按钮 ⚡
• 其他用户 → 使用 NPX 标准配置 ⚙️

🔑 第二步：获取 API 密钥

1. 访问 Hope Domain 官网 注册/登录
2. 进入控制台 → API Keys 页面
3. 点击 "Create API Key" 按钮
4. 复制生成的 API 密钥（格式：sk-xxxxxxxxxx）

⚙️ 第三步：配置 API 密钥

环境变量方式：

export HOPE_DOMAIN_API_KEY="sk-your_actual_api_key_here"

或在配置文件中直接设置：

{
  "env": {
    "HOPE_DOMAIN_API_KEY": "sk-your_actual_api_key_here"
  }
}

✨ 第四步：开始使用！

现在您可以使用以下强大工具：

• 🔍 whois_single - 单个域名 WHOIS 查询
• 📊 whois_batch - 批量域名查询（最多1000个）
• 🤖 ai_domain_recommend - AI 域名推荐
• 💰 get_user_credits - 账户积分查询

⚙️ 配置指南

🔐 环境变量配置

方式一：系统环境变量

export HOPE_DOMAIN_API_KEY="sk-your_actual_api_key_here"
export HOPE_DOMAIN_BASE_URL="https://hopedomain.com/api"  # 可选，默认为生产环境 API

方式二：项目 .env 文件

HOPE_DOMAIN_API_KEY=sk-your_actual_api_key_here
HOPE_DOMAIN_BASE_URL=https://hopedomain.com/api

📋 不同客户端配置示例

Claude Desktop

📁 配置文件： ~/.config/claude/claude_desktop_config.json (Linux/Mac)
📁 配置文件： %APPDATA%\Claude\claude_desktop_config.json (Windows)

{
  "mcpServers": {
    "hopedomain-mcp": {
      "command": "npx",
      "args": ["hopedomain-mcp@latest"],
      "env": {
        "HOPE_DOMAIN_API_KEY": "sk-your_actual_api_key_here"
      }
    }
  }
}

Cursor IDE

📁 配置位置： 设置 → Extensions → MCP

{
  "mcpServers": {
    "hopedomain-mcp": {
      "command": "npx",
      "args": ["hopedomain-mcp@latest"],
      "env": {
        "HOPE_DOMAIN_API_KEY": "${HOPE_DOMAIN_API_KEY}"
      }
    }
  }
}

本地开发

适用场景： 源码开发、调试、自定义修改

{
  "mcpServers": {
    "hopedomain-mcp": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/whois-mcp",
      "env": {
        "HOPE_DOMAIN_API_KEY": "sk-your_actual_api_key_here",
        "HOPE_DOMAIN_BASE_URL": "https://hopedomain.com/api"
      }
    }
  }
}

🛠️ 可用工具

🔍 whois_single - 单域名查询

快速查询单个域名的完整 WHOIS 信息。

📥 输入参数：

• domain (string, 必需): 要查询的域名

💡 使用示例：

{
  "domain": "example.com"
}

💰 积分消耗： 免费 ✅

📊 whois_batch - 批量域名查询

一次性查询多个域名的 WHOIS 信息，效率更高。

📥 输入参数：

• domains (array, 必需): 域名数组 (1-1000个)
• format (string, 可选): 返回格式，默认 "json"

💡 使用示例：

{
  "domains": ["google.com", "facebook.com", "twitter.com"],
  "format": "json"
}

💰 积分消耗：

• ✅ ≤50 域名： 免费
• 💎 >50 域名： 1积分（需要 API 密钥）

🤖 ai_domain_recommend - AI 域名推荐

基于项目描述，使用 AI 生成创意域名建议。

📥 输入参数：

• description (string, 必需): 项目或服务描述
• count (number, 可选): 推荐数量 (1-50)，默认 20

💡 使用示例：

{
  "description": "面向开发者的在线代码编辑器",
  "count": 10
}

💰 积分消耗： 1积分（需要 API 密钥）

💰 get_user_credits - 账户积分查询

查看当前账户的积分余额和使用状态。

📥 输入参数： 无

💡 使用示例：

{}

💰 积分消耗： 免费 ✅（需要 API 密钥）

💎 积分系统

🎁 新用户福利

• 注册即送 100 免费积分
• 无需付费即可体验所有功能

💰 积分消耗规则

| 操作类型 | 积分消耗 | 说明 | |---------|---------|------| | 🔍 单域名查询 | 免费 | 无限制使用 | | 📊 批量查询 (≤50) | 免费 | 日常使用足够 | | 📊 批量查询 (>50) | 1积分 | 大批量处理 | | 🤖 AI 域名推荐 | 1积分 | 智能创意生成 | | 💰 积分余额查询 | 免费 | 随时查看状态 |

🔄 积分充值

访问 Hope Domain 控制台 进行积分充值。

👨‍💻 开发指南

📁 项目结构

whois-mcp/
├── 📂 src/
│   └── 📄 index.ts          # MCP 服务器主要实现
├── 📂 dist/                 # TypeScript 编译输出
├── 📂 configs/              # 配置文件模板
│   ├── 📄 claude-desktop.json
│   ├── 📄 cursor-mcp.json
│   └── 📄 local-dev.json
├── 📄 package.json          # 项目依赖和脚本
├── 📄 tsconfig.json         # TypeScript 配置
├── 📄 manifest.json         # DXT 扩展清单
└── 📄 README.md            # 项目文档

🛠️ 开发脚本

# 🔨 编译 TypeScript 到 JavaScript
npm run build

# 👀 监控模式编译（开发时使用）
npm run dev  

# 🚀 启动 MCP 服务器
npm start

# 📦 发布前准备
npm run prepare

🏗️ 从源码构建

# 1️⃣ 安装依赖
npm install

# 2️⃣ 构建项目
npm run build

# 3️⃣ 运行服务器
npm start

🧪 本地测试

# 构建并运行
npm run build && npm start

# 或使用开发模式
npm run dev

💡 使用场景示例

🔍 域名研究

// 检查多个域名的可用性
{
  "tool": "whois_batch",
  "params": {
    "domains": ["myapp.com", "myapp.io", "myapp.dev"]
  }
}

🎨 品牌域名发现

// 为金融科技初创公司获取 AI 推荐
{
  "tool": "ai_domain_recommend", 
  "params": {
    "description": "面向小企业的移动支付应用",
    "count": 15
  }
}

📊 竞争对手域名分析

// 分析竞争对手域名信息
{
  "tool": "whois_batch",
  "params": {
    "domains": ["competitor1.com", "competitor2.com", "competitor3.com"]
  }
}

💰 积分监控

// 在执行付费操作前检查剩余积分
{
  "tool": "get_user_credits",
  "params": {}
}

🚨 常见问题解决

❌ 常见错误

| 错误类型 | 原因 | 解决方案 | |---------|-----|---------| | 🔑 API密钥错误 | 密钥未设置或无效 | 检查环境变量，确保密钥以 sk- 开头 | | 🌐 网络连接错误 | 网络问题或服务暂时不可用 | 检查网络连接，稍后重试 |
| 💳 积分不足 | 账户积分余额不够 | 使用 get_user_credits 查询余额 | | ⚡ 构建错误 | Node.js版本或依赖问题 | 确保 Node.js ≥18.0.0，运行 npm install |

🐛 调试模式

启用详细日志输出：

export DEBUG=hope-domain-mcp-server
npm start

⏱️ API 频率限制

为确保服务稳定性：

• 🔍 单域名查询: 100 次/分钟
• 📊 批量查询: 10 次/分钟
• 🤖 AI推荐: 5 次/分钟

🤝 贡献指南

1. 🍴 Fork 项目仓库
2. 🌿 创建功能分支
3. ✨ 添加您的改进
4. 🧪 添加必要的测试
5. 📤 提交 Pull Request

📄 许可证

MIT 许可证 - 详见 LICENSE 文件

🆘 获取帮助

| 渠道 | 链接 | 说明 | |-----|------|-----| | 📧 邮件支持 | [email protected] | 技术问题咨询 | | 🌐 官方网站 | hopedomain.com | 产品介绍和注册 | | 📖 API文档 | API 文档 | 详细接口说明 | | 🐛 问题反馈 | GitHub Issues | Bug报告和功能请求 | | 📦 NPM 包 | NPM | 包信息和版本历史 |

📝 更新日志

🆕 v1.0.3 (最新版)

• ✅ 修复 deprecation 警告
• ⚡ 使用 Node.js 原生 fetch API
• 📦 减少包大小和依赖项
• 🔧 改进构建脚本和权限处理

📋 v1.0.0

• 🎉 首次发布
• 🛠️ 支持所有 Hope Domain API 端点
• 📡 完整 MCP 协议兼容
• 🛡️ 全面错误处理
• 💰 积分系统集成

🚀 立即开始使用 Hope Domain MCP 服务器！