# 🔍 Web Search for Agents (MCP)

> Даёт AI-агентам внутри VS Code доступ к **актуальной информации из интернета** через стандартный протокол **MCP** (Model Context Protocol).

[![VS Code Marketplace](https://img.shields.io/badge/VS%20Code-Extension-blue?logo=visualstudiocode)](https://marketplace.visualstudio.com/)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-Compatible-orange.svg)](https://modelcontextprotocol.io/)

---

## ✨ Зачем это нужно

AI-агенты (GitHub Copilot Agent, Qoder CN, Cline, Roo Code и др.) имеют ограниченный контекст и «устаревшие» знания. Это расширение добавляет им два инструмента:

- **`web_search`** — поиск актуальной информации в интернете
- **`fetch_url`** — получение очищенного текста любой веб-страницы

Агент **сам решает**, когда и какой инструмент использовать — вы просто задаёте вопрос, а он ищет свежие данные.

## 🤝 Поддерживаемые агенты

| Агент | Как подключить |
|---|---|
| **GitHub Copilot** (Agent mode) | Автоматически через VS Code MCP API |
| **Qoder CN** (бывший Tongyi Lingma) | Кнопкой `Install to Qoder CN` |
| **Cline** | Кнопкой `Install to Cline` |
| **Roo Code / Continue / Cursor** | Вставкой JSON-конфига из буфера обмена |

## 🚀 Быстрый старт

### 1. Установка
Установите расширение из Marketplace или через `.vsix`:
```bash
code --install-extension web-search-for-agents-0.1.0.vsix
```

### 2. Откройте панель настроек
Кликните по иконке 🔍 **Web Search** в нижней панели VS Code  
или выполните команду:

### 3. Получите API-ключи (рекомендуется)

| Провайдер | Приоритет | Бесплатный лимит | Где получить |
|---|---|---|---|
| **Tavily** | 1 (лучшее качество) | 1000 запросов/мес | [tavily.com](https://tavily.com) |
| **Brave Search** | 2 | 2000 запросов/мес | [brave.com/search/api](https://brave.com/search/api) |
| **DuckDuckGo** | 3 (fallback) | ∞ без ключа | ключ не нужен |

Вставьте ключи в Webview и нажмите **Сохранить**.

### 4. Установите в вашего агента
- Для **Qoder CN** → нажмите кнопку `Install to Qoder CN`
- Для **Cline** → нажмите кнопку `Install to Cline`
- Для **других агентов** → нажмите `Copy MCP Config` и вставьте JSON в настройки агента

### 5. Работайте!
В режиме Agent спросите у ИИ что-то требующее свежих данных:
> *«Какая сейчас последняя стабильная версия Node.js?»*
> *«Найди актуальные курсы рубля к доллару на сегодня»*
> *«Прочитай содержимое https://example.com и сделай краткий пересказ»*

## 🔧 Как это работает

### Каскад провайдеров поиска
При вызове `web_search` расширение пытается провайдеры **строго по порядку**:

Если провайдер недоступен или вернул ошибку — автоматический переход к следующему. Это гарантирует, что поиск **всегда работает**, даже без ключей.

### Инструменты MCP

| Инструмент | Параметры | Описание |
|---|---|---|
| `web_search` | `query` (обязательный), `num_results` (1–10, по умолч. 6) | Поиск в интернете, возврат заголовка, URL и сниппета |
| `fetch_url` | `url` (обязательный) | Загрузка страницы и возврат очищенного основного текста (скрипты/стили убраны, ~20 000 символов) |

### Безопасность
- 🔐 API-ключи хранятся в **VS Code Secret Storage** (не в `settings.json`)
- 🔐 Ключи передаются в MCP-сервер через **переменные окружения** (не попадают в конфиг)
- 🔐 `fetch_url` принимает только `http://` и `https://` (защита от `file://`, `ftp://` и т.п.)

## 🎛️ Команды расширения

Все команды доступны через `Ctrl+Shift+P`:

- `Web Search: Open Settings Panel` — открыть Webview с настройками
- `Web Search: Set Tavily API Key` — ввести/обновить ключ Tavily
- `Web Search: Set Brave API Key` — ввести/обновить ключ Brave
- `Web Search: Clear API Keys` — удалить все ключи
- `Web Search: Install to Qoder CN` — прописать сервер в `mcp.json` Qoder CN
- `Web Search: Install to Cline` — прописать сервер в конфиг Cline
- `Web Search: Copy MCP Config` — скопировать JSON-конфиг в буфер обмена

## 📦 Ручная установка MCP-сервера

Если ваш агент не поддерживается кнопками установки, вставьте в его `mcp.json` (путь зависит от агента):

```json
{
  "mcpServers": {
    "web-search-for-agents": {
      "command": "node",
      "args": [
        "C:\\путь\\к\\расширению\\dist\\server.js"
      ],
      "env": {
        "TAVILY_API_KEY": "tvly-...",
        "BRAVE_API_KEY": "BSA..."
      }
    }
  }
}
```

> **Важно:** требуется Node.js ≥ 18. Путь к `server.js` должен быть абсолютным.

## 🛠️ Для разработчиков### Тестирование сервера без VS Code
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node dist/server.js
```

### Сборка VSIX для публикации
```bash
npm run package
```

## 🗺️ Roadmap

- [ ] Поддержка провайдера **Exa.ai**
- [ ] Поддержка провайдера **Firecrawl** (улучшенный `fetch_url`)
- [ ] Кэширование результатов поиска
- [ ] История последних запросов в Webview
- [ ] Настройка лимита размера страницы в `fetch_url`
- [ ] Индикатор прогресса при поиске

## ❓ Troubleshooting

### Агент не видит инструменты
- Проверьте, что Node.js установлен (`node --version` должно выдавать ≥ 18)
- Перезапустите VS Code после установки расширения
- В Qoder CN: `Settings → MCP Server` — проверьте, что `web-search-for-agents` активен
- В Cline: откройте `cline_mcp_settings.json` и убедитесь, что путь к `server.js` корректный

### Поиск возвращает пустой результат
- DuckDuckGo иногда блокирует частые запросы — добавьте ключ Tavily или Brave
- Проверьте подключение к интернету
- Посмотрите вывод в консоли агента — там могут быть ошибки

### Ключи не сохраняются
- Secret Storage VS Code должен быть доступен (обычно так и есть)
- Попробуйте удалить и ввести ключ заново через Webview

## 📄 Лицензия

MIT © 2026

---

<p align="center">
  Сделано с ❤️ для AI-агентов и разработчиков
</p>

### Сборка из исходников
```bash
git clone https://github.com/your-user/web-search-for-agents
cd web-search-for-agents
npm install
npm run build
```

### Запуск в режиме разработки
1. Откройте проект в VS Code
2. Нажмите `F5` — запустится Extension Development Host
3. Тестируйте команды и Webview

### Структура проекта

web-search-for-agents/
├── src/
│   ├── extension.ts              # Точка входа расширения
│   ├── mcp/
│   │   ├── server.ts             # stdio MCP-сервер
│   │   ├── tools/                # web_search, fetch_url
│   │   └── providers/            # tavily, brave, duckduckgo + cascade
│   ├── commands/                 # Команды и установщики
│   ├── ui/                       # Webview + Status Bar
│   └── utils/                    # Secret Storage, генерация конфигов
├── dist/                         # Собранные бандлы (создаётся при build)
├── build.mjs                     # Сборщик (esbuild)
└── package.json