# Percepta MCP 配置与部署指南
## 📋 配置验证结果
✅ **所有验证测试通过！**
- ✅ 环境变量配置
- ✅ AI 路由逻辑
- ✅ MCP stdio 协议
- ✅ Docker 配置
## 🔧 AI 服务商配置详解
### 支持的 AI 服务商
Percepta MCP 支持以下 AI 服务商，按默认优先级排序：
1. **Ollama (本地)** - 优先级 1 (最高)
- 无需 API 密钥，完全本地运行
- 默认模型：`llama2:7b`
- 成本：免费
2. **Google Gemini** - 优先级 2
- 需要 `GOOGLE_API_KEY`
- 模型：`gemini-pro`
- 成本：低
3. **Anthropic Claude** - 优先级 3
- 需要 `ANTHROPIC_API_KEY`
- 模型：`claude-3-sonnet-20240229`
- 成本：中等
4. **OpenAI GPT** - 优先级 4 (最低)
- 需要 `OPENAI_API_KEY`
- 模型：`gpt-4-turbo-preview`
- 成本：最高
### AI 服务商选择逻辑
#### 多个 AI 服务商配置时
系统按以下逻辑选择 AI 服务商：
1. **优先级排序**: 数字越小优先级越高 (1 > 2 > 3 > 4)
2. **可用性检查**: 检查 API 密钥是否配置
3. **速率限制**: 检查是否达到请求限制
4. **故障转移**: 如果首选服务商失败，自动切换到下一个
```python
# 选择逻辑示例
providers = [
"ollama-local (priority=1, available=True)",
"gemini-free (priority=2, available=True if GOOGLE_API_KEY set)",
"claude-sonnet (priority=3, available=True if ANTHROPIC_API_KEY set)",
"gpt-4 (priority=4, available=True if OPENAI_API_KEY set)"
]
# 实际选择：优先级最高且可用的服务商
```
#### 只配置一个 AI 服务商时
- 如果只配置了一个服务商的 API 密钥，系统将使用该服务商
- Ollama 始终可用（本地服务，无需 API 密钥）
- 如果所有配置的服务商都不可用，将回退到 Ollama
### 环境变量配置
#### 基础配置（最少配置）
```bash
# 只使用本地 Ollama（无需其他配置）
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_DEFAULT_MODEL=llama2:7b
```
#### 单个云服务商配置
```bash
# 选项 A: 只使用 Google Gemini
GOOGLE_API_KEY=your_google_api_key_here
# 选项 B: 只使用 Anthropic Claude
ANTHROPIC_API_KEY=your_anthropic_api_key_here
# 选项 C: 只使用 OpenAI GPT
OPENAI_API_KEY=your_openai_api_key_here
```
#### 多服务商配置
```bash
# 配置多个服务商（推荐）
OPENAI_API_KEY=your_openai_api_key_here
ANTHROPIC_API_KEY=your_anthropic_api_key_here
GOOGLE_API_KEY=your_google_api_key_here
# 自定义优先级（可选）
AI_PROVIDER_PRIORITY=gemini-free:1,ollama-local:2,claude-sonnet:3,gpt-4:4
# 默认回退服务商（可选）
DEFAULT_AI_PROVIDER=ollama-local
```
#### 完整配置示例
```bash
# AI Provider API Keys
OPENAI_API_KEY=sk-your-openai-key-here
ANTHROPIC_API_KEY=sk-ant-your-anthropic-key-here
GOOGLE_API_KEY=your-google-api-key-here
# Ollama 本地配置
OLLAMA_BASE_URL=http://localhost:11434
OLLAMA_DEFAULT_MODEL=llama3:8b
# AI 服务商优先级自定义
AI_PROVIDER_PRIORITY=ollama-local:1,gemini-free:2,claude-sonnet:3,gpt-4:4
DEFAULT_AI_PROVIDER=ollama-local
# MCP 服务配置
PERCEPTA_LOG_LEVEL=INFO
# 浏览器配置
DEFAULT_BROWSER=chromium
HEADLESS_MODE=true
BROWSER_TIMEOUT=30000
# 功能开关
ENABLE_OCR=true
ENABLE_VISUAL_ANALYSIS=true
ENABLE_COST_TRACKING=true
```
## 🚀 部署验证
### 本地启动验证
```bash
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env 文件，至少配置一个 AI 服务商
# 2. 安装依赖
uv sync
uv run playwright install chromium
# 3. 启动 MCP 服务器
uv run python -m src.percepta_mcp.server
# 4. 验证日志输出
# 应该看到类似输出：
# INFO:src.percepta_mcp.ai_router:Initialized provider: ollama-local (ollama)
# INFO:src.percepta_mcp.ai_router:Initialized provider: gemini-free (google)
# INFO:__main__:Percepta MCP Server started with stdio transport
```
### Docker 部署验证
```bash
# 1. 配置环境变量
cp .env.example .env
# 编辑 .env 文件
# 2. 构建并启动
docker-compose up -d
# 3. 检查容器状态
docker-compose ps
# 应该显示 percepta-mcp 容器正在运行
# 4. 查看日志
docker-compose logs percepta-mcp
# 应该看到成功启动的日志
# 5. 健康检查
docker-compose exec percepta-mcp pgrep -f "python.*percepta_mcp"
# 应该返回进程 ID
```
### MCP 客户端配置验证
#### Claude Desktop 配置
```json
{
"mcpServers": {
"percepta-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "src.percepta_mcp.server"],
"cwd": "/path/to/percepta-mcp"
}
}
}
```
#### VS Code MCP 配置
```json
{
"mcp.servers": {
"percepta-mcp": {
"command": "uv",
"args": ["run", "python", "-m", "src.percepta_mcp.server"],
"cwd": "/path/to/percepta-mcp"
}
}
}
```
## 🔍 常见问题解决
### Q: 如何验证 AI 服务商是否正确配置？
**A: 使用验证脚本**
```bash
uv run python verify_deployment.py
```
### Q: 只想使用本地 Ollama，需要配置什么？
**A: 无需额外配置**
Ollama 是默认配置，确保 Ollama 服务运行即可：
```bash
# 启动 Ollama 服务
ollama serve
# 下载模型（如果需要）
ollama pull llama2:7b
```
### Q: 如何更改 AI 服务商优先级？
**A: 设置 AI_PROVIDER_PRIORITY 环境变量**
```bash
# 示例：优先使用 Gemini，然后是 Claude
AI_PROVIDER_PRIORITY=gemini-free:1,claude-sonnet:2,ollama-local:3,gpt-4:4
```
### Q: Docker 健康检查失败怎么办？
**A: 检查进程和日志**
```bash
# 检查容器进程
docker-compose exec percepta-mcp ps aux | grep python
# 查看详细日志
docker-compose logs -f percepta-mcp
# 手动测试健康检查命令
docker-compose exec percepta-mcp pgrep -f "python.*percepta_mcp"
```
### Q: MCP 客户端连接失败？
**A: 检查协议和路径**
1. 确认使用 stdio 协议（不是 HTTP）
2. 确认工作目录 `cwd` 正确
3. 确认命令路径正确
4. 检查环境变量是否正确设置
## 📊 技术特性总结
- ✅ **标准 MCP stdio 协议**: 完全兼容 MCP 规范
- ✅ **智能 AI 路由**: 自动选择最优 AI 服务商
- ✅ **灵活配置**: 支持任意组合的 AI 服务商
- ✅ **故障转移**: 自动切换到可用服务商
- ✅ **成本优化**: 优先使用免费/低成本服务商
- ✅ **本地优先**: 默认优先使用本地 Ollama
- ✅ **Docker 支持**: 完整的容器化部署
- ✅ **健康监控**: 进程健康检查和日志监控
