# Web Search Router — MCP-сервер на Cloudflare

Remote MCP-сервер на Cloudflare Workers. Единая точка веб-поиска, которая маршрутизирует запросы между разными источниками и работает как «умный роутер».

## Что делает
Принимает MCP-вызов `web_search` и отдаёт нормализованный результат (список ссылок и/или синтезированный ответ с цитатами). Внутри выбирает подходящий источник, следит за квотами и переключается (fallback) при исчерпании лимитов или ошибках.

## Источники (3 типа)
1. **HTTP-API поисковиков**: Tavily, Exa, Serper, Brave, SerpAPI.
2. **Внешние MCP-серверы** (MCP-of-MCPs): роутер подключается как клиент к другим remote MCP search-серверам через `MCPClientManager`.
3. **LLM-поиск с веб-grounding** (как у Gemini): Google Gemini `google_search`, Perplexity Sonar, опц. OpenAI `web_search` — отдают синтезированный ответ + цитаты.

## Ключевые возможности
- **Учёт квот/лимитов** по каждому провайдеру с авто-fallback при превышении или ошибке (хранится в Durable Object).
- **Умный выбор источника** в зависимости от типа поиска (`general/news/research/shopping`) и режима выдачи (`results/answer/auto`).
- **Подключение к другим MCP-серверам** как к провайдерам.
- **LLM-поиск**: готовый ответ с цитатами, когда нужен синтез, а не список ссылок.
- **Мульти-аккаунт (пул ключей)**: несколько ключей к одному сервису; квота и кулдаун на каждый ключ отдельно, балансировка и fallback между ключами того же провайдера, затем между провайдерами.
- **REST API для встраивания**: HTTP JSON-API `/api/*` (`POST /api/search`, `GET /api/health`) повторяет параметры `web_search` — для прямого вызова из кода/фронтенда; CORS, опц. `API_TOKEN`.

## Текущий статус
- **Greenfield**: каталог пуст, кода пока нет.
- План реализации утверждён пользователем, но **реализация ещё не начата**.
- API-ключи провайдеров и список внешних MCP-серверов ожидаются от пользователя.

## Структура документации
| Файл | О чём |
| --- | --- |
| `architecture.md` | Архитектура, поток запроса, компоненты, диаграмма |
| `packages.md` | Архитектура пакетов (npm workspaces monorepo, в стиле pi agent) |
| `providers.md` | Все провайдеры (HTTP/MCP/LLM), API, нормализованная схема |
| `routing.md` | Умный роутер: режим выдачи, классификация, селектор, fallback |
| `quota.md` | Quota Durable Object: состояние, RPC, кулдаун, сброс периода |
| `setup.md` | Стек, зависимости, конфиг, секреты, локальная разработка, деплой, тесты |
| `api.md` | REST JSON-API для встраивания в код (`/api/*`) |
| `decisions.md` | Принятые решения, риски, что вне объёма, открытые вопросы |

> План реализации (актуальный) хранится в системе планов (`create_plan`/`edit_plans`). Эта документация — производное снимок-описание для контекста новых сессий.

## Стек
Cloudflare Workers, TypeScript, npm workspaces monorepo (пакеты `@wed/*`, см. `packages.md`), пакет `agents` (`McpAgent`), `@modelcontextprotocol/sdk`, Streamable HTTP transport на `/mcp`. Тесты — `vitest`.