# Monitor Control MCP

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

基于 MCP (Model Context Protocol) 的屏幕亮度控制工具，让 AI 助手可以智能调节你的显示器亮度。

本项目全程使用[Qwen Code CLI](https://qwenlm.github.io/qwen-code-docs/zh/users/overview/)程序Qwen3.5-Plus模型生成

## ✨ 功能特性

- 🔍 **显示器检测**: 获取所有支持 DDC/CI 协议的显示器信息
- 🎯 **精确控制**: 设置显示器亮度为指定百分比 (0-100%)
- 📈 **相对调节**: 在当前亮度基础上增加或减少亮度
- 🖥️ **多显示器支持**: 可同时控制所有显示器或指定特定显示器
- 🛡️ **资源管理**: 自动管理显示器句柄，防止资源泄漏
- 🎨 **对比度控制**: 设置和查询显示器对比度 (0-100%)
- 🌈 **RGB 增益查询**: 查询显示器的红/绿/蓝增益信息（设置功能因硬件兼容性问题已禁用）

## 📋 系统要求

- **操作系统**: **Windows 10/11**
- **Python**: 3.10 或更高版本
- **显示器**: 支持 DDC/CI 协议的显示器
- **权限**: 可能需要管理员权限

## 🚀 快速开始

### 1. 安装

#### 方式 A: 使用 uv（推荐）

```bash
# 克隆仓库
git clone https://github.com/your-username/monitor-control-mcp.git
cd monitor-control-mcp

# 安装依赖
uv sync
```

#### 方式 B: 使用 pip

```bash
# 克隆仓库
git clone https://github.com/your-username/monitor-control-mcp.git
cd monitor-control-mcp

# 创建虚拟环境
python -m venv .venv
.venv\Scripts\activate  # Windows

# 安装依赖
pip install -e .
```

### 2. 测试安装

```bash
# 直接运行测试
uv run python monitor_brightness.py

# 或使用 pip 安装后
python monitor_brightness.py
```

## 🔧 MCP 客户端配置

### Claude Desktop 配置

**Windows** (`%APPDATA%\Claude\claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "monitor-control": {
      "command": "uv",
      "args": ["run", "monitor-control-mcp"],
      "cwd": "C:\\path\\to\\monitor-control-mcp"
    }
  }
}
```

**macOS** (`~/Library/Application Support/Claude/claude_desktop_config.json`):

> ⚠️ 注意：此工具仅支持 Windows 系统。macOS 用户需要使用其他方法。

### Cursor IDE 配置

在 Cursor 的设置中，找到 MCP 配置，添加：

```json
{
  "mcpServers": {
    "monitor-control": {
      "command": "uv",
      "args": ["run", "monitor-control-mcp"],
      "cwd": "C:\\path\\to\\monitor-control-mcp"
    }
  }
}
```

### 其他 MCP 客户端

使用以下通用配置：
- **command**: `uv` (或 Python 可执行文件路径)
- **args**: `["run", "monitor-control-mcp"]`
- **cwd**: 项目的绝对路径

## 🛠️ 可用工具

### 1. `get_monitor_info` - 获取显示器信息

获取所有显示器的详细信息和当前亮度。

**参数**: 无

**返回示例**:
```json
{
  "success": true,
  "monitor_count": 2,
  "monitors": [
    {
      "description": "Dell U2720Q",
      "current_brightness": 60,
      "min_brightness": 0,
      "max_brightness": 100,
      "raw_current": 60
    },
    {
      "description": "LG UltraFine",
      "current_brightness": 45,
      "min_brightness": 0,
      "max_brightness": 100,
      "raw_current": 45
    }
  ]
}
```

### 2. `set_brightness` - 设置亮度

将显示器亮度设置为指定百分比。

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `brightness` | integer | ✅ | 目标亮度百分比 (0-100) |
| `monitor_description` | string | ❌ | 显示器描述关键字，用于指定特定显示器 |

**示例**:
```json
// 将所有显示器设置为 50% 亮度
{"brightness": 50}

// 仅设置 Dell 显示器
{"brightness": 70, "monitor_description": "Dell"}
```

### 3. `adjust_brightness` - 相对调节亮度

在当前亮度基础上增加或减少亮度。

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `delta` | integer | ✅ | 亮度调整幅度 (-100 到 100) |
| `monitor_description` | string | ❌ | 显示器描述关键字 |

**示例**:
```json
// 增加 10% 亮度
{"delta": 10}

// 降低 20% 亮度
{"delta": -20}

// 仅调节特定显示器
{"delta": 5, "monitor_description": "LG"}
```

### 4. `set_contrast` - 设置对比度

将显示器对比度设置为指定百分比。

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `contrast` | integer | ✅ | 目标对比度百分比 (0-100) |
| `monitor_description` | string | ❌ | 显示器描述关键字，用于指定特定显示器 |

**示例**:
```json
// 将所有显示器对比度设置为 70%
{"contrast": 70}

// 仅设置 Dell 显示器
{"contrast": 80, "monitor_description": "Dell"}
```

### 5. `get_contrast` - 获取对比度信息

获取显示器的当前对比度信息。

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `monitor_description` | string | ❌ | 显示器描述关键字，用于指定特定显示器 |

**返回示例**:
```json
{
  "success": true,
  "monitor_count": 1,
  "monitors": [
    {
      "description": "Dell U2720Q",
      "success": true,
      "current": 70,
      "min": 0,
      "max": 100,
      "percent": 70
    }
  ]
}
```

### 6. `get_gain` - 获取指定颜色增益

获取显示器指定颜色通道的增益信息。

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `color` | string | ✅ | 颜色通道：`red`、`green` 或 `blue` |
| `monitor_description` | string | ❌ | 显示器描述关键字 |

**返回示例**:
```json
{
  "success": true,
  "monitor_count": 1,
  "monitors": [
    {
      "description": "Dell U2720Q",
      "success": true,
      "current": 50,
      "min": 1,
      "max": 100,
      "percent": 49
    }
  ]
}
```

### 7. `get_all_gains` - 获取所有颜色增益

一次性获取显示器所有 RGB 增益信息。

**参数**:
| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| `monitor_description` | string | ❌ | 显示器描述关键字 |

**返回示例**:
```json
{
  "success": true,
  "monitor_count": 1,
  "monitors": [
    {
      "description": "Dell U2720Q",
      "success": true,
      "gains": {
        "red": {
          "current": 50,
          "min": 1,
          "max": 100,
          "percent": 49
        },
        "green": {
          "current": 50,
          "min": 1,
          "max": 100,
          "percent": 49
        },
        "blue": {
          "current": 50,
          "min": 1,
          "max": 100,
          "percent": 49
        }
      }
    }
  ]
}
```

### ⚠️ 关于 RGB 增益设置的说明

`set_gain` 工具已暂时禁用，原因如下：

- **硬件兼容性差**: 许多显示器不支持通过 DDC/CI 写入 RGB 增益值
- **只读限制**: 部分显示器允许读取增益值但不允许修改
- **预设模式限制**: 显示器处于预设模式（如标准、游戏、电影等）时通常禁止修改

如果未来需要启用此功能，请确保：
1. 显示器处于用户自定义模式
2. 在显示器 OSD 菜单中启用 DDC/CI 写入权限
3. 不同显示器型号可能需要不同的处理方式

## 💡 使用示例

### 场景 1: 查询当前所有显示器状态

> 用户：我现在的显示器亮度是多少？

> AI: 让我帮你查询一下。
> *[使用 `get_monitor_info` 工具]*
> 你目前有 2 台显示器：
> - Dell U2720Q: 亮度 60%
> - LG UltraFine: 亮度 45%

### 场景 2: 设置夜间模式

> 用户：太亮了，调暗一点

> AI: 好的，我来帮你降低亮度。
> *[使用 `adjust_brightness` 工具，delta: -20]*
> 已将亮度降低 20%，现在更舒适了。

### 场景 3: 精确控制

> 用户：把亮度设为 50%

> AI: 没问题。
> *[使用 `set_brightness` 工具，brightness: 50]*
> 已将所有显示器亮度设置为 50%。

### 场景 4: 控制特定显示器

> 用户：只调暗主显示器

> AI: 好的。
> *[使用 `set_brightness` 工具，brightness: 30, monitor_description: "Dell"]*
> 已将 Dell 显示器亮度设置为 30%。

### 场景 5: 调整对比度

> 用户：把对比度调高一些

> AI: 好的，我来帮你调整对比度。
> *[先使用 `get_contrast` 查询当前值，再使用 `set_contrast` 设置为 75%]*
> 已将对比度从 60% 调整为 75%。

### 场景 6: 查询色彩平衡

> 用户：我的显示器 RGB 增益设置怎么样？

> AI: 让我帮你检查一下。
> *[使用 `get_all_gains` 工具]*
> 你的显示器 RGB 增益设置如下：
> - 红色：50%
> - 绿色：50%
> - 蓝色：50%
> 色彩平衡正常。

## 🔍 故障排除

### 问题 1: "未检测到任何支持 DDC/CI 的物理显示器"

**可能原因**:
1. 显示器不支持 DDC/CI 协议
2. DDC/CI 功能在显示器 OSD 菜单中被禁用
3. 使用了不支持的转接头或线缆

**解决方案**:
1. 检查显示器规格，确认支持 DDC/CI
2. 在显示器 OSD 菜单中找到并启用 "DDC/CI" 选项
3. 使用原装或高质量的 DisplayPort/HDMI 线缆
4. 避免使用廉价的转接头

### 问题 2: "获取亮度信息失败" 或 "设置亮度失败"

**可能原因**:
- 权限不足
- 显示器暂时无法响应

**解决方案**:
1. 以管理员身份运行终端/IDE
2. 重启显示器后重试
3. 检查是否有其他软件正在控制显示器亮度

### 问题 3: 笔记本内置屏幕无法调节

**说明**: 某些笔记本的内置屏幕不支持 DDC/CI 协议，这是正常现象。此工具主要适用于外接显示器。

**替代方案**: 使用 Windows 内置的亮度调节功能或笔记本厂商提供的控制软件。

### 问题 4: MCP 服务器无法启动

**检查步骤**:
1. 确认 Python 版本 >= 3.10
2. 确认已安装所有依赖：`uv sync`
3. 检查配置文件中的路径是否正确
4. 查看错误日志

## 📁 项目结构

```
monitor-control-mcp/
├── mcp_server.py          # MCP 服务器主程序
├── monitor_brightness.py  # 显示器亮度控制模块
├── pyproject.toml         # 项目配置和依赖
├── README.md              # 项目文档
├── LICENSE                # 开源许可证
├── .gitignore             # Git 忽略文件
└── tests/                 # 测试目录（待添加）
    └── test_server.py
```

## 🔧 开发指南

### 本地开发

```bash
# 克隆仓库
git clone https://github.com/your-username/monitor-control-mcp.git
cd monitor-control-mcp

# 安装开发依赖
uv sync --extra dev

# 运行测试
uv run pytest
```

### 直接测试模块

```bash
# 测试亮度控制模块
uv run python monitor_brightness.py

# 测试 MCP 服务器（需要 MCP 客户端连接）
uv run python mcp_server.py
```

### 构建分发包

```bash
# 使用 uv 构建
uv build

# 或使用 pip
pip install build
python -m build
```

## 📝 API 参考

### MonitorController 类

底层控制器类，管理显示器句柄和 DDC/CI 通信。

```python
from monitor_brightness import MonitorController

controller = MonitorController()
controller.load_dll()

# 获取显示器列表
monitors = controller.get_monitor_handles()

# 设置亮度
success, message = controller.set_brightness_for_monitor(handle, 50)

# 获取当前亮度
current, min_val, max_val = controller.get_current_brightness(handle)

# 清理资源
controller.cleanup_monitors(monitors)
```

### 便捷函数

模块提供的便捷函数：

```python
from monitor_brightness import (
    control_monitor_brightness,  # 控制亮度（高级 API）
    get_monitor_handles,         # 获取显示器句柄
    get_current_brightness,      # 获取当前亮度
    set_brightness_for_monitor,  # 设置单个显示器亮度
    cleanup_monitors,            # 清理资源
)

# 使用高级 API
result = control_monitor_brightness(50)  # 设置所有显示器为 50%
result = control_monitor_brightness(50, "Dell")  # 仅设置 Dell 显示器
```

## 🤝 贡献

欢迎贡献代码、报告问题或提出建议！

1. Fork 本仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 开启 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🔗 相关链接

- [MCP 协议文档](https://modelcontextprotocol.io/)
- [DDC/CI 规范](https://en.wikipedia.org/wiki/Display_Data_Channel)
- [Python 官方网站](https://www.python.org/)

## ⭐ 致谢

感谢使用本项目！如果这个项目对你有帮助，请给一个 Star ⭐

---

**注意**: 本项目仅适用于 Windows 系统，需要显示器支持 DDC/CI 协议。