Ref MCP Server

Ref MCP

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

Подробнее см. на ref.tools

Агентный поиск точно подходящего контекста

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

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

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

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 тысяч токенов, большинство из которых нерелевантны.

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

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

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

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

Представьте, что вы используете Claude Opus в качестве фонового агента и начинаете с того, что агент загружает контекст документации, предположим, он загружает 10 000 токенов контекста, из которых 4 000 релевантны, а 6 000 — лишний шум. При ценообразовании 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>
  }
}

Инструменты

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

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

Или запустите и наблюдатель, и инспектор:

npm run dev

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

1. Клонируйте репозиторий
2. Установите зависимости:

npm install

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

npm run build

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

npm run watch

Лицензия

MIT