MCP-советник высшего уровня (Aurai Advisor)

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

Текущий репозиторий соответствует «долгосрочной» версии, в которой реализованы следующие ключевые возможности:

• Многоходовые консультации и отчеты о прогрессе

• Синхронизация файлов sync_context

• Автоматическое преобразование кода/конфигурационных файлов в текст для загрузки

• Изоляция сессий (session_id)

• Персистенция истории, файловые блокировки, атомарная запись

• Автоматическое резюмирование истории

• Обрезка контекстного окна

Что нового в этом обновлении

В этом основном обновлении основное внимание уделено следующему:

• Исправлена проблема, при которой история «воскресала» после перезапуска после очистки

• Добавлена изоляция сессий через session_id, чтобы избежать смешивания контекстов разных задач

• Подключены реально работающие конфигурации: AURAI_TEMPERATURE, AURAI_MAX_ITERATIONS, AURAI_LOG_LEVEL и другие

• Обеспечена передача контекста project_info и дополнительных ответов «старшему советнику»

• Добавлены файловые блокировки истории и атомарная запись для снижения риска повреждения файлов истории при параллельной записи

• Добавлено автоматическое резюмирование истории, чтобы длинные сессии не становились слишком громоздкими

• Добавлена обрезка контекстного окна, AURAI_CONTEXT_WINDOW теперь работает корректно

• sync_context теперь поддерживает автоматическое преобразование текстовых файлов (код/конфиги) в формат для отправки, больше не нужно вручную копировать их в .txt

• Переписаны README, руководство по установке и руководство пользователя, шаги установки теперь вынесены на более видное место

Если вы впервые знакомитесь с этим репозиторием, самое важное:

1. Сначала ознакомьтесь с «Инструкцией по установке» ниже

2. Файлы кода теперь можно передавать напрямую в sync_context

Для чего это подходит

Этот MCP подходит для использования в Claude Code или других MCP-клиентах, поддерживающих протокол stdio.

Типичные сценарии:

• Локальный ИИ уже пытался решить задачу, но она все еще не решена

• Необходимо передать ошибки, код, документацию и конфигурацию «старшему советнику»

• Желание превратить сложный процесс отладки в многоходовую схему «Вопрос -> Выполнение -> Отчет -> Следующий шаг»

Обзор функций

• consult_aurai Основной инструмент для консультаций. Отправка вопроса, фрагментов кода, контекста, предпринятых попыток для получения анализа и рекомендаций от старшего советника.

• sync_context Синхронизация контекста кода и документации. Теперь поддерживает не только .txt/.md, но и автоматически преобразует .py/.js/.ts/.json/.yaml/.toml/.ini и другие текстовые файлы в формат, пригодный для отправки.

• report_progress Отчет о результатах выполнения старшему советнику для продолжения итерации.

• get_status Просмотр статуса текущей сессии, количества записей в истории, путей к модели и файлам истории.

Инструкция по установке

Более подробные шаги установки см. в:

• Руководство по установке Claude Code

• Руководство пользователя

Здесь приведен наиболее распространенный процесс установки.

1. Подготовка окружения

# 需要 Python 3.10+
python --version

# 进入仓库目录
cd G:\codex\mcp-aurai-server

2. Создание виртуального окружения и установка зависимостей

python -m venv venv
venv\Scripts\activate
pip install -e ".[all-dev]"

3. Регистрация MCP в Claude Code

claude mcp add --scope user --transport stdio aurai-advisor ^
  --env AURAI_API_KEY="your-api-key" ^
  --env AURAI_BASE_URL="https://api.example.com/v1" ^
  --env AURAI_MODEL="gpt-4o" ^
  -- "G:\codex\mcp-aurai-server\venv\Scripts\python.exe" "-m" "mcp_aurai.server"

Примечание:

• AURAI_BASE_URL должен быть адресом интерфейса, совместимого с OpenAI

• В текущей версии оставлен только способ custom, старый AURAI_PROVIDER больше не используется

• --scope user означает, что сервис будет доступен во всех проектах

4. Проверка установки

claude mcp list
pytest

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

• claude mcp list показывает aurai-advisor

