252 lines
18 KiB
Markdown
252 lines
18 KiB
Markdown
# Универсальный MCP-сервер для локальных LLM (oMLX, LM Studio, Ollama, llama.cpp и др.)
|
|
|
|
|
|
|
|
|
|
[](https://git.cube2.ru/erjemin/2026-omlx-mcp-server)
|
|
|
|
Сервер реализует протокол Model Context Protocol (MCP) через стандартные потоки ввода-вывода (`stdio`) и предоставляет AI-ассистентам (включая JetBrains Junie в PyCharm, Claude Desktop, Cursor и др.) доступ к локальным языковым моделям через любой OpenAI-совместимый REST API.
|
|
|
|
Сервер изначально оптимизирован для **oMLX** (Apple Silicon MLX), но полностью совместим со всеми популярными локальными бэкендами:
|
|
- **[oMLX](https://omlx.ai/)**
|
|
- **[LM Studio](https://lmstudio.ai/)**
|
|
- **[Ollama](https://ollama.com/)**
|
|
- **[llama.cpp / llama-server](https://github.com/ggerganov/llama.cpp)**
|
|
- **[vLLM](https://docs.vllm.ai/)**
|
|
- **[LocalAI](https://localai.io/)** / **[Jan](https://jan.ai/)** / **[Text Generation WebUI](https://github.com/oobabooga/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. Клонирование и установка зависимостей
|
|
|
|
Перейдите в директорию проекта и установите виртуальное окружение:
|
|
|
|
```bash
|
|
cd /путь/к/2026-omlx-mcp-server
|
|
poetry install
|
|
```
|
|
|
|
### 2. Настройка переменных окружения
|
|
|
|
Создайте файл `.env` на основе примера `.env.example`:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Отредактируйте `.env` под разные бэкенды:
|
|
|
|
|
|
```ini
|
|
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`:
|
|
|
|
```json
|
|
{
|
|
"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:
|
|
|
|
```json
|
|
{
|
|
"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)
|
|
|
|
Выполните команду в терминале:
|
|
|
|
```bash
|
|
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}' | python3 main.py
|
|
```
|
|
|
|
Сервер мгновенно вернет JSON-ответ инициализации:
|
|
```json
|
|
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "serverInfo": {"name": "omlx-local-bridge", "version": "1.0.0"}}}
|
|
```
|
|
|
|
Для проверки получения списка инструментов:
|
|
|
|
```bash
|
|
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | python3 main.py
|
|
```
|
|
|
|
### Способ 2. Интерактивный запуск
|
|
|
|
1. Запустите скрипт:
|
|
```bash
|
|
python3 main.py
|
|
```
|
|
*(или `poetry run python main.py`)*
|
|
|
|
2. Скрипт перейдет в режим ожидания (курсор на пустой строке). Вставьте JSON-запрос инициализации и нажмите `Enter`:
|
|
```json
|
|
{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0"}}}
|
|
```
|
|
Получите ответ:
|
|
```json
|
|
{"jsonrpc": "2.0", "id": 1, "result": {"protocolVersion": "2024-11-05", "capabilities": {"tools": {}}, "serverInfo": {"name": "omlx-local-bridge", "version": "1.0.0"}}}
|
|
```
|
|
|
|
3. Проверка работы локального ИИ:
|
|
```json
|
|
{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "ask_local_model", "arguments": {"prompt": "Напиши японское хокку про язык программирования Python"}}}
|
|
```
|
|
Ответ сервера:
|
|
```json
|
|
{"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` любого проекта, где вы хотите использовать гибридный подход (пример):
|
|
|
|
```markdown
|
|
* Для локального ревью кода, генерации черновых вариантов или второго мнения используй 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».*
|