mistral-simple-mcp

Model Context Protocol サーバーであり、エージェントに Mistral をバックエンドとする2つのツールを提供します。単発のテキスト補完と、指定した JSON Schema に従って検証される構造化データ抽出です。

独立したプロジェクトであり、Mistral AI とは提携・承認関係はありません。

これが何か

2つのツールを Streamable HTTP と stdio で提供します：

• mistral_complete — 単発のテキスト補完：要約、書き換え、分類、下書き作成など。

• mistral_extract — 指定した JSON Schema に基づく構造化データ抽出。応答は返却前に検証されます。

Streamable HTTP は POST /mcp で提供され、stdio は --stdio フラグで選択します。両ツールとも有料の非決定的な API を呼び出すため、読み取り専用や冪等性は付与されていません。

Related MCP server: Mistral MCP Server

クイックスタート

Bun 1.3以上が必要です。

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

サーバーはデフォルトで Streamable HTTP で起動し、http://127.0.0.1:3000/mcp で待機します。 起動後、GET /health で {"status":"ok"} が返ります。

クライアント設定

stdio

サーバーを子プロセスとして起動するクライアント（Claude Code、Claude Desktop、または標準入出力で MCP をやり取りする任意のクライアント）の場合：

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

--stdio は .env の設定に関係なく MCP_TRANSPORT を上書きします。bun run build 実行後は、src/index.ts ではなく dist/index.js を args に指定してください。どちらも同じサーバーが起動します。

Streamable HTTP

サーバーを起動（bun run dev、または下記の Docker イメージ）し、クライアントを /mcp に指定します：

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

MCP_AUTH_TOKEN が設定されている場合は、一致するヘッダーを追加します：

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

使用すべきケース

限定されたサブタスクを別のモデルに委譲する場合。 すでに大きなコンテキストを保持しているエージェントが、自己完結した作業（ドキュメントの要約、段落のトーン変更、サポートチケットの分類など）をインラインで処理する代わりに mistral_complete に委譲できます。各呼び出しは単発であり、呼び出し間で会話状態は保持されないため、「委譲 → 回答を得る → 続行」というパターンに適しており、やり取り型のチャットではありません。

非構造化テキストからスキーマ検証済みの JSON を取得する場合。 補完結果が人間ではなくコードによって読み取られる場合（構造体へのパース、データベースへの挿入、別のツールへの受け渡しなど）は、mistral_extract が適しています。必要な形状を記述した JSON Schema を指定すると、応答はそのスキーマに対して検証されてから返されるため、成功した呼び出しは常にスキーマに一致し、不一致の場合は明確で再試行可能なエラーとして返されるため、後続のコードが誤った形状に起因する問題を引き起こすことはありません。

ツールリファレンス

以下の説明は各ツールのスキーマからコピーされているため、このセクションとサーバーに乖離はありません。例の応答はリクエスト/レスポンスの形状を示しますが、実際の文言やトークン数は呼び出しごとに異なります。

mistral_complete

Mistral モデルでテキストを生成します。自己完結したサブタスク（要約、書き換え、分類、下書き）を別のモデルに委譲するために使用します。入力全体を prompt に送信します。これは単発の呼び出しであり、呼び出し間で会話状態は保持されません。特定の JSON 形状に一致する出力が必要な場合は、代わりに mistral_extract を使用してください。

呼び出し例

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

応答例

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

指定した JSON Schema に一致する構造化データを抽出します。そのスキーマに対して検証済みのオブジェクトを返すため、成功した呼び出しは常に要求された形状と一致します。結果が人間ではなくコードによって読み取られる場合は、mistral_complete の代わりにこちらを使用してください。オプションプロパティは欠損状態で返され、null にはなりません。

呼び出し例

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

応答例

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

schemaで表現できることとできないことについては、以下の構造化出力を参照してください。

構造化出力

mistral_extractのschema引数はそのままMistralに送信されます — 正規化や書き換えは一切行われません。これにより、このセクションの残りの内容が成立します。

スキーマはZodバリデーターにコンパイルされ、そのバリデーターが応答をチェックします。 どちらもインラインで行われます。コンパイルは軽量で、コストを高くする可能性のある2つの構造は事前に拒否されます。Zodが表現できないもの（if/then/else、not、dependentSchemas、unevaluatedProperties）は、リクエスト送信前のコンパイル時に失敗し、ツール呼び出しは問題を特定するメッセージを報告します。不良なスキーマはコストを発生させません。

$refは一切サポートされていません。 代わりに定義をインライン化してください。参照を使用すると、数百バイトで巨大または無限の構造を記述でき、propertiesやitemsを介して決して降下しないサイクルはコンパイルは通りますが、応答をチェックする際にデータを一切見ることなく再帰するため、戻り値が返ってきません。実際的な結果として、再帰的なスキーマは表現できません — 木構造やリンクリストの形状には$refが必要です。それがユースケースにとって重要であれば、これが考慮すべき制限です。

