# Sky PC MCP Companion Safe

一个面向 Windows 版《Sky: Children of the Light / 光·遇》的本地 MCP 服务。它让支持 MCP 的
AI 客户端读取经过验证的游戏窗口、执行本地 OCR，并在用户明确开启权限后发送有限的游戏按键或聊天文本。

本项目参考了 [Aevella/sky-pc-mcp-companion](https://github.com/Aevella/sky-pc-mcp-companion)
所展示的使用场景，但采用 clean-room 方式重新实现，没有复制授权不明的原仓库源码。

## 与原型相比的主要改进

- 使用官方 MCP Python SDK v2，支持标准 stdio 与 Streamable HTTP。
- 同时校验窗口标题和进程名，避免只靠模糊标题控制错误窗口。
- 找不到游戏窗口时默认报错，不会静默截取整个桌面。
- 输入和聊天分别授权，默认均关闭。
- 按键白名单、禁止 Windows/Meta 键、按压最长 2 秒。
- 所有聚焦、按键和剪贴板操作串行执行，降低并发卡键风险。
- 恢复剪贴板前检查内容，避免覆盖用户刚复制的新数据。
- LAN HTTP 必须提供 Bearer Token，并启用 MCP Host allowlist。
- HTTP 请求体最大 256 KiB。
- `screenshot` 是正式工具名，同时保留 `take_screenshot` 兼容别名。
- 不在工具结果中回显聊天正文。
- pytest、Ruff 和 GitHub Actions CI。

## 安装

需要 Windows、Python 3.10 或更新版本。

```powershell
git clone https://github.com/ll13355154947/sky-pc-mcp-companion-safe.git
cd sky-pc-mcp-companion-safe
python -m venv .venv
.venv\Scripts\python -m pip install -e .
```

需要 OCR 时，先安装 Windows 版 Tesseract 及中文语言包，然后执行：

```powershell
.venv\Scripts\python -m pip install -e ".[ocr]"
```

## 默认安全模式

默认只允许 `status`、`screenshot`、`take_screenshot` 和 `read_screen`。开启输入：

```powershell
$env:SKY_MCP_ENABLE_INPUT="1"
```

单独开启聊天：

```powershell
$env:SKY_MCP_ENABLE_CHAT="1"
```

聊天要求输入权限也已开启。不要在不受信任的客户端上开放这两项权限。

## 启动 stdio MCP

```powershell
.venv\Scripts\sky-mcp-safe stdio
```

客户端配置示例：

```json
{
  "command": "C:\\path\\to\\sky-pc-mcp-companion-safe\\.venv\\Scripts\\sky-mcp-safe.exe",
  "args": ["stdio"]
}
```

## 启动本机 Streamable HTTP

```powershell
.venv\Scripts\sky-mcp-safe http
```

端点为 `http://127.0.0.1:9800/mcp`，健康检查为 `http://127.0.0.1:9800/health`。

## 局域网模式

可直接双击 `start-http-lan.bat`。它会为本次启动生成随机 Token。客户端连接：

```text
URL: http://电脑局域网IP:9800/mcp
Authorization: Bearer 启动窗口显示的Token
```

不要通过路由器端口转发、反向代理或公网防火墙规则把它暴露到互联网。普通 HTTP 不提供传输加密，
因此局域网也必须是可信网络；跨网络访问请使用受控 VPN 或带 TLS 的反向代理。

## 工具

| 工具 | 默认可用 | 说明 |
|---|---:|---|
| `status` | 是 | 权限、OCR 与窗口状态 |
| `screenshot` | 是 | 仅截取验证后的游戏窗口 |
| `take_screenshot` | 是 | 截图兼容别名 |
| `read_screen` | 是 | 本地 OCR，不上传到云端 |
| `press_key` | 否 | 发送白名单内的有限游戏按键 |
| `open_chat` | 否 | 打开聊天输入框 |
| `type_text` | 否 | 向已打开且已聚焦的聊天框粘贴文本 |
| `send_chat` | 否 | 聚焦游戏、打开聊天并发送文本 |

## 窗口识别

默认要求进程名是 `Sky.exe`。如果实际安装不同，可配置逗号分隔列表：

```powershell
$env:SKY_MCP_PROCESS_NAMES="Sky.exe,YourSkyExecutable.exe"
$env:SKY_MCP_WINDOW_TITLES="Sky: Children of the Light,光遇"
```

只有在明确接受隐私风险时，才允许找不到窗口后截取显示器：

```powershell
$env:SKY_MCP_ALLOW_MONITOR_FALLBACK="1"
```

## 边界

本项目不读取游戏内存、不修改客户端、不破解协议，也不提供刷资源、自动跑图或代肝功能。
模拟输入仍可能受到游戏或平台规则限制；如果规则不允许，请勿开启输入功能。

## 开发

```powershell
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest
```

项目采用 MIT License。安全问题请阅读 [SECURITY.md](SECURITY.md)。