• pytest проходит успешно

Быстрый старт

Сценарий 1: Прямой вопрос

consult_aurai(
    problem_type="runtime_error",
    error_message="启动时报 KeyError: api_key",
    code_snippet="config = load_config()\napi_key = config['api_key']",
    context={
        "file_path": "src/config.py",
        "terminal_output": "Traceback ...",
    }
)

Сценарий 2: Сначала загрузка кода, затем вопрос

sync_context(
    operation="incremental",
    files=["src/main.py", "config/settings.json", "README.md"],
    project_info={
        "project_name": "My Project",
        "tech_stack": "Python + FastAPI"
    }
)

consult_aurai(
    problem_type="runtime_error",
    error_message="请结合已同步文件帮我排查启动失败"
)

Внимание:

• Не нужно вручную копировать main.py в main.txt

• Текстовые файлы кода будут автоматически преобразованы и отправлены

• Бинарные файлы будут пропущены

Сценарий 3: Параллельные вопросы с использованием изоляции сессий

consult_aurai(
    problem_type="runtime_error",
    error_message="问题 A",
    session_id="issue-a"
)

consult_aurai(
    problem_type="design_issue",
    error_message="问题 B",
    session_id="issue-b"
)

Это предотвращает смешивание контекстов разных задач.

Правила загрузки файлов через sync_context

Будут отправлены напрямую

• .md, .markdown, .mdx

• .txt

• Различные текстовые файлы кода и конфигураций, например:

  • .py .js .ts .tsx

  • .json .yaml .yml .toml

  • .ini .cfg .env

  • .java .go .rs .cpp .cs

Будут автоматически преобразованы

• Файлы, не являющиеся .txt/.md, но содержащие текст

• Будет автоматически сгенерировано имя для отправки с расширением .txt или .md

• Перед содержимым будет добавлена информация об «исходном пути файла» и «автоматически преобразованном имени»

Будут пропущены

• Изображения

• Архивы

• Аудио/видео

• Исполняемые файлы

• Очевидный бинарный контент

Если в наборе файлов есть и код, и изображения:

• Код будет загружен как обычно

• Изображения будут помечены как skipped_files

• Синхронизация в целом будет считаться успешной

Переменные окружения

Обязательные

Часто используемые опции

Ключевое поведение текущей версии

1. Изоляция сессий

• Каждый session_id имеет свою историю

• Если не указан, используется default

• Разные сессии сохраняются в разные файлы истории

2. Резюмирование истории

• Старая история автоматически сжимается в «резюме истории»

• Последние раунды и последний sync_context сохраняются в исходном виде

• Это экономит контекст для текущей задачи

3. Обрезка контекстного окна

• Приоритет отдается системным подсказкам

• Приоритет отдается последнему sync_context

• Затем сохраняются последние раунды истории

• При необходимости автоматически сокращается длина вывода для предотвращения переполнения окна

4. Надежность файлов истории

• При сохранении используются файлы блокировки для предотвращения повреждения при параллельной записи

• Запись выполняется через временный файл с последующей заменой, чтобы избежать неполных JSON-файлов

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

pytest

Текущие приоритеты тестирования включают:

• Очистка и персистенция истории

• Изоляция сессий

• Автоматическое преобразование и загрузка текста

• Блокировки истории и атомарная запись

• Резюмирование истории

• Обрезка контекстного окна

Документация

• Руководство по установке Claude Code

• Руководство пользователя

• Документация для разработчиков

Часто задаваемые вопросы

Почему старший советник не получил загруженный мной файл кода?

Старые версии требовали ручного преобразования в .txt. Текущая версия поддерживает автоматическое преобразование текстовых файлов.

Если файл все еще не получен, проверьте:

• Существует ли путь к файлу

• Не является ли файл бинарным

• Что возвращает sync_context в полях uploaded_files / skipped_files

Почему разные задачи влияют друг на друга?

Если вы хотите полной изоляции, передавайте разным задачам разные session_id.

Почему файл истории стал короче?

Это работает резюмирование истории. Старая история сжата в краткое содержание, она не потеряна, а заменена на более компактный «протокол встречи».