# deepin-desktop-mcp

用 MCP 控制本机 Deepin 桌面：WiFi、蓝牙、亮度、主题、音量、应用开关等。

核心是标准 **stdio MCP Server**（`deepin_mcp_server.py`），不绑定某一家 Agent。可选两种接入方式：

1. **小智 AI**：经 `mcp_pipe.py` 桥到官方 WSS 接入点（语音控制）
2. **其他 Agent**（Cursor / Claude Desktop 等）：客户端直接以 stdio 拉起本 Server

小智协议与官方示例一致：[78/mcp-calculator](https://github.com/78/mcp-calculator) / [小智 MCP 接入说明](https://ccnphfhqs21z.feishu.cn/wiki/HiPEwZ37XiitnwktX13cEM5KnSb)。

**许可证**：[MIT](./LICENSE)

## 免责声明

本项目为第三方开源工具，**与 Deepin、小智 AI 官方无关**，按「现状（AS IS）」提供，不作任何明示或暗示担保。

本工具可控制系统设置、开关机、读写/删除本地文件等。错误调用、模型误判或配置（尤其是 `MCP_ENDPOINT` token）泄露，可能导致数据丢失、隐私风险或系统异常。使用即表示你了解并**自行承担全部风险**；作者不对任何直接或间接损失负责。

请勿将含 token 的 `.env`、真实接入点 URL 或本地 `config.json` 提交到公开仓库或发给不可信方。

## 架构

```text
方式 A：小智                          方式 B：其他 MCP 客户端
小智设备 / 大模型                     Cursor / Claude Desktop / …
       │                                      │
       ▼                                      │ stdio 直接启动
xiaozhi.me MCP 接入点 (wss://...)             │
       │  mcp_pipe.py 主动连出                 │
       ▼                                      ▼
              deepin_mcp_server.py  (FastMCP, stdio)
                              │
                              ▼
              Deepin 25（nmcli / gsettings / D-Bus / pactl …）
```

- `deepin_mcp_server.py`：标准 MCP（stdio），可被任意兼容客户端调用。
- `mcp_pipe.py`：仅小智需要；把 stdio 桥到云端 WSS。不要自己再开 WebSocket 服务端。

## 环境要求

- Deepin 25（已按本机 D-Bus / gsettings 适配；其他版本可能需微调）
- Python 3.10+
- 图形桌面会话（D-Bus session 可用）

## 安装

```bash
cd /path/to/deepin-desktop-mcp
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
cp config.example.json config.json
```

## 配置

分两个文件：

| 文件 | 用途 |
|------|------|
| `.env` | 密钥与运行环境：`MCP_ENDPOINT`、`LOG_LEVEL` |
| `config.json` | 业务配置：应用命令、壁纸目录、重连参数、`mcpServers` 等 |

示例 `.env`：

```bash
MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=你的token
LOG_LEVEL=INFO
```

`MCP_ENDPOINT` 优先读 `.env`；若为空，再读 `config.json` 的 `mcp_endpoint`。

常用 `config.json` 字段：

- `app_commands`：各应用可执行文件候选列表
- `wallpaper_dirs`：随机壁纸搜索目录
- `max_result_chars`：返回给小智的最大字符数（建议 ≤1000）
- `mcpServers.deepin`：stdio 启动命令（默认用 `.venv/bin/python`）

获取接入点：登录 [xiaozhi.me](https://xiaozhi.me) → 智能体「配置角色」→ 右下角 MCP 接入点。

## 运行（小智 AI）

需先在 `.env` 填写 `MCP_ENDPOINT`。

```bash
# 推荐
./run.sh

# 或手动
source .venv/bin/activate
python mcp_pipe.py
```

`./run.sh` / 无参数的 `mcp_pipe.py` 会按 `config.json` 的 `mcpServers` 启动。

成功日志类似：

```text
MCP_PIPE - INFO - Connecting to WebSocket server...
MCP_PIPE - INFO - Successfully connected to WebSocket server
MCP_PIPE - INFO - Started server process: ...
Processing request of type ListToolsRequest
```

然后到小智后台刷新，确认 MCP 已接入即可语音控制电脑。

## 运行（stdio / 其他 Agent）

不连小智时，**不要**启动 `mcp_pipe.py` / `./run.sh`。让 MCP 客户端自行用 stdio 启动 `deepin_mcp_server.py`。

`command` 请用本仓库虚拟环境里的 Python（绝对路径更稳），工作目录建议为本仓库根目录（以便读到 `config.json`）。

### Cursor

在 `~/.cursor/mcp.json`（或项目级 MCP 配置）中加入：

```json
{
  "mcpServers": {
    "deepin-desktop": {
      "command": "/绝对路径/deepin-desktop-mcp/.venv/bin/python",
      "args": ["/绝对路径/deepin-desktop-mcp/deepin_mcp_server.py"]
    }
  }
}
```

保存后在 Cursor 设置里确认 MCP 已启用；应能看到 `open_url`、`launch_app` 等工具。

### Claude Desktop

编辑 Claude 的 MCP 配置（常见路径：`~/.config/Claude/claude_desktop_config.json`），写入同样结构：

```json
{
  "mcpServers": {
    "deepin-desktop": {
      "command": "/绝对路径/deepin-desktop-mcp/.venv/bin/python",
      "args": ["/绝对路径/deepin-desktop-mcp/deepin_mcp_server.py"]
    }
  }
}
```

重启 Claude Desktop 后生效。

### 任意 stdio MCP 客户端

只要客户端支持「command + args」启动本地 MCP Server，配置方式相同：

| 字段 | 值 |
|------|-----|
| `command` | `.venv/bin/python` 的绝对路径 |
| `args` | `["…/deepin_mcp_server.py"]` |

stdio 模式下不需要 `MCP_ENDPOINT`；业务配置仍读本地 `config.json`（应用命令、壁纸目录等）。

注意：

1. 须在**图形桌面会话**用户下由客户端拉起（需要 D-Bus session）。
2. 可与小智并存（各起各的 server 进程）；但不要对同一小智接入点开多个 `mcp_pipe`。
3. `max_result_chars` 主要照顾小智侧长度限制；其他客户端一般也能用，返回偏短属正常。

## 可用工具

| 工具 | 作用 |
|------|------|
| `open_url` | 用默认浏览器打开网址/站点别名（如 B站）；已开浏览器时通常新标签 |
| `switch_wifi` | 开关 WiFi |
| `switch_bluetooth` | 开关蓝牙 |
| `get_bluetooth_devices` | 已连接蓝牙设备 |
| `set_brightness` | 屏幕亮度 0–100 |
| `switch_eyes_protection` | 护眼/自动色温 |
| `switch_theme` | 浅色 / 深色 / 自动主题 |
| `switch_wallpaper` | 随机换壁纸 |
| `set_volume` | 音量 / 静音 |
| `set_performance_mode` | 高性能 / 平衡 / 节能 |
| `launch_app` | 打开/关闭应用（系统 + WPS/钉钉/微信等） |
| `get_system_memory` | 内存占用 |
| `set_font_size` | 系统字号 |
| `file_operation` | 打开/复制/移动/重命名/删除/建文件夹 |
| `read_file_content` | 读文本文件（有长度限制） |
| `shutdown_system` | 关机 |
| `create_schedule` | 生成 ICS 日程并通知 |
| `music_control` | 播放/暂停/上一首/下一首（MPRIS） |

### 打开网址

语音示例：「打开 B 站」「打开百度」「打开 https://github.com」

- 工具：`open_url`
- 别名在 `config.json` → `url_aliases`（可自行增删）
- 使用系统默认浏览器；已打开时一般会**新建标签页**

### 打开第三方应用

`launch_app` 的 `app_name` 示例：

| app_name | 应用 |
|----------|------|
| `wps` | WPS Office |
| `wpsWriter` / `wpsPresentation` / `wpsSpreadsheet` | 文字 / 演示 / 表格 |
| `dingtalk` | 钉钉 |
| `wechat` | 微信 |
| `wecom` | 企业微信 |

在 `config.json` 的 `app_desktop_ids` / `app_commands` 里按同样格式添加即可扩展更多应用（改完重启 `./run.sh`）。

## 注意事项

1. **不要用 `print`**：stdio 用于 MCP 传输，调试请用 `logger`。  
2. **返回值宜短**：小智侧通常限制约 1024 字节。  
3. **工具名与 docstring 要清晰**：方便大模型决定何时调用。  
4. **接入点连接数有上限**：不要多开多个 `mcp_pipe` 连同一接入点。  
5. **部分应用需已安装**：未安装时 `launch_app` 会提示找不到命令。  
6. **关机/删文件等高危操作**：仅在明确意图时调用。

## 目录说明

```text
deepin-desktop-mcp/
├── .env / .env.example       # 密钥（MCP_ENDPOINT）
├── config.json               # 本地业务配置（勿提交密钥）
├── config.example.json       # 配置模板
├── config_loader.py          # 配置加载
├── deepin_mcp_server.py      # Deepin MCP Server（stdio）
├── mcp_pipe.py               # stdio ↔ 小智 WSS 桥接
├── run.sh                    # 一键启动
├── requirements.txt
├── LICENSE
├── SECURITY.md
└── README.md
```

## 常见问题

**打开浏览器/设置返回成功但没窗口**  
旧版直接跑 `sensible-browser` / `dde-control-center` 会假成功。当前版本已改为：
- 浏览器：`xdg-open` 打开默认浏览器（含 linglong Edge）
- 设置：D-Bus `org.deepin.dde.ControlCenter1.ShowHome`
- 其它应用：优先 `dde-am`  

修改代码后需重启 `./run.sh`。

**连不上 WebSocket**  
检查 `.env` 里 `MCP_ENDPOINT` 是否完整、网络能否访问 `api.xiaozhi.me`。

**工具列表有了但执行失败**  
确认在图形会话用户下运行（需要 D-Bus session）。

**只想本地测工具、不连小智 / 给 Cursor 等用**  
见上文「运行（stdio / 其他 Agent）」：客户端直接 stdio 启动 `deepin_mcp_server.py`，不要跑 `./run.sh`。

## 致谢

- [78/mcp-calculator](https://github.com/78/mcp-calculator)：小智 MCP 的 stdio ↔ WebSocket 桥接参考实现（`mcp_pipe.py` 基于其思路）
- [Model Context Protocol](https://modelcontextprotocol.io/) 与 Python MCP SDK

## License

本项目采用 [MIT License](./LICENSE)。