mistral-simple-mcp

Ein Model Context Protocol-Server, der einem Agenten zwei Tools bereitstellt, die auf Mistral basieren: einmalige Textvervollständigung und strukturierte Datenextraktion, validiert gegen ein von Ihnen bereitgestelltes JSON-Schema.

Ein unabhängiges Projekt, nicht verbunden mit oder unterstützt von Mistral AI.

Was dies ist

Zwei Tools, bereitgestellt über Streamable HTTP und stdio:

• mistral_complete — einmalige Textvervollständigung: zusammenfassen, umschreiben, klassifizieren, entwerfen.

• mistral_extract — strukturierte Datenextraktion gegen ein von Ihnen bereitgestelltes JSON-Schema, wobei die Antwort validiert wird, bevor sie zurückkommt.

Streamable HTTP wird unter POST /mcp bereitgestellt; stdio wird mit dem --stdio-Flag ausgewählt. Beide Tools rufen eine kostenpflichtige, nicht-deterministische API auf, daher ist keines als schreibgeschützt oder idempotent annotiert.

Related MCP server: AgentTasker MCP Server

Schnellstart

Erfordert Bun 1.3+.

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

Der Server startet standardmäßig auf Streamable HTTP und hört unter http://127.0.0.1:3000/mcp. GET /health antwortet mit {"status":"ok"}, sobald er läuft.

Client-Konfiguration

stdio

Für einen Client, der den Server als Unterprozess startet — Claude Code, Claude Desktop oder alles andere, das einen Prozess startet und MCP über stdin/stdout spricht:

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

--stdio überschreibt MCP_TRANSPORT, egal was in .env steht. Nach bun run build zeigen Sie args auf dist/index.js statt src/index.ts — beide führen denselben Server aus.

Streamable HTTP

Starten Sie den Server (bun run dev oder das Docker-Image unten), dann richten Sie einen Client auf /mcp aus:

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

Wenn MCP_AUTH_TOKEN gesetzt ist, fügen Sie einen passenden Header hinzu:

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

Wann man es verwendet

Delegieren einer abgegrenzten Teilaufgabe an ein separates Modell. Ein Agent, der bereits einen großen eigenen Kontext hält, kann eine in sich geschlossene Arbeit — Zusammenfassen eines Dokuments, Umschreiben eines Absatzes in einem anderen Ton, Klassifizieren eines Support-Tickets — an mistral_complete delegieren, anstatt es inline zu erledigen. Jeder Aufruf ist einmalig und behält keinen Gesprächszustand zwischen den Aufrufen, daher passt dies zu einem „delegieren, Antwort erhalten, fortfahren“-Muster und nicht zu einem Hin-und-Her-Chat.

Schema-validiertes JSON aus unstrukturiertem Text gewinnen. Wenn das Ergebnis einer Vervollständigung von Code statt von einer Person gelesen wird — in eine Struktur geparst, in eine Datenbank eingefügt, an ein anderes Tool übergeben — ist mistral_extract die bessere Wahl. Geben Sie ein JSON-Schema an, das die benötigte Form beschreibt; die Antwort wird gegen dasselbe Schema validiert, bevor sie zurückgegeben wird, sodass ein erfolgreicher Aufruf garantiert übereinstimmt und eine Nichtübereinstimmung als klarer, wiederholbarer Fehler zurückkommt, anstatt dass nachgelagerter Code über die falsche Form stolpert.

Tool-Referenz

Die folgenden Beschreibungen sind aus dem jeweiligen Schema jedes Tools kopiert, sodass dieser Abschnitt und der Server nicht auseinanderdriften können. Beispielantworten zeigen die Anfrage-/Antwortform; genaue Formulierung und Token-Anzahl variieren pro Aufruf.

mistral_complete

Text mit einem Mistral-Modell generieren. Verwenden Sie dies, um eine in sich geschlossene Teilaufgabe — Zusammenfassen, Umschreiben, Klassifizieren, Entwerfen — an ein separates Modell zu delegieren. Senden Sie die gesamte Eingabe in prompt; dies ist ein einmaliger Aufruf, der keinen Gesprächszustand zwischen den Aufrufen behält. Für Ausgaben, die einer bestimmten JSON-Form entsprechen müssen, verwenden Sie stattdessen mistral_extract.

