mistral-simple-mcp

Сервер, реализующий Model Context Protocol, предоставляющий агенту два инструмента на базе Mistral: однократное заверенеие текста и извлечение структурированных данных, проверяемых по предоставленной вами JSON Schema.

Незавиимый проект, не связанный с Mistral AI и не одобренный им.

Что это такое

Два инструмента, работающие через Streamable HTTP и stdio:

• mistral_complete — однократное заверенеие текста: обобщение, переписка, классификация, чертование.

• mistral_extract — извлечение структурированных данных по предоставленной вами JSON Schema с проверкой ответа перед возвратом.

Streamable HTTP доступен по адресу POST /mcp; stdio выбирается флагом --stdio. Оба инструмента вызывают платную, недетерминированную API, поэтому ни один из них не помечен как read-only или idempotent.

Related MCP server: AgentTasker 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 через 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 переопределяет MCP_TRANSPORT независимо от содержимого .env. После 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 Schema 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 может и не может выражать.

Структурированный вывод

Аргумент schema в mistral_extract отправляется в Mistral дословно — он никогда не нормализуется и не переписывается. Именно это делает верным всё остальное в этом разделе.

Схема компилируется в валидатор Zod, и этот валидатор проверяет ответ. Оба действия выполняются встроенно: компиляция дешева, и две конструкции, которые могли бы сделать ее дорогой, сначала отклоняются. Все, что 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"]} — это стандартный способ указать, что поле может быть null, у него нет дочерних элементов для умножения, и он компилируется значительно быстрее миллисекунды, независимо от глубины вложенности.

С этими двумя отклоненными случаями оставшаяся стоимость пропорциональна размеру схемы, который транспорт уже ограничивает — схема размером 300 КБ компилируется примерно за 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, заполните два значения и выполните 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 с помощью проверки bearer-токена с постоянным временем. /health намеренно остаётся неаутентифицированным — он возвращает только {"status":"ok"}, и средам выполнения контейнеров необходимо обращаться к нему без токена для выполнения проверки работоспособности.

Известные ограничения

mistral_extract компилирует JSON Schema, предоставленную вызывающей стороной, поэтому он отказывается от двух конструкций, которые делают стоимость компиляции намного выше, чем размер схемы: $ref в любой форме и тип массива значений на узле, который имеет подсхемы под ним. Практическая цена заключается в том, что рекурсивные схемы не поддерживаются.

Полный список см. в 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 в этой конфигурации, так что линтинг может пройти для diff, который 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