Mistral OCR MCP Server

A local OCR server using Mistral OCR, compliant with MCP principles. This server allows you to perform OCR on uploaded images and interact with it via a Model Context Protocol (MCP) interface.

Features

FastAPI Backend: Built with the modern, fast (high-performance) FastAPI framework.
OCR Processing: (Details about the specific Mistral OCR capabilities would go here - e.g., supported languages, image formats, accuracy).
Standard OCR Endpoint: Provides a regular HTTP endpoint (/v1/ocr) for direct file uploads and OCR.
Configuration Management: Uses Pydantic settings for easy configuration.
Logging: Integrated logging for monitoring and debugging.
Health Check: A simple /health endpoint to verify server status.

Project Structure

.
├── .gitignore
├── main.py                 # FastAPI application and MCP server setup
├── pyproject.toml          # Project metadata and dependencies
├── README.md               # This file
├── ocr/
│   ├── __init__.py
│   ├── config.py           # Configuration settings
│   ├── router.py           # Handles the OCR model routing and processing logic
│   ├── schemas.py          # Pydantic models for API requests and responses
│   └── adapters/           # (If you have model-specific adapter logic)
│       └── __init__.py
└── tests/                  # (If you have tests)
    └── ...

Prerequisites

Python 3.10 or higher
An environment with pip or uv for package management.

Installation

1. Clone the repository (if applicable):

    # git clone <your-repository-url>

    # cd mistral-ocr-mcp-server

    

2. Create and activate a virtual environment (recommended):

    python -m venv venv

    source venv/bin/activate  # On Windows: venv\Scripts\activate

    

3. Install dependencies:
The project uses pyproject.toml to manage dependencies. You can install them using pip:

    pip install .

    

For development, including tools for testing, linting, and formatting, install the dev extras:

    pip install .[dev]

    

Configuration

Configuration for the application (like supported file types, model settings, etc.) is managed in ocr/config.py using Pydantic settings. You can override these settings using environment variables. Refer to ocr/config.py for available settings and their corresponding environment variable names.

Default supported file types usually include common image formats (e.g., image/jpeg, image/png).

The maximum upload file size is set by default (e.g., 1MB in main.py lifespan function).

Running the Server

You can run the FastAPI server using Uvicorn:

uvicorn main:app --reload

This will typically start the server on http://127.0.0.1:8000. The --reload flag enables auto-reloading when code changes are detected, which is useful for development.

API Endpoints

1. OCR Endpoint

POST /v1/ocr
Description: Upload an image file to perform OCR.
Request Body: multipart/form-data with a file field containing the image.
Content-Type Header for file: Must be one of the settings.supported_file_types.
Response: OCRResult (JSON object containing the extracted text and other relevant information as defined in ocr.schemas.OCRResult).
Example using cURL:

        curl -X POST -F "file=@/path/to/your/image.png" http://127.0.0.1:8000/v1/ocr

        

2. MCP Endpoint

BASE_URL/mcp
Description: Provides MCP-compliant tools for interacting with the OCR service. The available tools and resources can be discovered by MCP clients.
This endpoint is automatically managed by fastapi-mcp.

3. Health Check

GET /health
Description: A simple endpoint to check if the server is running and healthy.
Response:

        {

          "status": "ok"

        }

        

Development

Running Type Checker

To check types with Mypy:

mypy .

(Ensure Mypy is configured in pyproject.toml to scan the correct paths, e.g., mypy ocr main.py)

Running Tests

If you have tests in a tests/ directory, you can run them using Pytest:

pytest

Coverage reports can also be generated if configured (see tool.pytest.ini_options in pyproject.toml).

Contributing

Contributions are welcome! Please feel free to submit a Pull Request or open an issue.
(Add more specific contribution guidelines if you have them).