# MCP Browser Text Reader

一个强大的 Model Context Protocol (MCP) 服务器，用于控制真实的Chrome浏览器并读取页面文字内容。支持多种文本提取方式和灵活的配置选项。

## 功能特性

- 🌐 **真实Chrome浏览器控制**: 直接控制系统中的Chrome浏览器，可见窗口操作
- 📝 **灵活的文本提取**: 支持可见文本、所有文本、innerText、textContent等多种提取方式
- 🎯 **精确元素选择**: 使用CSS选择器精确定位需要提取的元素
- ⏱️ **智能等待机制**: 支持等待特定元素加载完成
- 🔍 **详细的元数据**: 提供字符数、词数、提取时间等详细信息
- 🛡️ **错误处理**: 完善的错误处理和资源清理机制
- 🔄 **智能连接**: 自动连接现有Chrome实例或启动新实例
- 👀 **可视化操作**: 实时观察浏览器操作过程

## 安装

### 1. 克隆项目
```bash
git clone <repository-url>
cd mcp-browser-text-reader
```

### 2. 安装依赖
```bash
npm install
```

### 3. 确保Chrome浏览器已安装
确保系统中已安装Google Chrome浏览器：
- **macOS**: `/Applications/Google Chrome.app/`
- **Windows**: `C:\Program Files\Google\Chrome\Application\chrome.exe`
- **Linux**: `/usr/bin/google-chrome`

### 4. 编译 TypeScript
```bash
npm run build
```

## 使用方法

### 作为 MCP 服务器运行

```bash
npm start
```

### 在 Cursor 中配置

在 Cursor 的 MCP 配置文件中添加以下配置：

**位置**: `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "browser-text-reader": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"]
    }
  }
}
```

### 在 Claude Desktop 中配置

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

```json
{
  "mcpServers": {
    "browser-text-reader": {
      "command": "node",
      "args": ["/absolute/path/to/your/project/dist/index.js"]
    }
  }
}
```

## 可用工具

### 1. `get_page_text`
获取指定URL页面的文本内容

**参数**:
- `url` (可选): 要读取的网页URL
- `selector` (可选): CSS选择器，用于选择特定元素
- `waitForSelector` (可选): 等待特定元素出现的CSS选择器
- `timeout` (可选): 超时时间（毫秒），默认10000
- `includeHidden` (可选): 是否包含隐藏元素，默认false
- `textType` (可选): 文本提取类型，可选值：`visible`、`all`、`innerText`、`textContent`

**示例**:
```json
{
  "url": "https://example.com",
  "selector": "article",
  "textType": "visible",
  "timeout": 15000
}
```

### 2. `get_current_page_text`
获取当前浏览器页面的文本内容

**参数**:
- `selector` (可选): CSS选择器
- `includeHidden` (可选): 是否包含隐藏元素
- `textType` (可选): 文本提取类型

### 3. `navigate_to_page`
导航到指定URL

**参数**:
- `url` (必需): 要导航到的网页URL
- `waitForSelector` (可选): 等待特定元素出现
- `timeout` (可选): 超时时间

### 4. `get_page_info`
获取当前页面的基本信息（标题、URL等）

### 5. `launch_chrome_manually`
手动启动Chrome浏览器（可见窗口）

### 6. `get_browser_status`
获取浏览器连接状态

### 7. `close_browser`
关闭浏览器实例或断开连接

## 文本提取类型说明

- **`visible`** (默认): 只提取用户可见的文本
- **`all`**: 提取所有文本内容，包括隐藏元素
- **`innerText`**: 使用 `element.innerText` 提取文本
- **`textContent`**: 使用 `element.textContent` 提取文本

## 使用示例

### 在 AI 助手中使用

1. **读取网页内容**:
   ```
   请使用 get_page_text 工具读取 https://news.ycombinator.com 的内容
   ```

2. **提取特定元素**:
   ```
   请读取当前页面中所有 h2 标题的文本
   ```

3. **等待动态内容加载**:
   ```
   请访问 https://example.com 并等待 .content 元素加载完成后提取文本
   ```

### 直接测试

运行测试脚本来验证功能：

```bash
npm run build
# 运行Chrome浏览器测试
node dist/test-chrome-server.js
```

测试将会：
1. 启动可见的Chrome浏览器窗口
2. 导航到测试网页
3. 提取页面文本内容
4. 演示各种功能

## 开发

### 项目结构
```
src/
├── index.ts                # MCP 服务器主入口
├── chrome-browser-manager.ts # Chrome浏览器管理器
└── test-chrome-server.ts   # Chrome测试脚本

dist/                       # 编译后的 JavaScript 文件
package.json               # 项目配置
tsconfig.json             # TypeScript 配置
```

### 开发模式
```bash
# 监听文件变化并自动重新编译
npm run dev
```

### 构建
```bash
npm run build
```

## 故障排除

### 常见问题

1. **Chrome浏览器未安装或路径错误**
   确保系统已安装Chrome浏览器，并且路径正确。

2. **权限问题**
   确保有足够的权限运行浏览器，在某些环境中可能需要额外的参数。

3. **超时错误**
   增加 `timeout` 参数值，特别是对于加载较慢的页面。

4. **内存使用过高**
   定期调用 `close_browser` 工具来释放资源。

### 调试

启用详细日志输出：
```bash
DEBUG=* npm start
```

## 技术栈

- **Node.js**: JavaScript 运行时
- **TypeScript**: 类型安全的 JavaScript
- **Puppeteer**: Chrome浏览器自动化
- **MCP SDK**: Model Context Protocol 官方 SDK
- **Zod**: 运行时类型验证

## 许可证

MIT License

## 贡献

欢迎提交 Issue 和 Pull Request！

## 更新日志

### v1.0.0
- 初始版本
- 支持基本的页面文本提取功能
- 支持多种文本提取类型
- 完整的 MCP 协议支持