LocalAiMCP

Stateless, асинхронная управляющая плоскость FastMCP для LocalAI. В комплект входит Swagger-спецификация LocalAI, содержащая 114 путей / 123 операции, и все 123 остаются доступными через типизированные проверяемые вызываемые объекты. Чтобы не отправлять модели около 123 схем операций при каждом MCP-запросе, напрямую анонсируется только подобранный набор; всё остальное доступно для обнаружения и выполнения по требованию.

Две WebSocket-операции Swagger реализованы как ограниченные однократные обмены, multipart-маршруты поддерживают загрузку файлов, а бинарные ответы можно сохранять в ./data/output и возвращать инлайн в формате base64, если они достаточно малы.

Запуск

git clone https://github.com/twinlunarstarz-dev/LocalAiMCP.git
cd LocalAiMCP
cp .env.example .env
# Edit LOCALAI_BASE_URL / LOCALAI_API_KEY if needed.
docker compose up -d --build

Конечная точка MCP:

http://localhost:8000/mcp

Для VS Code/Zoo Code или другого Streamable HTTP MCP-клиента используйте этот URL как конечную точку удалённого MCP-сервера. Контейнер по умолчанию использует host.docker.internal:8080 для LocalAI и включает Linux-маппинг host-gateway.

Related MCP server: mcp-file-system-lmstudio

Подобранный набор инструментов

Сервер не анонсирует все 123 операции LocalAI по умолчанию. Пресет по умолчанию анонсирует 20 часто полезных инструментов операций плюс пять фиксированных вспомогательных инструментов обнаружения/системы.

Инструменты операций, напрямую доступные по умолчанию:

# System/model information
get_system_info
get_metrics
get_token_metrics
list_models
list_model_capabilities
get_backend_monitor

# Generation/media
chat
complete_text
generate_image
inpaint_image
generate_sound
generate_video
text_to_speech
text_to_speech_with_voice

# Voice
list_voice_profiles
create_voice_profile
analyze_voice
verify_speakers

# 3D
generate_3d_asset
remesh_3d_asset

Пять фиксированных MCP-помощников:

list_additional_tools
search_additional_tools
execute_additional_tool
server_health
schema_audit

Таким образом, набор tools/list по умолчанию составляет 25 инструментов, а не около 128. Точное число настраивается.

Настройка того, какие операции LocalAI видны напрямую

Установите LOCALAI_MCP_EXPOSED_TOOLS в список семантических имён операций, разделённых запятыми:

LOCALAI_MCP_EXPOSED_TOOLS=chat,list_models,generate_image,text_to_speech,generate_3d_asset

Особые значения:

*       expose all 123 Swagger operations directly
none    expose no Swagger operations directly; use only the gateway/system helpers
gateway-only  same as none

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

Изменение прямого доступа влияет только на то, что MCP-клиенты получают в tools/list; это не удаляет скрытую операцию из LocalAiMCP.

Шлюз дополнительных инструментов

Менее распространённые инструменты остаются во внутреннем типизированном реестре и доступны через три небольших инструмента.

list_additional_tools

Возвращает полный отсортированный список имён скрытых инструментов и ничего громоздкого со схемами. Он намеренно компактен, чтобы модель могла по требованию просмотреть весь скрытый каталог, не неся постоянно эти схемы в каждом запросе.

search_additional_tools

Ищет только среди скрытых инструментов, используя цель на простом языке или точное имя инструмента. Каждое совпадение возвращает:

• семантическое имя инструмента

• подробное описание назначения/входа/выхода

• теги

• полную JSON-схему входа

Примеры:

search_additional_tools(query="detokenize token ids")
search_additional_tools(query="transcribe audio")
search_additional_tools(query="install a backend")
search_additional_tools(query="inspect request traces")

execute_additional_tool

Выполняет скрытую возможность по семантическому имени:

{
  "tool_name": "detokenize",
  "arguments": {
    "request": {
      "model": "my-model",
      "tokens": [1, 42, 9001]
    }
  }
}

Объект arguments проверяется по той же сгенерированной Pydantic-схеме, которая используется напрямую доступной операцией. Недопустимые или неизвестные поля возвращают ошибку валидации и ожидаемую схему входа до выполнения любого запроса к LocalAI. Это не диспетчер в стиле curl: модель использует семантические имена инструментов и типизированные аргументы, а не HTTP-методы/маршруты.

Напрямую доступные операции намеренно отклоняются execute_additional_tool; клиент должен вызывать их обычный MCP-инструмент напрямую.

Прежний расширенный запасной механизм raw_request и помощник probe_safe_endpoints сохранены как скрытые дополнительные инструменты, так что сокращение tools/list не удаляет эти возможности.

Описания, ориентированные на LLM

Реестр спроектирован так, чтобы модели не требовалось предварительное знание API LocalAI:

• Имена инструментов описывают задачи, а не зеркалируют HTTP-маршруты или методы.

• Каждая типизированная HTTP-операция указывает своё назначение, ожидаемые входы и успешный выход.

• JSON-схемы запросов содержат описания на уровне полей, включая консервативные запасные указания, когда Swagger говорит только что-то вроде Request или оставляет поле без документации.

• Ссылочные объекты запросов выводят полезные поля верхнего уровня непосредственно в описания.

