# Percepta MCP Server
基于模型上下文协议（MCP）的强大工具集合，提供浏览器自动化、AI分析、视觉处理、网页爬虫、自动化测试生成和DevTools分析等功能。
**本项目专为本地单用户使用设计，不适合公开部署。**
## 快速开始
### 环境要求
- Python 3.12+
- uv (推荐) 或 pip
### 本地安装运行
```bash
# 克隆项目
git clone <repository-url>
cd percepta-mcp
# 安装依赖 (推荐使用 uv)
uv venv
uv sync
# 配置环境变量
cp .env.example .env
# 编辑 .env 文件，添加您的 API 密钥
# 安装浏览器驱动
uv run playwright install chromium
# 启动服务
uv run python -m src.percepta_mcp.server
```
### Docker 部署
```bash
# 配置环境变量
cp .env.example .env
# 编辑 .env 文件
# 构建并启动
docker-compose up -d
# 查看状态
docker-compose ps
curl http://localhost:8000/health
```
## MCP 客户端配置
### Claude Desktop
编辑配置文件 `claude_desktop_config.json`:
**本地运行配置**:
```json
{
"mcpServers": {
"percepta-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "src.percepta_mcp.server"],
"cwd": "/path/to/percepta-mcp"
}
}
}
```
**Docker 配置**:
```json
{
"mcpServers": {
"percepta-mcp": {
"command": "docker",
"args": ["exec", "percepta-mcp", "uv", "run", "python", "-m", "src.percepta_mcp.server"]
}
}
}
```
### VS Code
配置 `settings.json`:
```json
{
"mcp.servers": {
"percepta-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "src.percepta_mcp.server"],
"cwd": "${workspaceFolder}"
}
}
}
```
## 功能特性
- **浏览器自动化**: 页面导航、元素交互、截图、表单操作
- **AI 智能分析**: 支持 OpenAI、Anthropic、Google、Ollama
- **视觉处理**: 图像分析、OCR、对象检测
- **网页爬虫**: 智能数据提取、结构化爬取
- **自动化测试**: AI 驱动的测试用例生成和执行
- **DevTools 分析**: 性能监控、异常检测
## 项目结构
```tree
percepta-mcp/
├── src/percepta_mcp/
│ ├── server.py # MCP 服务器主入口
│ ├── config.py # 配置管理
│ ├── ai_router.py # AI 提供商路由
│ └── tools/ # 工具模块
├── tests/ # 测试文件
├── .env.example # 环境变量模板
├── docker-compose.yml # Docker 部署配置
└── Dockerfile # Docker 镜像构建
```
## 测试
```bash
# 运行所有测试
uv run pytest
# 带覆盖率报告
uv run pytest --cov=src --cov-report=html
```
当前测试覆盖率: **89%** (209个测试全部通过)
## 环境变量
关键环境变量配置：
- `OPENAI_API_KEY`: OpenAI API 密钥
- `ANTHROPIC_API_KEY`: Anthropic API 密钥
- `GOOGLE_API_KEY`: Google AI API 密钥
- `PERCEPTA_HOST`: 服务监听地址 (默认: 0.0.0.0)
- `PERCEPTA_PORT`: 服务端口 (默认: 8000)
- `PERCEPTA_LOG_LEVEL`: 日志级别 (默认: INFO)
## 许可证
MIT License
