Corporate MCP — RAG Debugger

Руководство по работе с MCP сервером

Что делает rag-debugger MCP

Основная идея — мост между Cline и Langfuse. Cline не умеет читать трейсы напрямую, MCP сервер делает это за него и возвращает готовый диагноз.

Что происходит внутри при анализе

Langfuse API → получить трейс → разобрать spans →
найти span "supervisor" → JSON parse action →
fallback: regex \breject\b / \bask\b →
найти span "retrieval"  → проверить docs_count →
детектировать CONTEXT_IGNORED →
└─ автоматически записать hallucination_risk score в Langfuse →
собрать issues[] → поставить verdict

Ключевые пороги из env

EMPTY_RETRIEVAL_THRESHOLD=50   # retrieval < 50 chars → WARNING
MAX_SPANS_THRESHOLD=80         # spans > 80 → возможная петля
RAG_TRACE_FLUSH_WAIT=4         # секунд ожидания после вызова RAG
                               # перед поллингом Langfuse API

Принцип работы

Cline получает задачу через промпт → вызывает MCP инструменты по цепочке → анализирует результат → вносит изменения → верифицирует → сохраняет паттерн в memory (нужно донастроить еще один mcp). Каждый запрос к агенту оставляет полный трейс со всеми span-ами, входами и выходами. Это единственный способ понять что происходит внутри LangGraph без добавления логов в код.

Инструменты

rag-debugger

Диагностика трейсов

Поиск и сравнение

Вызов RAG и регрессия

⚠️

run_rag_test_suite

vs

run_regression_check

: оба прогоняют вопросы, но

run_regression_check

дополнительно записывает

auto_regression

scores в Langfuse и возвращает

scoring_errors

если запись упала.

Вердикты и severity

Каждый анализ возвращает один из трёх вердиктов:

Настройки MCP сервера

Зайди в Cline и выбери сконфигурировать MCP. Откроется json файл куда вставь конфиг.

Тест-кейсы по инструментам

🔍 Диагностика

TC-01 — Быстрый осмотр последнего запроса

Сценарий: разработчик вручную протестировал агента, ответ показался странным.

Промпт для Cline:

Проверь последний запрос к RAG агенту.
Используй rag-debugger, инструмент get_agent_health_report,
hours=1. Если есть проблемы — диагностируй.

Ожидаемый результат:

• health_score_percent
• список issues если есть
• вердикт HEALTHY / DEGRADED / CRITICAL

TC-02 — Глубокая диагностика конкретного трейса

Сценарий: в Langfuse найден подозрительный трейс, есть его ID.

Промпт для Cline:

diagnose_trace <trace_id>

Ожидаемый результат:

• verdict с объяснением
• список issues с severity
• readable_flow — путь запроса через граф
• ссылка на трейс в Langfuse

TC-03 — Визуализация пути запроса

Сценарий: непонятно через какие узлы прошёл запрос.

Промпт для Cline:

get_langgraph_flow <trace_id>

Ожидаемый результат:

• readable_flow: supervisor → clean_query → rag → answer
• дерево span-ов с длительностью
• топ медленных узлов

TC-09 — Мгновенный снапшот последнего трейса

Сценарий: только что вручную задал вопрос агенту через UI, хочу быстро посмотреть что произошло без поиска trace_id.

Промпт для Cline:

Покажи последний трейс RAG агента.
Используй analyze_last_rag_query, trace_name="LangGraph".

Ожидаемый результат:

• trace_id и timestamp последнего трейса
• user_query и agent_answer (первые 500 символов)
• verdict + список issues
• retrieval_called, retrieval_docs_found

💡 Разница от TC-01: работает без health_report, возвращает ответ агента целиком. Удобно как первый шаг любой отладки.

TC-10 — Быстрый срез по последним N запросам

Сценарий: нужно понять общую картину перед разговором с командой, не запуская полный health_report на 50 трейсов.

Промпт для Cline:

Проанализируй последние 10 запросов к RAG агенту за 6 часов.
Используй analyze_last_n_queries, n=10, hours=6.
Покажи health_score и топ проблем.

Ожидаемый результат:

• health_score (например "80.0%")
• verdicts: {HEALTHY: 8, DEGRADED: 1, CRITICAL: 1}
• top_issues отсортированные по частоте
• список трейсов с вердиктами

🔎 Поиск аномалий

TC-11 — Пакетный поиск сломанных трейсов

Сценарий: прошла ночь, нужно найти все проблемные запросы не просматривая каждый трейс вручную.

Промпт для Cline:

Найди все трейсы с проблемами за последние 12 часов.
Используй find_bad_traces, hours=12, min_issues=1.
Для каждого покажи trace_id и тип issues.

Ожидаемый результат:

• total_found — количество проблемных трейсов
• для каждого: verdict, issue_types, retrieval_called
• трейсы отсортированы: CRITICAL → DEGRADED → HEALTHY

⚠️ При большом limit (>30) инструмент использует ThreadPoolExecutor — параллельная загрузка spans ускоряет работу в ~5×.

TC-12 — Поиск кандидатов на галлюцинацию

Сценарий: нужно аудировать качество ответов — найти случаи где агент отвечал не по документам.

Промпт для Cline:

Найди трейсы где агент мог галлюцинировать за последние 48 часов.
Используй find_hallucination_candidates, hours=48, limit=15.
Для каждого покажи user_query и issue_types.

