web-basics-mcp

Небольшие, надежные веб-инструменты для агентов. Без ключей API и без встроенной инфраструктуры.

Инструменты

fetch_url возвращает чистый Markdown для HTML-страниц и постов Reddit, выбираемый текст для PDF, прямой контент для текстовых/Markdown/JSON/XML ответов и нативный MCP-контент изображений для PNG, JPEG, WebP и GIF.

Длинный текст читается ограниченными частями. Вызовите тот же URL снова с возвращенным next_start_index:

{
  "url": "https://example.com/long-page",
  "start_index": 8000,
  "max_length": 8000
}

Успешные загрузки кэшируются в памяти на пять минут, поэтому чтения со смещением обычно используют один и тот же извлеченный документ. Результаты поиска кэшируются на две минуты, чтобы избежать повторения одинаковой работы SearXNG во время выполнения агента. Оба кэша ограничены, объединяют одновременные дублирующиеся запросы и могут быть отброшены в любое время; корректность инструментов от них никогда не зависит.

Related MCP server: Basic MCP Tools

Требования

• Node.js 20.18.1 или новее

• Существующий экземпляр SearXNG с включенными JSON-ответами

Укажите его базовый URL в переменной окружения или в файле .env этого пакета:

SEARXNG_URL=http://127.0.0.1:8088

Сервер запускается, даже если SearXNG недоступен, поэтому fetch_url остается работоспособным. Вызовы web_search возвращают четкую ошибку соединения, пока SearXNG не станет доступен.

Установка

git clone https://github.com/yoloyash/web-basics-mcp.git
cd web-basics-mcp
npm install
npm run build

Настройте MCP-клиент для запуска build/index.js через stdio. Например:

codex mcp add web-basics -- node /absolute/path/to/web-basics-mcp/build/index.js

Входные данные инструментов

web_search

{
  "query": "Model Context Protocol",
  "limit": 5
}

limit по умолчанию равен 5 и принимает значения от 1 до 10. Результаты имеют стабильную структуру {link, title, snippet}.

fetch_url

{
  "url": "https://example.com",
  "start_index": 0,
  "max_length": 8000
}

• start_index по умолчанию равен 0.

• max_length по умолчанию равен 8000 и ограничен 20000.

• Текстовые ответы сообщают total_chars, returned_chars, truncated и, если осталось больше контента, next_start_index.

• HTML сначала использует Defuddle, а Mozilla Readability — как условный запасной вариант. Ответ сообщает выбранный extractor и причину использования запасного варианта, если применимо.

• Дополнительные сетевые экстракторы Defuddle отключены. Каждый удаленный запрос остается в проверенном HTTP-пути этого сервера.

• URL-адреса постов Reddit загружаются через RSS-ленту Reddit и включают пост и комментарии, доступные в этой ленте. RSS может содержать меньше комментариев, чем веб-сайт.

Безопасность и ограничения

• Принимаются только публичные HTTP(S) URL.

• Учетные данные в URL, частные имена хостов, частные DNS-результаты и небезопасные перенаправления отклоняются.

• Каждое перенаправление проверяется независимо.

• Запросы используют тайм-ауты, ограниченные повторные попытки, лимиты размера ответа и стабильный user-agent.

• Стандартные ответы и изображения ограничены 5 МиБ; PDF — 15 МиБ.

• Кэширование загрузок учитывает Cache-Control: no-store, no-cache и max-age=0.

Этот сервер намеренно не предоставляет автоматизацию браузера, рендеринг JavaScript, сканирование, аутентификацию, куки, маршрутизацию через прокси/VPN или синтез ответов.

Разработка

npm test
npm pack --dry-run

Тесты используют сохраненные фикстуры и локальные заглушки, а не многократные запросы к публичным сервисам.