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를 호출하므로, 읽기 전용 또는 멱등성으로 주석 처리되지 않습니다.

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 또는 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"
      }
    }
  }
}

--stdio는 .env 설정과 관계없이 MCP_TRANSPORT를 재정의합니다. bun run build 후에는 args를 src/index.ts 대신 dist/index.js로 지정하세요. 둘 다 동일한 서버를 실행합니다.

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 유효성 검사기로 컴파일되며, 해당 검사기가 응답을 확인합니다. 두 작업 모두 인라인으로 수행됩니다. 컴파일은 저렴하며, 비용이 많이 들 수 있는 두 가지 구조는 먼저 거부됩니다. Zod가 표현할 수 없는 것(if/then/else, not, dependentSchemas, unevaluatedProperties)은 요청 전송 전에 컴파일 시점에 실패하며, 도구 호출은 문제를 명시하는 메시지를 반환합니다. 잘못된 스키마는 비용이 들지 않습니다.

$ref는 어떤 형태로든 지원되지 않습니다. 대신 정의를 인라인으로 작성하세요. 참조는 적은 바이트로 크거나 무한한 구조를 설명할 수 있게 하지만, properties나 items를 통해 내려가지 않는 순환은 컴파일은 잘 되지만 응답을 확인할 때 데이터를 전혀 보지 않고 재귀하기 때문에 반환되지 않습니다. 실제 결과는 재귀적 스키마를 표현할 수 없다는 것입니다. 트리나 연결 리스트 형태는 $ref가 필요합니다. 해당 사항이 사용 사례에 중요하다면 이 한계를 고려하세요.

하위 스키마가 있는 노드에서 배열 값의 type은 거부됩니다. 컴파일러는 해당 노드의 자식들을 배열의 각 항목마다 한 번씩 변환하므로, 문서가 수준당 몇 문자씩 증가하는 동안 비용이 모든 수준에서 두 배가 됩니다. 18단계 깊이로 중첩된 {"type": ["object", "object"], "properties": {…}}는 881바이트이며 3.5초가 걸립니다. 22단계에서는 약 18초가 소요됩니다. 해당 노드에는 단일 type을 지정하세요.

리프 노드에서 배열 값의 type은 괜찮습니다. 이것이 실제로 자주 발생하는 경우입니다. {"type": ["string", "null"]}은 필드가 nullable임을 표현하는 일반적인 방법이며, 곱할 자식이 없고 아무리 깊이 중첩되어도 1밀리초 미만으로 컴파일됩니다.

이 두 가지가 거부되면, 나머지 비용은 스키마 크기에 비례하며, 이는 전송이 이미 제한합니다. 300KB 스키마는 약 13ms에 컴파일되며, 깊은 중첩, allOf, anyOf, patternProperties 모두 선형적으로 확장됩니다. 스택을 소진할 정도로 깊은 스키마는 예외를 발생시키며, 이는 다른 스키마 문제와 마찬가지로 포착되어 보고됩니다.

응답은 반환되기 전에 유효성 검사됩니다. 스키마가 정규화되지 않았기 때문에 strict는 기본적으로 false이며, Mistral의 제약적 디코딩이 형태를 보장하지 않습니다. 이 유효성 검사가 도구의 계약을 유지합니다. 불일치가 발생하면 각 문제 필드 경로를 나열하는 SchemaError로 반환되므로, 호출 모델이 추측 대신 수정하고 재시도할 수 있습니다.

선택적 속성은 null이 아닌 누락된 상태로 반환되며, 추가 속성은 제거되지 않습니다. 두 경우 모두 스키마를 그대로 전송하기 때문입니다. 선택적 속성은 선택적으로 유지되며, additionalProperties: false를 설정하지 않은 스키마는 추가 항목을 금지하지 않습니다.

설정

재시도 횟수 설정은 의도적으로 없습니다. Mistral SDK에는 시도 횟수 옵션이 없습니다. 재시도 동작은 고정된 시도 횟수가 아닌 백오프 형태(초기 간격, 최대 간격, 지수)입니다. 따라서 이 서버가 제공하는 설정은 MISTRAL_TIMEOUT_MS이며, 이는 재시도 시퀀스가 실행될 수 있는 시간을 제한하는 것이지 실행 횟수를 제한하는 것이 아닙니다. 재시도 예산은 이 값의 80%로 설정되며, 전체보다 의도적으로 적게 설정됩니다. SDK는 재시도 예산이 소진된 후에야 업스트림 응답을 보고하므로, 예산이 마감 시간과 같으면 속도 제한이 속도 제한 대신 타임아웃으로 반환됩니다.

도커

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를 컴파일하므로, 컴파일 비용이 스키마 크기보다 훨씬 커지게 하는 두 가지 구성을 거부합니다: 모든 형태의 $ref와, 하위 스키마가 있는 노드의 배열 값 type입니다. 실제 결과는 재귀 스키마가 지원되지 않음입니다.

전체 목록은 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에 해당하는 것이 없으므로, 린트가 통과해도 Prettier가 거부할 수 있습니다. 별도의 게이트로 취급하고 커밋 전에 실행하세요:

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

테스트는 테스트 대상과 같은 위치에 있습니다 (src/config.ts / src/config.test.ts). 네트워크 접근 없이, 실제 API 키 없이 실행됩니다. 실제 MistralClient 대신 가짜 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