Мы опубликовали на GitHub проект cioinside/ragmir-mcp-server — универсальный MCP-сервер для локальной RAG-системы Ragmir. Сервер превращает CLI-инструмент Ragmir в управляемый HTTP/SSE-сервис с 14 MCP-инструментами и двумя дополнительными инструментами для загрузки бинарных файлов, к которому могут подключаться OpenCode, Claude, Cursor, Open WebUI и любые другие MCP-совместимые агенты — без SSH, без CLI на хостах агентов и без отправки данных во внешние облака.

Контекст: что такое Ragmir и зачем ему MCP-сервер

Ragmir (npm-пакет @jcode.labs/ragmir, v4.0.0) — это «конфиденциальный локальный RAG для кодинг-агентов и Node.js-приложений». Его ключевая идея — retrieval-only ядро, которое:

• индексирует только те файлы проекта, которые пользователь явно выбрал через glob-паттерны;
• возвращает ограниченные по объёму цитаты с указанием источника (source lines, PDF pages, PPTX slides, XLSX cells, EPUB spine positions);
• работает offline-first по умолчанию: не загружает корпус, не вызывает LLM и не открывает HTTP-порт;
• под капотом использует LanceDB для векторного хранилища и опционально Transformers.js для семантического поиска;
• распространяется под AGPL-3.0 (с отдельной коммерческой лицензией).

Сам Ragmir изначально поставляется с локальным stdio-MCP для разработчика, сидящего прямо в редакторе, и с CLI rgr для скриптов. Этого достаточно для сценария «одиночный разработчик + свой редактор», но не работает в трёх типичных ситуациях:

1. AI-агент запущен на другой машине в локальной сети (рабочий ноутбук → сервер с базой знаний).
2. К базе знаний нужно одновременно подключить и AI-агента, и чат-интерфейс (например, Open WebUI) с разной семантикой транспортов.
3. В проекте есть большие бинарные вложения (.docx, .pdf, .xlsx, изображения), которые невозможно передать через JSON-RPC MCP-вызов.

Ragmir MCP Server закрывает все три сценария, оборачивая один и тот же server.js (внутренний MCP-адаптер Ragmir) в три параллельных транспорта и автоматизируя их развёртывание через systemd.

Что сделано

• 14 MCP-инструментов через единый Node.js-процесс: управление проектами, файловые операции, индексация, поиск и синтетический «multi-query research».
• Три транспорта на одном сервере: SSE для OpenCode/Claude/Cursor (порт 8001), OpenAPI/REST через mcpo для Open WebUI (порт 8000), отдельный HTTP-эндпоинт для загрузки бинарных файлов (порт 8002).
• Дополнительный локальный MCP-сервер upload-client — для агентов на Windows, чтобы они могли загружать .docx/.pdf/.xlsx/изображения с локального диска на удалённый сервер без копипасты shell-команд и без лимита undici/fetch в 50 МБ.
• Полное развёртывание через systemd: три юнит-файла (ragmir-mcp.service, ragmir-sse.service, ragmir-upload.service), которые стартуют автоматически.
• Установка одной строкой: curl -sSL ... | bash — скрипт раскладывает всё по /usr/local/lib/ragmir-server/, /etc/ragmir/, /opt/ragmir-projects/ и прописывает переменные окружения.
• OpenAPI-документация автогенерируется на /docs (через mcpo) — интерактивный Swagger UI без ручного труда.
• Локальный приоритет по умолчанию: ключевая особенность — данные вообще не покидают LAN, никакие абстрактные «команды эмбеддеров» или управляемые сервисы не задействованы.

Архитектура

         AI-агент (OpenCode / Claude / Cursor)        Open WebUI / любой REST-клиент
                       │                                       │
                       │  SSE (MCP-транспорт)                  │  REST / OpenAPI
                       ▼                                       ▼
              mcp-proxy :8001                            mcpo :8000
                       │                                       │
                       │  stdio (stdin/stdout)                 │  stdio
                       └────────────────┬──────────────────────┘
                                        │
                                        ▼
                                server.js
                            (Node.js, MCP-адаптер)
                                        │
                ┌───────────────────────┼───────────────────────┐
                ▼                       ▼                       ▼
        rgr CLI (search,         upload-server :8002      /opt/ragmir-projects/
        ingest, ask, research)   (multipart/form-data)    (по каталогу на проект)
                │                       │
                └───────── LanceDB ──────┘

