MistralDocAI MCP Server

Mistral AI의 OCR 및 비전 모델을 사용하여 문서와 이미지를 Markdown으로 변환하는 MCP 서버입니다. PDF, 슬라이드 데크, Word 문서 또는 스캔한 이미지를 지정하면 MCP 클라이언트가 Markdown을 받게 됩니다.

이미 Claude Desktop과 같은 MCP 클라이언트를 사용하고 있으며 별도의 도구가 아닌 클라이언트 내에서 문서 변환을 원하는 사람들을 위한 것입니다.

상태: 개인 프로젝트로 적극적으로 유지 관리되며, 최선을 다하고 있습니다. 현재 버전은 2.0입니다. 1.x에서 업그레이드하기 전에 버전 및 호환성을 참조하세요.

언어: 이 프로젝트는 영어 전용입니다. 인터페이스 텍스트, 문서, 오류 메시지는 영어이며, 지역화된 빌드는 게시되지 않습니다. 처리하는 문서는 Mistral 모델이 지원하는 모든 언어일 수 있습니다.

요구 사항

Python 종속성을 직접 설치할 필요는 없습니다. 서버는 첫 실행 시 ~/.mistraldocai-mcp/ 아래에 가상 환경을 생성합니다.

Related MCP server: Mistral OCR MCP Server

설치

머신에서 실행할 수 있는지 확인하세요:

npx @trsdn/mistraldocai-mcp-server --test

이 명령은 Python 환경을 생성하고, 종속성을 설치하고, 서버를 가져오고, 발견한 내용을 보고합니다. 클라이언트를 구성하기 전에 실행하세요. 클라이언트 측의 조용한 실패를 읽을 수 있는 오류로 바꿔주기 때문입니다.

구성

API 키

클라이언트가 서버를 시작하는 환경에서 내보내거나:

export MISTRAL_API_KEY=your_key_here

또는 서버가 첫 실행 시 생성하는 ~/.mistraldocai-mcp/.env에 넣으세요:

MISTRAL_API_KEY=your_key_here

파일이 일반적으로 더 안정적인 옵션입니다. 데스크톱 MCP 클라이언트는 종종 셸 환경을 상속하지 않기 때문입니다.

Claude Desktop

claude_desktop_config.json에 다음을 추가하세요:

{
  "mcpServers": {
    "mistraldocai": {
      "command": "npx",
      "args": ["@trsdn/mistraldocai-mcp-server"],
      "env": {
        "MISTRAL_API_KEY": "your_key_here"
      }
    }
  }
}

기타 클라이언트

stdio를 통해 MCP 서버를 시작하는 모든 클라이언트가 작동합니다. 명령으로 npx @trsdn/mistraldocai-mcp-server를 사용하고 환경에 MISTRAL_API_KEY를 제공하세요.

도구

process_document

하나의 문서 또는 이미지를 Markdown으로 변환합니다. 경로 또는 base64 콘텐츠를 제공하세요.

{ "name": "process_document", "arguments": { "file_path": "/path/to/report.pdf" } }

process_directory

디렉터리의 모든 지원 파일을 변환하여 입력당 하나의 .md 파일을 작성하고 디렉터리 구조를 유지합니다.

get_supported_formats

지원되는 형식과 제한 사항을 반환합니다. 매개변수를 사용하지 않습니다.

지원 형식

제한 사항은 Mistral의 OCR API에 의해 설정됩니다: 파일당 50MB, 문서당 1,000페이지. 가격 및 처리량은 이 프로젝트가 아닌 Mistral의 것입니다. README에 복사된 숫자를 신뢰하지 말고 가격 페이지에서 현재 수치를 확인하세요.

데이터 및 개인정보 보호

처리하는 문서는 Mistral AI로 전송됩니다. 이것이 서버의 핵심 목적이지만, 콘텐츠가 사용자의 머신을 떠난다는 것을 의미합니다. 제3자 AI 제공업체와 공유할 수 없는 자료를 처리하지 마세요.

접근성

콘솔 출력은 색상이나 장식 기호가 없는 일반 ASCII이므로 화면 판독기, Windows 터미널, 서식이 제거된 클라이언트 로그에서도 읽을 수 있습니다.

알려진 제한 사항: 서버에는 자체 인터페이스가 없습니다. 보이는 모든 것은 MCP 클라이언트에서 오므로 키보드 접근, 포커스 처리, 대비는 이 프로젝트가 아닌 클라이언트의 동작입니다. 대화 보기의 접근성 문제는 클라이언트의 이슈 트래커에 제출하세요.

버전 및 호환성

이 프로젝트는 시맨틱 버전 관리를 따릅니다. 주요 버전은 Node 최소 버전이 올라가거나, Python mcp 종속성이 주요 버전을 넘거나, 도구의 계약이 변경될 때입니다.

1.x에서 업그레이드하려면 Node.js 22 이상이 필요합니다. 버전 1.0.4 이하는 깨끗한 환경에서 전혀 설치할 수 없습니다. Python 요구 사항이 제한되지 않아 현재 호환되지 않는 릴리스로 해석되기 때문입니다. 지원되는 1.x 대체 버전은 없습니다. 전체 내용은 CHANGELOG.md에 있습니다.

작동 방식

MCP client  --stdio-->  dist/index.js  --spawn-->  python/mcp_server.py  --HTTPS-->  api.mistral.ai
                             |                            |
                    manages ~/.mistraldocai-mcp/    docmistral.py does the
                    venv, deps, and .env            conversion

두 가지 제약 조건이 대부분의 설계를 설명합니다:

• stdout은 프로토콜입니다. MCP 클라이언트는 stdout을 JSON-RPC로 구문 분석하므로 두 언어의 모든 진단 정보는 stderr로 전송됩니다. 잘못된 print는 세션을 손상시킵니다.

• 패키지 디렉터리는 읽기 전용입니다. 전역 npm 설치에는 쓸 수 없으므로 가상 환경, .env 및 기타 모든 상태는 ~/.mistraldocai-mcp/ 아래에 있습니다.

개발

git clone https://github.com/trsdn/MistralDocAI-mcp.git
cd MistralDocAI-mcp
npm ci
npm run build

CI도 실행하는 단일 명령으로 변경 사항을 검증하세요:

npm run verify

python/ 아래의 내용을 변경한 경우 python/mcp_requirements.txt가 설치된 인터프리터로 ruff check . 및 python3 scripts/verify_python_server.py도 실행하세요.

AGENTS.md에는 전체 레이아웃, 규칙, 금지된 작업 목록이 있습니다. AI 에이전트를 위해 작성되었지만 인간에게도 가장 빠른 안내서입니다.

프로젝트 문서

라이선스

MIT.

이 저장소는 trsdn 저장소 품질 표준에 따라 평가됩니다. 결과는 .github/conformance.yml에 기록되며, 기준별 증거는 docs/self-assessment.md에 있습니다.