サブスキーマを持つノードでは、配列値のtypeは拒否されます。 コンパイラはそのノードの子を配列のエントリごとに変換するため、ドキュメントがレベルごとに数文字増えるたびに、コストは各レベルで倍増します。{"type": ["object", "object"], "properties": {…}}を18階層ネストすると881バイトで3.5秒かかります。22階層では約18秒になります。そのようなノードには単一のtypeを指定してください。

リーフノードでの配列値のtypeは問題ありません。これは実際によくあるケースで、{"type": ["string", "null"]}はフィールドをnullableにする標準的な方法であり、子を持たず、何階層ネストしてもコンパイルは1ミリ秒未満で完了します。

これら2つが拒否されれば、残りのコストはスキーマのサイズに比例します。これはトランスポートがすでに制限しています — 300 KBのスキーマは約13ミリ秒でコンパイルされ、深いネスト、allOf、anyOf、patternPropertiesはすべて線形にスケーリングします。スタックを枯渇させるほど深いスキーマは例外をスローし、他のスキーマ問題と同様に捕捉されて報告されます。

応答は返される前に検証されます。 スキーマは正規化されないため、strictはデフォルトでfalseとなり、Mistralの制約付きデコードは形状を保証しません — この検証がツールの契約を支えています。不一致があった場合は、各違反フィールドパスを列挙したSchemaErrorが返されるため、呼び出し元のモデルは推測ではなく修正と再試行が可能です。

オプショナルなプロパティは欠落した状態で返され、nullにはなりません。 また、余分なプロパティは削除されません。 どちらもスキーマをそのまま送信することに起因します。オプショナルなプロパティはオプショナルのままであり、additionalProperties: falseを設定していないスキーマは余分なプロパティを禁止しません。

設定

リトライ回数の設定は意図的に設けていません。Mistral SDKには試行回数のオプションはなく、リトライ動作はバックオフ形状（初期間隔、最大間隔、指数）に基づいており、固定回数ではありません。そのため、このサーバーが公開する設定は MISTRAL_TIMEOUT_MS であり、これはバックオフシーケンスの実行時間を制限するもので、試行回数そのものを制限するものではありません。リトライ予算はその80%に設定されており、全体よりも意図的に少なくなっています。SDKはリトライ予算を使い果たした後にのみ上流の応答を報告するため、予算が期限と同じだと、レート制限がタイムアウトとして返ってきてしまい、レート制限として認識されないからです。

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

またはComposeを使用する場合 — docker-compose.example.yml をコピーし、2つの値を入力して、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

代わりにstdioを使用する場合は、エントリポイントを維持し、デフォルトの引数を上書きします：

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

MCP_AUTH_TOKEN と 0.0.0.0

イメージは MCP_HOST=0.0.0.0 にバインドするため、コンテナは外部から到達可能になります。127.0.0.1 でリッスンしているコンテナは、自身のネットワーク名前空間内からの接続のみを受け入れます。実際には、外部からの接続は一切受け付けません。イメージを実行する際は必ず MCP_AUTH_TOKEN を設定してください。設定しない場合、公開ポートに到達可能なものはすべて、認証なしで mistral_complete や mistral_extract を呼び出し、所有者のMistral APIクレジットを消費できます。サーバーは起動時に、トークンが設定されずに広くバインドされている場合、stderrに警告を出力します。

MCP_AUTH_TOKEN は、定数時間のベアラートークンチェックで /mcp を保護します。/health は意図的に認証なしのままです。{"status":"ok"} のみを返し、コンテナランタイムがヘルスプローブを実行するためにトークンなしで到達できる必要があります。

既知の制限事項

mistral_extract は呼び出し元から提供されたJSONスキーマをコンパイルするため、スキーマのサイズに比べてコンパイルコストが大幅に高くなる2つの構造を拒否します。$ref をあらゆる形式で使用すること、および、サブスキーマを持つノードに配列形式の type を使用することです。実質的な制約として、再帰スキーマはサポートされません。

完全なリストは docs/known-limitations.md を参照してください。既知の3つの無制限ワーククラスと、それらに対する防御策が含まれています。

開発

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

bun run lint:check は、Prettier が強制するすべてのフォーマットルールを捕捉するわけではありません。特に末尾のカンマは、この設定ではESLintに相当するものがないため、lintが通過してもPrettierが拒否する差分が生じる可能性があります。これを別のゲートとして扱い、コミット前に実行してください：

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

テストはテスト対象と同じ場所に配置されます（src/config.ts / src/config.test.ts）。ネットワークアクセスや実際のAPIキーは使用せず、代わりに偽の MistralClient が注入されて実行されます。

bun run build はバンドルしてから、ビルドしたものを実行します。

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

build は src/index.ts を dist/ にバンドルします。Dockerfile は同じコマンドを --minify 付きで実行します。

ライセンス

MIT © Maxime Bertheau