# lucky-mcp

通过 MCP 和 Lucky OpenToken，让 AI 用自然语言管理 Lucky。

当前适配并完成静态接口清点的版本：**Lucky 3.0.0**。接口目录包含反向代理、端口转发、DDNS、STUN、证书、计划任务、网络唤醒、Web 终端、网络存储、IP 过滤、安全组、日志中心、Docker、Cloudflared 等网页模块。

> Lucky 3.0.0 的 OpenToken 页面声明 OpenToken 仅限个人学习、研究和调试，不得用于商业用途。使用者应自行阅读并遵守自己所用 Lucky 版本展示的条款。

## 安全边界

lucky-mcp 对一般 Lucky 功能不设置额外限制，包括创建、修改、启停、删除和执行操作；但代码永久禁止修改：

- Lucky 管理员账号；
- Lucky 管理员密码；
- OpenToken 的值、开关和确认状态。

这不是提示词约束。业务工具、通用目录接口和设置合并逻辑都会经过代码检查。API 返回中的密码、Token、密钥、Cookie 等字段会自动脱敏。

## 快速开始

要求 Node.js 20 或更高版本。用户只需要 Lucky 地址和 OpenToken：

```json
{
  "mcpServers": {
    "lucky": {
      "command": "npx",
      "args": ["-y", "lucky-mcp"],
      "env": {
        "LUCKY_BASE_URL": "https://lucky.example.com:16601",
        "LUCKY_OPEN_TOKEN": "填写自己的32位OpenToken"
      }
    }
  }
}
```

源码运行：

```powershell
npm install
$env:LUCKY_BASE_URL="https://lucky.example.com:16601"
$env:LUCKY_OPEN_TOKEN="填写自己的OpenToken"
npm run build
npm start
```

自签名证书实例可以设置 `LUCKY_TLS_VERIFY=false`。除非明确了解风险，否则不要关闭证书校验。

## 主要工具

- `lucky_status`：版本、系统信息和模块状态。
- `lucky_api_catalog`：按模块和副作用查询接口。
- `lucky_api_describe`：查看单个接口的版本及请求信息。
- `lucky_api_call`：调用目录中任意非 multipart 接口，不能调用目录外地址。
- 端口转发、Web 服务、DDNS、证书、STUN 的增删改查工具。
- `lucky_get_settings` / `lucky_update_settings`：脱敏读取和安全合并设置。

完整接口见 [API 目录](docs/api-catalog.md) 和 [功能矩阵](docs/feature-matrix.md)。

## 一句话示例

- “列出 Lucky 中所有端口转发规则。”
- “创建一个 TCP4 和 UDP4 的端口转发，名称为 home-ssh。”
- “检查所有反向代理的后端地址和证书有效期。”
- “立即执行指定 DDNS 任务并返回最近日志。”
- “查询今天 Web 服务中被 WAF 阻止的来源 IP 排名。”

删除、重启、升级、导入配置等操作能造成明显影响。MCP 客户端可能仍会按自身策略要求确认。

## 开发与验证

```powershell
npm run check
```

`.capture/` 只用于本地分析对应版本的公开网页前端，不进入 Git。重新提取接口目录的方法见 [升级接口目录](docs/upgrading-api-catalog.md)。

## 非官方声明

本项目不是 Lucky 官方项目，也不包含 Lucky 源码、前端文件、账号、OpenToken 或用户配置。Lucky 更新可能改变未公开接口，使用前请先备份配置。