Универсальный MCP-сервер для локальных LLM (oMLX, LM Studio, Ollama, llama.cpp и др.)

Сервер реализует протокол Model Context Protocol (MCP) через стандартные потоки ввода-вывода (stdio) и предоставляет AI-ассистентам (включая JetBrains Junie в PyCharm, Claude Desktop, Cursor и др.) доступ к локальным языковым моделям через любой OpenAI-совместимый REST API.

Сервер изначально оптимизирован для oMLX (Apple Silicon MLX), но полностью совместим со всеми популярными локальными бэкендами:

• oMLX
• LM Studio
• Ollama
• llama.cpp / llama-server
• vLLM
• LocalAI / Jan / Text Generation WebUI (oobabooga) и так далее.

Мой персональный выбор в пользу oMLX связан с тем, что в нем агент написания кода не сбрасывает кэш ключ-значение (KV-cache) десятки раз за сессию, а сохраняет каждый блок кэша на SSD. Из-за этого агент, возвращаясь к предыдущему префиксу, восстанавливает контекст за миллисекунды, а не пересчитывает его с нуля.

Реализация выполнена на стандартной библиотеке Python 3.12+ без сторонних зависимостей во время выполнения и оптимизирована для управления окружением через poetry.

---

Что такое MCP и зачем он нужен Junie

Model Context Protocol (MCP) — это открытый стандартизированный протокол взаимодействия AI-ассистентов с внешними источниками контекста и исполнительными инструментами (tools). Вместо написания уникальных плагинов под каждую модель и IDE, MCP предоставляет единый протокол обмена сообщениями на базе JSON-RPC.

Почему интеграция через MCP полезна для Junie:

1. Двухуровневая архитектура (Гибридный интеллект):

   • Junie (внешняя облачная модель) выступает в роли главного архитектора и координатора: глубоко понимает проект, планирует шаги и ведет разработку.
   • Локальная модель (oMLX / LM Studio / Ollama) выступает в роли быстрого эксперта: Junie может на лету делегировать локальной модели ревью фрагментов кода, проверку гипотез, брейншторм или черновые генерации через вызовы инструментов MCP (ask_local_model, review_code_locally).

2. Приватность и безопасность данных:

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

3. Экономия токенов и лимитов:

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

4. Полная независимость и автономность:

   • Вы можете менять локальный ИИ-движок или в фоновом режиме через .env или меняя default-модель (Qwen, DeepSeek, Llama, Mistral) в настройках локального ИИ-движка, не меняя настройки самого агента.

---

Возможности сервера

Сервер предоставляет следующие инструменты (MCP Tools):

1. ask_local_model — отправка запроса к локальной языковой модели для генерации текста, анализа, генерации альтернативных вариантов реализации или выполнения вспомогательных вычислений с сохранением приватности данных.

   • Параметры:
     • prompt (строка, обязательный) — основной текст запроса.
     • system_prompt (строка, опциональный) — системная инструкция.
     • model (строка, опциональный) — имя конкретной модели oMLX (по умолчанию берется активная/первая доступная).
     • temperature (число, опциональный, по умолчанию 0.2) — температура генерации от 0.0 до 1.0.
     • max_tokens (целое число, опциональный) — лимит на количество токенов в ответе.

2. check_local_model_status — проверка сетевой доступности локального сервера oMLX и получение списка загруженных моделей.

   • Параметры: отсутствуют.

3. review_code_locally — проведение локального код-ревью фрагмента кода силами модели oMLX (поиск потенциальных дефектов, узких мест и предложений по рефакторингу).

   • Параметры:
     • code_snippet (строка, обязательный) — исходный код для анализа.
     • instructions (строка, опциональный) — специальные указания для ревью.
     • model (строка, опциональный) — имя модели oMLX.

---

Требования

• Python версии 3.12 или выше.
• Менеджер пакетов poetry.
• Любой запущенный локальный сервер моделей с OpenAI-совместимым API (oMLX, LM Studio, Ollama, llama.cpp / llama-server, vLLM, Jan, LocalAI и др.).
• macOS, Linux или Windows.

---

Установка и настройка

1. Клонирование и установка зависимостей

Перейдите в директорию проекта и установите виртуальное окружение:

cd /путь/к/2026-omlx-mcp-server
poetry install

2. Настройка переменных окружения

Создайте файл .env на основе примера .env.example:

cp .env.example .env

Отредактируйте .env под разные бэкенды:

OMLX_BASE_URL=http://127.0.0.1:8008/v1
OMLX_API_KEY=укажите_ваш_API_ключ_если_нужен
OMLX_MODEL_NAME=default
OMLX_TIMEOUT=120

Сервер автоматически считывает переменные из файла .env, расположенного рядом со скриптом main.py или в текущей рабочей директории, если они не были переданы напрямую через системное окружение.

---

Подключение к JetBrains Junie (PyCharm)

Для подключения MCP-сервера к агенту Junie в PyCharm укажите конфигурацию в файле .junie/mcp.json в корне любого вашего рабочего проекта.

Другой способ (для глобальной конфигурации) — в настройках плагина Junie Pro: Junie Settings → вкладка Junie Model Context Protocol (MCP) → в блоке Add Custom MCP configuration here... нажать + и вставить JSON с настройками. На момент октября 2026 года это срабатывало, но интерфейс может меняться.

