LocalAiMCP

Un plano de control FastMCP asíncrono y sin estado para LocalAI. El Swagger de LocalAI incluido contiene 114 rutas / 123 operaciones, y las 123 siguen siendo utilizables mediante invocables tipados y validados. Para evitar enviar aproximadamente 123 esquemas de operación al modelo en cada solicitud MCP, solo se anuncia directamente un conjunto seleccionado; todo lo demás es descubrible y ejecutable bajo demanda.

Dos operaciones WebSocket de Swagger se implementan como intercambios acotados de una sola llamada, las rutas multipart admiten subida de archivos y las respuestas binarias pueden guardarse en ./data/output y devolverse en línea como base64 cuando son lo bastante pequeñas.

Ejecución

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

El endpoint MCP es:

http://localhost:8000/mcp

Para VS Code/Zoo Code u otro cliente MCP Streamable HTTP, usa esa URL como endpoint del servidor MCP remoto. El contenedor usa por defecto host.docker.internal:8080 para LocalAI e incluye la asignación host-gateway de Linux.

Related MCP server: LM Studio MCP Bridge

Superficie de herramientas seleccionadas

El servidor no anuncia las 123 operaciones de LocalAI por defecto. El ajuste predefinido anuncia 20 herramientas de operación de uso común más cinco ayudas fijas de descubrimiento/sistema.

Herramientas de operación expuestas directamente por defecto:

# 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

Las cinco ayudas MCP fijas son:

list_additional_tools
search_additional_tools
execute_additional_tool
server_health
schema_audit

Por tanto, la superficie tools/list por defecto es de 25 herramientas, en lugar de unas 128. El número exacto es configurable.

Configurar qué operaciones de LocalAI son visibles directamente

Establece LOCALAI_MCP_EXPOSED_TOOLS como una lista separada por comas de nombres semánticos de operación:

LOCALAI_MCP_EXPOSED_TOOLS=chat,list_models,generate_image,text_to_speech,generate_3d_asset

Valores especiales:

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

Un valor vacío o no establecido usa el ajuste predefinido integrado de 20 operaciones. Los nombres no válidos provocan un fallo al arrancar en lugar de desaparecer silenciosamente.

Cambiar la exposición directa solo afecta a lo que los clientes MCP reciben en tools/list; no elimina la operación oculta de LocalAiMCP.

Puerta de enlace de herramientas adicionales

Las herramientas menos comunes permanecen en un registro interno tipado y se accede a ellas mediante tres herramientas pequeñas.

list_additional_tools

Devuelve la lista ordenada completa de nombres de herramientas ocultas y nada con mucho esquema. Es intencionadamente compacta para que un modelo pueda inspeccionar todo el catálogo oculto bajo demanda sin llevar permanentemente esos esquemas en cada solicitud.

search_additional_tools

Busca solo entre las herramientas ocultas usando un objetivo en lenguaje natural o un nombre de herramienta exacto. Cada coincidencia devuelve:

• nombre semántico de la herramienta

• descripción detallada de propósito/entrada/salida

• etiquetas

• esquema JSON de entrada completo

Ejemplos:

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

Ejecuta una capacidad oculta por nombre semántico:

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

El objeto arguments se valida contra el mismo esquema Pydantic generado que usa una operación expuesta directamente. Los campos no válidos o desconocidos devuelven un error de validación y el esquema de entrada esperado antes de realizar cualquier solicitud a LocalAI. Esto no es un despachador al estilo curl: el modelo usa nombres semánticos de herramienta y argumentos tipados en lugar de métodos/rutas HTTP.

Las operaciones expuestas directamente son rechazadas intencionadamente por execute_additional_tool; el cliente debe llamar directamente a su herramienta MCP normal.

La antigua vía de escape avanzada raw_request y la ayuda probe_safe_endpoints se conservan como herramientas adicionales ocultas, de modo que reducir tools/list no elimina esas capacidades.

Descripciones orientadas a LLM

El registro está diseñado para que un modelo no necesite conocimientos previos de la API de LocalAI:

• Los nombres de las herramientas describen tareas en lugar de reflejar rutas o métodos HTTP.

• Cada operación HTTP tipada indica su propósito, las entradas esperadas y la salida en caso de éxito.

• Los esquemas JSON de solicitud incluyen descripciones a nivel de campo, con orientación conservadora de respaldo cuando Swagger solo dice cosas como Request o deja un campo sin documentar.

• Los objetos de solicitud referenciados muestran campos de nivel superior útiles directamente en las descripciones.

• Las descripciones de respuesta explican si los datos aparecen en data, text, events, base64 o saved_path.

• La búsqueda devuelve el esquema de entrada completo solo cuando la herramienta oculta es relevante.

• La infraestructura interna del envoltorio, como las cabeceras personalizadas y los tiempos de espera por llamada, queda fuera de las operaciones tipadas normales.

Por ejemplo, la herramienta oculta detokenize explica que su solicitud contiene:

