Metadata-Version: 2.5
Name: mcp-server-domainwatch
Version: 1.3.0
Summary: MCP server for domain registration price & expiry monitoring (Spaceship + RDAP).
Project-URL: Repository, https://github.com/YOUR_GITHUB_USERNAME/astrbot_plugin_xyz_price_monitor
License: GPL-3.0-only
License-File: LICENSE
Keywords: astrbot,domain,mcp,monitor,rdap,spaceship,whois
Requires-Python: >=3.10
Requires-Dist: mcp<2,>=1.29.0
Description-Content-Type: text/markdown

# AstrBot 6位数字 .xyz 价格监控 + MCP 域名监控 v1.3.0

一套核心，两种用法：

1. **AstrBot 插件**：命令 + 后台定时检查 + 主动推送（降价 / 变可注册）
2. **MCP server（`uvx mcp-server-domainwatch`）**：给 Claude 等 MCP 客户端用，自然语言管理监控、查价、查到期，不用记命令

插件启动时会**自动**把 MCP 服务器注册进 AstrBot 的 MCP 运行时——在群里直接跟 LLM 说话即可（例如「帮我盯着 617831.xyz，低于 15 刀提醒我」）。

## 功能

- Spaceship 官方 API 查可用状态 + 注册价（含 Registry Premium）
- 价格历史落盘；降价 ≥50% / ≥67%、已注册 → 可注册 时**主动推送**
- MCP 工具：监控列表管理、立即查价、价格历史、RDAP 到期/NS/注册商查询（免 Key）、触发提醒汇总
- 数据互通：插件与 MCP 共用同一份 `data.json`

## 安装 AstrBot 插件

- **Git**：克隆本仓库到 `AstrBot/data/plugins/`，重启或面板热重载
- **zip**：面板「插件管理」上传（`metadata.yaml` 须在 zip 根目录；打包时包含 `main.py`、`metadata.yaml`、`_conf_schema.json`、`README.md`、`LICENSE`、`domainwatch/` 目录）
- 要求 AstrBot **>= 4.23.0**（插件自动注册 MCP 依赖该版本的 stdio 校验与运行时）

### AstrBot 配置

- `Spaceship API Key` / `Spaceship API Secret`：只需 `domains:read` 权限；也可用环境变量 `SPACESHIP_API_KEY` / `SPACESHIP_API_SECRET`
- `后台检查间隔`：默认 6 小时（1～24）
- `自动注册 MCP 服务器`：默认开；关闭则不会调用 `uvx`

### 命令（可选，不用命令也能全靠对话）

- `/xyz_add 617831` / `/xyz_remove 617831` / `/xyz_list`
- `/xyz_check`（立即查询） / `/xyz_history 617831` / `/xyz_test`（连通性测试）

后台检查只覆盖六位数字 `.xyz`；任意域名的按需查价/查到期走 MCP 工具。

## MCP server（uvx）

### 一次下载，之后走缓存

```bash
uvx mcp-server-domainwatch
```

uvx **首次**运行会从 PyPI 下载并建环境，**之后直接用本地缓存**，不会每次执行都重新下载。只有 `@latest`、`--refresh`、`uv cache clean` 才会刷新缓存。锁定版本（推荐生产/集成用）：

```bash
uvx mcp-server-domainwatch@1.3.0
```

### Claude Desktop / Claude Code 配置示例

```json
{
  "mcpServers": {
    "domainwatch": {
      "command": "uvx",
      "args": ["mcp-server-domainwatch@1.3.0"],
      "env": {
        "SPACESHIP_API_KEY": "YOUR_SPACESHIP_API_KEY",
        "SPACESHIP_API_SECRET": "YOUR_SPACESHIP_API_SECRET"
      }
    }
  }
}
```

不配 Spaceship Key 也能用：`domainwatch_domain_info`（RDAP）、`domainwatch_list_watches`、`domainwatch_price_history`、`domainwatch_triggered_alerts` 全部可用；只有 `domainwatch_check_prices` 需要 Key。

### AstrBot 侧（自动）

插件 `initialize()` 时自动执行等价于上面的注册（含 Key 与数据文件路径注入），WebUI「插件 → MCP」中可见、可停用。失败时日志会给出手动配置指引。

数据文件：

- 插件注入 `DOMAINWATCH_DATA` → 指向插件的 `data.json`（与命令、推送共用）
- 独立运行 MCP（无插件）时默认 `~/.domainwatch/data.json`，可用 `DOMAINWATCH_DATA` 覆盖

### MCP 工具一览

| 工具 | 说明 | 需 Key |
|---|---|---|
| `domainwatch_watch_domain` | 加入监控，可设 `alert_below` 价格目标 | 否 |
| `domainwatch_unwatch_domain` | 移出监控 | 否 |
| `domainwatch_list_watches` | 列表 + 状态/价格/到期剩余 | 否 |
| `domainwatch_check_prices` | Spaceship 立即查价并更新历史 | 是 |
| `domainwatch_price_history` | 本地价格历史 | 否 |
| `domainwatch_domain_info` | RDAP：到期/注册商/NS/状态（任意域名） | 否 |
| `domainwatch_triggered_alerts` | 汇总已触发提醒（低于目标价 / ≤30·7·1 天到期 / 可注册） | 否 |

## 为什么需要 Spaceship API Key/Secret

六位数字 `.xyz` 很可能属于 Registry Premium；免费公开接口在这类名字上常返回空价格。Spaceship 官方 `POST /v1/domains/available` 会为可注册的普通/Registry Premium 域名返回注册价格，只需 `domains:read` 权限。

## 发布（维护者）

```bash
# 改 pyproject.toml / metadata.yaml / MCP_PACKAGE_SPEC 中的版本（保持一致）
uv build                 # 产出 dist/
uv publish               # 发布到 PyPI（需 PyPI 账号 token）
git tag v1.3.0 && git push origin v1.3.0
```

MCP registry（可选）：README 中保留 `<!-- mcp-name: io.github.YOUR_GITHUB_USERNAME/mcp-server-domainwatch -->` 注释供 `mcp-publisher` 验证。

## 安全

- 只调用 Spaceship 官方 API 与公开 RDAP（`rdap.org`），无第三方 Python 包（MCP server 仅依赖官方 `mcp` SDK），不开放监听端口
- API Key 建议仅授权 `domains:read`；面板中 Key/Secret 以密码框显示，不写入日志
- 不要把真实 Key 提交进 Git

## 许可

[GPLv3](LICENSE)。AstrBot 文档见 [docs.astrbot.app](https://docs.astrbot.app)（`docs.astrbot.ai` 已失效）。