Два порта для агентов, один порт для файлов. Порты 8000 и 8001 обслуживают один и тот же серверный процесс через разные транспортные адаптеры: REST/OpenAPI для интеграции с Open WebUI и классических HTTP-клиентов, SSE — то, что нативно понимают OpenCode, Claude Desktop и Cursor. Порт 8002 вынесен в отдельный легковесный Node.js-процесс (upload-server.js), потому что принимает multipart-формы и отдаёт файлы напрямую, минуя JSON-RPC.

Под капотом — три независимых systemd-сервиса, которые шарят каталог /opt/ragmir-projects/:

14 MCP-инструментов

Все инструменты доступны через любой из транспортов с одинаковой сигнатурой.

Управление проектами

Файловые операции

Индексация и поиск

Особенность ragmir_write_file / ragmir_write_files_batch: флаг autoIngest (по умолчанию true) заставляет сервер сразу же запустить индексацию — файл становится доступен поиску в течение одной операции, без отдельного шага.

Быстрая установка

# Требования: Node.js >= 22, npm, uv или pip (для mcpo)
curl -sSL https://raw.githubusercontent.com/cioinside/ragmir-mcp-server/main/install.sh | bash

Ручной режим — для случая, когда хочется явно контролировать каждый шаг:

# 1. Установить CLI Ragmir
npm install -g @jcode.labs/ragmir

# 2. Положить MCP-сервер
sudo mkdir -p /usr/local/lib/ragmir-server
sudo cp server.js /usr/local/lib/ragmir-server/
sudo chmod +x /usr/local/lib/ragmir-server/server.js

# 3. Каталоги
sudo mkdir -p /opt/ragmir-projects
sudo mkdir -p /etc/ragmir

# 4. Конфиг mcpo
sudo tee /etc/ragmir/mcpo-config.json << 'EOF'
{
  "mcpServers": {
    "ragmir": {
      "command": "node",
      "args": ["/usr/local/lib/ragmir-server/server.js"],
      "env": { "RAGMIR_PROJECTS_DIR": "/opt/ragmir-projects" }
    }
  }
}
EOF

# 5. systemd-юнит (не забудьте подставить свой API-ключ!)
sudo cp ragmir-mcp.service /etc/systemd/system/
sudo sed -i 's/CHANGE-ME/YOUR_SECRET_KEY/' /etc/systemd/system/ragmir-mcp.service
sudo systemctl daemon-reload && sudo systemctl enable --now ragmir-mcp

# 6. Открыть порт
sudo ufw allow 8000/tcp

Подключение агентов

OpenCode / Claude / Cursor — добавить в ~/.config/opencode/opencode.jsonc:

{
  "mcp": {
    "ragmir": {
      "type": "remote",
      "url": "http://192.168.1.100:8001/sse",
      "enabled": true
    }
  }
}

Open WebUI — Admin Settings → Connections → OpenAPI Servers → Add:

Бинарные файлы и отдельный upload-client для Windows

Передача бинарных вложений через JSON-RPC MCP неудобна — base64 раздувает размер, undici/fetch режет на 50 МБ. Поэтому:

• Текстовые файлы (.py, .md, .js, конфиги) — через ragmir_write_files_batch, привычным MCP-вызовом.
• Бинарные файлы (.docx, .pdf, .xlsx, изображения) — через отдельный HTTP-эндпоинт на 8002:

curl -X POST http://192.168.1.100:8002/upload \
  -F "project=my-project" \
  -F "path=docs/report.docx" \
  -F "file=@/path/to/report.docx"

Ответ:

{ "ok": true, "project": "my-project", "path": "docs/report.docx", "bytes": 12345, "ingested": true }

При autoIngest=true файл автоматически попадает в индекс сразу после загрузки.

Для агентов на Windows, которые не должны писать shell-команды самостоятельно, в репозитории есть подпроект upload-client/ — локальный MCP-сервер с двумя инструментами:

• upload_to_ragmir(project, path, localPath) — читает файл с локального диска и отправляет на удалённый сервер.
• list_local_files(directory, extensions?) — показывает агенту, что вообще есть на диске, чтобы агенту не приходилось угадывать.

