# Percepta MCP Server

![Python](https://img.shields.io/badge/python-3.12+-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

基于模型上下文协议（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