Поскольку сервер реализован на стандартной библиотеке Python без сторонних зависимостей, его можно запускать напрямую через системный python3 без накладных расходов на Poetry или виртуальные окружения.

Вариант 1. Прямой запуск через python3 (Рекомендуемый и самый надежный)

Укажите прямой путь к скрипту main.py и параметры подключения в блоке env:

{
  "mcpServers": {
    "omlx-local": {
      "command": "python3",
      "args": [
        "путь/к/omlx-mcp-server/main.py"
      ],
      "env": {
        "OMLX_BASE_URL": "http://127.0.0.1:8008/v1",
        "OMLX_MODEL_NAME": "default",
        "OMLX_API_KEY": "укажите_ваш_API_ключ_если_нужен",
        "OMLX_TIMEOUT": "120"
      }
    }
  }
}

Преимущество: Работает мгновенно из любого проекта, не зависит от наличия Poetry в PATH фоновых процессов IDE и позволяет задавать настройки прямо в конфигурации MCP.

Примечание: Если python3 не обнаружен в PATH внутри IDE или нужная версия Python находится в виртуальном окружении, укажите полный путь к исполняемому файлу (например, /путь/к/omlx-mcp-server/.venv/bin/python или /usr/local/bin/python3).

Вариант 2. Запуск через Poetry

Если вы предпочитаете запускать сервер в изолированном окружении через Poetry:

{
  "mcpServers": {
    "omlx-local": {
      "command": "poetry",
      "args": [
        "run",
        "python",
        "main.py"
      ],
      "cwd": "/Users/e-serg/PRJ/2026-omlx-mcp-server"
    }
  }
}

Примечание: Если poetry не обнаружен в PATH внутри IDE, укажите полный путь к исполняемому файлу (например, /Users/e-serg/.local/bin/poetry или ~/.local/bin/poetry).

---

Проверка работоспособности

Сервер общается по протоколу JSON-RPC через стандартные потоки ввода-вывода (stdin/stdout). При прямом запуске в терминале он ожидает входные данные.

Способ 1. Быстрая проверка одной командой (через конвейер / pipe)

Выполните команду в терминале:

echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}' | python3 main.py

Сервер мгновенно вернет JSON-ответ инициализации:

{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "serverInfo": {"name": "omlx-local-bridge", "version": "1.0.0"}}}

Для проверки получения списка инструментов:

echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | python3 main.py

Способ 2. Интерактивный запуск

1. Запустите скрипт:

   python3 main.py
   

   (или poetry run python main.py)

2. Скрипт перейдет в режим ожидания (курсор на пустой строке). Вставьте JSON-запрос инициализации и нажмите Enter:

   {"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}
   

   Получите ответ:

   {"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "serverInfo": {"name": "omlx-local-bridge", "version": "1.0.0"}}}
   

3. Проверка работы локального ИИ:

   {"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "ask_local_model", "arguments": {"prompt": "Напиши японское хокку про язык программирования Python"}}}
   

   Ответ сервера:

   {"jsonrpc": "2.0", "id": 1, "result": {"content": [{"type": "text", "text": "Синтаксис прост —  \nPython, как тихий поток,  \nЛегко читать, легко писать."}], "isError": false}}
   

4. Для выхода нажмите Ctrl+C или Ctrl+D.

---

Практическое применение: интеграция Junie и локального ИИ

Для эффективной совместной работы облачного агента Junie и локальной языковой модели через MCP рекомендуется настроить файл правил .junie/AGENTS.md (или .junie/guidelines.md) в вашем рабочем проекте, а также использовать специальные формулировки в диалогах.

1. Настройка .junie/AGENTS.md (Системные инструкции для агента)

Добавьте следующие правила в .junie/AGENTS.md любого проекта, где вы хотите использовать гибридный подход (пример):

* Для локального ревью кода, генерации черновых вариантов или второго мнения используй MCP-инструменты oMLX (`ask_local_model`, `review_code_locally`).
* Архитектура взаимодействия: внешняя модель выступает главным координатором (валидирует требования, структуру проекта и стандарты), а локальная модель — экспертом по проверке фрагментов кода и генерации идей.
* При работе с конфиденциальными алгоритмами или приватными данными делегируй их обработку локальной модели через инструмент `ask_local_model`.
* При недоступности или таймауте локальной модели продолжай работу самостоятельно, не блокируя выполнение задачи.

2. Примеры запросов к Junie в диалоге

Благодаря MCP-протоколу вам не нужно вручную копировать код между окнами — Junie сама вызовет локальную модель через зарегистрированные инструменты.

Пример А: Запрос на альтернативное мнение / брейншторм

«Junie, спроси у локальной модели 3 варианта оптимизации функции calculate_metrics в файле analytics.py и сравни их с твоим предложением».

Пример Б: Локальное код-ревью перед коммитом

«Сделай локальное ревью изменений в модуле auth.py через инструмент review_code_locally и выдели критичные замечания».

Пример В: Обработка приватных данных или конфиденциального кода

«Проанализируй алгоритм расчета формулы через ask_local_model, не отправляя сырые данные в облако, и напиши тесты на основе его ответа».

Пример Г: Проверка критичных таблиц или данных

«Проверь через локальный ИИ поля таблицы person и валидацию для записи #42».