Важная деталь: клиент работает через http.request напрямую, без undici, поэтому лимит 50 МБ отсутствует в принципе — файлы любого размера проходят без разбиения на чанки.

Под капотом

Кому это нужно

• Тем, кто поднимает self-hosted RAG для команды — Open WebUI как чат-интерфейс, OpenCode/Claude/Cursor как агентские клиенты, общий сервер с базой знаний на отдельной машине. Все довольны, ничего не уходит наружу.
• Тем, у кого агенты запускаются на ноутбуке, а база — на рабочей станции или мини-сервере. SSE-прокси решает вопрос «как пробросить локальный MCP наружу» без туннелей и без публичного доменного имени.
• Тем, кто индексирует PDF/Word/Excel в дополнение к коду и Markdown. У upload-server есть multipart-эндпоинт и есть MCP-клиент для Windows; агенту достаточно одного вызова upload_to_ragmir(...).
• Тем, кто не хочет платить сторонним RAG-сервисам или не может пропускать документы через внешние API. Весь цикл — индексация, поиск, цитирование — работает офлайн на своём железе.

Ограничения, о которых полезно знать

• Без LLM. Ядро возвращает контекст с цитатами, но не генерирует ответов. Это сознательная архитектура Ragmir: «hosted agent receives only passages your integration sends under that provider's data policy; use a local consumer when no passage may leave the workstation». Если нужен чат «отвечающий» — добавляется @jcode.labs/ragmir-chat, который даёт цитируемую генерацию на локальной GGUF-модели.
• Безопасность встроенная, но минимальная. API-ключ передаётся как Authorization: Bearer, без TLS-терминации внутри — подразумевается, что рядом стоит reverse-proxy с Let’s Encrypt или сеть приватная. Запуск на публичном IP без TLS — на ваш страх и риск.
• Индексируемые форматы ограничены тем, что поддерживает ядро Ragmir (текст, PDF, PPTX, XLSX, EPUB, изображения через OCR по желанию). Экзотика типа .pages, .numbers, .key — за пределами.

Что под капотом истории коммитов

Репозиторий живёт всего несколько недель, но уже прошёл через несколько итераций, видных по истории коммитов:

1. Базовый MCP-сервер — server.js с 14 инструментами и OpenAPI-прокси.
2. SSE-шлюз — первая попытка через supergateway, затем замена на mcp-proxy ради стабильных реконнектов.
3. Бинарные файлы — сначала через ragmir_upload_binary (base64), затем рефакторинг в единый write_file/write_files_batch с авто-ингестом, наконец — выделенный HTTP-эндпоинт на порт 8002, потому что JSON-RPC для этого избыточен.
4. Watch-режим — file-watcher.js, который автоматически запускает ингест при изменении файлов на диске.
5. upload-client для Windows-агентов — локальный MCP-сервер с инструментами загрузки, без лимита 50 МБ (через http.request вместо fetch).
6. Официальный @modelcontextprotocol/sdk — переход с самописной реализации ради совместимости с растущим числом MCP-клиентов.

Ссылки

• Репозиторий: github.com/cioinside/ragmir-mcp-server
• MIT-лицензия на сервер (см. LICENSE в корне репозитория).
• Зависимость: @jcode.labs/ragmir (npm), исходники — AGPL-3.0 + commercial license.
• Установка одной строкой:

  curl -sSL https://raw.githubusercontent.com/cioinside/ragmir-mcp-server/main/install.sh | bash

• Issues / Pull requests: github.com/cioinside/ragmir-mcp-server/issues

Что важно запомнить. Ragmir MCP Server — это «тонкая» обёртка над ядром Ragmir с правильно подобранными транспортами: SSE для современных агентов, OpenAPI для Open WebUI, multipart-HTTP для бинарных файлов, локальный MCP-клиент для Windows. Всё работает на Node.js 22+, разворачивается одной командой и не отправляет данные никуда, кроме вашей локальной сети. Если вы уже пользуетесь Ragmir как CLI — это превращение его в полноценный backend для команды AI-агентов. Если не пользуетесь — порог входа низкий, пакет один, npm install и вперёд.