# Percepta MCP Server 使用指南
## 概述
Percepta MCP Server 是一个强大的模型上下文协议（MCP）服务器，提供以下功能：
- **AI模型路由**: 支持 OpenAI、Anthropic、Google Gemini、Ollama 等多个AI提供商
- **浏览器自动化**: 基于 Playwright 的网页自动化功能
- **视觉分析**: 图像处理、OCR、对象检测等
- **网络爬虫**: 结构化数据提取、表单分析等
## 安装与设置
### 1. 安装依赖
```bash
# 克隆项目
git clone <repository-url>
cd percepta-mcp
# 使用 uv 安装依赖
uv venv
uv pip install -e .
# 使用 uv 同步依赖
uv pip sync
uv pip install -e ".[dev]"
```
### 2. 安装浏览器驱动
```bash
# 安装 Playwright 浏览器
playwright install chromium
```
### 3. 配置环境变量
复制示例配置文件并根据需要修改：
```bash
cp config.example.yaml config.yaml
```
设置 API 密钥（可选）：
```bash
export OPENAI_API_KEY="your-openai-api-key"
export ANTHROPIC_API_KEY="your-anthropic-api-key"
export GOOGLE_API_KEY="your-google-api-key"
```
## 运行服务器
### 基本运行
```bash
python -m src.percepta_mcp.server
```
### 使用配置文件
```bash
python -m src.percepta_mcp.server --config config.yaml --log-level DEBUG
```
### 测试服务器
```bash
python test_server.py
```
## 可用工具
### 浏览器自动化工具
1. **browser_navigate** - 导航到指定URL
```json
{
"url": "https://example.com",
"wait_for": "networkidle"
}
```
2. **browser_click** - 点击页面元素
```json
{
"selector": "button#submit",
"timeout": 5000
}
```
3. **browser_fill** - 填写表单字段
```json
{
"selector": "input[name='username']",
"text": "myusername"
}
```
4. **browser_screenshot** - 截取页面截图
```json
{
"full_page": true
}
```
5. **browser_extract_text** - 提取页面文本
```json
{
"selector": ".content"
}
```
6. **browser_wait_for_element** - 等待元素出现
```json
{
"selector": ".loading",
"timeout": 10000,
"state": "visible"
}
```
### 视觉分析工具
1. **analyze_image** - 分析图像内容
```json
{
"image_data": "base64_encoded_image",
"analysis_type": "general",
"prompt": "描述这张图片"
}
```
2. **extract_text_from_image** - 从图像提取文本（OCR）
```json
{
"image_data": "base64_encoded_image",
"language": "eng"
}
```
3. **compare_images** - 比较两张图像
```json
{
"image1_data": "base64_encoded_image1",
"image2_data": "base64_encoded_image2",
"method": "structural"
}
```
### 网络爬虫工具
1. **scrape_website** - 爬取网站内容
```json
{
"url": "https://example.com",
"selector": ".content",
"extract_type": "text"
}
```
2. **extract_structured_data** - 提取结构化数据
```json
{
"url": "https://example.com",
"extract_type": "structured"
}
```
### AI交互工具
1. **ai_analyze** - AI内容分析
```json
{
"content": "要分析的内容",
"task": "总结这段文本",
"model": "gpt-4"
}
```
2. **ai_generate** - AI内容生成
```json
{
"prompt": "写一个关于AI的短文",
"model": "claude-sonnet"
}
```
3. **ai_chat** - AI对话
```json
{
"message": "你好，请介绍一下自己",
"conversation_id": "unique-session-id",
"model": "gemini-free"
}
```
### 自动化测试生成工具
1. **generate_test_case** - 生成自动化测试用例
```json
{
"url": "https://example.com",
"description": "测试登录页面功能",
"test_type": "form",
"elements": [
{"description": "用户名输入框", "selector": "#username"},
{"description": "密码输入框", "selector": "#password"}
]
}
```
2. **execute_test_case** - 执行生成的测试用例
```json
{
"test_case_path": "/path/to/test_case.py",
"timeout": 60
}
```
3. **generate_and_execute_test** - 生成并立即执行测试用例
```json
{
"url": "https://example.com/form",
"description": "测试表单提交流程",
"test_type": "e2e"
}
```
### DevTools 数据分析工具
1. **start_devtools_monitoring** - 开始监控 DevTools 数据
```json
{
"url": "https://example.com",
"monitoring_types": ["console", "network", "performance"]
}
```
2. **collect_devtools_data** - 收集当前 DevTools 数据
```json
{
"include_raw_data": true
}
```
3. **analyze_devtools_anomalies** - 分析 DevTools 数据异常
```json
{
"severity_filter": "high"
}
```
4. **generate_devtools_report** - 生成 DevTools 分析报告
```json
{
"include_recommendations": true,
"format": "json"
}
```
5. **monitor_and_analyze_page** - 完整的页面监控和分析
```json
{
"url": "https://example.com",
"duration_seconds": 30,
"include_performance": true
}
```
## 配置说明
### AI提供商配置
```yaml
ai_providers:
openai:
api_key: "your-key"
enabled: true
models:
- "gpt-4"
- "gpt-3.5-turbo"
anthropic:
api_key: "your-key"
enabled: true
models:
- "claude-3-sonnet"
ollama:
base_url: "http://localhost:11434"
enabled: true
models:
- "llama2"
```
### 路由策略
```yaml
routing:
default_provider: "gpt-4"
priority_order:
- "gpt-4"
- "claude-sonnet"
- "gemini-free"
failover_enabled: true
max_retries: 3
```
### 速率限制
```yaml
rate_limits:
requests_per_minute: 60
burst_size: 10
per_provider:
openai: 100
anthropic: 50
```
## 故障排除
### 常见问题
1. **API密钥错误**
- 确保正确设置环境变量
- 检查配置文件中的密钥设置
2. **浏览器启动失败**
- 运行 `playwright install` 安装浏览器
- 检查系统是否有必要的依赖
3. **依赖安装问题**
- 使用 `uv sync` 重新安装依赖
- 检查 Python 版本（需要 3.12+）
### 日志调试
启用详细日志：
```bash
python -m src.percepta_mcp.server --log-level DEBUG
```
## 开发与扩展
### 添加新工具
1. 在 `src/percepta_mcp/tools/` 目录下创建新的工具模块
2. 在 `server.py` 中注册新工具
3. 更新工具列表和处理逻辑
### 添加新的AI提供商
1. 在 `ai_router.py` 中实现新的提供商类
2. 继承 `AIProvider` 基类
3. 在配置中添加新提供商设置
## 许可证
本项目遵循 MIT 许可证。
