Полнотекстовый поиск

Обзор

swag2mcp включает встроенный движок полнотекстового поиска (bluge), который индексирует все эндпоинты во всех спецификациях. LLM может искать эндпоинты по методу, пути, описанию или тегу — даже не зная ID эндпоинта.

Как работает индексация

Когда спецификация добавляется или обновляется, каждый эндпоинт индексируется. Следующие поля доступны для поиска:

Поле	Описание	Пример
method	HTTP-метод	GET, POST, PUT
path	Путь эндпоинта API	/api/v1/users/{id}
summary	Краткое описание OpenAPI	"Найти питомца по ID"
tag	Категория эндпоинта	"pets", "users"
_all	Все поля вместе	method + path + tag + summary + spec_domain + collection_title

Индекс перестраивается при каждом запуске MCP-сервера. Он хранится в памяти для быстрого поиска.

Синтаксис запросов

Поиск поддерживает богатый синтаксис запросов для точной фильтрации:

Пример	Описание
pet	Простой текстовый поиск по всем полям
method:GET	Найти все GET-эндпоинты
tag:pets	Найти эндпоинты в теге "pets"
path:"/api/v1/users"	Точное совпадение пути
+method:POST +tag:pet	Должны совпадать оба условия
-method:DELETE	Исключить DELETE-методы
create~	Нечёткий поиск (устойчив к опечаткам)
cr*	Поиск с подстановочным знаком
"find pet"	Поиск фразы
+summary:pet -method:DELETE	Включить "pet" в summary, исключить DELETE

Поиск по полям

Вы можете искать в конкретных полях, используя синтаксис field:value:

method:GET
tag:pets
path:"/pet/findByStatus"
summary:"find pet by status"

Логические операторы

• + — терм должен совпадать (И)
• - — терм не должен совпадать (НЕ)
• Пробел между термами — ИЛИ (любой терм может совпадать)

Нечёткий поиск и подстановочные знаки

• term~ — нечёткий поиск (находит похожие слова, обрабатывает опечатки)
• te* — подстановочный знак (соответствует любым символам)
• te?t — подстановочный знак для одного символа

Примеры

# Найти все GET-запросы
method:GET

# Найти POST-запросы в теге pet
+method:POST +tag:pet

# Найти эндпоинты по точному пути
path:"/pet/findByStatus"

# Найти по описанию
"find pet by status"

# Найти всё, кроме DELETE
+summary:pet -method:DELETE

# Нечёткий поиск "create" (обрабатывает опечатки)
create~

MCP-инструмент

MCP-инструмент search предоставляет доступ к поисковому движку для LLM:

→ search(query: "find pet by status", limit: 5)
← GET /pet/findByStatus — Находит питомцев по статусу
   GET /pet/{petId} — Найти питомца по ID

Параметры

Параметр	Обязательно	Описание
query	Да	Поисковый запрос (поддерживает структурированный синтаксис)
limit	Да	Максимальное количество результатов (1-50)

Важные замечания

• Индекс в памяти — перестраивается каждый раз при запуске MCP-сервера. Постоянного файла индекса нет.
• Все поля в нижнем регистре — поиск нечувствителен к регистру
• Лимит ограничен 50 — вы не можете запросить более 50 результатов
• Неверный синтаксис запроса возвращает понятное сообщение об ошибке с примерами
• Поле _all объединяет method, path, tag, summary, spec_domain и collection_title для простого текстового поиска