Beispielaufruf

{
  "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
}

Beispielantwort

{
  "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

Strukturierte Daten extrahieren, die einem von Ihnen bereitgestellten JSON-Schema entsprechen. Gibt ein gegen dieses Schema validiertes Objekt zurück, sodass ein erfolgreicher Aufruf immer der angeforderten Form entspricht. Verwenden Sie dies anstelle von mistral_complete, wenn das Ergebnis von Code statt von einer Person gelesen wird. Optionale Eigenschaften werden als fehlend zurückgegeben, nicht als null.

Beispielaufruf

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

Beispielantwort

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

Siehe Strukturierte Ausgabe unten für das, was schema ausdrücken kann und was nicht.

Strukturierte Ausgabe

Das schema-Argument von mistral_extract wird wortwörtlich an Mistral gesendet – es wird nie normalisiert oder umgeschrieben. Das macht den Rest dieses Abschnitts wahr.

Das Schema wird zu einem Zod-Validator kompiliert, und dieser Validator prüft die Antwort. Beides geschieht inline: Die Kompilierung ist günstig, und die beiden Konstrukte, die sie teuer machen könnten, werden zuerst abgelehnt. Alles, was Zod nicht darstellen kann – if/then/else, not, dependentSchemas, unevaluatedProperties – schlägt zur Kompilierzeit fehl, bevor eine Anfrage gesendet wird, und der Tool-Aufruf meldet eine Nachricht, die das Problem benennt. Ein schlechtes Schema kostet nichts.

$ref wird in keiner Form unterstützt. Definieren Sie die Definition stattdessen inline. Ein Verweis lässt einige hundert Bytes eine große oder unendliche Struktur beschreiben, und ein Zyklus, der nie durch properties oder items absteigt, kompiliert einwandfrei und kehrt dann nie zurück, wenn eine Antwort dagegen geprüft wird, weil er rekursiv ist, ohne jemals auf die Daten zu schauen. Die praktische Konsequenz ist, dass rekursive Schemata nicht ausgedrückt werden können – eine Baum- oder Listenstruktur benötigt $ref. Wenn das für Ihren Anwendungsfall wichtig ist, ist dies die Einschränkung, die Sie abwägen sollten.

Ein array-wertiger type wird auf einem Knoten abgelehnt, der Unterschemata unter sich hat. Der Compiler konvertiert die Kinder dieses Knotens einmal pro Eintrag im Array, sodass sich die Kosten auf jeder Ebene verdoppeln, während das Dokument um ein paar Zeichen pro Ebene wächst. {"type": ["object", "object"], "properties": {…}} 18 Ebenen tief sind 881 Bytes und dauern 3,5 Sekunden; bei 22 Ebenen etwa 18. Geben Sie einem solchen Knoten einen einzelnen type.

Ein array-wertiger type auf einem Blatt ist in Ordnung, was der Fall ist, der tatsächlich vorkommt: {"type": ["string", "null"]} ist die übliche Art, ein Feld als nullbar zu kennzeichnen, hat keine Kinder, die multipliziert werden, und kompiliert in deutlich unter einer Millisekunde, egal wie tief es verschachtelt ist.

Mit diesen beiden abgelehnten Fällen ist der verbleibende Aufwand proportional zur Größe des Schemas, die der Transport bereits begrenzt – ein 300 KB großes Schema kompiliert in etwa 13 ms, und tiefe Verschachtelung, allOf, anyOf und patternProperties skalieren alle linear. Ein Schema, das tief genug ist, um den Stack zu erschöpfen, wirft einen Fehler, der abgefangen und wie jedes andere Schema-Problem gemeldet wird.

Die Antwort wird validiert, bevor sie zurückgegeben wird. Da das Schema nicht normalisiert ist, ist strict standardmäßig false und die eingeschränkte Dekodierung von Mistral garantiert nicht die Form – diese Validierung ist es, die den Vertrag des Tools hält. Eine Nichtübereinstimmung wird als SchemaError zurückgegeben, der jeden fehlerhaften Feldpfad auflistet, sodass ein aufrufendes Modell korrigieren und erneut versuchen kann, anstatt zu raten.

Optionale Eigenschaften werden als abwesend zurückgegeben, nicht als null, und zusätzliche Eigenschaften werden nicht entfernt. Beides folgt daraus, dass das Schema wortwörtlich gesendet wird: Eine optionale Eigenschaft bleibt optional, und ein Schema, das nicht additionalProperties: false setzt, verbietet keine Extras.

Konfiguration

Es gibt bewusst keine Einstellung für die Anzahl der Wiederholungen. Das Mistral SDK hat keine Option für die Anzahl der Versuche – sein Wiederholungsverhalten ist eine Backoff-Form (anfängliches Intervall, maximales Intervall, Exponent), keine feste Anzahl von Versuchen – daher ist der Knopf, den dieser Server bereitstellt, MISTRAL_TIMEOUT_MS, der begrenzt, wie lange diese Backoff-Sequenz laufen darf, und nicht, wie oft sie läuft. Das Wiederholungsbudget ist auf 80 % davon festgelegt, bewusst weniger als das Ganze: Das SDK meldet die Antwort des Upstreams erst, wenn sein Wiederholungsbudget aufgebraucht ist, daher führt ein Budget, das der Frist entspricht, dazu, dass eine Ratenbegrenzung als Zeitüberschreitung und nicht als Ratenbegrenzung zurückkommt.

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

Oder mit Compose – kopieren Sie docker-compose.example.yml, füllen Sie die beiden Werte aus und führen Sie docker compose -f docker-compose.example.yml up -d aus:

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

Für stdio stattdessen behalten Sie den Entrypoint bei und überschreiben die Standard-Argumente:

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

MCP_AUTH_TOKEN und 0.0.0.0

Das Image bindet MCP_HOST=0.0.0.0, damit der Container von außerhalb erreichbar ist – ein Container, der auf 127.0.0.1 lauscht, akzeptiert nur Verbindungen aus seinem eigenen Netzwerk-Namespace, was in der Praxis bedeutet, dass keine Verbindungen ankommen. Setzen Sie immer MCP_AUTH_TOKEN, wenn Sie das Image ausführen: Ohne diesen kann alles, was den veröffentlichten Port erreicht, mistral_complete und mistral_extract ohne Authentifizierung aufrufen und die Mistral-API-Guthaben des Besitzers verbrauchen. Der Server protokolliert beim Start eine Warnung auf stderr, wenn er weit offen gebunden ist und kein Token konfiguriert ist.

MCP_AUTH_TOKEN schützt /mcp mit einer zeitkonstanten Bearer-Token-Prüfung. /health bleibt absichtlich unauthentifiziert – es gibt nichts zurück außer {"status":"ok"}, und Container-Laufzeiten müssen es ohne Token erreichen können, um ihre Gesundheitsprüfung durchzuführen.

Bekannte Einschränkungen

mistral_extract kompiliert das vom Aufrufer bereitgestellte JSON Schema und lehnt daher die beiden Konstrukte ab, die die Kompilierungskosten weit über das hinaus treiben, was die Größe des Schemas vermuten lässt: $ref in jeglicher Form und ein array-wertiges type auf einem Knoten, der Unterschemata unter sich hat. Der praktische Nachteil ist, dass rekursive Schemas nicht unterstützt werden.

Siehe docs/known-limitations.md für die vollständige Liste, einschließlich der drei bekannten Klassen unbegrenzter Arbeit und was dagegen schützt.

Entwicklung

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

bun run lint:check erfasst nicht jede Formatierungsregel, die Prettier durchsetzt – insbesondere nachgestellte Kommas haben in dieser Konfiguration kein ESLint-Äquivalent, daher kann Lint einen Diff bestehen, den Prettier dennoch ablehnen würde. Behandeln Sie es als separates Tor und führen Sie es vor dem Commit aus:

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

Tests befinden sich am selben Ort wie das, was sie testen (src/config.ts / src/config.test.ts), werden ohne Netzwerkzugriff und ohne echten API-Schlüssel ausgeführt – ein gefälschter MistralClient wird anstelle des echten injiziert.

bun run build bündelt und führt dann das Gebaute aus.

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

build bündelt src/index.ts nach dist/. Das Dockerfile führt denselben Befehl mit --minify aus.

Lizenz

MIT © Maxime Bertheau