# playwright-mcp-server

**Repository Path**: warm_joy/playwright-mcp-server

## Basic Information

- **Project Name**: playwright-mcp-server
- **Description**: 123313121312312313
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-02-04
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Playwright MCP Server - 本地模型版本

基于 FastMCP 的 Playwright 文档检索服务，使用**纯本地模型**运行，无需 API Key，保护数据隐私。

## ✨ 特性

- 🏠 **完全本地运行** - 无需任何外网大模型 API
- 🔒 **数据隐私** - 所有数据本地处理
- 🚀 **开箱即用** - 自动下载和配置模型
- 🌐 **多种访问方式** - stdio、HTTP、直接调用
- 🇨🇳 **中文优化** - 使用针对中文优化的嵌入模型

## 🚀 快速开始

### 1. 安装依赖

```bash
pip install -r requirements.txt
```

### 2. 自动设置

```bash
python scripts/setup_local_models.py
```

这个脚本会：
- ✅ 检查 Python 依赖
- ✅ 下载并配置嵌入模型
- ✅ 初始化向量库
- ✅ 测试 MCP 服务器

### 3. 启动服务器

```bash
# stdio 模式（Claude Desktop）
python src/run.py

# HTTP 模式（远程访问）
python src/run_http.py --host localhost --port 8000
```

## 📦 使用的模型

### 嵌入模型

- **模型**: `BAAI/bge-small-zh-v1.5`
- **大小**: 102MB
- **特点**: 中文优化，轻量级
- **无需 API Key**

首次运行会自动下载模型到本地缓存。

## 🎯 使用方式

### 方式 1: 直接调用工具（最简单）

```python
from src.tools import search_playwright_docs_detailed

result = search_playwright_docs_detailed("如何定位元素", k=3)
print(result)
```

### 方式 2: MCP 服务器（Claude Desktop）

配置 Claude Desktop：

```json
{
  "mcpServers": {
    "playwright-docs": {
      "command": "python",
      "args": ["D:/path/to/playwright-mcp-server/src/run.py"]
    }
  }
}
```

### 方式 3: HTTP API（远程访问）

```bash
# 启动服务器
python src/run_http.py

# 调用 API
curl -X POST http://localhost:8000/sse \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "search_docs_detailed",
      "arguments": {"query": "如何定位元素", "k": 3}
    }
  }'
```

### 方式 4: Python 客户端

```python
from examples.http_client import MCPHTTPClient

client = MCPHTTPClient()
result = client.search_docs_detailed("如何定位元素", k=3)
print(result)
```

## 🛠️ 可用工具

| 工具 | 描述 |
|------|------|
| `search_docs` | 基础文档搜索 |
| `search_docs_detailed` | 详细搜索（推荐） |
| `search_docs_with_score` | 带相似度评分的搜索 |
| `get_topic` | 主题深度探索 |
| `get_code_examples` | 代码示例搜索 |
| `get_vector_store_info` | 向量库信息 |

查看详细列表：

```bash
python scripts/list_tools_simple.py
```

## 📚 文档

- [本地模型使用指南](docs/LOCAL_MODELS.md) - 模型配置、性能优化
- [HTTP API 文档](docs/HTTP_INTEGRATION.md) - HTTP 接口说明
- [工具列表](docs/TOOLS.md) - 完整工具文档

## 🔧 高级配置

### 更换嵌入模型

```bash
# 使用更小的模型（速度更快）
export EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2

# 使用更大的模型（效果更好）
export EMBEDDING_MODEL=BAAI/bge-base-zh-v1.5

# 重新初始化向量库
python scripts/init_docs.py --clear
```

### 使用 GPU 加速

```bash
# 安装 GPU 版本的 PyTorch
pip install torch --index-url https://download.pytorch.org/whl/cu118

# 代码中会自动检测并使用 GPU
```

### 自定义分块大小

```bash
# 更大的分块（更多上下文）
python scripts/init_docs.py --chunk-size 1000 --chunk-overlap 150

# 更小的分块（更精确）
python scripts/init_docs.py --chunk-size 500 --chunk-overlap 50
```

## 🐛 常见问题

### Q: 模型下载失败

A: 使用 HuggingFace 镜像：

```bash
export HF_ENDPOINT=https://hf-mirror.com
python scripts/setup_local_models.py
```

### Q: 内存不足

A: 使用更小的模型：

```bash
export EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
python scripts/init_docs.py --clear
```

### Q: 搜索结果不准确

A: 尝试：
1. 增加返回结果数量 `k=5`
2. 使用更大的模型 `bge-base-zh-v1.5`
3. 调整相似度阈值 `min_similarity=0.5`

更多问题参考：[本地模型使用指南](docs/LOCAL_MODELS.md)

## 📊 性能对比

| 模型 | 大小 | 速度 | 准确率 | 推荐场景 |
|------|------|------|--------|----------|
| bge-small-zh | 102MB | ⚡⚡⚡⚡⚡ | ⭐⭐⭐⭐ | 日常使用（默认） |
| bge-base-zh | 400MB | ⚡⚡⚡⚡ | ⭐⭐⭐⭐⭐ | 精确搜索 |
| bge-large-zh | 1.3GB | ⚡⚡⚡ | ⭐⭐⭐⭐⭐ | 生产环境 |
| all-MiniLM-L6-v2 | 80MB | ⚡⚡⚡⚡⚡ | ⭐⭐⭐ | 英文文档 |

## 🎬 使用示例

### 示例 1: 搜索文档

```python
from src.tools import search_playwright_docs_detailed

# 搜索如何定位元素
result = search_playwright_docs_detailed("定位元素", k=3)
print(result)

# 搜索带相似度分数
from src.tools import search_playwright_docs_with_score
result = search_playwright_docs_with_score("输入框", k=3, min_similarity=0.5)
print(result)
```

### 示例 2: 获取代码示例

```python
from src.tools import get_playwright_code_examples

# 获取 click 相关代码
examples = get_playwright_code_examples("click", k=5)
print(examples)
```

### 示例 3: 主题探索

```python
from src.tools import get_playwright_topic

# 深入了解等待机制
content = get_playwright_topic("等待机制", k=8)
print(content)
```

## 🏗️ 项目结构

```
playwright-mcp-server/
├── src/
│   ├── server.py          # MCP 服务器
│   ├── run.py             # stdio 启动脚本
│   ├── run_http.py        # HTTP 启动脚本
│   ├── tools/             # 工具函数
│   ├── services/          # 向量检索服务
│   ├── model/             # 模型配置
│   ├── config/            # 配置管理
│   ├── rag/               # RAG 模块（向量库、文档加载）
│   └── data/              # 数据文件（Playwright 文档）
├── examples/
│   ├── http_client.py     # Python 客户端
│   └── http_client.js     # Node.js 客户端
├── docs/                  # 文档
└── scripts/               # 辅助脚本（初始化、设置）
```

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

## 📄 许可证

MIT License

---

**特别说明**: 本项目专注于本地模型，完全移除了外网大模型依赖（OpenAI、Anthropic、DashScope 等），保护用户数据隐私。