mistral-simple-mcp

Un servidor del Protocolo de Contexto de Modelo que proporciona a un agente dos herramientas respaldadas por Mistral: finalización de texto de un solo disparo y extracción de datos estructurados validados contra un esquema JSON que tú proporcionas.

Un proyecto independiente, no afiliado ni respaldado por Mistral AI.

Qué es esto

Dos herramientas, servidas a través de HTTP Transmisible y stdio:

• mistral_complete — finalización de texto de un solo disparo: resumir, reescribir, clasificar, redactar.

• mistral_extract — extracción de datos estructurados contra un esquema JSON que tú proporcionas, con la respuesta validada antes de que regrese.

HTTP Transmisible se sirve en POST /mcp; stdio se selecciona con la bandera --stdio. Ambas herramientas llaman a una API paga y no determinista, por lo que ninguna está anotada como de solo lectura o idempotente.

Related MCP server: AgentTasker MCP Server

Inicio rápido

Requiere Bun 1.3+.

bun install
cp .env.example .env
# edit .env and set MISTRAL_API_KEY (console.mistral.ai/api-keys)
bun run dev

El servidor se inicia por defecto en HTTP Transmisible, escuchando en http://127.0.0.1:3000/mcp. GET /health responde {"status":"ok"} una vez que está activo.

Configuración del cliente

stdio

Para un cliente que inicia el servidor como un subproceso — Claude Code, Claude Desktop, o cualquier otra cosa que lance un proceso y hable MCP a través de stdin/stdout:

{
  "mcpServers": {
    "mistral": {
      "command": "bun",
      "args": ["run", "/path/to/mistral-simple-mcp/src/index.ts", "--stdio"],
      "env": {
        "MISTRAL_API_KEY": "your-api-key-here"
      }
    }
  }
}

--stdio anula MCP_TRANSPORT sin importar lo que diga .env. Después de bun run build, apunta args a dist/index.js en lugar de src/index.ts — ambos ejecutan el mismo servidor.

HTTP Transmisible

Inicia el servidor (bun run dev, o la imagen Docker a continuación), luego apunta un cliente a /mcp:

