Percepta MCP Server

基于模型上下文协议（MCP）的强大工具集合，提供浏览器自动化、AI分析、视觉处理、网页爬虫、自动化测试生成和DevTools分析等功能。

本项目专为本地单用户使用设计，不适合公开部署。

快速开始

环境要求

• Python 3.12+
• uv (推荐) 或 pip

本地安装运行

# 克隆项目
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 部署

# 配置环境变量
cp .env.example .env
# 编辑 .env 文件

# 构建并启动
docker-compose up -d

# 查看状态
docker-compose ps
curl http://localhost:8000/health

MCP 客户端配置

Claude Desktop

编辑配置文件 claude_desktop_config.json:

本地运行配置:

{
  "mcpServers": {
    "percepta-mcp": {
      "command": "uv",
      "args": ["run", "python", "-m", "src.percepta_mcp.server"],
      "cwd": "/path/to/percepta-mcp"
    }
  }
}

Docker 配置:

{
  "mcpServers": {
    "percepta-mcp": {
      "command": "docker",
      "args": ["exec", "percepta-mcp", "uv", "run", "python", "-m", "src.percepta_mcp.server"]
    }
  }
}

VS Code

配置 settings.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 分析: 性能监控、异常检测

项目结构

percepta-mcp/
├── src/percepta_mcp/
│   ├── server.py          # MCP 服务器主入口
│   ├── config.py          # 配置管理
│   ├── ai_router.py       # AI 提供商路由
│   └── tools/             # 工具模块
├── tests/                 # 测试文件
├── .env.example           # 环境变量模板
├── docker-compose.yml     # Docker 部署配置
└── Dockerfile             # Docker 镜像构建

测试

# 运行所有测试
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