• Описания ответов объясняют, появляются ли данные в data, text, events, base64 или saved_path.

• Поиск возвращает полную схему входа только тогда, когда скрытый инструмент релевантен.

• Обвязка-обёртка, такая как пользовательские заголовки и таймауты на вызов, остаётся вне обычных типизированных операций.

Например, скрытый инструмент detokenize объясняет, что его запрос содержит:

• tokens: целочисленные идентификаторы токенов для преобразования обратно в текст

• model: имя или алиас модели LocalAI, чей токенизатор следует использовать

и что JSON-ответ содержит content — детокенизированный текст.

Дизайн

• FastMCP 3.4.7, зафиксирован для воспроизводимости.

• Streamable HTTP + stateless-режим. Несколько Uvicorn-воркеров безопасны, поскольку обнаружение и выполнение используют локальный для процесса неизменяемый реестр, а не состояние диалога/сессии.

• Асинхронный LocalAI I/O с httpx; независимые вызовы могут выполняться конкурентно.

• 123 типизированных вызываемых объекта Swagger-операций с семантическими именами и сгенерированной валидацией входа; напрямую с FastMCP регистрируется только настроенное подмножество.

• Шлюз по требованию для скрытых операций, сохраняющий полную функциональность LocalAI без анонсирования каждой схемы в каждом запросе.

• Поддержка multipart для аудио, изображений, GLB-файлов, брендинговых ассетов и голосовых профилей. Файловые аргументы принимают data: URI, base64:<data>, HTTP(S) URL или файлы в /data.

• Поддержка бинарных данных для аудио/изображений/GLB-ответов. Небольшие полезные нагрузки возвращаются как base64; бинарные полезные нагрузки также можно сохранять в /data/output.

• Обработка ответов с учётом SSE агрегирует SSE-события LocalAI в структурированный результат.

• Поддержка WebSocket для стриминга логов бэкенда и преобразований аудио в реальном времени с использованием ограниченных обменов.

• Bearer-аутентификация через LOCALAI_API_KEY; токен не хранится в коде и не возвращается MCP-клиентам.

Обёртка ответа

Типизированные HTTP-операции возвращают предсказуемую обёртку:

• ok: вернул ли LocalAI успешный HTTP-статус

• status_code: HTTP-статус LocalAI

• elapsed_ms: длительность запроса

• data: разобранные JSON-тела ответов

• text: текстовые ответы

• events: собранные полезные нагрузки SSE data:

• base64, size_bytes, mime_type, saved_path: метаданные/содержимое бинарного ответа, когда применимо

Всегда проверяйте ok перед использованием тела ответа.

Файловые входы

Для multipart-инструментов файловый аргумент может быть любым из:

• data:<mime>;base64,<payload>

• base64:<payload>

• http:// или https:// URL, который может загрузить MCP-контейнер

• локальный путь в LOCALAI_MCP_FILE_ROOT (/data в Compose)

Compose-файл монтирует ./data в /data.

Поведение стриминга LocalAI

Тела запросов LocalAI, устанавливающие stream=true, пересылаются без изменений. Если LocalAI отвечает text/event-stream, MCP-вызов собирает SSE-события data: и возвращает их, когда поток LocalAI завершается.

Два WebSocket-маршрута Swagger отображаются особым образом:

• stream_backend_logs: собирает сообщения логов бэкенда для модели до max_messages, затем закрывается.

• stream_audio_transform: отправляет один объект сессии/конфигурации плюс base64 PCM-кадры, собирает преобразованные сообщения до max_messages, затем закрывается.

Они могут быть прямыми или скрытыми в зависимости от LOCALAI_MCP_EXPOSED_TOOLS; скрытые WebSocket-инструменты остаются выполнимыми через execute_additional_tool.

Проверка

Тесты репозитория проверяют:

• точное покрытие Swagger: 114 путей / 123 операции

• 123 уникальных проверенных семантических имени

• количество по умолчанию в подобранной экспозиции и количество MCP tools/list

• полный каталог скрытых имён

• скрытый поиск, возвращающий реальные описания и сгенерированные схемы входа

• скрытое выполнение, проверяющее аргументы до сетевого доступа

• каждая не-WebSocket-операция, описание которой объясняет входы и выходы

• ссылочные схемы запросов/ответов, выводящие реальные поля

• detokenize, предоставляющий полезные указания по токенам/модели/контенту по требованию

• обнаружение WebSocket, обёртку ответов и обработку бинарных данных

• собранные wheel-пакеты, содержащие все четыре встроенные части Swagger-полезной нагрузки

Запуск локально с установленными зависимостями:

python -m pip install -e '.[test]'
pytest

Проверка в контейнере:

docker compose config
docker compose build

MCP-клиент должен выполнить обычное MCP-рукопожатие initialize против http://localhost:8000/mcp.

Конфигурация

Примечание по безопасности

Шлюз дополнительных инструментов по-прежнему может выполнять административные/разрушительные операции LocalAI, включая установку/удаление моделей/бэкендов, управление задачами/джобами, очистку трейсов/логов, брендинг, бюджеты узлов и администрирование голосовых профилей. Скрытие инструмента из tools/list уменьшает размер контекста; это не граница авторизации. Не публикуйте порт 8000 в ненадёжную сеть без аутентификации и контроля сетевого доступа перед ним.