{
  "mcpServers": {
    "mistral": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Si MCP_AUTH_TOKEN está configurado, agrega un encabezado coincidente:

{
  "mcpServers": {
    "mistral": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {"Authorization": "Bearer YOUR_TOKEN_HERE"}
    }
  }
}

Cuándo usarlo

Delegar una subtarea acotada a un modelo separado. Un agente que ya mantiene un contexto grande propio puede delegar un trabajo autónomo — resumir un documento, reescribir un párrafo en un tono diferente, clasificar un ticket de soporte — a mistral_complete en lugar de hacerlo en línea. Cada llamada es de un solo disparo y no mantiene estado de conversación entre invocaciones, por lo que esto se ajusta a un patrón de "delegar, obtener respuesta, continuar" en lugar de un chat de ida y vuelta.

Obtener JSON validado por esquema a partir de texto no estructurado. Cuando el resultado de una finalización va a ser leído por código en lugar de por una persona — analizado en una estructura, insertado en una base de datos, pasado a otra herramienta — mistral_extract es la opción más adecuada. Proporciona un Esquema JSON que describa la forma que necesitas; la respuesta se valida contra ese mismo esquema antes de ser devuelta, por lo que una llamada exitosa está garantizada para coincidir, y una discrepancia se devuelve como un error claro y reintentable en lugar de que el código posterior tropiece con la forma incorrecta.

Referencia de herramientas

Las descripciones a continuación están copiadas del esquema de cada herramienta, por lo que esta sección y el servidor no pueden divergir. Las respuestas de ejemplo muestran la forma de solicitud/respuesta; la redacción exacta y los recuentos de tokens variarán por llamada.

mistral_complete

Genera texto con un modelo Mistral. Úsalo para delegar una subtarea autónoma — resumir, reescribir, clasificar, redactar — a un modelo separado. Envía toda la entrada en prompt; esta es una llamada de un solo disparo que no mantiene estado de conversación entre invocaciones. Para salida que debe coincidir con una forma JSON específica, usa mistral_extract en su lugar.

Ejemplo de llamada

{
  "prompt": "Rewrite this for a support ticket, one sentence: users cant login when they use special chars in password",
  "system": "You write clear, professional bug report summaries.",
  "temperature": 0.2
}

Ejemplo de respuesta

{
  "text": "Login fails for users whose password contains special characters.",
  "model": "mistral-medium-latest",
  "finishReason": "stop",
  "usage": {
    "promptTokens": 42,
    "completionTokens": 12,
    "totalTokens": 54
  }
}

mistral_extract

Extrae datos estructurados que coinciden con un Esquema JSON que tú proporcionas. Devuelve un objeto validado contra ese esquema, por lo que una llamada exitosa siempre coincide con la forma solicitada. Úsalo en lugar de mistral_complete cuando el resultado vaya a ser leído por código en lugar de por una persona. Las propiedades opcionales se devuelven ausentes, no como nulo.

Ejemplo de llamada

{
  "prompt": "Extract the person described: Ada Lovelace, age 36.",
  "schema": {
    "type": "object",
    "properties": {
      "name": {"type": "string"},
      "age": {"type": "integer"}
    },
    "required": ["name", "age"]
  },
  "schemaName": "person"
}

Ejemplo de respuesta

{
  "data": {
    "name": "Ada Lovelace",
    "age": 36
  },
  "model": "mistral-medium-latest",
  "usage": {
    "promptTokens": 20,
    "completionTokens": 8,
    "totalTokens": 28
  }
}

Consulta Salida estructurada a continuación para ver qué puede y qué no puede expresar schema.

Salida estructurada

El argumento schema de mistral_extract se envía a Mistral tal cual — nunca se normaliza ni se reescribe. Eso es lo que hace que el resto de esta sección sea cierto.

El esquema se compila en un validador Zod, y ese validador verifica la respuesta. Ambos ocurren en línea: compilar es barato, y las dos construcciones que podrían hacerlo costoso son rechazadas primero. Cualquier cosa que Zod no pueda representar — if/then/else, not, dependentSchemas, unevaluatedProperties — falla en tiempo de compilación, antes de que se envíe cualquier solicitud, y la llamada a la herramienta informa un mensaje nombrando el problema. Un esquema malo no cuesta nada.

$ref no es compatible, en ninguna forma. En su lugar, incluye la definición. Una referencia permite que unos pocos cientos de bytes describan una estructura grande o infinita, y un ciclo que nunca desciende a través de properties o items se compila bien y luego nunca retorna cuando se verifica una respuesta contra él, porque recurre sin mirar nunca los datos. La consecuencia práctica es que los esquemas recursivos no se pueden expresar — una forma de árbol o lista enlazada necesita $ref. Si eso es importante para tu caso de uso, esta es la limitación a considerar.

Un type con valor de array es rechazado en un nodo que tiene subesquemas debajo. El compilador convierte los hijos de ese nodo una vez por cada entrada en el array, por lo que el costo se duplica en cada nivel mientras el documento crece unos pocos caracteres por nivel. {"type": ["object", "object"], "properties": {…}} anidado 18 niveles tiene 881 bytes y toma 3.5 segundos; a 22 niveles, aproximadamente 18. Asigna a dicho nodo un único type.

Un type con valor de array en una hoja está bien, que es el caso que realmente surge: {"type": ["string", "null"]} es la forma habitual de decir que un campo es anulable, no tiene hijos que multiplicar, y se compila en mucho menos de un milisegundo sin importar cuán profundamente esté anidado.

Con esos dos rechazados, el costo restante es proporcional al tamaño del esquema, que el transporte ya limita — un esquema de 300 KB se compila en aproximadamente 13 ms, y el anidamiento profundo, allOf, anyOf y patternProperties escalan linealmente. Un esquema lo suficientemente profundo como para agotar la pila lanza un error, y eso es capturado e informado como cualquier otro problema de esquema.

La respuesta se valida antes de ser devuelta. Debido a que el esquema no se normaliza, strict por defecto es false y la decodificación restringida de Mistral no garantiza la forma — esta validación es lo que mantiene el contrato de la herramienta. Una discrepancia se devuelve como un SchemaError que enumera cada ruta de campo infractora, para que un modelo llamante pueda corregir y reintentar en lugar de adivinar.

Las propiedades opcionales se devuelven ausentes, no nulas, y las propiedades adicionales no se eliminan. Ambos son consecuencia de enviar el esquema tal cual: una propiedad opcional sigue siendo opcional, y un esquema que no establece additionalProperties: false no prohíbe las adicionales.

No hay deliberadamente una configuración de número de reintentos. El SDK de Mistral no tiene una opción de número de intentos: su comportamiento de reintento es una forma de retroalimentación (intervalo inicial, intervalo máximo, exponente), no un número fijo de intentos, por lo que el parámetro que expone este servidor es MISTRAL_TIMEOUT_MS, que acota cuánto tiempo puede ejecutarse esa secuencia de retroalimentación en lugar de cuántas veces se ejecuta. El presupuesto de reintentos se establece en el 80% del mismo, deliberadamente menos que el total: el SDK solo informa la respuesta ascendente una vez que se ha gastado su presupuesto de reintentos, por lo que un presupuesto igual al plazo significa que un límite de tasa regresa como un tiempo de espera en lugar de como un límite de tasa.

Docker

docker build -t mistral-simple-mcp .
docker run -d -p 3000:3000 \
  -e MISTRAL_API_KEY=your-api-key-here \
  -e MCP_AUTH_TOKEN=generate-a-long-random-string \
  mistral-simple-mcp

O con Compose — copia docker-compose.example.yml, completa los dos valores y ejecuta docker compose -f docker-compose.example.yml up -d:

services:
  mistral-simple-mcp:
    image: ghcr.io/maxbth/mistral-simple-mcp:latest
    ports:
      - '3000:3000'
    environment:
      MISTRAL_API_KEY: your-api-key-here
      MCP_AUTH_TOKEN: generate-a-long-random-string
    restart: unless-stopped

Para stdio en su lugar, mantén el punto de entrada y sobrescribe los argumentos predeterminados:

docker run -i --rm -e MISTRAL_API_KEY=your-api-key-here mistral-simple-mcp --stdio

MCP_AUTH_TOKEN y 0.0.0.0

La imagen enlaza MCP_HOST=0.0.0.0 para que el contenedor sea accesible desde fuera de sí mismo — un contenedor escuchando en 127.0.0.1 solo acepta conexiones desde dentro de su propio espacio de nombres de red, lo que en la práctica significa ninguna. Siempre establece MCP_AUTH_TOKEN al ejecutar la imagen: sin él, cualquier cosa que pueda alcanzar el puerto publicado puede llamar a mistral_complete y mistral_extract sin autenticación alguna y gastar los créditos de la API de Mistral del propietario. El servidor registra una advertencia en stderr al inicio cada vez que está enlazado sin restricciones y sin token configurado.

MCP_AUTH_TOKEN protege /mcp con una verificación de token bearer de tiempo constante. /health permanece sin autenticación a propósito — no devuelve nada más que {"status":"ok"}, y los runtimes de contenedores necesitan alcanzarlo sin un token para ejecutar su sonda de salud.

Limitaciones conocidas

mistral_extract compila el esquema JSON proporcionado por el llamante, por lo que rechaza las dos construcciones que hacen que el costo de compilación sea enormemente mayor de lo que sugiere el tamaño del esquema: $ref en cualquier forma, y un type con valor de array en un nodo que tiene subesquemas debajo. El costo práctico es que los esquemas recursivos no son compatibles.

Consulta docs/known-limitations.md para la lista completa, incluyendo las tres clases conocidas de trabajo no acotado y qué las defiende.

Desarrollo

bun install
bun test
bun run typecheck   # Bun does not typecheck; this is what does
bun run lint:check

bun run lint:check no detecta todas las reglas de formato que Prettier aplica — las comas finales en particular no tienen equivalente en ESLint en esta configuración, por lo que lint puede pasar en un diff que Prettier aún rechazaría. Trátalo como una compuerta separada y ejecútalo antes de confirmar:

bunx prettier --check src scripts   # or: bun run format, to fix in place

Las pruebas están colocalizadas con lo que prueban (src/config.ts / src/config.test.ts), se ejecutan sin acceso a la red y sin una clave API real — se inyecta un MistralClient falso en lugar del real.

bun run build empaqueta y luego ejecuta lo que construyó.

bun run build          # bundle into dist/, then verify it
bun run verify:build   # just the verification, against an existing dist/

build empaqueta src/index.ts en dist/. El Dockerfile ejecuta el mismo comando con --minify.

Licencia

MIT © Maxime Bertheau