Ожидаемый результат:

• кандидаты с issue_types из списка: NO_RETRIEVAL / EMPTY_RETRIEVAL / CONTEXT_IGNORED / SUPERVISOR_REJECTED / SUPERVISOR_ASK
• agent_answer (первые 300 символов) для каждого
• recommendation — конкретно что исправить

💡 После нахождения кандидатов — передай trace_id в diagnose_trace для детального разбора или в compare_traces для сравнения с HEALTHY трейсом.

🧪 Тестирование агента

TC-04 — Изолированный тест одного вопроса

Сценарий: проверить конкретный вопрос и сразу получить трейс.

Промпт для Cline:

Отправь вопрос "Что такое DataSpace?" в RAG агент
через run_rag_test и покажи результат.

Ожидаемый результат:

• ответ агента
• verdict трейса
• retrieval_called=true
• retrieval_docs_count > 0

TC-05 — Регрессия перед коммитом

Сценарий: изменили промпт, нужно убедиться что ничего не сломалось.

Промпт для Cline:

Запусти run_regression_check для стандартного набора вопросов,
score_results=true. Если всё прошло — покажи git diff и подготовь коммит.

Ожидаемый результат:

• pass_rate = 100%
• scoring_errors = []
• оценки записаны в Langfuse

TC-06 — Воспроизведение бага

Сценарий: пользователь сообщил о проблеме с конкретным вопросом.

Промпт для Cline:

# Проблема с RAG агентом

## Контекст системы
RAG агент на LangGraph, localhost:8000. Трейсы в Langfuse.
MCP сервер rag-debugger умеет отправлять вопросы и читать трейсы.

## Что не работает
- "С чего начать разработку?"

## Что происходит
Агент отвечает общими словами, не показывает примеры из документации.

## Что должно происходить
Агент должен находить учебные примеры из документации и отвечать на их основе.

Используй rag-debugger: воспроизведи через run_rag_test,
диагностируй, найди причину, исправь, проверь.

## Критерий завершения
Задача выполнена ТОЛЬКО когда вопрос возвращает verdict=HEALTHY
и в ответе есть примеры из документации.
Нельзя завершить без успешного run_rag_test.

Ожидаемый результат:

• найдена причина (CONTEXT_IGNORED / EMPTY_RETRIEVAL / SUPERVISOR_REJECTED)
• исправлен промпт или код
• run_rag_test возвращает HEALTHY
• паттерн сохранён в memory

🔁 Автономный цикл

TC-07 — Утренний мониторинг

Сценарий: начало рабочего дня, нужно понять состояние системы.

Промпт для Cline:

Проверь здоровье RAG агента за последние 24 часа.
Используй get_agent_health_report. Если health_score < 90% —
найди причины и предложи фикс.

Ожидаемый результат:

• сводка: total_traces, health_score_percent, verdicts
• top_issues с частотой
• список problematic_trace_ids
• рекомендация или готовый фикс

TC-08 — Сравнение до и после фикса

Сценарий: применили фикс, хотим доказать что стало лучше.

Промпт для Cline:

Сравни трейсы до и после фикса.
trace_before: <id>
trace_after: <id>
Используй compare_traces.

Ожидаемый результат:

• изменился ли readable_flow
• уменьшилось ли число spans
• появился ли retrieval
• исчез ли SUPERVISOR_REJECTED

TC-13 — Полный цикл автономной отладки

Сценарий: Cline работает автономно от поиска проблемы до верификации фикса.

Промпт для Cline:

Выполни автономный цикл отладки RAG агента:

1. analyze_last_n_queries (n=10, hours=24) — найди проблемы
2. Если health_score < 90%:
   a. find_bad_traces — определи worst трейсы
   b. diagnose_trace для каждого CRITICAL трейса
   c. find_hallucination_candidates — проверь галлюцинации
3. Для самой частой проблемы:
   a. compare_traces (один HEALTHY vs один CRITICAL)
   b. Предложи конкретный фикс промпта или кода
4. После фикса: run_regression_check (score_results=true)
5. Если pass_rate < 100% — повтори с шага 3

Останови цикл только при pass_rate=100% или после 3 итераций.

Ожидаемый результат:

• полный лог каждого шага цепочки
• найденная root cause
• применённый фикс (diff промпта/кода)
• финальный run_regression_check с pass_rate=100%
• scoring_errors=[]

⚠️ Этот промпт требует

autoApprove

для всех инструментов в конфиге. Без него Cline будет запрашивать подтверждение на каждый вызов.

Типы ошибок которые умеет находить

Метрики здоровья

Рекомендуемый порядок инструментов

Быстрая проверка (< 1 мин):
  analyze_last_rag_query → если плохо → diagnose_trace

Срез за период (1-2 мин):
  analyze_last_n_queries → find_bad_traces → diagnose_trace

Аудит галлюцинаций (2-5 мин):
  find_hallucination_candidates → compare_traces → export_fix_context

Полный цикл отладки (5-15 мин):
  analyze_last_n_queries
  → find_bad_traces + find_hallucination_candidates (параллельно)
  → diagnose_trace (для CRITICAL)
  → compare_traces (HEALTHY vs CRITICAL)
  → [применить фикс]
  → run_regression_check