feat: initial release — PDF to Markdown MCP server

- FastMCP SSE server with two tools: pdf_to_markdown and pdf_to_structured_markdown
- Mistral OCR integration with lifespan-managed client
- Pydantic Settings: secrets in .env, non-secret config in development.yml
- Loguru structured logging across all layers
- CORS middleware + /health liveness probe
- Railway deployment config (railway.json, proxy_headers, PORT injection)
- .gitignore, sample.env, and uv lockfile included

.gitignore

@@ -0,0 +1,29 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Secrets — never commit real credentials
+.env
+
+# Local dev output
+output/
+docs/
+temp/
+logs/
+
+# Test files
+test.py
+tests/
+
+# OS / editor noise
+.DS_Store
+.idea/
+.vscode/
+

.python-version

@@ -0,0 +1 @@
+3.12

README.md

@@ -0,0 +1,281 @@
+<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.

app/core/config.py

@@ -0,0 +1,69 @@
+from typing import List, Tuple, Type
+from functools import lru_cache
+
+from pydantic import Field
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    YamlConfigSettingsSource,
+)
+
+
+class Settings(BaseSettings):
+    """Centralized settings.
+
+    Priority (highest → lowest):
+      1. Environment variables
+      2. .env file          ← secrets only (MISTRAL_API_KEY)
+      3. development.yml    ← non-secret config (model, server, CORS)
+    """
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=True,
+        extra="ignore",
+    )
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: Type[PydanticBaseSettingsSource],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> Tuple[PydanticBaseSettingsSource, ...]:
+        return (
+            init_settings,
+            env_settings,
+            dotenv_settings,
+            YamlConfigSettingsSource(settings_cls, yaml_file="development.yml"),
+            file_secret_settings,
+        )
+
+    # ── Mistral (secret in .env, rest in development.yml) ─────────────────────
+    MISTRAL_API_KEY: str
+    MISTRAL_OCR_MODEL: str = "mistral-ocr-latest"
+    MISTRAL_TABLE_FORMAT: str = "markdown"
+
+    # ── Server (development.yml) ───────────────────────────────────────────────
+    APP_NAME: str = "Markdown & Layout Extractor"
+    HOST: str = "127.0.0.1"
+    PORT: int = 8000
+    LOG_LEVEL: str = "INFO"
+
+    # ── CORS (development.yml) ─────────────────────────────────────────────────
+    CORS_ALLOW_ORIGINS: List[str] = Field(default_factory=lambda: ["*"])
+    CORS_ALLOW_METHODS: List[str] = Field(default_factory=lambda: ["*"])
+    CORS_ALLOW_HEADERS: List[str] = Field(default_factory=lambda: ["*"])
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Cached settings instance — call this everywhere instead of instantiating."""
+    return Settings()
+
+
+settings = get_settings()

app/core/exceptions.py

@@ -0,0 +1,10 @@
+class MCPExtractorError(Exception):
+    """Base exception for this application."""
+
+
+class OCRProcessingError(MCPExtractorError):
+    """Raised when OCR / document conversion fails."""
+
+
+class InvalidDocumentURLError(MCPExtractorError):
+    """Raised when the provided document URL is invalid or unreachable."""

app/core/lifespan.py

@@ -0,0 +1,27 @@
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from dataclasses import dataclass
+
+from mcp.server.fastmcp import FastMCP
+from mistralai.client import Mistral
+
+from app.core.config import settings
+from app.core.logger import logger
+
+
+@dataclass
+class AppContext:
+    """Shared resources available to all tools via ctx.request_context.lifespan_context."""
+
+    mistral: Mistral
+
+
+@asynccontextmanager
+async def app_lifespan(server: FastMCP) -> AsyncIterator[AppContext]:
+    """Initialize and cleanly tear down shared clients."""
+    logger.info("Initializing Mistral client...")
+    client = Mistral(api_key=settings.MISTRAL_API_KEY)
+    try:
+        yield AppContext(mistral=client)
+    finally:
+        logger.info("Shutting down lifespan resources.")

app/core/logger.py

@@ -0,0 +1,20 @@
+import sys
+
+from loguru import logger
+
+from app.core.config import settings
+
+
+def _configure_logger() -> None:
+    logger.remove()
+    logger.add(
+        sys.stdout,
+        format="{time:YYYY-MM-DD HH:mm:ss} | {level:<8} | {name} | {message}",
+        level=settings.LOG_LEVEL,
+        colorize=True,
+    )
+
+
+_configure_logger()
+
+__all__ = ["logger"]

app/server.py

@@ -0,0 +1,52 @@
+from mcp.server.fastmcp import FastMCP
+from starlette.middleware.cors import CORSMiddleware
+from starlette.requests import Request
+
+from app.core.config import settings
+from app.core.lifespan import app_lifespan
+from app.core.logger import logger
+from app.tools import register_markdown_tools
+from app.utils.response import create_response
+
+
+def _build_mcp_server() -> FastMCP:
+    """Build the FastMCP instance and register every tool."""
+    mcp = FastMCP(settings.APP_NAME, lifespan=app_lifespan)
+    register_markdown_tools(mcp)
+    return mcp
+
+
+async def _health(_: Request):
+    """Simple liveness probe."""
+    return create_response(
+        status_value=True,
+        message="Service is healthy",
+        data={"app": settings.APP_NAME},
+    )
+
+
+def create_app():
+    """Build the ASGI application.
+
+    Mounts CORS and the health route directly on the MCP Starlette app to avoid
+    nesting two Starlette instances (which produces a double http.response.start
+    crash with uvicorn).
+    """
+    logger.info("Building application: {}", settings.APP_NAME)
+    mcp = _build_mcp_server()
+
+    # sse_app() returns a Starlette instance — use it as the single ASGI app.
+    app = mcp.sse_app()
+
+    # Inject health route before the MCP catch-all mount.
+    app.add_route("/health", _health, methods=["GET"])
+
+    # Add CORS once at the outermost middleware layer.
+    app = CORSMiddleware(
+        app,
+        allow_origins=settings.CORS_ALLOW_ORIGINS,
+        allow_methods=settings.CORS_ALLOW_METHODS,
+        allow_headers=settings.CORS_ALLOW_HEADERS,
+    )
+ 
+    return app

app/services/ocr_service.py

@@ -0,0 +1,88 @@
+from typing import Any, Dict, List
+
+from mistralai.client import Mistral
+
+from app.core.logger import logger
+from app.core.config import settings
+from app.core.exceptions import OCRProcessingError
+
+
+class OCRService:
+    """Encapsulates document-to-markdown conversion via Mistral OCR."""
+
+    def __init__(self, client: Mistral) -> None:
+        self._client = client
+        self._model = settings.MISTRAL_OCR_MODEL
+        self._table_format = settings.MISTRAL_TABLE_FORMAT
+
+    async def document_to_markdown(self, document_url: str) -> str:
+        """Convert a remote document (PDF / image) to markdown.
+
+        Args:
+            document_url: Public URL of the document.
+
+        Returns:
+            Concatenated markdown content (pages joined by blank lines).
+
+        Raises:
+            OCRProcessingError: If the OCR call fails or returns no pages.
+        """
+        logger.info("Starting OCR for document: {}", document_url)
+        try:
+            response = await self._client.ocr.process_async(
+                model=self._model,
+                document={
+                    "type": "document_url",
+                    "document_url": document_url,
+                },
+                table_format=self._table_format,
+            )
+        except Exception as exc:
+            logger.exception("Mistral OCR call failed")
+            raise OCRProcessingError(f"OCR processing failed: {exc}") from exc
+
+        pages = getattr(response, "pages", None) or []
+        if not pages:
+            raise OCRProcessingError("OCR returned no pages for the given document.")
+
+        markdown = "\n\n".join(
+            page.markdown for page in pages if getattr(page, "markdown", None)
+        )
+        logger.info("OCR succeeded: {} pages, {} chars", len(pages), len(markdown))
+        return markdown
+
+    async def document_to_structured(self, document_url: str) -> Dict[str, Any]:
+        """Convert a document and return per-page structure alongside merged markdown.
+
+        Useful when callers need page-level metadata (page index, individual markdown).
+        """
+        logger.info("Starting structured OCR for document: {}", document_url)
+        try:
+            response = await self._client.ocr.process_async(
+                model=self._model,
+                document={
+                    "type": "document_url",
+                    "document_url": document_url,
+                },
+                table_format=self._table_format,
+            )
+        except Exception as exc:
+            logger.exception("Mistral OCR call failed")
+            raise OCRProcessingError(f"OCR processing failed: {exc}") from exc
+
+        pages: List[Dict[str, Any]] = []
+        merged_parts: List[str] = []
+        for idx, page in enumerate(getattr(response, "pages", []) or []):
+            md = getattr(page, "markdown", "") or ""
+            pages.append({"index": idx, "markdown": md})
+            if md:
+                merged_parts.append(md)
+
+        if not pages:
+            raise OCRProcessingError("OCR returned no pages for the given document.")
+
+        return {
+            "page_count": len(pages),
+            "pages": pages,
+            "markdown": "\n\n".join(merged_parts),
+        }

app/tools/__init__.py

@@ -0,0 +1,3 @@
+from app.tools.markdown_tools import register_markdown_tools
+
+__all__ = ["register_markdown_tools"]

app/tools/markdown_tools.py

@@ -0,0 +1,60 @@
+from typing import Any, Dict
+
+from mcp.server.fastmcp import Context, FastMCP
+
+from app.core.logger import logger
+from app.services.ocr_service import OCRService
+from app.utils.validators import validate_document_url
+from app.core.exceptions import InvalidDocumentURLError, OCRProcessingError
+
+
+def register_markdown_tools(mcp: FastMCP) -> None:
+    """Attach markdown-extraction tools to the given FastMCP server."""
+
+    @mcp.tool()
+    async def pdf_to_markdown(document_url: str, ctx: Context) -> str:
+        """Convert a PDF or document from a URL to Markdown using Mistral OCR.
+
+        Args:
+            document_url: Publicly accessible URL of the PDF / document.
+
+        Returns:
+            Markdown string (all pages concatenated).
+        """
+        try:
+            url = validate_document_url(document_url)
+        except InvalidDocumentURLError as exc:
+            logger.warning("Invalid URL rejected: {}", exc)
+            return f"Error: {exc}"
+
+        service = OCRService(client=ctx.request_context.lifespan_context.mistral)
+
+        try:
+            return await service.document_to_markdown(url)
+        except OCRProcessingError as exc:
+            logger.error("OCR failed for {}: {}", url, exc)
+            return f"Error: {exc}"
+
+    @mcp.tool()
+    async def pdf_to_structured_markdown(
+        document_url: str, ctx: Context
+    ) -> Dict[str, Any]:
+        """Convert a document to per-page structured markdown.
+
+        Returns:
+            Dict with keys: page_count (int), pages (list of {index, markdown}),
+            markdown (str, merged).
+        """
+        try:
+            url = validate_document_url(document_url)
+        except InvalidDocumentURLError as exc:
+            logger.warning("Invalid URL rejected: {}", exc)
+            return {"error": str(exc), "page_count": 0, "pages": [], "markdown": ""}
+
+        service = OCRService(client=ctx.request_context.lifespan_context.mistral)
+
+        try:
+            return await service.document_to_structured(url)
+        except OCRProcessingError as exc:
+            logger.error("Structured OCR failed for {}: {}", url, exc)
+            return {"error": str(exc), "page_count": 0, "pages": [], "markdown": ""}

app/utils/response.py

@@ -0,0 +1,30 @@
+from typing import Any, Dict, List, Union
+from fastapi import status as http_status
+from fastapi.responses import JSONResponse
+
+
+def create_response(
+    status_value: bool,
+    message: str,
+    data: Union[Dict[str, Any], List[Any], None] = None,
+    code: int = http_status.HTTP_200_OK,
+) -> JSONResponse:
+    """Create standardized JSON response.
+
+    Args:
+        status_value: Success/failure boolean.
+        message: Human-readable message.
+        data: Response payload (dict, list, or None).
+        code: HTTP status code (default: 200).
+
+    Returns:
+        JSONResponse with structure {status, message, data}.
+    """
+    return JSONResponse(
+        status_code=code,
+        content={
+            "status": status_value,
+            "message": message,
+            "data": data if data is not None else {},
+        },
+    )

app/utils/validators.py

@@ -0,0 +1,30 @@
+from urllib.parse import urlparse
+from app.core.exceptions import InvalidDocumentURLError
+
+
+def validate_document_url(url: str) -> str:
+    """Validate that the given string is a well-formed http(s) URL.
+
+    Args:
+        url: The URL to validate.
+
+    Returns:
+        The trimmed URL.
+
+    Raises:
+        InvalidDocumentURLError: If the URL is malformed.
+    """
+    if not url or not isinstance(url, str):
+        raise InvalidDocumentURLError("Document URL must be a non-empty string.")
+
+    url = url.strip()
+    parsed = urlparse(url)
+
+    if parsed.scheme not in {"http", "https"}:
+        raise InvalidDocumentURLError(
+            f"Unsupported URL scheme: '{parsed.scheme}'. Use http or https."
+        )
+    if not parsed.netloc:
+        raise InvalidDocumentURLError("Document URL is missing a valid host.")
+
+    return url

development.yml

@@ -0,0 +1,18 @@
+# ─── Mistral ───────────────────────────────────────────────────────────────────
+MISTRAL_OCR_MODEL: mistral-ocr-latest
+MISTRAL_TABLE_FORMAT: markdown
+
+# ─── Server ────────────────────────────────────────────────────────────────────
+# Local defaults — Railway overrides HOST and PORT via its Variables tab.
+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:
+  - "*"

main.py

@@ -0,0 +1,18 @@
+import uvicorn
+
+from app.server import create_app
+from app.core.config import settings
+
+app = create_app()
+
+
+if __name__ == "__main__":
+    uvicorn.run(
+        app,
+        host=settings.HOST,
+        port=settings.PORT,
+        log_level=settings.LOG_LEVEL.lower(),
+        # Trust X-Forwarded-* headers from Railway's edge proxy.
+        proxy_headers=True,
+        forwarded_allow_ips="*",
+    )

pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "pdf-to-md-mcp"
+version = "0.1.0"
+description = "Add your description here"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "fastapi==0.135.3",
+    "loguru==0.7.3",
+    "mcp[cli]==1.27.0",
+    "mistralai==2.3.2",
+    "pydantic-settings>=2.13.1",
+    "python-dotenv==1.2.2",
+    "pyyaml>=6.0.2",
+    "starlette==1.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "black==26.3.1",
+]
+
+[tool.black]
+target-version = ["py312"]
+
+

railway.json

@@ -0,0 +1,13 @@
+{
+  "$schema": "https://railway.com/railway.schema.json",
+  "build": {
+    "builder": "NIXPACKS"
+  },
+  "deploy": {
+    "startCommand": "uv run main.py",
+    "healthcheckPath": "/health",
+    "healthcheckTimeout": 30,
+    "restartPolicyType": "ON_FAILURE",
+    "restartPolicyMaxRetries": 3
+  }
+}

sample.env

@@ -0,0 +1 @@
+MISTRAL_API_KEY=<YOUR-MISTRAL-API-KEY>