promptready-mcp 0.3.3__tar.gz

promptready_mcp-0.3.3/LICENSE

@@ -0,0 +1,27 @@
+MIT License
+
+Copyright (c) 2026 PromptReady / HydRoMo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Note: This license applies to the **PromptReady MCP client** source code only.
+Use of the PromptReady cloud service (https://promptready.space) remains
+subject to the PromptReady Terms of Service and Privacy Policy.

promptready_mcp-0.3.3/MANIFEST.in

@@ -0,0 +1 @@
+prune tests

promptready_mcp-0.3.3/PKG-INFO

@@ -0,0 +1,245 @@
+Metadata-Version: 2.4
+Name: promptready-mcp
+Version: 0.3.3
+Summary: MCP server (stdio) for PromptReady — convert PDF/CSV to Markdown from AI agents.
+Author: PromptReady
+License-Expression: MIT
+Project-URL: Homepage, https://promptready.space
+Project-URL: Documentation, https://github.com/hydrojwh/promptready-mcp#readme
+Project-URL: Source, https://github.com/hydrojwh/promptready-mcp
+Project-URL: Issues, https://github.com/hydrojwh/promptready-mcp/issues
+Keywords: mcp,model-context-protocol,pdf,csv,markdown,ocr,claude,cursor
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp<2,>=1.2.0
+Requires-Dist: httpx<1,>=0.27
+Dynamic: license-file
+
+# PromptReady MCP
+
+<!-- mcp-name: io.github.hydrojwh/promptready-mcp -->
+
+Official [Model Context Protocol](https://modelcontextprotocol.io/) client for
+[PromptReady](https://promptready.space) — convert PDF/CSV to Markdown from AI
+agents (Grok, Claude Code, Cursor, and other MCP hosts).
+
+**Same PromptReady account and credits as the web app.**
+
+## Features
+
+- Browser Google login (tokens stay on your machine)
+- `get_credits`, `convert_pdf`, `get_status`, `wait_and_download`
+- Saved convert defaults (engine, tables, images) — not on every call
+- Factory default: **PaddleOCR-VL**, tables on, images off
+
+## Install
+
+```bash
+pip install promptready-mcp
+```
+
+Or run it without installing:
+
+```bash
+uvx promptready-mcp
+```
+
+<details>
+<summary>From source</summary>
+
+```bash
+git clone https://github.com/hydrojwh/promptready-mcp.git
+cd promptready-mcp
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+</details>
+
+## Login (once per machine)
+
+```bash
+promptready-mcp-login
+```
+
+If you installed with `uvx`, the login command lives in the same package:
+
+```bash
+uvx --from promptready-mcp promptready-mcp-login
+```
+
+Either opens Google OAuth and saves credentials to
+`~/.config/promptready/credentials.json` (file mode `0600`). That path is in your
+home directory, so it survives `uvx` cache resets. You can also log in from inside
+an MCP host by calling the `login` tool.
+
+Supabase Auth must allow redirect:
+
+`http://127.0.0.1:18765/callback`
+
+<details>
+<summary>Email login fallback</summary>
+
+If browser-based Google login is not an option, the same command accepts email
+and password:
+
+```bash
+promptready-mcp-login --email you@x.com
+```
+
+Leave out `--password` and you will be prompted for it instead — this keeps the
+password out of your shell history.
+
+</details>
+
+Already have an access token? Set `PROMPTREADY_ACCESS_TOKEN` in the environment
+(MCP host or shell). Environment variables take precedence over the saved
+credentials file.
+
+## MCP host config
+
+### Fastest: let your AI agent install it
+
+If you are already in an MCP-capable agent, skip the JSON editing and just
+ask:
+
+> Install the PromptReady MCP server for me. The PyPI package is
+> `promptready-mcp` (stdio command `promptready-mcp`). Add it to your MCP
+> config, then I will run the `login` tool.
+
+In Claude Code the agent can use the built-in CLI:
+
+```bash
+claude mcp add promptready -- promptready-mcp
+```
+
+### Reconnect after changing config
+
+Hosts do not pick up MCP config changes mid-session. After changing the
+config, restart the host or reconnect the server — in Claude Code, open the
+`/mcp` panel and reconnect.
+
+Seeing tools in the `/mcp` panel does **not** mean the server is connected:
+the panel can list the tool catalog while the session has no live server,
+and picking a tool from that list will not run it. If tools are listed but
+calls fail, reconnect first.
+
+### Claude Code
+
+```bash
+claude mcp add promptready -- promptready-mcp
+```
+
+The default scope is `local` (this project only). Use `--scope user` to
+register it for all your projects, or `--scope project` to share the
+registration through a committed `.mcp.json`.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` for a single project):
+
+```json
+{
+  "mcpServers": {
+    "promptready": {
+      "command": "promptready-mcp"
+    }
+  }
+}
+```
+
+### Grok
+
+```toml
+[mcp_servers.promptready]
+command = "promptready-mcp"
+enabled = true
+tool_timeout_sec = 3600
+```
+
+### Claude Desktop / generic JSON
+
+```json
+{
+  "mcpServers": {
+    "promptready": {
+      "command": "promptready-mcp"
+    }
+  }
+}
+```
+
+No access token in config files required after login.
+
+<details>
+<summary>Host cannot find <code>promptready-mcp</code></summary>
+
+GUI hosts start servers with a narrow `PATH`, so a console script installed by
+`pip install --user` is often invisible to them — the host reports a spawn
+failure or "server disconnected" rather than a missing command.
+
+Two reliable fixes:
+
+```json
+{ "mcpServers": { "promptready": {
+  "command": "uvx", "args": ["promptready-mcp"] } } }
+```
+
+or point at the absolute path of the script:
+`/ABS/PATH/.venv/bin/promptready-mcp`.
+
+</details>
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `login` / `logout` | Browser auth / clear local credentials |
+| `get_credits` | Credit balance |
+| `get_convert_settings` / `set_convert_settings` | Saved convert defaults |
+| `convert_pdf` | Upload path → queue (optional `wait`) |
+| `get_status` | Job status |
+| `wait_and_download` | Poll + save `.md` |
+
+Downloaded names follow the web app: `{name}_PaddleOCR-VL.md` (engine label).
+
+Credits are deducted by the server when a job is queued, exactly as on the web
+app. `convert_pdf(wait=True)` can run for a long time, so give the host a high
+tool timeout.
+
+## Security
+
+- Tokens are **never** hardcoded in this repository.
+- Do **not** commit `~/.config/promptready/*` or `.env`.
+- Only use the official package linked from https://promptready.space
+- Vulnerability reports: see [SECURITY.md](SECURITY.md)
+
+## Service terms
+
+Using the cloud API is subject to the
+[Terms of Service](https://promptready.space/legal/terms-of-service.en.md) and
+[Privacy Policy](https://promptready.space/legal/privacy-policy.en.md).
+This MIT-licensed client does not grant free unlimited conversion.
+
+## Smoke test (no account)
+
+```bash
+./scripts/smoke_stdio.sh
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

promptready_mcp-0.3.3/README.md

@@ -0,0 +1,215 @@
+# PromptReady MCP
+
+<!-- mcp-name: io.github.hydrojwh/promptready-mcp -->
+
+Official [Model Context Protocol](https://modelcontextprotocol.io/) client for
+[PromptReady](https://promptready.space) — convert PDF/CSV to Markdown from AI
+agents (Grok, Claude Code, Cursor, and other MCP hosts).
+
+**Same PromptReady account and credits as the web app.**
+
+## Features
+
+- Browser Google login (tokens stay on your machine)
+- `get_credits`, `convert_pdf`, `get_status`, `wait_and_download`
+- Saved convert defaults (engine, tables, images) — not on every call
+- Factory default: **PaddleOCR-VL**, tables on, images off
+
+## Install
+
+```bash
+pip install promptready-mcp
+```
+
+Or run it without installing:
+
+```bash
+uvx promptready-mcp
+```
+
+<details>
+<summary>From source</summary>
+
+```bash
+git clone https://github.com/hydrojwh/promptready-mcp.git
+cd promptready-mcp
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e .
+```
+
+</details>
+
+## Login (once per machine)
+
+```bash
+promptready-mcp-login
+```
+
+If you installed with `uvx`, the login command lives in the same package:
+
+```bash
+uvx --from promptready-mcp promptready-mcp-login
+```
+
+Either opens Google OAuth and saves credentials to
+`~/.config/promptready/credentials.json` (file mode `0600`). That path is in your
+home directory, so it survives `uvx` cache resets. You can also log in from inside
+an MCP host by calling the `login` tool.
+
+Supabase Auth must allow redirect:
+
+`http://127.0.0.1:18765/callback`
+
+<details>
+<summary>Email login fallback</summary>
+
+If browser-based Google login is not an option, the same command accepts email
+and password:
+
+```bash
+promptready-mcp-login --email you@x.com
+```
+
+Leave out `--password` and you will be prompted for it instead — this keeps the
+password out of your shell history.
+
+</details>
+
+Already have an access token? Set `PROMPTREADY_ACCESS_TOKEN` in the environment
+(MCP host or shell). Environment variables take precedence over the saved
+credentials file.
+
+## MCP host config
+
+### Fastest: let your AI agent install it
+
+If you are already in an MCP-capable agent, skip the JSON editing and just
+ask:
+
+> Install the PromptReady MCP server for me. The PyPI package is
+> `promptready-mcp` (stdio command `promptready-mcp`). Add it to your MCP
+> config, then I will run the `login` tool.
+
+In Claude Code the agent can use the built-in CLI:
+
+```bash
+claude mcp add promptready -- promptready-mcp
+```
+
+### Reconnect after changing config
+
+Hosts do not pick up MCP config changes mid-session. After changing the
+config, restart the host or reconnect the server — in Claude Code, open the
+`/mcp` panel and reconnect.
+
+Seeing tools in the `/mcp` panel does **not** mean the server is connected:
+the panel can list the tool catalog while the session has no live server,
+and picking a tool from that list will not run it. If tools are listed but
+calls fail, reconnect first.
+
+### Claude Code
+
+```bash
+claude mcp add promptready -- promptready-mcp
+```
+
+The default scope is `local` (this project only). Use `--scope user` to
+register it for all your projects, or `--scope project` to share the
+registration through a committed `.mcp.json`.
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (or `.cursor/mcp.json` for a single project):
+
+```json
+{
+  "mcpServers": {
+    "promptready": {
+      "command": "promptready-mcp"
+    }
+  }
+}
+```
+
+### Grok
+
+```toml
+[mcp_servers.promptready]
+command = "promptready-mcp"
+enabled = true
+tool_timeout_sec = 3600
+```
+
+### Claude Desktop / generic JSON
+
+```json
+{
+  "mcpServers": {
+    "promptready": {
+      "command": "promptready-mcp"
+    }
+  }
+}
+```
+
+No access token in config files required after login.
+
+<details>
+<summary>Host cannot find <code>promptready-mcp</code></summary>
+
+GUI hosts start servers with a narrow `PATH`, so a console script installed by
+`pip install --user` is often invisible to them — the host reports a spawn
+failure or "server disconnected" rather than a missing command.
+
+Two reliable fixes:
+
+```json
+{ "mcpServers": { "promptready": {
+  "command": "uvx", "args": ["promptready-mcp"] } } }
+```
+
+or point at the absolute path of the script:
+`/ABS/PATH/.venv/bin/promptready-mcp`.
+
+</details>
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `login` / `logout` | Browser auth / clear local credentials |
+| `get_credits` | Credit balance |
+| `get_convert_settings` / `set_convert_settings` | Saved convert defaults |
+| `convert_pdf` | Upload path → queue (optional `wait`) |
+| `get_status` | Job status |
+| `wait_and_download` | Poll + save `.md` |
+
+Downloaded names follow the web app: `{name}_PaddleOCR-VL.md` (engine label).
+
+Credits are deducted by the server when a job is queued, exactly as on the web
+app. `convert_pdf(wait=True)` can run for a long time, so give the host a high
+tool timeout.
+
+## Security
+
+- Tokens are **never** hardcoded in this repository.
+- Do **not** commit `~/.config/promptready/*` or `.env`.
+- Only use the official package linked from https://promptready.space
+- Vulnerability reports: see [SECURITY.md](SECURITY.md)
+
+## Service terms
+
+Using the cloud API is subject to the
+[Terms of Service](https://promptready.space/legal/terms-of-service.en.md) and
+[Privacy Policy](https://promptready.space/legal/privacy-policy.en.md).
+This MIT-licensed client does not grant free unlimited conversion.
+
+## Smoke test (no account)
+
+```bash
+./scripts/smoke_stdio.sh
+```
+
+## License
+
+MIT — see [LICENSE](LICENSE).

promptready_mcp-0.3.3/promptready_mcp/__init__.py

@@ -0,0 +1,7 @@
+"""PromptReady MCP server (stdio).
+
+P0: get_credits
+P1: convert_pdf, get_status, wait_and_download
+"""
+
+__version__ = "0.3.3"

promptready_mcp-0.3.3/promptready_mcp/client.py

@@ -0,0 +1,166 @@
+"""Thin async HTTP client for the PromptReady backend API.
+
+Source of truth:
+  - app/api/endpoints/users.py  GET /api/v1/users/credits
+  - app/api/endpoints/convert.py  POST /api/v1/convert, GET /api/v1/convert/status
+  - app/api/endpoints/auth.py  POST /api/v1/auth/refresh
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+import httpx
+
+API_PREFIX = "/api/v1"
+DEFAULT_TIMEOUT = 60.0
+CONVERT_TIMEOUT = 300.0  # upload + queue only; OCR runs async
+
+
+class PromptReadyAPIError(Exception):
+    """API or transport failure with a user-facing message."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status_code: Optional[int] = None,
+        body: Optional[str] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status_code = status_code
+        self.body = body
+
+
+def _url(base_url: str, path: str) -> str:
+    return f"{base_url.rstrip('/')}{API_PREFIX}{path}"
+
+
+def _auth_headers(access_token: str) -> Dict[str, str]:
+    return {"Authorization": f"Bearer {access_token}"}
+
+
+async def fetch_credits(
+    base_url: str, access_token: str, *, timeout: float = DEFAULT_TIMEOUT
+) -> Dict[str, Any]:
+    """GET /users/credits → {credit_balance, email}."""
+    async with httpx.AsyncClient(timeout=timeout) as http:
+        resp = await http.get(
+            _url(base_url, "/users/credits"),
+            headers=_auth_headers(access_token),
+        )
+        if resp.status_code >= 400:
+            raise PromptReadyAPIError(
+                f"credits failed HTTP {resp.status_code}",
+                status_code=resp.status_code,
+                body=resp.text[:500],
+            )
+        return resp.json()
+
+
+async def refresh_access_token(
+    base_url: str, refresh_token: str, *, timeout: float = DEFAULT_TIMEOUT
+) -> Dict[str, str]:
+    """POST /auth/refresh → {access_token, refresh_token}."""
+    async with httpx.AsyncClient(timeout=timeout) as http:
+        resp = await http.post(
+            _url(base_url, "/auth/refresh"),
+            json={"refresh_token": refresh_token},
+        )
+        if resp.status_code >= 400:
+            raise PromptReadyAPIError(
+                f"token refresh failed HTTP {resp.status_code}",
+                status_code=resp.status_code,
+                body=resp.text[:500],
+            )
+        data = resp.json()
+        if not data.get("success") or not data.get("access_token"):
+            raise PromptReadyAPIError(
+                data.get("message") or "token refresh returned no access_token",
+                body=str(data)[:500],
+            )
+        out: Dict[str, str] = {"access_token": data["access_token"]}
+        if data.get("refresh_token"):
+            out["refresh_token"] = data["refresh_token"]
+        return out
+
+
+async def convert_pdf(
+    base_url: str,
+    access_token: str,
+    file_path: Path,
+    *,
+    timeout: float = CONVERT_TIMEOUT,
+    params: Optional[Dict[str, str]] = None,
+) -> Dict[str, Any]:
+    """POST /convert multipart — queues PDF and returns ConvertResponse JSON.
+
+    Query params come from user_settings (saved defaults), not per-call UI.
+    """
+    from .user_settings import settings_to_api_params
+
+    path = Path(file_path).expanduser().resolve()
+    if not path.is_file():
+        raise PromptReadyAPIError(f"file not found: {path}")
+    if path.suffix.lower() not in (".pdf", ".csv"):
+        raise PromptReadyAPIError("only .pdf or .csv files are supported")
+
+    query = params if params is not None else settings_to_api_params()
+    data = path.read_bytes()
+    if not data:
+        raise PromptReadyAPIError("file is empty")
+
+    files = {
+        "file": (path.name, data, "application/pdf" if path.suffix.lower() == ".pdf" else "text/csv"),
+    }
+    async with httpx.AsyncClient(timeout=timeout) as http:
+        resp = await http.post(
+            _url(base_url, "/convert"),
+            headers=_auth_headers(access_token),
+            params=query,
+            files=files,
+        )
+        if resp.status_code >= 400:
+            raise PromptReadyAPIError(
+                f"convert failed HTTP {resp.status_code}: {resp.text[:300]}",
+                status_code=resp.status_code,
+                body=resp.text[:500],
+            )
+        return resp.json()
+
+
+async def get_conversion_status(
+    base_url: str, access_token: str, *, timeout: float = DEFAULT_TIMEOUT
+) -> Dict[str, Any]:
+    """GET /convert/status for the authenticated user's session."""
+    async with httpx.AsyncClient(timeout=timeout) as http:
+        resp = await http.get(
+            _url(base_url, "/convert/status"),
+            headers=_auth_headers(access_token),
+        )
+        if resp.status_code >= 400:
+            raise PromptReadyAPIError(
+                f"status failed HTTP {resp.status_code}",
+                status_code=resp.status_code,
+                body=resp.text[:500],
+            )
+        return resp.json()
+
+
+async def download_url_to_path(
+    url: str, dest: Path, *, timeout: float = CONVERT_TIMEOUT
+) -> Path:
+    """Download markdown_url (presigned) to dest path."""
+    dest = Path(dest).expanduser().resolve()
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    async with httpx.AsyncClient(timeout=timeout, follow_redirects=True) as http:
+        resp = await http.get(url)
+        if resp.status_code >= 400:
+            raise PromptReadyAPIError(
+                f"download failed HTTP {resp.status_code}",
+                status_code=resp.status_code,
+                body=resp.text[:300],
+            )
+        dest.write_bytes(resp.content)
+    return dest