docreadi-mcp 0.1.0__tar.gz

docreadi_mcp-0.1.0/.gitignore

@@ -0,0 +1,67 @@
+# Secrets — never commit
+.env
+
+# Claude Code local settings (gitignore the directory's contents
+# via /* so the directory itself stays trackable, then carve out
+# the project-shared settings.json — added 2026-05-26 for the
+# team-wide ruff pre-push hook. Using `.claude/` here would
+# block the !.claude/settings.json re-include because git can't
+# re-include a file under an excluded directory).
+.claude/*
+!.claude/settings.json
+# Custom subagents are shared, durable assets (brand-guardian, marketing-agent
+# …) — version them. Re-include the dir, then the .md definitions inside it.
+!.claude/agents/
+!.claude/agents/*.md
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+env/
+
+# Docker volumes / data
+data/
+*.sqlite
+*.db
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Logs
+*.log
+logs/
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/
+
+# WSL metadata garbage from Windows copy-paste (foo.png:Zone.Identifier)
+*:Zone.Identifier
+
+# Generated/temp HTML renders of the markdown review docs — never track
+PRODUCT_REVIEW.html
+PRODUCT_REVIEW_tmp.html
+*_tmp.html
+
+# Local-only working / handover docs + ad-hoc probes — never track
+HANDOVER.md
+PIPELINE_CONCURRENCY_GOVERNOR_PLAN.md
+test_ocr_concurrency.py

docreadi_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: docreadi-mcp
+Version: 0.1.0
+Summary: MCP server for DocReadi — document data extraction for finance, in your AI client.
+Project-URL: Homepage, https://docreadi.com
+Project-URL: Documentation, https://api.docreadi.com/api/docs-guide
+Project-URL: Repository, https://github.com/greenmartian138/doc_intelligence
+Author-email: DocReadi <support@docreadi.com>
+License: Proprietary
+Keywords: docreadi,documents,extraction,finance,invoice,mcp,ocr
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27.0
+Requires-Dist: mcp>=1.2.0
+Description-Content-Type: text/markdown
+
+# docreadi-mcp
+
+A **local** [MCP](https://modelcontextprotocol.io) server for **DocReadi** —
+document data extraction for finance. It runs on your machine, reads documents
+off your disk, and calls the hosted DocReadi API with your API key, so an AI
+client (Claude Desktop, Claude Code, Cursor, …) can extract documents and query
+your DocReadi corpus without leaving the chat.
+
+> **Status: v1, in progress** (see `../../MCP_SERVER_PLAN.md`). Tools land
+> phase by phase; this is the skeleton + first read tool.
+
+## How it works
+
+Your MCP client spawns `docreadi-mcp` as a local subprocess and talks to it over
+stdio. The server is a thin courier — all extraction/storage happens on the
+hosted DocReadi API; the server just translates tool calls into HTTPS requests
+and (for ingestion) reads local files. Your API key lives only in your client
+config, never in this repo.
+
+## Install / configure
+
+Add the server to your MCP client config with your DocReadi API key
+(get one at **docreadi.com → Settings → API keys**):
+
+```jsonc
+{
+  "mcpServers": {
+    "docreadi": {
+      "command": "uvx",
+      "args": ["docreadi-mcp"],
+      "env": {
+        "DOCREADI_API_KEY": "dr_live_…"
+        // "DOCREADI_BASE_URL": "https://api.docreadi.com"  // override if self-hosting
+      }
+    }
+  }
+}
+```
+
+| Env var | Required | Default |
+|---|---|---|
+| `DOCREADI_API_KEY` | yes | — |
+| `DOCREADI_BASE_URL` | no | `https://api.docreadi.com` |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `check_connection` | First-run self-test — is DocReadi reachable and is your API key valid? Never errors; returns a diagnostic. |
+| `extract_document` | Extract structured data from a **local** PDF/JPG/PNG — uploads, waits for extraction, returns the fields + line items + totals + confidence. |
+| `get_document` | Fetch a document's status + extracted data by id. |
+| `extract_adhoc` | One-off, non-destructive extraction of caller-defined fields from a document already in DocReadi (e.g. "who signed these delivery notes?"). |
+| `classify_document` | (Re)classify a document's type; returns the type + reasoning. |
+| `search_documents` | Search/list the workspace's documents (by vendor, number, type, status, or date range) — a summary row per match. |
+| `list_counterparties` | List vendors/customers (VAT, aliases, doc counts), paginated. |
+| `list_reports` | List the workspace's saved reports. |
+| `run_report` | Run a saved report and return its rows — the way to query/search the corpus. |
+| `export_report_csv` | Run a saved report and write the result as a CSV to a local path. |
+
+_(`search_documents` is the raw query surface; for richer column selection and
+saved queries, author a report in the UI and use `run_report` /
+`export_report_csv`.)_
+
+## Development
+
+This package lives in the DocReadi monorepo so it's reviewed and CI'd alongside
+the API it wraps. Its layering keeps the dependency-free parts testable in the
+main CI without the `mcp` SDK:
+
+- `docreadi_mcp/config.py` — env config.
+- `docreadi_mcp/catalog.py` — pure-data tool→endpoint registry (the maintenance
+  anchor: `tests/test_mcp_catalog_contract.py` binds it to `agent_guide.GUIDE`).
+- `docreadi_mcp/client.py` — httpx client (tested with `MockTransport`).
+- `docreadi_mcp/server.py` — thin FastMCP glue (lazy-imports the `mcp` SDK).
+
+```bash
+# from the repo root
+pip install -e services/mcp          # installs mcp + httpx
+DOCREADI_API_KEY=dr_… python -m docreadi_mcp   # run over stdio
+```
+
+**Maintenance contract:** when a DocReadi API endpoint a tool wraps changes,
+update `docreadi_mcp/catalog.py` (and the tool) — the contract test fails CI
+otherwise. See `MCP_SERVER_PLAN.md` §5.

docreadi_mcp-0.1.0/PUBLISHING.md

@@ -0,0 +1,53 @@
+# Publishing `docreadi-mcp` to PyPI
+
+This is a **founder action** — it needs a PyPI account + an API token (a secret
+that must never go in the repo, chat, or CI logs without a protected store). The
+package itself is ready; this is the one step an agent can't do.
+
+## One-time setup
+
+1. Create a PyPI account at <https://pypi.org> (and ideally
+   <https://test.pypi.org> for a dry run).
+2. Create a **project-scoped API token** (Account → API tokens). For the very
+   first upload the project doesn't exist yet, so use an account-scoped token,
+   then rotate to a project-scoped one afterwards.
+3. Reserve the name by doing the first upload (the name `docreadi-mcp` is set in
+   `pyproject.toml`).
+
+## Build + upload
+
+From `services/mcp/` (in a clean venv):
+
+```bash
+python -m pip install --upgrade build twine
+python -m build                      # writes dist/docreadi_mcp-<v>.tar.gz + .whl
+python -m twine check dist/*         # metadata sanity
+# dry run first (optional):
+python -m twine upload --repository testpypi dist/*
+# real upload:
+python -m twine upload dist/*        # paste the token as the password (user: __token__)
+```
+
+Then verify the user-facing install path works from a clean machine:
+
+```bash
+DOCREADI_API_KEY=dr_live_… uvx docreadi-mcp   # should start and wait on stdio
+```
+
+## Releasing a new version
+
+1. Bump the version in **both** `pyproject.toml` and
+   `docreadi_mcp/__init__.py` (`__version__`) — they must match (the
+   `User-Agent` header reports `__version__`).
+2. `python -m build && python -m twine upload dist/*` (delete the old `dist/`
+   first).
+3. PyPI is append-only — you cannot overwrite a version, only yank it. Never
+   reuse a version number.
+
+## Notes
+
+- **No registry listing yet** (open decision #3 in `MCP_SERVER_PLAN.md`) — list
+  in an MCP registry only after a hosted/remote v2.
+- CI does **not** publish (no token in GitHub Actions). Publishing stays a
+  manual, founder-gated step until a release workflow with a protected token is
+  set up deliberately.

docreadi_mcp-0.1.0/README.md

@@ -0,0 +1,84 @@
+# docreadi-mcp
+
+A **local** [MCP](https://modelcontextprotocol.io) server for **DocReadi** —
+document data extraction for finance. It runs on your machine, reads documents
+off your disk, and calls the hosted DocReadi API with your API key, so an AI
+client (Claude Desktop, Claude Code, Cursor, …) can extract documents and query
+your DocReadi corpus without leaving the chat.
+
+> **Status: v1, in progress** (see `../../MCP_SERVER_PLAN.md`). Tools land
+> phase by phase; this is the skeleton + first read tool.
+
+## How it works
+
+Your MCP client spawns `docreadi-mcp` as a local subprocess and talks to it over
+stdio. The server is a thin courier — all extraction/storage happens on the
+hosted DocReadi API; the server just translates tool calls into HTTPS requests
+and (for ingestion) reads local files. Your API key lives only in your client
+config, never in this repo.
+
+## Install / configure
+
+Add the server to your MCP client config with your DocReadi API key
+(get one at **docreadi.com → Settings → API keys**):
+
+```jsonc
+{
+  "mcpServers": {
+    "docreadi": {
+      "command": "uvx",
+      "args": ["docreadi-mcp"],
+      "env": {
+        "DOCREADI_API_KEY": "dr_live_…"
+        // "DOCREADI_BASE_URL": "https://api.docreadi.com"  // override if self-hosting
+      }
+    }
+  }
+}
+```
+
+| Env var | Required | Default |
+|---|---|---|
+| `DOCREADI_API_KEY` | yes | — |
+| `DOCREADI_BASE_URL` | no | `https://api.docreadi.com` |
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `check_connection` | First-run self-test — is DocReadi reachable and is your API key valid? Never errors; returns a diagnostic. |
+| `extract_document` | Extract structured data from a **local** PDF/JPG/PNG — uploads, waits for extraction, returns the fields + line items + totals + confidence. |
+| `get_document` | Fetch a document's status + extracted data by id. |
+| `extract_adhoc` | One-off, non-destructive extraction of caller-defined fields from a document already in DocReadi (e.g. "who signed these delivery notes?"). |
+| `classify_document` | (Re)classify a document's type; returns the type + reasoning. |
+| `search_documents` | Search/list the workspace's documents (by vendor, number, type, status, or date range) — a summary row per match. |
+| `list_counterparties` | List vendors/customers (VAT, aliases, doc counts), paginated. |
+| `list_reports` | List the workspace's saved reports. |
+| `run_report` | Run a saved report and return its rows — the way to query/search the corpus. |
+| `export_report_csv` | Run a saved report and write the result as a CSV to a local path. |
+
+_(`search_documents` is the raw query surface; for richer column selection and
+saved queries, author a report in the UI and use `run_report` /
+`export_report_csv`.)_
+
+## Development
+
+This package lives in the DocReadi monorepo so it's reviewed and CI'd alongside
+the API it wraps. Its layering keeps the dependency-free parts testable in the
+main CI without the `mcp` SDK:
+
+- `docreadi_mcp/config.py` — env config.
+- `docreadi_mcp/catalog.py` — pure-data tool→endpoint registry (the maintenance
+  anchor: `tests/test_mcp_catalog_contract.py` binds it to `agent_guide.GUIDE`).
+- `docreadi_mcp/client.py` — httpx client (tested with `MockTransport`).
+- `docreadi_mcp/server.py` — thin FastMCP glue (lazy-imports the `mcp` SDK).
+
+```bash
+# from the repo root
+pip install -e services/mcp          # installs mcp + httpx
+DOCREADI_API_KEY=dr_… python -m docreadi_mcp   # run over stdio
+```
+
+**Maintenance contract:** when a DocReadi API endpoint a tool wraps changes,
+update `docreadi_mcp/catalog.py` (and the tool) — the contract test fails CI
+otherwise. See `MCP_SERVER_PLAN.md` §5.

docreadi_mcp-0.1.0/docreadi_mcp/__init__.py

@@ -0,0 +1,17 @@
+"""DocReadi MCP server — local-first wrapper over the DocReadi REST API.
+
+A small process the user's MCP client (Claude Desktop / Claude Code / …) spawns
+locally. It reads files off the user's disk and calls the hosted DocReadi API
+with the user's API key — so an agent can extract documents and query a corpus
+without leaving the chat. See MCP_SERVER_PLAN.md.
+
+Layering (deliberate, so the maintenance-contract + client tests run in CI
+without the `mcp` SDK installed):
+  * config.py   — env config (DOCREADI_API_KEY / DOCREADI_BASE_URL). No deps.
+  * catalog.py  — pure-data tool→endpoint registry. No deps. The contract test
+                  (tests/test_mcp_catalog_contract.py) binds it to agent_guide.GUIDE.
+  * client.py   — httpx client wrapping the REST API. Tested with MockTransport.
+  * server.py   — thin FastMCP glue (imports the `mcp` SDK lazily).
+"""
+
+__version__ = "0.1.0"

docreadi_mcp-0.1.0/docreadi_mcp/__main__.py

@@ -0,0 +1,28 @@
+"""Console entry point: `docreadi-mcp` (and `python -m docreadi_mcp`).
+
+Runs the MCP server over stdio — the user's MCP client spawns this as a
+subprocess. A missing API key (ConfigError) prints an actionable message and
+exits non-zero rather than dumping a traceback.
+"""
+from __future__ import annotations
+
+import sys
+
+
+def main() -> int:
+    from .config import ConfigError
+
+    try:
+        from .server import build_server
+
+        server = build_server()
+    except ConfigError as exc:
+        print(f"docreadi-mcp: {exc}", file=sys.stderr)
+        return 2
+
+    server.run()  # FastMCP defaults to stdio transport
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

docreadi_mcp-0.1.0/docreadi_mcp/catalog.py

@@ -0,0 +1,34 @@
+"""Tool → REST-endpoint catalog (pure data, no dependencies).
+
+This is the **maintenance anchor** (MCP_SERVER_PLAN.md §5): every MCP tool
+declares which DocReadi endpoint(s) it wraps, as the EXACT
+``"METHOD /path"`` string that appears in ``agent_guide.GUIDE["endpoints"]``.
+``tests/test_mcp_catalog_contract.py`` asserts every entry here resolves to a
+real GUIDE endpoint — so a tool can never wrap an endpoint that was removed or
+renamed without CI going red.
+
+Keep this module dependency-free so that contract test runs in the main CI
+without the `mcp` SDK installed.
+"""
+from __future__ import annotations
+
+# tool name → the GUIDE endpoint(s) it calls, each "METHOD /path" verbatim from
+# agent_guide.GUIDE. A tool may wrap more than one (e.g. submit + poll).
+TOOL_ENDPOINTS: dict[str, list[str]] = {
+    "check_connection": [
+        "GET /health",
+        "GET /api/v1/reports",
+    ],
+    "extract_document": [
+        "POST /ingest/process",
+        "GET /ingest/document/{document_id}",
+    ],
+    "get_document": ["GET /ingest/document/{document_id}"],
+    "extract_adhoc": ["POST /api/v1/documents/{id}/extract-adhoc"],
+    "classify_document": ["POST /classify"],
+    "search_documents": ["GET /api/v1/documents"],
+    "list_counterparties": ["GET /api/v1/counterparties"],
+    "list_reports": ["GET /api/v1/reports"],
+    "run_report": ["GET /api/v1/reports/{report_id}"],
+    "export_report_csv": ["GET /api/v1/reports/{report_id}/csv"],
+}

docreadi_mcp-0.1.0/docreadi_mcp/client.py

@@ -0,0 +1,272 @@
+"""Thin synchronous HTTP client over the DocReadi REST API.
+
+All the real work — extraction, storage — happens on the hosted API; this client
+is a courier. Sync (no pytest-asyncio in the repo's test env, and FastMCP runs
+sync tool functions in a threadpool just fine). Errors map to a single clean,
+user-facing ``DocReadiError`` so a tool failure reads as a sentence, not a stack
+trace.
+"""
+from __future__ import annotations
+
+import time
+from typing import Any, Callable
+
+import httpx
+
+from . import __version__
+from .config import Config
+from .errors import DocReadiError
+
+# Terminal document statuses (see routes/ingest.py + the GUIDE status list).
+_TERMINAL_OK = {"extracted", "approved"}
+_TERMINAL_FAIL = {"failed", "voided", "rejected"}
+
+__all__ = ["DocReadiClient", "DocReadiError"]
+
+
+def _format_http_error(resp: httpx.Response) -> str:
+    """Turn a 4xx/5xx into a readable sentence. Prefers the API's own ``detail``
+    field; adds guidance for the auth/permission cases an agent will hit."""
+    detail = None
+    try:
+        body = resp.json()
+        if isinstance(body, dict):
+            detail = body.get("detail") or body.get("error")
+    except (ValueError, httpx.HTTPError):
+        detail = (resp.text or "").strip()[:300] or None
+
+    code = resp.status_code
+    if code == 401:
+        return "DocReadi rejected the API key (401). Check DOCREADI_API_KEY in your MCP config."
+    if code == 403:
+        return (
+            f"DocReadi denied this request (403){f': {detail}' if detail else ''}. "
+            "The key may be a read-only (reviewer) key, or lack permission for this action."
+        )
+    if code == 404:
+        return f"Not found (404){f': {detail}' if detail else ''}."
+    if code == 429:
+        return "DocReadi rate-limited this request (429). Wait a moment and retry."
+    return f"DocReadi API error ({code}){f': {detail}' if detail else ''}."
+
+
+class DocReadiClient:
+    """Wraps the DocReadi REST API. Construct from a Config; pass a custom
+    ``transport`` (e.g. ``httpx.MockTransport``) in tests."""
+
+    def __init__(
+        self,
+        config: Config,
+        *,
+        transport: httpx.BaseTransport | None = None,
+        timeout: float = 60.0,
+    ) -> None:
+        self._config = config
+        self._http = httpx.Client(
+            base_url=config.base_url,
+            headers={
+                "X-Api-Key": config.api_key,
+                "User-Agent": f"docreadi-mcp/{__version__}",
+                "Accept": "application/json",
+            },
+            timeout=timeout,
+            transport=transport,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> "DocReadiClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+        try:
+            resp = self._http.request(method, path, **kwargs)
+        except httpx.HTTPError as exc:
+            raise DocReadiError(
+                f"Could not reach DocReadi at {self._config.base_url}: {exc}"
+            ) from exc
+        if resp.status_code >= 400:
+            raise DocReadiError(_format_http_error(resp))
+        if not resp.content:
+            return None
+        try:
+            return resp.json()
+        except ValueError:
+            return resp.text
+
+    # ── Tools (one method per wrapped endpoint) ──────────────────────────────
+
+    def check_connection(self) -> dict:
+        """Two cheap probes for a first-run self-test: is the DocReadi service
+        reachable (GET /health, no auth) and does the API key work (GET
+        /api/v1/reports, an authed reviewer-OK read). Never raises — returns a
+        diagnostic dict so the agent can explain *what* is wrong (bad URL, down
+        service, bad/insufficient key) instead of a cryptic stack trace."""
+        result: dict[str, Any] = {
+            "base_url": self._config.base_url,
+            "service_reachable": False,
+            "authenticated": False,
+        }
+        try:
+            health = self._request("GET", "/health")
+            result["service_reachable"] = True
+            if isinstance(health, dict):
+                result["health"] = health
+        except DocReadiError as exc:
+            result["error"] = str(exc)
+            return result
+        try:
+            self._request("GET", "/api/v1/reports")
+            result["authenticated"] = True
+            result["message"] = "Connected — DocReadi is reachable and the API key is valid."
+        except DocReadiError as exc:
+            result["error"] = str(exc)
+            result["message"] = (
+                "DocReadi is reachable but the API key check failed — see error."
+            )
+        return result
+
+    def get_document(self, document_id: str) -> Any:
+        """GET /ingest/document/{document_id} — status + extracted data."""
+        return self._request("GET", f"/ingest/document/{document_id}")
+
+    def ingest(
+        self,
+        file_bytes: bytes,
+        filename: str,
+        content_type: str,
+        *,
+        source: str = "mcp",
+        document_type: str | None = None,
+        template_id: str | None = None,
+    ) -> Any:
+        """POST /ingest/process — upload a document. Returns immediately with
+        ``{document_id, status: ...}``; the pipeline runs in the background."""
+        files = {"file": (filename, file_bytes, content_type)}
+        data: dict[str, str] = {"source": source}
+        if document_type:
+            data["document_type"] = document_type
+        if template_id:
+            data["template_id"] = template_id
+        return self._request("POST", "/ingest/process", files=files, data=data)
+
+    def extract_and_wait(
+        self,
+        file_bytes: bytes,
+        filename: str,
+        content_type: str,
+        *,
+        document_type: str | None = None,
+        template_id: str | None = None,
+        poll_interval: float = 2.0,
+        timeout: float = 180.0,
+        _sleep: Callable[[float], None] = time.sleep,
+        _clock: Callable[[], float] = time.monotonic,
+    ) -> Any:
+        """Upload a document and poll until extraction finishes, returning the
+        final document record. Raises DocReadiError on a failed/voided document
+        or if it doesn't finish within ``timeout`` (the doc still exists — fetch
+        it later with get_document)."""
+        ingested = self.ingest(
+            file_bytes, filename, content_type,
+            document_type=document_type, template_id=template_id,
+        )
+        doc_id = (ingested or {}).get("document_id") if isinstance(ingested, dict) else None
+        if not doc_id:
+            raise DocReadiError(f"Ingest did not return a document_id (got {ingested!r}).")
+
+        deadline = _clock() + timeout
+        while True:
+            current = self.get_document(doc_id)
+            status = str((current or {}).get("status") or "").lower() if isinstance(current, dict) else ""
+            if status in _TERMINAL_OK:
+                return current
+            if status in _TERMINAL_FAIL:
+                err = current.get("error") or current.get("error_message") if isinstance(current, dict) else None
+                raise DocReadiError(
+                    f"Document {doc_id} ended in status '{status}'"
+                    + (f": {err}" if err else "") + "."
+                )
+            if _clock() >= deadline:
+                raise DocReadiError(
+                    f"Extraction of {doc_id} did not finish within {timeout:.0f}s "
+                    f"(last status '{status or 'unknown'}'). It is still processing — "
+                    f"fetch it later with get_document."
+                )
+            _sleep(poll_interval)
+
+    def extract_adhoc(
+        self,
+        document_id: str,
+        fields: list,
+        *,
+        system_instructions: str | None = None,
+    ) -> Any:
+        """POST /api/v1/documents/{id}/extract-adhoc — one-off, non-destructive
+        extraction of caller-defined fields from an already-ingested document."""
+        body: dict[str, Any] = {"fields": fields}
+        if system_instructions:
+            body["system_instructions"] = system_instructions
+        return self._request(
+            "POST", f"/api/v1/documents/{document_id}/extract-adhoc", json=body
+        )
+
+    def classify(self, document_id: str) -> Any:
+        """POST /classify — (re)classify a document's type."""
+        return self._request("POST", "/classify", json={"document_id": document_id})
+
+    def list_counterparties(
+        self, *, page: int = 1, page_size: int = 100, status: str | None = None
+    ) -> Any:
+        """GET /api/v1/counterparties — paginated vendors/customers."""
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        if status:
+            params["status"] = status
+        return self._request("GET", "/api/v1/counterparties", params=params)
+
+    def list_documents(
+        self,
+        *,
+        page: int = 1,
+        page_size: int = 100,
+        status: str | None = None,
+        document_type: str | None = None,
+        q: str | None = None,
+        created_after: str | None = None,
+        created_before: str | None = None,
+    ) -> Any:
+        """GET /api/v1/documents — list/search documents (newest first)."""
+        params: dict[str, Any] = {"page": page, "page_size": page_size}
+        if status:
+            params["status"] = status
+        if document_type:
+            params["document_type"] = document_type
+        if q:
+            params["q"] = q
+        if created_after:
+            params["created_after"] = created_after
+        if created_before:
+            params["created_before"] = created_before
+        return self._request("GET", "/api/v1/documents", params=params)
+
+    def list_reports(self) -> Any:
+        """GET /api/v1/reports — the workspace's saved reports."""
+        return self._request("GET", "/api/v1/reports")
+
+    def run_report(
+        self, report_id: str, *, page: int = 1, page_size: int = 100, dedup: str = "primary"
+    ) -> Any:
+        """GET /api/v1/reports/{report_id} — run a saved report, return rows."""
+        params = {"page": page, "page_size": page_size, "dedup": dedup}
+        return self._request("GET", f"/api/v1/reports/{report_id}", params=params)
+
+    def report_csv(self, report_id: str, *, dedup: str = "primary") -> str:
+        """GET /api/v1/reports/{report_id}/csv — the report as CSV text."""
+        out = self._request(
+            "GET", f"/api/v1/reports/{report_id}/csv", params={"dedup": dedup}
+        )
+        return out if isinstance(out, str) else str(out)

docreadi_mcp-0.1.0/docreadi_mcp/config.py

@@ -0,0 +1,41 @@
+"""Runtime config for the DocReadi MCP server — read from the environment.
+
+The user supplies these in their MCP client config (see services/mcp/README.md):
+
+    "env": { "DOCREADI_API_KEY": "dr_live_…", "DOCREADI_BASE_URL": "https://…" }
+
+No secrets are ever read from or written to the repo — the key lives only in the
+user's local client config.
+"""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+DEFAULT_BASE_URL = "https://api.docreadi.com"
+
+
+@dataclass(frozen=True)
+class Config:
+    api_key: str
+    base_url: str
+
+
+class ConfigError(RuntimeError):
+    """Raised when required configuration is missing — surfaced to the user at
+    server startup with an actionable message."""
+
+
+def load_config(env: dict | None = None) -> Config:
+    """Build a Config from the environment. Raises ConfigError (actionable) when
+    DOCREADI_API_KEY is absent. ``env`` overridable for tests."""
+    src = os.environ if env is None else env
+    api_key = (src.get("DOCREADI_API_KEY") or "").strip()
+    if not api_key:
+        raise ConfigError(
+            "DOCREADI_API_KEY is not set. Add it to your MCP client config under "
+            'the docreadi server\'s "env" (get a key at '
+            "https://docreadi.com → Settings → API keys)."
+        )
+    base_url = (src.get("DOCREADI_BASE_URL") or DEFAULT_BASE_URL).strip().rstrip("/")
+    return Config(api_key=api_key, base_url=base_url)

docreadi_mcp-0.1.0/docreadi_mcp/errors.py

@@ -0,0 +1,11 @@
+"""Shared, dependency-free error type.
+
+Lives in its own module so both `client.py` (httpx) and `files.py` (pure
+stdlib) can raise it without `files.py` pulling in httpx.
+"""
+from __future__ import annotations
+
+
+class DocReadiError(RuntimeError):
+    """A clean, user-facing error from a DocReadi operation — surfaced as the
+    MCP tool's error text (a sentence, not a stack trace)."""

docreadi_mcp-0.1.0/docreadi_mcp/files.py

@@ -0,0 +1,62 @@
+"""Local file reading for the ingest tools (pure stdlib — no httpx/mcp).
+
+The whole point of a *local* MCP server is disk access: the agent passes a path,
+we read the bytes and POST them. Kept dependency-free so its test runs in the
+main CI.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+from .errors import DocReadiError
+
+# DocReadi accepts PDF + common image formats (see routes/ingest.py).
+CONTENT_TYPES: dict[str, str] = {
+    ".pdf": "application/pdf",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".png": "image/png",
+}
+
+# Guard against an agent passing a huge/wrong path. 50 MB is comfortably above
+# any real invoice; the API enforces its own limit too.
+MAX_BYTES = 50 * 1024 * 1024
+
+
+def read_document_file(file_path: str) -> tuple[str, bytes, str]:
+    """Return (filename, content_bytes, content_type) for a local document.
+
+    Raises DocReadiError (clean, user-facing) for a missing path, a non-file, an
+    unsupported extension, or an oversize file."""
+    p = Path(file_path).expanduser()
+    if not p.exists():
+        raise DocReadiError(f"No file at {p}")
+    if not p.is_file():
+        raise DocReadiError(f"{p} is not a file (is it a directory?).")
+    ext = p.suffix.lower()
+    if ext not in CONTENT_TYPES:
+        raise DocReadiError(
+            f"Unsupported file type '{ext or '(none)'}' — DocReadi accepts "
+            f"PDF, JPG, PNG."
+        )
+    size = p.stat().st_size
+    if size > MAX_BYTES:
+        raise DocReadiError(
+            f"{p.name} is {size / 1024 / 1024:.1f} MB — over the "
+            f"{MAX_BYTES // 1024 // 1024} MB limit."
+        )
+    return p.name, p.read_bytes(), CONTENT_TYPES[ext]
+
+
+def write_text_file(out_path: str, text: str) -> dict:
+    """Write ``text`` to a local file, returning {path, bytes}. Raises a clean
+    DocReadiError when the target is a directory or its parent folder is
+    missing (so the tool gives an actionable message instead of an OSError)."""
+    p = Path(out_path).expanduser()
+    if p.is_dir():
+        raise DocReadiError(f"{p} is a directory — give a file path to write to.")
+    if not p.parent.exists():
+        raise DocReadiError(f"The folder {p.parent} does not exist.")
+    data = text if isinstance(text, str) else str(text)
+    p.write_text(data, encoding="utf-8")
+    return {"path": str(p), "bytes": len(data.encode("utf-8"))}

docreadi_mcp-0.1.0/docreadi_mcp/server.py

@@ -0,0 +1,219 @@
+"""FastMCP glue — registers the DocReadi tools and runs over stdio.
+
+Deliberately thin: each tool is a few lines that call `DocReadiClient`. The
+`mcp` SDK is imported lazily inside `build_server` so the rest of the package
+(config / client / catalog) and their tests don't require the SDK installed.
+"""
+from __future__ import annotations
+
+from .catalog import TOOL_ENDPOINTS
+from .client import DocReadiClient
+from .config import Config, load_config
+from .files import read_document_file, write_text_file
+
+
+def build_server(client: DocReadiClient | None = None, config: Config | None = None):
+    """Construct the FastMCP server with every tool registered.
+
+    ``client`` is injectable for tests (so the SDK wiring can be exercised
+    without real config/network). In normal use both args are None and config is
+    read from the environment.
+    """
+    # Resolve config/client FIRST so a missing DOCREADI_API_KEY surfaces as the
+    # friendly ConfigError before we touch the SDK.
+    if client is None:
+        client = DocReadiClient(config or load_config())
+
+    from mcp.server.fastmcp import FastMCP  # lazy — only needed to actually run
+
+    mcp = FastMCP("docreadi")
+
+    @mcp.tool()
+    def check_connection() -> dict:
+        """Check that DocReadi is reachable and your API key works — run this
+        first if anything seems wrong. Returns {service_reachable, authenticated,
+        message, …}; it never errors, so use it to diagnose a bad DOCREADI_API_KEY
+        or DOCREADI_BASE_URL before trying other tools."""
+        return client.check_connection()
+
+    @mcp.tool()
+    def extract_document(
+        file_path: str, document_type: str = "", template_id: str = ""
+    ) -> dict:
+        """Extract structured data from a local document file (PDF, JPG, or PNG)
+        on this machine. Uploads it to DocReadi, waits for extraction to finish
+        (usually well under a minute), and returns the document's status and the
+        structured extracted data (fields, line items, totals, confidence).
+
+        Args:
+            file_path: path to the document file on this machine.
+            document_type: optional — force a type (e.g. 'ap_invoice'); leave
+                empty to auto-detect.
+            template_id: optional — id of a custom extraction template to use.
+        """
+        filename, content, content_type = read_document_file(file_path)
+        return client.extract_and_wait(
+            content, filename, content_type,
+            document_type=document_type or None,
+            template_id=template_id or None,
+        )
+
+    @mcp.tool()
+    def get_document(document_id: str) -> dict:
+        """Fetch a DocReadi document by its id: its processing status and, once
+        extraction has finished, the structured extracted data.
+
+        Args:
+            document_id: the DocReadi document UUID (e.g. returned when a
+                document was ingested).
+        """
+        return client.get_document(document_id)
+
+    @mcp.tool()
+    def extract_adhoc(
+        document_id: str, fields: list, system_instructions: str = ""
+    ) -> dict:
+        """One-off, non-destructive extraction of specific fields from a document
+        that is already in DocReadi — without changing its stored extraction.
+        Use it to answer an ad-hoc question ("who signed these delivery notes?").
+
+        Args:
+            document_id: the DocReadi document UUID.
+            fields: the fields to extract — a list of
+                {"name": str, "type": str, "description": str} objects
+                (type one of string/number/date/boolean/list_of_strings).
+            system_instructions: optional extra guidance for the model.
+        """
+        return client.extract_adhoc(
+            document_id, fields, system_instructions=system_instructions or None
+        )
+
+    @mcp.tool()
+    def classify_document(document_id: str) -> dict:
+        """Classify (or re-classify) a document already in DocReadi — returns the
+        detected document_type and the model's reasoning. (Classification runs
+        automatically during ingestion; use this only to re-run it.)
+
+        Args:
+            document_id: the DocReadi document UUID.
+        """
+        return client.classify(document_id)
+
+    @mcp.tool()
+    def search_documents(
+        q: str = "",
+        status: str = "",
+        document_type: str = "",
+        created_after: str = "",
+        created_before: str = "",
+        page: int = 1,
+        page_size: int = 100,
+    ) -> dict:
+        """Search/list the documents in this DocReadi workspace (newest first).
+        The quick way to find documents by vendor, number, type, status, or date
+        — returns a summary row per document (id, type, status, number, vendor,
+        date, total, currency, filename). Use get_document for the full data, or
+        a saved report (list_reports / run_report) for richer columns.
+
+        Args:
+            q: free-text match over vendor name / document number / filename.
+            status: filter by processing status (e.g. 'extracted', 'approved',
+                'flagged').
+            document_type: filter by type (e.g. 'ap_invoice').
+            created_after: only documents created on/after this date (YYYY-MM-DD).
+            created_before: only documents created on/before this date
+                (YYYY-MM-DD, inclusive).
+            page: 1-based page number.
+            page_size: rows per page (max 500).
+        """
+        return client.list_documents(
+            page=page,
+            page_size=page_size,
+            status=status or None,
+            document_type=document_type or None,
+            q=q or None,
+            created_after=created_after or None,
+            created_before=created_before or None,
+        )
+
+    @mcp.tool()
+    def list_counterparties(
+        page: int = 1, page_size: int = 100, status: str = ""
+    ) -> dict:
+        """List this workspace's counterparties (vendors / customers) with their
+        VAT numbers, aliases, and document counts. Paginated.
+
+        Args:
+            page: 1-based page number.
+            page_size: rows per page (max 500).
+            status: optional filter — 'confirmed' or 'candidate'.
+        """
+        return client.list_counterparties(
+            page=page, page_size=page_size, status=status or None
+        )
+
+    @mcp.tool()
+    def list_reports() -> list:
+        """List the saved reports in this DocReadi workspace (id, name,
+        description, columns). Use run_report to fetch a report's rows — saved
+        reports are how you query/search the document corpus."""
+        return client.list_reports()
+
+    @mcp.tool()
+    def run_report(
+        report_id: str, page: int = 1, page_size: int = 100, dedup: str = "primary"
+    ) -> dict:
+        """Run a saved report and return its rows — the way to query/search the
+        documents in this workspace (e.g. "last month's approved AP invoices").
+
+        Args:
+            report_id: the saved report's id (from list_reports).
+            page: 1-based page number.
+            page_size: rows per page.
+            dedup: 'primary' (default, one row per document), 'all', or
+                'duplicates'.
+        """
+        return client.run_report(
+            report_id, page=page, page_size=page_size, dedup=dedup
+        )
+
+    @mcp.tool()
+    def export_report_csv(report_id: str, out_path: str, dedup: str = "primary") -> dict:
+        """Run a saved report and write the full result as a CSV file to a LOCAL
+        path on this machine. Returns {path, bytes}.
+
+        Args:
+            report_id: the saved report's id (from list_reports).
+            out_path: where to write the CSV on this machine (e.g.
+                '/Users/me/Desktop/report.csv').
+            dedup: 'primary' (default), 'all', or 'duplicates'.
+        """
+        csv_text = client.report_csv(report_id, dedup=dedup)
+        return write_text_file(out_path, csv_text)
+
+    # Guardrail: every registered tool must be declared in the catalog (which
+    # the contract test binds to the API reference). Catches "added a tool,
+    # forgot the catalog entry" at startup.
+    registered = set(_tool_names(mcp))
+    undeclared = registered - set(TOOL_ENDPOINTS)
+    if undeclared:
+        raise RuntimeError(
+            f"MCP tools not declared in catalog.TOOL_ENDPOINTS: {sorted(undeclared)}"
+        )
+
+    return mcp
+
+
+def _tool_names(mcp) -> list[str]:
+    """Best-effort introspection of registered tool names across FastMCP
+    versions (the internal accessor has shifted)."""
+    mgr = getattr(mcp, "_tool_manager", None)
+    if mgr is not None and hasattr(mgr, "_tools"):
+        return list(mgr._tools.keys())
+    lister = getattr(mcp, "list_tools", None)
+    if callable(lister):
+        try:
+            return [t.name for t in lister()]
+        except Exception:
+            pass
+    return list(TOOL_ENDPOINTS)  # fall back to the declared set

docreadi_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "docreadi-mcp"
+version = "0.1.0"
+description = "MCP server for DocReadi — document data extraction for finance, in your AI client."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "Proprietary" }
+authors = [{ name = "DocReadi", email = "support@docreadi.com" }]
+keywords = ["mcp", "docreadi", "invoice", "extraction", "documents", "finance", "ocr"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Topic :: Office/Business :: Financial",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = [
+    "mcp>=1.2.0",
+    "httpx>=0.27.0,<1",
+]
+
+[project.urls]
+Homepage = "https://docreadi.com"
+Documentation = "https://api.docreadi.com/api/docs-guide"
+Repository = "https://github.com/greenmartian138/doc_intelligence"
+
+[project.scripts]
+docreadi-mcp = "docreadi_mcp.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["docreadi_mcp"]