mistral-simple-mcp

一个模型上下文协议服务器，为智能体提供两个由Mistral支持的工具：单次文本补全，以及根据您提供的 JSON Schema 进行验证的结构化数据提取。

这是一个独立项目，与 Mistral AI 无关联，也未获得其认可。

这是什么

两个工具，通过 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 或任何其他启动进程并通过 stdin/stdout 使用 MCP 协议的工具：

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

无论 .env 文件如何设置，--stdio 都会覆盖 MCP_TRANSPORT。在 bun run build 之后，将 args 指向 dist/index.js 而不是 src/index.ts——两者运行的是同一个服务器。

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；响应在返回前会针对同一模式进行验证，因此成功调用保证匹配，不匹配则会返回清晰、可重试的错误，而不是下游代码因错误形状而出错。

工具参考

以下描述直接复制自每个工具自身的模式，因此本节与服务器不会出现偏差。示例响应展示了请求/响应的结构；具体措辞和 token 数量因调用而异。

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——不会被标准化或重写。这也正是本部分内容成立的基础。

该 schema 会被编译成 Zod 验证器，并由该验证器检查响应。 这两步均为内联执行：编译成本很低，两种可能导致编译昂贵的构造会预先被拒绝。任何 Zod 无法表示的内容——if/then/else、not、dependentSchemas、unevaluatedProperties——会在编译时失败（在发送任何请求之前），工具调用会报告描述问题的消息。错误的 schema 不会产生额外成本。

不支持任何形式的 $ref。 请改为内联定义。引用机制允许用几百字节描述一个巨大或无限的结构，但如果一个循环从未通过 properties 或 items 向下展开，编译会通过，而在根据该循环检查响应时却永远不会返回结果，因为它会不断递归而从不查看数据。实际后果是 无法表达递归 schema——树或链表结构需要使用 $ref。如果这对您的用例很重要，则需要权衡这一限制。

在具有子 schema 的节点上，数组值 type 会被拒绝。 编译器会针对数组中每个条目转换该节点的子节点，因此每层成本翻倍，而文档每层仅增加几个字符。嵌套 18 层的 {"type": ["object", "object"], "properties": {…}} 占用 881 字节，需要 3.5 秒；22 层时约为 18 秒。请为这类节点指定单一 type。

叶子节点上的数组值 type 没问题，这也是实际会遇到的场景：{"type": ["string", "null"]} 是声明字段可空的常规方式，它没有子节点需要倍增，无论嵌套多深，编译时间都远低于 1 毫秒。

拒绝上述两种构造后，剩余成本与 schema 大小成正比，而传输层已经限制了大小——一个 300 KB 的 schema 编译约需 13 毫秒，深度嵌套、allOf、anyOf 和 patternProperties 均为线性扩展。深度足以耗尽栈的 schema 会抛出异常，该异常会被捕获并像其他 schema 问题一样报告。

响应会在返回前进行验证。 由于 schema 不会被标准化，strict 默认为 false，Mistral 的约束解码不保证形状——正是这个验证保证了工具的契约。不匹配会作为 SchemaError 返回，列出每个违规字段路径，因此调用模型可以修正并重试，而非猜测。

可选属性不会返回，而是直接缺失，并且额外属性不会被剔除。这两点都源于原样发送 schema：可选属性保持可选，未设置 additionalProperties: false 的 schema 也不会禁止额外属性。

配置

故意没有设置重试次数。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，填写两个值，然后运行 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 通过常量时间 bearer 令牌检查保护 /mcp。/health 故意保持未认证状态——它只返回 {"status":"ok"}，容器运行时需要无需令牌即可访问它以运行健康检查。

已知限制

mistral_extract 会编译调用者提供的 JSON Schema，因此它拒绝两种会使编译成本远超 schema 大小的结构：任何形式的 $ref，以及节点上具有子 schema 的数组类型 type。实际代价是不支持递归 schema。

完整列表请参见 docs/known-limitations.md，包括三种已知的无界工作类别及其防御措施。

开发

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