• tokens: IDs de token enteros para convertir de vuelta a texto

• model: nombre o alias del modelo LocalAI cuyo tokenizador debe usarse

y que la respuesta JSON contiene content, el texto destokenizado.

Diseño

• FastMCP 3.4.7, fijado para reproducibilidad.

• Streamable HTTP + modo sin estado. Varios workers de Uvicorn son seguros porque el descubrimiento y la ejecución usan un registro inmutable local al proceso en lugar de estado conversacional/de sesión.

• E/S asíncrona de LocalAI con httpx; las llamadas independientes pueden ejecutarse de forma concurrente.

• 123 invocables de operación Swagger tipados con nombres semánticos y validación de entrada generada; solo el subconjunto configurado se registra directamente con FastMCP.

• Puerta de enlace bajo demanda para operaciones ocultas, que conserva toda la funcionalidad de LocalAI sin anunciar cada esquema en cada solicitud.

• Soporte multipart para audio, imágenes, archivos GLB, recursos de marca y perfiles de voz. Los argumentos de archivo aceptan URIs data:, base64:<data>, URLs HTTP(S) o archivos en /data.

• Soporte binario para respuestas de audio/imágenes/GLB. Los payloads pequeños se devuelven como base64; los payloads binarios también pueden guardarse en /data/output.

• Gestión de respuestas compatible con SSE que agrega los eventos SSE de LocalAI en un resultado estructurado.

• Soporte WebSocket para la transmisión de registros del backend y transformaciones de audio en tiempo real mediante intercambios acotados.

• Autenticación Bearer mediante LOCALAI_API_KEY; no se almacena ningún token en el código ni se devuelve a los clientes MCP.

Envoltorio de respuesta

Las operaciones HTTP tipadas devuelven un envoltorio predecible:

• ok: si LocalAI devolvió un estado HTTP correcto

• status_code: estado HTTP de LocalAI

• elapsed_ms: duración de la solicitud

• data: cuerpos de respuesta JSON analizados

• text: respuestas de texto

• events: payloads data: de SSE recopilados

• base64, size_bytes, mime_type, saved_path: metadatos/contenido de respuesta binaria cuando corresponda

Comprueba siempre ok antes de consumir el cuerpo de la respuesta.

Entradas de archivo

Para las herramientas multipart, un argumento de archivo puede ser cualquiera de los siguientes:

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

• base64:<payload>

• una URL http:// o https:// que el contenedor MCP pueda obtener

• una ruta local bajo LOCALAI_MCP_FILE_ROOT (/data en Compose)

El archivo de Compose monta ./data en /data.

Comportamiento de streaming de LocalAI

Los cuerpos de solicitud de LocalAI que establecen stream=true se reenvían sin cambios. Si LocalAI responde con text/event-stream, la llamada MCP recopila los eventos data: de SSE y los devuelve cuando termina el stream de LocalAI.

Las dos rutas WebSocket de Swagger se asignan de forma especial:

• stream_backend_logs: recopila mensajes de registro del backend para un modelo hasta max_messages y luego cierra.

• stream_audio_transform: envía un objeto de sesión/configuración más tramas PCM en base64, recopila mensajes transformados hasta max_messages y luego cierra.

Pueden ser directas u ocultas según LOCALAI_MCP_EXPOSED_TOOLS; las herramientas WebSocket ocultas siguen siendo ejecutables mediante execute_additional_tool.

Verificación

Las pruebas del repositorio verifican:

• cobertura exacta de Swagger: 114 rutas / 123 operaciones

• 123 nombres semánticos únicos revisados

• el recuento de la exposición seleccionada por defecto y el recuento de tools/list de MCP

• el catálogo completo de nombres ocultos

• la búsqueda oculta que devuelve descripciones reales y esquemas de entrada generados

• la ejecución oculta que valida argumentos antes del acceso a la red

• que cada descripción de operación no WebSocket explica entradas y salidas

• que los esquemas de solicitud/respuesta referenciados muestran campos reales

• que detokenize expone orientación útil sobre token/modelo/contenido bajo demanda

• la detección de WebSocket, el envoltorio de respuestas y la gestión de binarios

• que las ruedas construidas contienen las cuatro partes del payload de Swagger incluidas

Ejecuta localmente con las dependencias instaladas:

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

Validación del contenedor:

docker compose config
docker compose build

Un cliente MCP debe realizar el handshake initialize normal de MCP contra http://localhost:8000/mcp.

Configuración

Nota de seguridad

La puerta de enlace de herramientas adicionales aún puede ejecutar operaciones administrativas/destructivas de LocalAI, incluida la instalación/eliminación de modelos/backends, controles de tareas/trabajos, borrado de trazas/registros, marca, presupuestos de nodos y administración de perfiles de voz. Ocultar una herramienta de tools/list reduce el tamaño del contexto; no es una frontera de autorización. No publiques el puerto 8000 en una red no fiable sin autenticación y controles de acceso a la red por delante.