# Open Assistant

**Repository Path**: ulyan/open-assistant

## Basic Information

- **Project Name**: Open Assistant
- **Description**: 一个开源的OpenCode MCP和Skill库，实现常规工作用途。
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-15
- **Last Updated**: 2026-04-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Open Assistant MCP 工具

一个为AI助手提供屏幕捕获、键盘模拟和鼠标模拟功能的模型上下文协议（MCP）服务器。

## 功能特性

- **屏幕捕获**：截取全屏或指定区域的屏幕截图，支持base64或文件输出
- **键盘模拟**：输入文本、按键、发送快捷键，模拟按键按下/释放事件，可配置输入间隔
- **鼠标模拟**：移动、点击、双击、右键点击、拖拽和滚动，支持精确坐标控制
- **安全第一**：内置安全特性，包括故障安全（移动鼠标到左上角中止）和输入验证
- **MCP协议**：完整的JSON-RPC 2.0实现，兼容MCP 2024-11-05协议
- **错误处理**：全面的错误处理和参数验证

## 安装

1. 确保已安装Python 3.7或更高版本
2. 安装所需的依赖项：

```bash
pip install pyautogui mss
```

## 作为MCP服务器使用

该工具可以作为MCP服务器与任何MCP兼容的客户端（如Claude Desktop、Cline等）一起使用。

### 配置

将服务器添加到您的MCP客户端配置中。例如，在OpenCode的`opencode.json`中：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "open_assistant_mcp": {
      "type": "local",
      "command": ["python", "/path/to/open-assistant-mcp.py"]
    }
  }
}
```

或，在Claude Desktop的`claude_desktop_config.json`中：

```json
{
  "mcpServers": {
    "open_assistant_mcp": {
      "command": "python",
      "args": ["/path/to/open-assistant-mcp.py"]
    }
  }
}
```

### 在OpenCode中使用

MCP客户端中，可以输入以下语句查看所有的MCP接口：
```text
List open_assistant_mcp mcp tools
```

如果截取一个全屏的图像，可以说：
```text
Take a screenshot of the entire screen and save as full.png
```

执行之后就可以看到截取屏幕的截图了。

### 可用工具

#### 1. 屏幕截图工具
截取屏幕或指定区域的截图。

**参数：**
- `region`（可选）：包含`left`、`top`、`width`、`height`属性的对象
- `output_format`（可选）："base64"（默认）或"file"

**使用示例：**
```json
{
  "name": "screenshot",
  "arguments": {
    "region": {
      "left": 0,
      "top": 0,
      "width": 800,
      "height": 600
    },
    "output_format": "base64"
  }
}
```

#### 2. 键盘动作工具
模拟键盘动作。

**参数：**
- `action_type`："type"、"press"、"hotkey"、"key_down"、"key_up"之一
- `text`：要输入的文本（用于"type"动作）
- `keys`：键名数组（用于"press"、"hotkey"动作）。对于"key_down"和"key_up"，也可以使用单个`key`参数。
- `interval`：按键之间的间隔时间（秒，默认：0.1）

**使用示例：**
```json
{
  "name": "keyboard_action",
  "arguments": {
    "action_type": "type",
    "text": "Hello World!",
    "interval": 0.05
  }
}
```

**其他示例：**
```json
// 按下Ctrl+C
{
  "name": "keyboard_action",
  "arguments": {
    "action_type": "hotkey",
    "keys": ["ctrl", "c"]
  }
}

// 按住Shift键
{
  "name": "keyboard_action",
  "arguments": {
    "action_type": "key_down",
    "key": "shift"
  }
}
```

#### 3. 鼠标动作工具
模拟鼠标动作。

**参数：**
- `action_type`："move"、"click"、"double_click"、"right_click"、"drag"、"scroll"之一
- `x`, `y`：动作的坐标
- `button`："left"（默认）、"right"或"middle"
- `clicks`：点击次数（默认：1）
- `duration`：移动持续时间（秒，默认：0.5）
- `dx`, `dy`：滚动量（用于"scroll"动作）

**使用示例：**
```json
{
  "name": "mouse_action",
  "arguments": {
    "action_type": "move",
    "x": 500,
    "y": 300,
    "duration": 1.0
  }
}
```

**其他示例：**
```json
// 在位置(100, 200)处双击
{
  "name": "mouse_action",
  "arguments": {
    "action_type": "double_click",
    "x": 100,
    "y": 200
  }
}

