localparse-mcp 0.1.0__tar.gz

localparse_mcp-0.1.0/.gitignore

@@ -0,0 +1,56 @@
+# --- Secrets (do NOT commit) ---
+.env
+.env.*
+!.env.example
+**/service-account.json
+**/credentials.json
+**/*.pem
+**/*.key
+# Supabase JWT/JWKS material and any local key dumps (the legacy "jtw" typo too).
+**/supabase_jtw.json
+**/supabase_jwt.json
+**/*.jwks.json
+
+# --- Downloaded data (large, regenerable) ---
+**/downloads/
+**/cases/
+**/stores/
+**/blocks.parquet
+**/entities.db
+**/index/
+
+# --- Generated eval / audit reports ---
+doc_extraction_v2/reports/
+doc_extraction_v2/scripts/reports/
+
+# --- Real-PDF test artifacts (regenerable, large) ---
+doc_extraction_v2/tests/real_pdfs/reports/
+.cache/doc-extraction-v2/
+
+# --- Extraction artifacts (regenerable per parse) ---
+**/figures/
+
+# --- Python ---
+.venv/
+venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+build/
+dist/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# --- OS / editor ---
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+
+# --- Logs ---
+*.log

localparse_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,87 @@
+Metadata-Version: 2.4
+Name: localparse-mcp
+Version: 0.1.0
+Summary: MCP server for LocalParse — accurate document parsing for Cursor, Claude Desktop, and other MCP clients.
+Project-URL: Homepage, https://localparse.com
+Project-URL: Source, https://github.com/stevencoveta/Agent-ingestor
+Author: LocalParse
+License: MIT
+Keywords: document parsing,localparse,mcp,model context protocol,ocr,pdf
+Requires-Python: >=3.10
+Requires-Dist: localparse>=0.1.0
+Requires-Dist: mcp>=1.2.0
+Requires-Dist: requests>=2.28
+Description-Content-Type: text/markdown
+
+# localparse-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that gives your coding agent
+(Cursor, Claude Desktop, etc.) **accurate document parsing** via
+[LocalParse](https://localparse.com) — table-detection recovery + arithmetic
+identity checks — instead of letting it write throwaway OCR scripts.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `parse_document(path, result_type)` | Parse a local file (PDF/image/PPTX/…). |
+| `parse_url(url, result_type)` | Download a remote doc and parse it. |
+| `parse_folder(path, case_id, resume)` | Ingest a whole folder into a named case; re-runs only parse changed files. |
+| `get_structured(job_id)` | Fetch the structured ingestion contract for a job. |
+| `case_manifest(case_id)` | List a case's ingested docs (path + hash + status). |
+| `case_failures(case_id)` | List a case's failed docs for reingest. |
+
+`result_type` ∈ `markdown` (default), `text`, `json`, `structured`.
+
+## Configure your client
+
+You need a LocalParse API key (`LOCALPARSE_API_KEY`).
+
+### Cursor — `~/.cursor/mcp.json` (or project `.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "localparse": {
+      "command": "uvx",
+      "args": ["localparse-mcp"],
+      "env": { "LOCALPARSE_API_KEY": "lp-your-key" }
+    }
+  }
+}
+```
+
+### Claude Desktop — `claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "localparse": {
+      "command": "uvx",
+      "args": ["localparse-mcp"],
+      "env": { "LOCALPARSE_API_KEY": "lp-your-key" }
+    }
+  }
+}
+```
+
+Then ask the agent things like *"parse the PDFs in ./data-room into case acme and
+tell me which tables don't reconcile."*
+
+## Local development (before it's on PyPI)
+
+Run the server straight from the repo and point the client at it:
+
+```json
+{
+  "mcpServers": {
+    "localparse": {
+      "command": "uv",
+      "args": ["run", "--directory", "/abs/path/to/Agent-ingestor", "localparse-mcp"],
+      "env": { "LOCALPARSE_API_KEY": "lp-your-key" }
+    }
+  }
+}
+```
+
+Point at a self-hosted parser by also setting `LOCALPARSE_BASE_URL`.

localparse_mcp-0.1.0/README.md

@@ -0,0 +1,72 @@
+# localparse-mcp
+
+An [MCP](https://modelcontextprotocol.io) server that gives your coding agent
+(Cursor, Claude Desktop, etc.) **accurate document parsing** via
+[LocalParse](https://localparse.com) — table-detection recovery + arithmetic
+identity checks — instead of letting it write throwaway OCR scripts.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `parse_document(path, result_type)` | Parse a local file (PDF/image/PPTX/…). |
+| `parse_url(url, result_type)` | Download a remote doc and parse it. |
+| `parse_folder(path, case_id, resume)` | Ingest a whole folder into a named case; re-runs only parse changed files. |
+| `get_structured(job_id)` | Fetch the structured ingestion contract for a job. |
+| `case_manifest(case_id)` | List a case's ingested docs (path + hash + status). |
+| `case_failures(case_id)` | List a case's failed docs for reingest. |
+
+`result_type` ∈ `markdown` (default), `text`, `json`, `structured`.
+
+## Configure your client
+
+You need a LocalParse API key (`LOCALPARSE_API_KEY`).
+
+### Cursor — `~/.cursor/mcp.json` (or project `.cursor/mcp.json`)
+
+```json
+{
+  "mcpServers": {
+    "localparse": {
+      "command": "uvx",
+      "args": ["localparse-mcp"],
+      "env": { "LOCALPARSE_API_KEY": "lp-your-key" }
+    }
+  }
+}
+```
+
+### Claude Desktop — `claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "localparse": {
+      "command": "uvx",
+      "args": ["localparse-mcp"],
+      "env": { "LOCALPARSE_API_KEY": "lp-your-key" }
+    }
+  }
+}
+```
+
+Then ask the agent things like *"parse the PDFs in ./data-room into case acme and
+tell me which tables don't reconcile."*
+
+## Local development (before it's on PyPI)
+
+Run the server straight from the repo and point the client at it:
+
+```json
+{
+  "mcpServers": {
+    "localparse": {
+      "command": "uv",
+      "args": ["run", "--directory", "/abs/path/to/Agent-ingestor", "localparse-mcp"],
+      "env": { "LOCALPARSE_API_KEY": "lp-your-key" }
+    }
+  }
+}
+```
+
+Point at a self-hosted parser by also setting `LOCALPARSE_BASE_URL`.

localparse_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,28 @@
+[project]
+name = "localparse-mcp"
+version = "0.1.0"
+description = "MCP server for LocalParse — accurate document parsing for Cursor, Claude Desktop, and other MCP clients."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "LocalParse" }]
+keywords = ["mcp", "model context protocol", "document parsing", "pdf", "ocr", "localparse"]
+dependencies = [
+    "localparse>=0.1.0",
+    "mcp>=1.2.0",
+    "requests>=2.28",
+]
+
+[project.scripts]
+localparse-mcp = "localparse_mcp.server:main"
+
+[project.urls]
+Homepage = "https://localparse.com"
+Source = "https://github.com/stevencoveta/Agent-ingestor"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/localparse_mcp"]

localparse_mcp-0.1.0/src/localparse_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""MCP server for LocalParse — accurate document parsing for MCP clients."""
+
+from __future__ import annotations
+
+__version__ = "0.1.0"
+
+__all__ = ["__version__"]

localparse_mcp-0.1.0/src/localparse_mcp/server.py

@@ -0,0 +1,188 @@
+"""MCP server exposing LocalParse's accurate document parsing to MCP clients.
+
+Run locally over stdio (how Cursor / Claude Desktop launch it):
+
+    LOCALPARSE_API_KEY=lp-... uvx localparse-mcp
+
+The tools let an agent parse local files / folders / URLs with a real parser
+(table-detection recovery + arithmetic identity checks) instead of writing
+ad-hoc OCR scripts.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from pathlib import Path
+from urllib.parse import urlparse
+
+import requests
+from localparse import LocalParse, LocalParseError, ParseResult
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("localparse")
+
+_client: LocalParse | None = None
+
+
+def _get_client() -> LocalParse:
+    """Build (once) a LocalParse client from the environment.
+
+    Reads ``LOCALPARSE_API_KEY`` (required) and ``LOCALPARSE_BASE_URL``
+    (optional; defaults to the hosted API). Raises ``LocalParseError`` with a
+    clear message when the key is missing so the tool can surface it.
+    """
+    global _client
+    if _client is None:
+        base_url = os.environ.get("LOCALPARSE_BASE_URL", "https://api.localparse.com")
+        _client = LocalParse(base_url=base_url)
+    return _client
+
+
+def _render(result: ParseResult, result_type: str) -> str:
+    if result_type in ("markdown", "md"):
+        return result.markdown or ""
+    if result_type in ("text", "txt"):
+        return result.text or ""
+    return json.dumps(result.data, indent=2, ensure_ascii=False)
+
+
+@mcp.tool()
+def parse_document(path: str, result_type: str = "markdown") -> str:
+    """Parse a local document with LocalParse and return its contents.
+
+    Use this instead of writing OCR/pdf-to-text scripts: LocalParse recovers
+    tables a layout model would miss and arithmetic-checks numeric Totals, so
+    the output is far more reliable on financial/tabular PDFs, scans, and decks.
+    Supports PDF, images, PPTX, and more. ``result_type`` is one of ``markdown``
+    (default), ``text``, ``json``, or ``structured`` (the ingestion contract).
+    """
+    try:
+        result = _get_client().parse(path, result_type=result_type)
+    except LocalParseError as exc:
+        return f"LocalParse error: {exc}"
+    return _render(result, result_type)
+
+
+@mcp.tool()
+def parse_url(url: str, result_type: str = "markdown") -> str:
+    """Download a remote document (e.g. a PDF URL) and parse it with LocalParse.
+
+    Same accuracy guarantees as ``parse_document``. ``result_type`` is one of
+    ``markdown`` (default), ``text``, ``json``, or ``structured``.
+    """
+    name = Path(urlparse(url).path).name or "download.pdf"
+    suffix = Path(name).suffix or ".pdf"
+    tmp_path: Path | None = None
+    try:
+        with requests.get(url, stream=True, timeout=60) as resp:
+            resp.raise_for_status()
+            with tempfile.NamedTemporaryFile(suffix=suffix, delete=False) as tmp:
+                tmp_path = Path(tmp.name)
+                for chunk in resp.iter_content(chunk_size=1 << 16):
+                    tmp.write(chunk)
+        result = _get_client().parse(tmp_path, result_type=result_type)
+    except requests.RequestException as exc:
+        return f"Download failed: {exc}"
+    except LocalParseError as exc:
+        return f"LocalParse error: {exc}"
+    finally:
+        if tmp_path is not None:
+            tmp_path.unlink(missing_ok=True)
+    return _render(result, result_type)
+
+
+@mcp.tool()
+def parse_folder(
+    path: str,
+    case_id: str,
+    resume: bool = True,
+    result_type: str = "markdown",
+) -> str:
+    """Parse every document in a local folder into a named LocalParse "case".
+
+    Ideal for ingesting a docs/ or data-room folder. Each file is persisted under
+    ``case_id`` with a folder-relative path; with ``resume`` (default) a re-run
+    only parses new/changed files (unchanged ones are skipped by content hash).
+    Returns a JSON summary: parsed/skipped counts and, per parsed file, its
+    ``job_id``, persisted ``doc_id``, and any arithmetic ``identity_violations``
+    (a non-zero count means a Total didn't reconcile — worth reviewing).
+    """
+    summary: dict[str, object] = {"case_id": case_id, "parsed": [], "skipped": []}
+    parsed: list[dict[str, object]] = summary["parsed"]  # type: ignore[assignment]
+    skipped: list[str] = summary["skipped"]  # type: ignore[assignment]
+
+    def _progress(rel: str, res: ParseResult | None) -> None:
+        if res is None:
+            skipped.append(rel)
+            return
+        identity = res.identity_check or {}
+        parsed.append(
+            {
+                "source_path": rel,
+                "job_id": res.job_id,
+                "persisted_doc_id": (res.persisted or {}).get("doc_id"),
+                "identity_violations": identity.get("violations"),
+            }
+        )
+
+    try:
+        _get_client().parse_folder(
+            path,
+            case_id=case_id,
+            resume=resume,
+            result_type=result_type,
+            on_progress=_progress,
+        )
+    except (LocalParseError, ValueError) as exc:
+        return f"LocalParse error: {exc}"
+    summary["parsed_count"] = len(parsed)
+    summary["skipped_count"] = len(skipped)
+    return json.dumps(summary, indent=2)
+
+
+@mcp.tool()
+def get_structured(job_id: str) -> str:
+    """Fetch the versioned structured-document contract for a finished job.
+
+    Returns the JSON ingestion contract (ordered blocks with provenance:
+    page, section_path, type, table_markdown, bbox, needs_review, ...).
+    """
+    try:
+        result = _get_client().get_result(job_id, result_type="structured")
+    except LocalParseError as exc:
+        return f"LocalParse error: {exc}"
+    return json.dumps(result.data, indent=2, ensure_ascii=False)
+
+
+@mcp.tool()
+def case_manifest(case_id: str) -> str:
+    """List a case's already-ingested documents (source_path + content hash + status).
+
+    Lets the agent see what's in a case before re-ingesting or to plan a delta.
+    """
+    try:
+        manifest = _get_client().case_manifest(case_id)
+    except LocalParseError as exc:
+        return f"LocalParse error: {exc}"
+    return json.dumps(manifest, indent=2, ensure_ascii=False)
+
+
+@mcp.tool()
+def case_failures(case_id: str, include_resolved: bool = False) -> str:
+    """List a case's failed documents (error, attempts, timestamps) for reingest."""
+    try:
+        failures = _get_client().case_failures(case_id, include_resolved=include_resolved)
+    except LocalParseError as exc:
+        return f"LocalParse error: {exc}"
+    return json.dumps(failures, indent=2, ensure_ascii=False)
+
+
+def main() -> None:
+    """Console entry point: run the server over stdio."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

localparse_mcp-0.1.0/tests/test_server.py

@@ -0,0 +1,78 @@
+"""Unit tests for the LocalParse MCP server (fake client, no network)."""
+
+from __future__ import annotations
+
+import json
+
+import localparse_mcp.server as server
+import pytest
+from localparse import AuthenticationError, ParseResult
+
+
+def test_render_flavours() -> None:
+    md = ParseResult(job_id="j", result_type="markdown", data={"markdown": "# Hi"})
+    assert server._render(md, "markdown") == "# Hi"
+    txt = ParseResult(job_id="j", result_type="text", data={"text": "hello"})
+    assert server._render(txt, "text") == "hello"
+    js = ParseResult(job_id="j", result_type="json", data={"pages": [1]})
+    assert json.loads(server._render(js, "json")) == {"pages": [1]}
+
+
+def test_get_client_requires_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("LOCALPARSE_API_KEY", raising=False)
+    server._client = None
+    with pytest.raises(AuthenticationError):
+        server._get_client()
+
+
+def test_parse_document_tool(monkeypatch: pytest.MonkeyPatch) -> None:
+    class FakeClient:
+        def parse(self, path: str, result_type: str = "markdown") -> ParseResult:
+            return ParseResult(
+                job_id="j", result_type=result_type, data={"markdown": "# Doc"}
+            )
+
+    monkeypatch.setattr(server, "_get_client", lambda: FakeClient())
+    assert server.parse_document("x.pdf", "markdown") == "# Doc"
+
+
+def test_parse_document_tool_surfaces_errors(monkeypatch: pytest.MonkeyPatch) -> None:
+    class FakeClient:
+        def parse(self, path: str, result_type: str = "markdown") -> ParseResult:
+            raise AuthenticationError("bad key")
+
+    monkeypatch.setattr(server, "_get_client", lambda: FakeClient())
+    out = server.parse_document("x.pdf")
+    assert "LocalParse error" in out and "bad key" in out
+
+
+def test_parse_folder_tool_summary(monkeypatch: pytest.MonkeyPatch) -> None:
+    class FakeClient:
+        def parse_folder(self, path, *, case_id, resume, result_type, on_progress):  # noqa: ANN001
+            on_progress(
+                "a.pdf",
+                ParseResult(
+                    job_id="j1",
+                    result_type="markdown",
+                    data={
+                        "job_metadata": {
+                            "identity_check": {"violations": 2},
+                            "persisted": {"doc_id": "d1"},
+                        }
+                    },
+                ),
+            )
+            on_progress("b.pdf", None)
+
+    monkeypatch.setattr(server, "_get_client", lambda: FakeClient())
+    data = json.loads(server.parse_folder("dir", "acme"))
+
+    assert data["parsed_count"] == 1
+    assert data["skipped_count"] == 1
+    assert data["skipped"] == ["b.pdf"]
+    assert data["parsed"][0] == {
+        "source_path": "a.pdf",
+        "job_id": "j1",
+        "persisted_doc_id": "d1",
+        "identity_violations": 2,
+    }