Ref MCP

Сервер ModelContextProtocol, который предоставляет вашему инструменту для программирования с ИИ или агенту доступ к документации по API, сервисам, библиотекам и т. д. Это универсальное решение, позволяющее поддерживать актуальность документации вашего агента быстрым и эффективным с точки зрения токенов способом.

Дополнительную информацию можно найти на ref.tools

Агентский поиск для получения именно того контекста, который нужен

Инструменты Ref разработаны так, чтобы соответствовать тому, как модели выполняют поиск, используя при этом как можно меньше контекста для уменьшения деградации контекста. Цель состоит в том, чтобы найти именно тот контекст, который необходим вашему агенту для успешной работы, используя минимум токенов.

В зависимости от сложности запроса, LLM-агенты для программирования, такие как Claude Code, обычно выполняют один или несколько поисков, а затем выбирают несколько ресурсов для более глубокого изучения.

Для простого запроса о REST API комментариев Figma он сделает пару вызовов, чтобы получить именно то, что нужно:

SEARCH 'Figma API post comment endpoint documentation' (54 tokens)
READ https://www.figma.com/developers/api#post-comments-endpoint (385 tokens)

Для более сложных ситуаций LLM будет пытаться уточнить свой запрос по мере чтения результатов. Например:

SEARCH 'n8n merge node vs Code node multiple inputs best practices' (126)
READ https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.merge/#merge (4961)
READ https://docs.n8n.io/flow-logic/merging/#merge-data-from-multiple-node-executions (138)
SEARCH 'n8n Code node multiple inputs best practices when to use' (107)
READ https://docs.n8n.io/code/code-node/#usage (80)
SEARCH 'n8n Code node access multiple inputs from different nodes' (370)
SEARCH 'n8n Code node $input access multiple node inputs' (372)
READ https://docs.n8n.io/code/builtin/output-other-nodes/#output-of-other-nodes (2310)

Ref использует сессии MCP для отслеживания траектории поиска и минимизации использования контекста. У нас в разработке еще много идей, но вот что мы реализовали на данный момент.

1. Фильтрация результатов поиска

При повторных похожих поисках в рамках одной сессии Ref никогда не будет возвращать повторяющиеся результаты. Традиционно вы углубляетесь в результаты поиска, переходя к следующей странице, но этот подход позволяет агенту одновременно перелистывать страницы И корректировать запрос.

2. Получение той части страницы, которая имеет значение

При чтении страницы документации Ref будет использовать историю поиска сессии агента, чтобы отсеять менее релевантные разделы и вернуть наиболее релевантные 5 тыс. токенов. Это помогает Ref избежать большой проблемы стандартного веб-скрейпинга с помощью fetch(), когда при обращении к большой странице документации вы можете легко получить в контекст более 20 тыс. токенов, большинство из которых не имеют отношения к делу.

Related MCP server: Firebase Realtime Database

Почему минимизация токенов из контекста документации имеет значение?

1. Больше контекста делает модели «глупее»

Хорошо задокументировано, что по состоянию на июль 2025 года модели становятся «глупее» при увеличении количества токенов. Вы, возможно, слышали о том, что модели теперь отлично справляются с длинным контекстом, и это отчасти правда, но это не вся картина. Для краткого ознакомления с некоторыми исследованиями посмотрите это видео от команды Chroma.

2. Токены стоят $$$

Представьте, что вы используете Claude Opus в качестве фонового агента, и вы начинаете с того, что агент извлекает контекст документации. Предположим, он извлекает 10 000 токенов контекста, из которых 4000 являются релевантными, а 6000 — лишним шумом. При ценах API эти 6 тыс. токенов стоят около $0.09 ЗА ШАГ. Если выполнение одного запроса в итоге занимает 11 шагов с Opus, вы потратили $1 без всякой причины.

Настройка

Существует два варианта настройки Ref в качестве MCP-сервера: через streamable-http сервер (рекомендуется) или локальный stdio сервер (устаревший).

Этот репозиторий содержит устаревший stdio сервер.

Streamable HTTP (рекомендуется)

"Ref": {
  "type": "http",
  "url": "https://api.ref.tools/mcp?apiKey=YOUR_API_KEY"
}

stdio

"Ref": {
  "command": "npx",
  "args": ["ref-tools-mcp@latest"],
  "env": {
    "REF_API_KEY": <sign up to get an api key>
  }
}

Инструменты

Сервер Ref MCP предоставляет все инструменты, связанные с документацией, необходимые вашему агенту.

ref_search_documentation

Мощный инструмент поиска для проверки технической документации. Отлично подходит для поиска фактов или фрагментов кода. Может использоваться для поиска общедоступной документации в Интернете или на GitHub, а также в частных ресурсах, таких как репозитории и PDF-файлы.

Параметры:

• query (обязательно): Запрос для поиска релевантной документации. Это должно быть полное предложение или вопрос.

ref_read_url

Инструмент, который извлекает содержимое по URL и преобразует его в markdown для удобного чтения с помощью Ref. Это мощный инструмент при использовании в сочетании с инструментом ref_search_documentation, который возвращает URL-адреса релевантного контента.

Параметры:

• url (обязательно): URL-адрес веб-страницы для чтения.

Поддержка глубокого исследования OpenAI

Ref можно использовать в качестве источника для глубокого исследования. OpenAI требует специфических определений инструментов, поэтому при использовании с клиентом OpenAI, Ref предоставит те же инструменты с немного другими названиями.

ref_search_documentation(query) -> search(query)
ref_read_url(url) -> fetch(id)

Разработка

npm install
npm run dev

Запуск с помощью Inspector

Для целей разработки и отладки вы можете использовать инструмент MCP Inspector. Inspector предоставляет визуальный интерфейс для тестирования и мониторинга взаимодействий с MCP-сервером.

Посетите документацию Inspector для получения подробных инструкций по настройке.

Для тестирования локально с помощью Inspector:

npm run inspect

Или запустите и watcher, и inspector:

npm run dev

Локальная разработка

1. Клонируйте репозиторий

2. Установите зависимости:

npm install

3. Соберите проект:

npm run build

4. Для разработки с автоматической пересборкой:

npm run watch

Лицензия

MIT