# 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 协议支持