// 在当前位置右键点击
{
  "name": "mouse_action",
  "arguments": {
    "action_type": "right_click"
  }
}

// 向下滚动
{
  "name": "mouse_action",
  "arguments": {
    "action_type": "scroll",
    "dy": -100
  }
}
```

#### 4. 获取屏幕尺寸工具
获取主屏幕的宽度和高度。

**参数：**
- 无参数

**使用示例：**
```json
{
  "name": "get_screen_size",
  "arguments": {}
}
```

**响应示例：**
```json
{
  "success": true,
  "width": 1920,
  "height": 1080,
  "monitor": "primary"
}
```

## 直接使用

您也可以直接将此工具作为Python模块使用。请参阅`test/example.py`查看完整的工作示例：

```python
import json
import subprocess
import sys

def communicate_with_server(request):
    """向MCP服务器发送请求并获取响应。"""
    process = subprocess.Popen(
        [sys.executable, "open-assistant-mcp.py"],
        stdin=subprocess.PIPE,
        stdout=subprocess.PIPE,
        stderr=subprocess.PIPE,
        text=True
    )
    
    stdout, stderr = process.communicate(json.dumps(request) + "\n")
    
    if stderr:
        print(f"服务器stderr: {stderr}")
    
    return json.loads(stdout.strip())

# 示例：截取屏幕截图
request = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "screenshot",
        "arguments": {
            "region": {"left": 0, "top": 0, "width": 800, "height": 600},
            "output_format": "base64"
        }
    }
}

response = communicate_with_server(request)
if "result" in response:
    result_text = response["result"]["content"][0]["text"]
    result_data = json.loads(result_text)
    print(f"截图尺寸: {result_data['width']}x{result_data['height']}")
```

运行示例：
```bash
python test/example.py
```

## 安全注意事项

⚠️ **重要**：此工具可以控制您的键盘和鼠标。请谨慎使用：

1. **故障安全**：PyAutoGUI默认启用了故障安全功能 - 将鼠标移动到屏幕左上角以中止执行
2. **安全配置**：工具配置了`pyautogui.FAILSAFE = True`和`pyautogui.PAUSE = 0.1`以实现更安全的操作
3. **参数验证**：所有输入参数都经过验证，以防止无效操作
4. **测试**：在生产环境使用前，请在安全环境中测试
5. **权限**：在macOS上，您可能需要授予Python辅助功能权限
6. **安全性**：仅从可信来源运行此工具

## 项目结构

```
open-assistant/
├── open-assistant-mcp.py    # 主MCP服务器实现
├── README.md                # 英文文档
├── README-zh.md            # 中文文档
└── test/                    # 测试文件目录
    ├── example.py              # 完整使用示例
    ├── test_open_assistant.py  # 基础功能测试
    └── final_test.py          # 验证和错误处理测试
```

## 测试

项目包含全面的测试以确保功能性和安全性：

### 运行测试
```bash
# 测试基本功能
python test/test_open_assistant.py

# 运行验证测试
python test/final_test.py

# 运行使用示例
python test/example.py
```

### 测试文件
- `test/test_open_assistant.py`：基本功能测试（MCP协议、屏幕截图）
- `test/final_test.py`：验证测试（错误处理、参数验证）
- `test/example.py`：完整使用示例

## 依赖项

### 必需依赖
- `pyautogui`：跨平台GUI自动化
- `mss`：快速屏幕捕获

### 可选依赖（用于示例脚本）
- `Pillow`：图像处理（在example.py中用于图像操作）

## 许可证

GPL 3.0

## 贡献

欢迎提交问题和拉取请求以添加新功能或修复错误。