mcp-dharmamitra 0.1.0__tar.gz

mcp_dharmamitra-0.1.0/.dockerignore

@@ -0,0 +1,15 @@
+.git
+.gitignore
+.idea
+.venv
+.pytest_cache
+__pycache__
+**/__pycache__
+**/*.pyc
+tests
+tmp
+*.md
+!README.md
+Dockerfile
+.dockerignore
+uv.lock

mcp_dharmamitra-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+.idea/
+.vscode/
+.venv/
+
+.claude/settings.local.json
+
+.DS_Store
+._*
+.~*#
+*.pyc
+*.swp
+*.swo
+*.swn
+.svn
+*.orig
+*.egg-info
+
+/bandit-report.html
+
+/tmp/

mcp_dharmamitra-0.1.0/CLAUDE.md

@@ -0,0 +1,60 @@
+# mcp-dharmamitra
+
+Python MCP server that runs OCR on an image via `https://dharmamitra.org/bff/api/ocr`
+and writes the extracted text to a local file. Aimed at Tibetan / Sanskrit /
+Devanagari sources.
+
+## Layout
+
+```
+src/mcp_dharmamitra/
+  server.py       # MCPServer instance + @mcp.tool() ocr_image
+  ocr_client.py   # submit_ocr() + poll_status() against Dharmamitra
+  __main__.py     # python -m mcp_dharmamitra
+tests/
+  test_ocr_client.py  # respx-mocked
+```
+
+The server exposes exactly one tool, `ocr_image(image_path, output_path, ...)`.
+It writes only `result.extracted_text` to `output_path` and returns a small
+JSON summary — full text is intentionally *not* returned to the MCP client
+(keeps responses compact and cheap).
+
+## Commands
+
+```bash
+uv sync --extra dev            # install
+uv run pytest -q               # tests (5 cases, respx-mocked, offline)
+uv run mcp-dharmamitra         # run server over stdio
+uv run mcp dev src/mcp_dharmamitra/server.py   # MCP inspector
+```
+
+## Gotchas
+
+- **`mcp` package is 2.x.** We use `from mcp.server.mcpserver import MCPServer`
+  (renamed from `FastMCP` in 2.0). Do not import `mcp.server.fastmcp` — it errors
+  at import time in 2.x. API surface (`.tool()`, `.run()`, `.list_tools()`) is
+  the same.
+- **Cloudflare / `cf_clearance`.** The endpoint sits behind Cloudflare. First
+  try without a cookie — usually works. On 403 the client raises
+  `DharmamitraForbiddenError`; the fix is to set `DHARMAMITRA_COOKIE` env var to
+  a fresh `cf_clearance` value grabbed from a browser. Never hardcode it —
+  Cloudflare rotates it.
+- **Polling.** `poll_status` loops with `asyncio.sleep(interval)` until status
+  is `completed` (success), any other terminal status like `failed`/`error`
+  (raises `DharmamitraError`), or the wall-clock deadline hits
+  (`TimeoutError`). Defaults: 2s interval, 300s timeout.
+- **HTTP client lifecycle.** Both `submit_ocr` and `poll_status` create their
+  own `httpx.AsyncClient` if none is passed, and close it. Tests pass in a
+  mocked transport via `respx`, which patches the default client.
+
+## When editing
+
+- Keep the tool output small (summary dict). Do not return `extracted_text`
+  itself — it can be tens of KB of CJK / Tibetan text and blows up token cost
+  on the client side.
+- Add new API params (`transliterate_*`, `model`, `instruction`) as tool
+  arguments with sensible defaults matching the Dharmamitra web UI (`false`,
+  `"auto"`, empty string).
+- If you add polling backoff or retries, keep the terminal-status set in
+  `ocr_client.TERMINAL_STATUSES` in sync.

mcp_dharmamitra-0.1.0/Dockerfile

@@ -0,0 +1,25 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1
+ENV PYTHONUNBUFFERED=1
+ENV PIP_DISABLE_PIP_VERSION_CHECK=1
+ENV PIP_NO_CACHE_DIR=1
+ENV USER app
+ENV GROUP app
+ENV WORKDIR /data
+
+WORKDIR ${WORKDIR}
+
+COPY pyproject.toml README.md ./
+COPY src ./src
+
+RUN pip install --no-cache-dir .
+
+RUN useradd --create-home --uid 1000 ${USER} \
+ && mkdir -p ${WORKDIR} \
+ && chown -R ${USER}:${GROUP} ${WORKDIR}
+
+USER ${USER}
+WORKDIR ${WORKDIR}
+
+ENTRYPOINT ["mcp-dharmamitra"]

mcp_dharmamitra-0.1.0/PKG-INFO

@@ -0,0 +1,163 @@
+Metadata-Version: 2.5
+Name: mcp-dharmamitra
+Version: 0.1.0
+Summary: MCP server for Dharmamitra OCR (Tibetan/Sanskrit/Devanagari)
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp[cli]>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: respx>=0.21; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# mcp-dharmamitra
+
+<!-- mcp-name: io.github.alex-deus/mcp-dharmamitra -->
+
+MCP server that runs OCR on an image via the public
+[Dharmamitra](https://dharmamitra.org) OCR endpoint and writes the extracted
+text to a local file. Optimised for Tibetan / Sanskrit / Devanagari input.
+
+## Tool
+
+### `ocr_image`
+
+| Argument | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `image_path` | `str` | — | Absolute path to a local image (png/jpg/…). |
+| `output_path` | `str` | — | File to write UTF-8 text into. Parent dirs are created. |
+| `transliterate_devanagari_to_iast` | `bool` | `false` | Passed to the API. |
+| `transliterate_tibetan_to_wylie` | `bool` | `false` | Passed to the API. |
+| `instruction` | `str` | `""` | Optional model instruction. |
+| `model` | `str` | `"auto"` | OCR model id. |
+| `poll_interval_seconds` | `float` | `2.0` | Delay between status polls. |
+| `timeout_seconds` | `float` | `300.0` | Overall polling deadline. |
+
+Returns a small JSON summary — the extracted text is written to `output_path`,
+not returned to the client.
+
+```json
+{
+  "job_id": "b8b26984b3ca49199c28303cad6a144d",
+  "output_path": "/abs/path/out.txt",
+  "pages": 1,
+  "processing_time_seconds": 3.957,
+  "chars": 1234
+}
+```
+
+## Install
+
+```bash
+uv sync                           # or: pip install -e '.[dev]'
+```
+
+Run locally with the MCP inspector:
+
+```bash
+uv run mcp dev src/mcp_dharmamitra/server.py
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+## Wire into Claude Desktop / Claude Code
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+      "dharmamitra": {
+        "command": "uv",
+        "args": ["--directory", "/path/mcp-dharmamitra", "run", "mcp-dharmamitra"],
+        "env": {"DHARMAMITRA_COOKIE": ""}
+      }
+    }
+  }
+```
+
+## Docker
+
+Build the image:
+
+```bash
+docker build -t mcp-dharmamitra:latest .
+```
+
+MCP talks over stdio, so the container must be run with `-i` (no `-t`). Mount
+a host directory that holds the input images — the tool arguments
+(`image_path`, `output_path`) are paths **inside the container**.
+
+Smoke-test the entrypoint:
+
+```bash
+docker run --rm --entrypoint python mcp-dharmamitra:latest \
+  -c "from mcp_dharmamitra.server import mcp; print(mcp.name)"
+```
+
+### Wire the container into Claude Desktop / Claude Code
+
+Replace `/Users/aleksei/projects/ai/mcp-dharmamitra/tmp` with any host
+directory you want the tool to be able to read/write. Files inside it will be
+visible under `/data` in the container.
+
+```json
+{
+  "mcpServers": {
+    "dharmamitra": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-v", "/Users/aleksei/projects/ai/mcp-dharmamitra/tmp:/data",
+        "-e", "DHARMAMITRA_COOKIE",
+        "mcp-dharmamitra:latest"
+      ],
+      "env": {
+        "DHARMAMITRA_COOKIE": ""
+      }
+    }
+  }
+}
+```
+
+Or the same via CLI:
+
+```bash
+claude mcp add dharmamitra \
+  --scope project \
+  -e DHARMAMITRA_COOKIE="" \
+  -- docker run -i --rm \
+       -v /Users/aleksei/projects/ai/mcp-dharmamitra/tmp:/data \
+       -e DHARMAMITRA_COOKIE \
+       mcp-dharmamitra:latest
+```
+
+When calling the tool, pass container paths. Example — image at
+`<host>/tmp/text.png` → `/data/text.png`:
+
+```json
+{
+  "image_path": "/data/text.png",
+  "output_path": "/data/text.txt"
+}
+```
+
+The resulting `text.txt` appears in the mounted host directory.
+
+## Cloudflare / `cf_clearance`
+
+The endpoint sits behind Cloudflare. Most requests go through without any
+cookie. If you start getting `403`, grab a fresh `cf_clearance` value from a
+logged-in browser session on `dharmamitra.org` and export it:
+
+```bash
+export DHARMAMITRA_COOKIE='cf_clearance value here'
+```
+
+The server will attach it as a cookie on every request. Do not hardcode it —
+Cloudflare rotates the value.

mcp_dharmamitra-0.1.0/README.md

@@ -0,0 +1,150 @@
+# mcp-dharmamitra
+
+<!-- mcp-name: io.github.alex-deus/mcp-dharmamitra -->
+
+MCP server that runs OCR on an image via the public
+[Dharmamitra](https://dharmamitra.org) OCR endpoint and writes the extracted
+text to a local file. Optimised for Tibetan / Sanskrit / Devanagari input.
+
+## Tool
+
+### `ocr_image`
+
+| Argument | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `image_path` | `str` | — | Absolute path to a local image (png/jpg/…). |
+| `output_path` | `str` | — | File to write UTF-8 text into. Parent dirs are created. |
+| `transliterate_devanagari_to_iast` | `bool` | `false` | Passed to the API. |
+| `transliterate_tibetan_to_wylie` | `bool` | `false` | Passed to the API. |
+| `instruction` | `str` | `""` | Optional model instruction. |
+| `model` | `str` | `"auto"` | OCR model id. |
+| `poll_interval_seconds` | `float` | `2.0` | Delay between status polls. |
+| `timeout_seconds` | `float` | `300.0` | Overall polling deadline. |
+
+Returns a small JSON summary — the extracted text is written to `output_path`,
+not returned to the client.
+
+```json
+{
+  "job_id": "b8b26984b3ca49199c28303cad6a144d",
+  "output_path": "/abs/path/out.txt",
+  "pages": 1,
+  "processing_time_seconds": 3.957,
+  "chars": 1234
+}
+```
+
+## Install
+
+```bash
+uv sync                           # or: pip install -e '.[dev]'
+```
+
+Run locally with the MCP inspector:
+
+```bash
+uv run mcp dev src/mcp_dharmamitra/server.py
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+## Wire into Claude Desktop / Claude Code
+
+`~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+      "dharmamitra": {
+        "command": "uv",
+        "args": ["--directory", "/path/mcp-dharmamitra", "run", "mcp-dharmamitra"],
+        "env": {"DHARMAMITRA_COOKIE": ""}
+      }
+    }
+  }
+```
+
+## Docker
+
+Build the image:
+
+```bash
+docker build -t mcp-dharmamitra:latest .
+```
+
+MCP talks over stdio, so the container must be run with `-i` (no `-t`). Mount
+a host directory that holds the input images — the tool arguments
+(`image_path`, `output_path`) are paths **inside the container**.
+
+Smoke-test the entrypoint:
+
+```bash
+docker run --rm --entrypoint python mcp-dharmamitra:latest \
+  -c "from mcp_dharmamitra.server import mcp; print(mcp.name)"
+```
+
+### Wire the container into Claude Desktop / Claude Code
+
+Replace `/Users/aleksei/projects/ai/mcp-dharmamitra/tmp` with any host
+directory you want the tool to be able to read/write. Files inside it will be
+visible under `/data` in the container.
+
+```json
+{
+  "mcpServers": {
+    "dharmamitra": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-v", "/Users/aleksei/projects/ai/mcp-dharmamitra/tmp:/data",
+        "-e", "DHARMAMITRA_COOKIE",
+        "mcp-dharmamitra:latest"
+      ],
+      "env": {
+        "DHARMAMITRA_COOKIE": ""
+      }
+    }
+  }
+}
+```
+
+Or the same via CLI:
+
+```bash
+claude mcp add dharmamitra \
+  --scope project \
+  -e DHARMAMITRA_COOKIE="" \
+  -- docker run -i --rm \
+       -v /Users/aleksei/projects/ai/mcp-dharmamitra/tmp:/data \
+       -e DHARMAMITRA_COOKIE \
+       mcp-dharmamitra:latest
+```
+
+When calling the tool, pass container paths. Example — image at
+`<host>/tmp/text.png` → `/data/text.png`:
+
+```json
+{
+  "image_path": "/data/text.png",
+  "output_path": "/data/text.txt"
+}
+```
+
+The resulting `text.txt` appears in the mounted host directory.
+
+## Cloudflare / `cf_clearance`
+
+The endpoint sits behind Cloudflare. Most requests go through without any
+cookie. If you start getting `403`, grab a fresh `cf_clearance` value from a
+logged-in browser session on `dharmamitra.org` and export it:
+
+```bash
+export DHARMAMITRA_COOKIE='cf_clearance value here'
+```
+
+The server will attach it as a cookie on every request. Do not hardcode it —
+Cloudflare rotates the value.

mcp_dharmamitra-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "mcp-dharmamitra"
+version = "0.1.0"
+description = "MCP server for Dharmamitra OCR (Tibetan/Sanskrit/Devanagari)"
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "mcp[cli]>=2.0.0",
+    "httpx>=0.27.0",
+]
+
+[project.scripts]
+mcp-dharmamitra = "mcp_dharmamitra.server:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "respx>=0.21",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcp_dharmamitra"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

mcp_dharmamitra-0.1.0/server.json

@@ -0,0 +1,30 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.alex-deus/mcp-dharmamitra",
+  "description": "OCR for Tibetan / Sanskrit / Devanagari images via the Dharmamitra API; writes extracted text to a local file.",
+  "repository": {
+    "url": "https://github.com/alex-deus/mcp-dharmamitra",
+    "source": "github"
+  },
+  "version": "0.1.0",
+  "packages": [
+    {
+      "registryType": "pypi",
+      "identifier": "mcp-dharmamitra",
+      "version": "0.1.0",
+      "runtimeHint": "uvx",
+      "transport": {
+        "type": "stdio"
+      },
+      "environmentVariables": [
+        {
+          "name": "DHARMAMITRA_COOKIE",
+          "description": "Optional cf_clearance cookie value. Only needed if requests start returning 403 from Cloudflare.",
+          "isRequired": false,
+          "isSecret": true,
+          "format": "string"
+        }
+      ]
+    }
+  ]
+}

mcp_dharmamitra-0.1.0/src/mcp_dharmamitra/__init__.py

@@ -0,0 +1,3 @@
+from .server import mcp, main
+
+__all__ = ["mcp", "main"]

mcp_dharmamitra-0.1.0/src/mcp_dharmamitra/__main__.py

@@ -0,0 +1,4 @@
+from .server import main
+
+if __name__ == "__main__":
+    main()

mcp_dharmamitra-0.1.0/src/mcp_dharmamitra/ocr_client.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import asyncio
+import mimetypes
+import os
+import time
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+BASE_URL = "https://dharmamitra.org/bff/api/ocr"
+DEFAULT_UA = (
+    "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 "
+    "(KHTML, like Gecko) Chrome/151.0.0.0 Safari/537.36"
+)
+TERMINAL_STATUSES = {"completed", "failed", "error"}
+
+
+class DharmamitraError(RuntimeError):
+    """Raised when the Dharmamitra OCR API returns a failure."""
+
+
+class DharmamitraForbiddenError(PermissionError):
+    """Raised on HTTP 403 — likely Cloudflare requires cf_clearance cookie."""
+
+
+def _default_headers() -> dict[str, str]:
+    return {
+        "accept": "*/*",
+        "origin": "https://dharmamitra.org",
+        "referer": "https://dharmamitra.org/translate",
+        "user-agent": DEFAULT_UA,
+    }
+
+
+def _cookies_from_env() -> dict[str, str] | None:
+    cookie = os.environ.get("DHARMAMITRA_COOKIE", "").strip()
+    if not cookie:
+        return None
+    return {"cf_clearance": cookie}
+
+
+def _build_client(client: httpx.AsyncClient | None) -> tuple[httpx.AsyncClient, bool]:
+    if client is not None:
+        return client, False
+    return (
+        httpx.AsyncClient(
+            timeout=httpx.Timeout(60.0, connect=10.0),
+            headers=_default_headers(),
+            cookies=_cookies_from_env(),
+        ),
+        True,
+    )
+
+
+async def submit_ocr(
+    image_path: Path,
+    *,
+    transliterate_devanagari_to_iast: bool = False,
+    transliterate_tibetan_to_wylie: bool = False,
+    instruction: str = "",
+    model: str = "auto",
+    client: httpx.AsyncClient | None = None,
+) -> str:
+    """POST the image to Dharmamitra OCR. Returns job_id."""
+    image_path = Path(image_path)
+    if not image_path.is_file():
+        raise FileNotFoundError(f"image not found: {image_path}")
+
+    mime = mimetypes.guess_type(image_path.name)[0] or "application/octet-stream"
+    data = {
+        "transliterate_devanagari_to_iast": "true" if transliterate_devanagari_to_iast else "false",
+        "transliterate_tibetan_to_wylie": "true" if transliterate_tibetan_to_wylie else "false",
+        "instruction": instruction,
+        "model": model,
+    }
+
+    ac, owns = _build_client(client)
+    try:
+        with image_path.open("rb") as fh:
+            files = {"file": (image_path.name, fh, mime)}
+            resp = await ac.post(BASE_URL, data=data, files=files)
+        _raise_for_status(resp)
+        payload = resp.json()
+    finally:
+        if owns:
+            await ac.aclose()
+
+    job_id = payload.get("job_id")
+    if not job_id:
+        raise DharmamitraError(f"submit response missing job_id: {payload!r}")
+    return job_id
+
+
+async def poll_status(
+    job_id: str,
+    *,
+    interval: float = 2.0,
+    timeout: float = 300.0,
+    client: httpx.AsyncClient | None = None,
+) -> dict[str, Any]:
+    """Poll status endpoint until the job reaches a terminal state.
+
+    Returns the final status payload on success. Raises DharmamitraError on
+    failure, TimeoutError if the deadline is exceeded.
+    """
+    url = f"{BASE_URL}/status"
+    ac, owns = _build_client(client)
+    deadline = time.monotonic() + timeout
+    last_payload: dict[str, Any] | None = None
+    try:
+        while True:
+            resp = await ac.get(url, params={"jobId": job_id})
+            _raise_for_status(resp)
+            payload = resp.json()
+            last_payload = payload
+            status = payload.get("status")
+            if status == "completed":
+                return payload
+            if status in TERMINAL_STATUSES:
+                raise DharmamitraError(
+                    f"job {job_id} ended with status={status!r} "
+                    f"error={payload.get('error')!r} "
+                    f"error_code={payload.get('error_code')!r}"
+                )
+            if time.monotonic() >= deadline:
+                raise TimeoutError(
+                    f"job {job_id} still status={status!r} after {timeout}s"
+                )
+            await asyncio.sleep(interval)
+    finally:
+        if owns:
+            await ac.aclose()
+    # unreachable
+    return last_payload  # type: ignore[return-value]
+
+
+def _raise_for_status(resp: httpx.Response) -> None:
+    if resp.status_code == 403:
+        raise DharmamitraForbiddenError(
+            "Dharmamitra returned 403 (likely Cloudflare). "
+            "Set DHARMAMITRA_COOKIE env var to a fresh cf_clearance value."
+        )
+    if resp.status_code >= 400:
+        body = resp.text[:500]
+        raise DharmamitraError(
+            f"Dharmamitra HTTP {resp.status_code} for {resp.request.url}: {body}"
+        )