内容
# myscrape
[](https://github.com/Bonifatius94/myscrape/actions/workflows/ci.yml)
一个自包含、单代码库的 **网络研究MCP服务器**，适用于本地LLM代理。它模仿了Claude的WebSearch/WebFetch的精神，并添加了一个经过烹饪的`web_research`工具，该工具在本地LLM内部运行整个搜索→获取→合成循环。
📖 **[完整用户指南 → `docs/USER_GUIDE.md`](docs/USER_GUIDE.md)** — 设置、运行（本地/Docker）、工具、配置和故障排除。
## 工具
| 工具 | 级别 | 内置LLM |
| --- | --- | --- |
| `web_search` | 原始 | 否 |
| `web_fetch` | 原始 | 否 |
| `web_research` | 精炼 | 是 |
参见 [`specs/SPEC.md`](specs/SPEC.md) 了解接口合约，以及设计文档：[`specs/IMPLEMENTATION_OPTIONS.md`](specs/IMPLEMENTATION_OPTIONS.md)、[`specs/TECH_STACK.md`](specs/TECH_STACK.md)、[`specs/BENCHMARK.md`](specs/BENCHMARK.md)。决策和检查点记录在 [`specs/DEVLOG.md`](specs/DEVLOG.md) 中；经验性工作在 [`specs/EXPERIMENTS.md`](specs/EXPERIMENTS.md) 中；搜索引擎选项在 [`specs/PROVIDERS.md`](specs/PROVIDERS.md) 中。
## 工具链
仅稳定工具 - 无类型检查器；我们依靠测试 + linting。
- **uv** — 环境、依赖、锁定、运行
- **Ruff** — lint + 格式
- **pytest** — 测试（TDD：红 → 绿 → 重构）
## 快速开始
```bash
uv sync # 创建虚拟环境，安装依赖
uv run pytest # 运行测试套件
uv run ruff check . && uv run ruff format --check . # lint + 格式检查
uv run bench # 运行稳定性基准测试（任何时候）
```
## 运行MCP服务器
```bash
uv run myscrape # 标准输入输出传输 — 本地MCP客户端启动此进程
```
`web_research` 需要本地的、与OpenAI兼容的LLM端点（Ollama / llama.cpp / LM Studio）。通过 `MYSCRAPE_*` 环境变量配置（参见 `src/myscrape/config.py`）：
```bash
export MYSCRAPE_LLM_BASE_URL=http://localhost:11434/v1
export MYSCRAPE_LLM_MODEL=qwen2.5:14b # 12GB GPU上的评估赢家（参见specs/EXPERIMENTS.md）
```
`web_search` 和 `web_fetch` 不需要LLM。已证明的稳定性操作点（8s + 2s抖动）是默认值；使用 `MYSCRAPE_REQUEST_MIN_INTERVAL` 覆盖。
### 在服务器上（Docker）
使用**主机**的原生Ollama（GPU）— 参见 [`specs/SERVING.md`](specs/SERVING.md)。
```bash
ollama pull qwen2.5:14b # 在主机上（评估赢家）
docker compose up --build # myscrape在:8000， 与主机Ollama通信
```
容器是一个进程，包括用于动态获取的Chromium，在 `http://localhost:8000/mcp` 处使用 `streamable-http` 协议，最大并发研究次数为2（GPU序列化合成 — 参见 EXPERIMENTS E-007）。对于自包含的容器内Ollama设置和GPU直通：`docker compose --profile ollama up`。
## 从编码会话（Claude Code）中使用
项目 [`.mcp.json`](.mcp.json) 指向正在运行的服务器：
```bash
claude mcp add --transport http myscrape http://localhost:8000/mcp # 或使用.mcp.json
```
然后 `web_search`、`web_fetch` 和 `web_research` 作为工具在会话中可用。（对于本地使用而无需Docker，运行 `uv run myscrape` 通过标准输入输出代替。）
## 工具
| 工具 | 输入（关键字段） | 返回 |
| --- | --- | --- |
| `web_search` | `query`、`max_results` | 排名结果（无获取，无LLM） |
| `web_fetch` | `url`、`max_tokens` | 清洁的Markdown + 元数据（无LLM） |
| `web_research` | `question`、`effort`、`return_mode` | 引用的答案 + 来源 + 覆盖率 |
## 状态
实现了端到端：所有三个工具、完整的搜索 → 获取 → 排名 → 合成循环，背后是一个稳定性门控 **通过**（`ratelimit_rate == 0`，在可获取的页面上提取100%）。静态 **和** 动态（Playwright）获取工作 — `web_fetch` 自动升级到无头浏览器以获取JS渲染的页面（在 `quotes.toscrape.com/js` 上实时验证）。参见 [`specs/DEVLOG.md`](specs/DEVLOG.md) 获取完整的构建日志和 [`specs/EXPERIMENTS.md`](specs/EXPERIMENTS.md) 获取经验性工作。
