Spaces:
Sleeping
Sleeping
| title: Markdown Layout Extractor | |
| emoji: 📄 | |
| colorFrom: red | |
| colorTo: yellow | |
| sdk: docker | |
| app_port: 7860 | |
| pinned: false | |
| <p> | |
| <div align="center"> | |
| <h1> | |
| PDF to Markdown MCP | |
| <br /> <br /> | |
| <a href=""> | |
| <img | |
| src="https://img.shields.io/badge/python%20%7C%203.12-blue" | |
| alt="Python 3.12" | |
| /> | |
| </a> | |
| <a href="https://github.com/astral-sh/uv"> | |
| <img | |
| src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" | |
| alt="uv" | |
| /> | |
| </a> | |
| <a href="https://modelcontextprotocol.io/"> | |
| <img | |
| src="https://img.shields.io/badge/MCP-FastMCP-6C47FF" | |
| alt="FastMCP" | |
| /> | |
| </a> | |
| <a href="https://mistral.ai/"> | |
| <img | |
| src="https://img.shields.io/badge/Mistral%20AI-FF7000?logoColor=white" | |
| alt="Mistral AI" | |
| /> | |
| </a> | |
| <a href="https://www.starlette.io/"> | |
| <img | |
| src="https://img.shields.io/badge/Starlette-ASGI-009688" | |
| alt="Starlette" | |
| /> | |
| </a> | |
| <a href="https://www.uvicorn.org/"> | |
| <img | |
| src="https://img.shields.io/badge/Uvicorn-server-4051B5" | |
| alt="Uvicorn" | |
| /> | |
| </a> | |
| <a href="https://loguru.readthedocs.io/"> | |
| <img | |
| src="https://img.shields.io/badge/Loguru-logging-FF6B6B" | |
| alt="Loguru" | |
| /> | |
| </a> | |
| </h1> | |
| </div> | |
| </p> | |
| An MCP (Model Context Protocol) server that converts PDFs and documents into Markdown using **Mistral OCR**. | |
| ## Features | |
| - **`pdf_to_markdown`** — Convert any publicly accessible PDF/document URL to merged Markdown. | |
| - **`pdf_to_structured_markdown`** — Convert and get per-page structured output (page index, individual markdown, merged result). | |
| - CORS-enabled SSE transport — connect from any MCP client or inspector. | |
| - `/health` endpoint for liveness probing. | |
| - Structured, colorized logging via Loguru. | |
| ## Project Structure | |
| ``` | |
| pdf_to_md_mcp/ | |
| ├── main.py # Entry point — uvicorn runner | |
| ├── pyproject.toml | |
| ├── sample.env # Secrets reference (copy to .env) | |
| ├── development.yml # Non-secret config (server, CORS, OCR model) | |
| └── app/ | |
| ├── server.py # ASGI app factory (MCP + CORS + health) | |
| ├── core/ | |
| │ ├── config.py # Pydantic settings (loads .env + development.yml) | |
| │ ├── logger.py # Loguru logger | |
| │ ├── lifespan.py # AppContext + Mistral client lifecycle | |
| │ └── exceptions.py # Domain exceptions | |
| ├── services/ | |
| │ └── ocr_service.py # Mistral OCR business logic | |
| ├── tools/ | |
| │ └── markdown_tools.py # @mcp.tool() definitions | |
| └── utils/ | |
| ├── response.py # create_response() helper | |
| └── validators.py # URL validation | |
| ``` | |
| ## Setup | |
| ```bash | |
| # Install uv if not already installed | |
| curl -LsSf https://astral.sh/uv/install.sh | sh | |
| # Install dependencies | |
| uv sync | |
| # Configure secrets | |
| cp sample.env .env | |
| # Edit .env — set MISTRAL_API_KEY | |
| # Non-secret config (server, CORS, OCR model) lives in development.yml | |
| ``` | |
| ## Run | |
| ```bash | |
| uv run main.py | |
| ``` | |
| Server starts at `http://127.0.0.1:8000` by default. | |
| | Endpoint | Description | | |
| | --- | --- | | |
| | `GET /health` | Liveness probe | | |
| | `GET /sse` | MCP SSE transport | | |
| | `POST /messages/` | MCP message handler | | |
| ## MCP Tools | |
| ### `pdf_to_markdown` | |
| Convert a document URL to merged Markdown (all pages concatenated). | |
| **Input** | |
| | Parameter | Type | Description | | |
| | --- | --- | --- | | |
| | `document_url` | `string` | Publicly accessible URL of a PDF or image document | | |
| **Returns** — `string` | |
| ``` | |
| # Introduction | |
| This paper presents... | |
| ## Section 2 | |
| ... | |
| ``` | |
| --- | |
| ### `pdf_to_structured_markdown` | |
| Convert a document URL and get per-page structured output alongside the merged result. | |
| **Input** | |
| | Parameter | Type | Description | | |
| | --- | --- | --- | | |
| | `document_url` | `string` | Publicly accessible URL of a PDF or image document | | |
| **Returns** — `object` | |
| ```json | |
| { | |
| "page_count": 3, | |
| "pages": [ | |
| { "index": 0, "markdown": "# Page 1\n..." }, | |
| { "index": 1, "markdown": "## Page 2\n..." }, | |
| { "index": 2, "markdown": "### Page 3\n..." } | |
| ], | |
| "markdown": "# Page 1\n...\n\n## Page 2\n...\n\n### Page 3\n..." | |
| } | |
| ``` | |
| ## Debugging with MCP Inspector | |
| ```bash | |
| npx -y @modelcontextprotocol/inspector | |
| ``` | |
| Connect to `http://127.0.0.1:8000/sse` locally or your Railway URL in production. | |
| ## Deploy to Railway | |
| ### 1. Push to GitHub | |
| ```bash | |
| git init | |
| git add . | |
| git commit -m "initial commit" | |
| gh repo create pdf-to-md-mcp --public --source=. --push | |
| ``` | |
| ### 2. Create a Railway project | |
| Go to [railway.app](https://railway.app) → **New Project** → **Deploy from GitHub repo** → select your repo. | |
| Railway detects the `railway.json` and uses `uv run main.py` as the start command automatically. | |
| ### 3. Set environment variables | |
| In Railway → your service → **Variables**, add: | |
| | Variable | Value | | |
| |---|---| | |
| | `MISTRAL_API_KEY` | your Mistral API key | | |
| | `HOST` | `0.0.0.0` | | |
| > `PORT` is injected automatically by Railway — do **not** set it manually. | |
| > All other config (`MISTRAL_OCR_MODEL`, `LOG_LEVEL`, etc.) is read from `development.yml`. | |
| ### 4. Deploy | |
| Railway triggers a deploy on every push to your default branch. Once live, your public SSE URL will be: | |
| ``` | |
| https://<your-service>.up.railway.app/sse | |
| ``` | |
| Use that URL in any MCP client or pass it to the inspector: | |
| ```bash | |
| npx -y @modelcontextprotocol/inspector | |
| # connect to: https://<your-service>.up.railway.app/sse | |
| ``` | |
| ### Why it works | |
| - Railway injects `PORT` as an env var — pydantic-settings reads env vars before `development.yml`, so it's picked up automatically. | |
| - `HOST=0.0.0.0` (set via Railway Variables) overrides the local `127.0.0.1` default so the container is reachable. | |
| - `proxy_headers=True` in `main.py` makes uvicorn trust Railway's `X-Forwarded-*` headers. | |
| - `/health` is set as Railway's healthcheck path in `railway.json`. | |
| ## Configuration | |
| Configuration is split across two files to separate secrets from non-sensitive settings. | |
| ### `.env` — Secrets only | |
| ```dotenv | |
| MISTRAL_API_KEY=your_mistral_api_key_here | |
| ``` | |
| ### `development.yml` — Non-secret config | |
| ```yaml | |
| # Mistral | |
| MISTRAL_OCR_MODEL: mistral-ocr-latest | |
| MISTRAL_TABLE_FORMAT: markdown | |
| # Server | |
| APP_NAME: "Markdown & Layout Extractor" | |
| HOST: "127.0.0.1" | |
| PORT: 8000 | |
| LOG_LEVEL: INFO | |
| # CORS | |
| CORS_ALLOW_ORIGINS: | |
| - "*" | |
| CORS_ALLOW_METHODS: | |
| - "*" | |
| CORS_ALLOW_HEADERS: | |
| - "*" | |
| ``` | |
| **Priority (highest → lowest):** environment variables → `.env` → `development.yml` | |
| ### All settings | |
| | Variable | File | Default | Description | | |
| | --- | --- | --- | --- | | |
| | `MISTRAL_API_KEY` | `.env` | **required** | Mistral AI API key | | |
| | `MISTRAL_OCR_MODEL` | `development.yml` | `mistral-ocr-latest` | OCR model identifier | | |
| | `MISTRAL_TABLE_FORMAT` | `development.yml` | `markdown` | Table output format | | |
| | `APP_NAME` | `development.yml` | `Markdown & Layout Extractor` | MCP server name | | |
| | `HOST` | `development.yml` | `127.0.0.1` | Bind address | | |
| | `PORT` | `development.yml` | `8000` | Bind port | | |
| | `LOG_LEVEL` | `development.yml` | `INFO` | Log level (`DEBUG`, `INFO`, `WARNING`, `ERROR`) | | |
| | `CORS_ALLOW_ORIGINS` | `development.yml` | `["*"]` | Allowed CORS origins | | |
| | `CORS_ALLOW_METHODS` | `development.yml` | `["*"]` | Allowed HTTP methods | | |
| | `CORS_ALLOW_HEADERS` | `development.yml` | `["*"]` | Allowed HTTP headers | | |
| ## Design Notes | |
| - **Single Starlette app** — `sse_app()` is the sole ASGI application; the health route and CORS middleware are injected directly onto it to prevent double-middleware stacking (which causes the `http.response.start` crash). | |
| - **Separation of concerns** — Tools are thin wrappers around `OCRService`; business logic is independently testable. | |
| - **Lifespan-managed client** — The Mistral client is initialized once at startup and shared across all tool calls. | |
| - **Loguru logging** — Structured, colorized logs across all layers via Loguru. | |
| - **Pydantic Settings** — Type-safe, `.env`-driven configuration with an LRU-cached singleton. | |