pdf-agent-kit 0.1.0__tar.gz

pdf_agent_kit-0.1.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: pdf-agent-kit
+Version: 0.1.0
+Summary: Local MCP + CLI thin adapter for pdf_editor_api.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.0; extra == "dev"
+
+# pdf-agent-kit
+
+`pdf-agent-kit` is a local adapter package for the pdf-agent-kit cloud API.
+
+- MCP entrypoint: `pdf-agent-kit` (stdio, one tool: `extract_pdf_to_json`)
+- CLI entrypoint: `pdf-edit`
+- Python import: `from pdf_agent_kit import extract`
+
+The package is thin by design: it reads a local PDF file, attaches `PDF_EDITOR_API_KEY`, and forwards to the cloud API.
+
+## Install
+
+```bash
+pip install pdf-agent-kit
+```
+
+or:
+
+```bash
+uvx pdf-agent-kit
+```
+
+## Environment
+
+```bash
+export PDF_EDITOR_API_KEY="sk_live_..."
+```
+
+If missing, commands fail with:
+
+```text
+PDF_EDITOR_API_KEY not set. Get your key at https://pdfagentkit.com/dashboard
+```
+
+## MCP Tool
+
+Tool name: `extract_pdf_to_json`
+
+Parameters:
+
+- `file_path` (required)
+- `pages` (optional, default `all`)
+- `filename` (optional override)
+
+Returns API JSON: metadata + per-page text + usage stats.
+
+## CLI
+
+```bash
+pdf-edit extract /path/to/file.pdf
+pdf-edit extract /path/to/file.pdf --pages "1-5"
+pdf-edit status
+pdf-edit setup
+```
+
+CLI contract:
+
+- success JSON goes to stdout
+- errors go to stderr
+- exit code `0` success, `1` user error, `2` server/network error
+
+## Setup
+
+`pdf-edit setup`:
+
+1. Reads `PDF_EDITOR_API_KEY` (or prompts once if missing)
+2. Verifies key with `/v1/account/status`
+3. Patches MCP config for:
+   - Claude Desktop
+   - Cursor
+   - VS Code
+4. Tries to add Claude Code integration via `claude mcp add-json`
+
+Injected server entry:
+
+```json
+{
+  "mcpServers": {
+    "pdf-agent-kit": {
+      "command": "uvx",
+      "args": ["pdf-agent-kit"],
+      "env": {
+        "PDF_EDITOR_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest -q
+```

pdf_agent_kit-0.1.0/README.md

@@ -0,0 +1,95 @@
+# pdf-agent-kit
+
+`pdf-agent-kit` is a local adapter package for the pdf-agent-kit cloud API.
+
+- MCP entrypoint: `pdf-agent-kit` (stdio, one tool: `extract_pdf_to_json`)
+- CLI entrypoint: `pdf-edit`
+- Python import: `from pdf_agent_kit import extract`
+
+The package is thin by design: it reads a local PDF file, attaches `PDF_EDITOR_API_KEY`, and forwards to the cloud API.
+
+## Install
+
+```bash
+pip install pdf-agent-kit
+```
+
+or:
+
+```bash
+uvx pdf-agent-kit
+```
+
+## Environment
+
+```bash
+export PDF_EDITOR_API_KEY="sk_live_..."
+```
+
+If missing, commands fail with:
+
+```text
+PDF_EDITOR_API_KEY not set. Get your key at https://pdfagentkit.com/dashboard
+```
+
+## MCP Tool
+
+Tool name: `extract_pdf_to_json`
+
+Parameters:
+
+- `file_path` (required)
+- `pages` (optional, default `all`)
+- `filename` (optional override)
+
+Returns API JSON: metadata + per-page text + usage stats.
+
+## CLI
+
+```bash
+pdf-edit extract /path/to/file.pdf
+pdf-edit extract /path/to/file.pdf --pages "1-5"
+pdf-edit status
+pdf-edit setup
+```
+
+CLI contract:
+
+- success JSON goes to stdout
+- errors go to stderr
+- exit code `0` success, `1` user error, `2` server/network error
+
+## Setup
+
+`pdf-edit setup`:
+
+1. Reads `PDF_EDITOR_API_KEY` (or prompts once if missing)
+2. Verifies key with `/v1/account/status`
+3. Patches MCP config for:
+   - Claude Desktop
+   - Cursor
+   - VS Code
+4. Tries to add Claude Code integration via `claude mcp add-json`
+
+Injected server entry:
+
+```json
+{
+  "mcpServers": {
+    "pdf-agent-kit": {
+      "command": "uvx",
+      "args": ["pdf-agent-kit"],
+      "env": {
+        "PDF_EDITOR_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest -q
+```

pdf_agent_kit-0.1.0/pyproject.toml

@@ -0,0 +1,32 @@
+[project]
+name = "pdf-agent-kit"
+version = "0.1.0"
+description = "Local MCP + CLI thin adapter for pdf_editor_api."
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "fastmcp>=2.0.0",
+    "httpx>=0.28.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9",
+]
+
+[project.scripts]
+pdf-agent-kit = "pdf_agent_kit.__main__:main"
+pdf-edit = "pdf_agent_kit.cli:main"
+
+[build-system]
+requires = ["setuptools>=75", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.package-dir]
+"" = "src"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

pdf_agent_kit-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

pdf_agent_kit-0.1.0/src/pdf_agent_kit/__init__.py

@@ -0,0 +1,9 @@
+"""pdf-agent-kit package."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.1.0"
+
+from pdf_agent_kit.server import extract
+
+__all__.append("extract")

pdf_agent_kit-0.1.0/src/pdf_agent_kit/__main__.py

@@ -0,0 +1,11 @@
+from __future__ import annotations
+
+from pdf_agent_kit.server import main as run_stdio_server
+
+
+def main() -> None:
+    run_stdio_server()
+
+
+if __name__ == "__main__":
+    main()

pdf_agent_kit-0.1.0/src/pdf_agent_kit/cli.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import os
+from pathlib import Path
+
+from pdf_agent_kit.client import PdfAgentKitClient, PdfAgentKitError
+from pdf_agent_kit.config import APP_NAME
+from pdf_agent_kit.server import _read_pdf_file
+from pdf_agent_kit.setup_cmd import prompt_for_api_key_if_missing, run_setup
+
+EXIT_USER_ERROR = 1
+EXIT_SERVER_ERROR = 2
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pdf-edit", description="CLI adapter for pdf-agent-kit.")
+    parser.add_argument("--version", action="version", version=APP_NAME)
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    extract_parser = subparsers.add_parser("extract", help="Extract PDF into JSON.")
+    extract_parser.add_argument("file", help="Path to PDF file")
+    extract_parser.add_argument("--pages", default="all", help="Pages filter, e.g. 1-5 or 1,3,7")
+    extract_parser.add_argument("--filename", help="Optional filename override sent to API")
+
+    subparsers.add_parser("status", help="Validate API key and show remaining credits.")
+    subparsers.add_parser("setup", help="Auto-configure MCP clients.")
+    return parser
+
+
+def run_extract(args: argparse.Namespace) -> int:
+    file_path = str(Path(args.file).expanduser())
+    try:
+        api_key = PdfAgentKitClient.require_api_key()
+        inferred_filename, content = _read_pdf_file(file_path)
+        payload = asyncio.run(
+            PdfAgentKitClient.from_env().extract_pdf(
+                api_key=api_key,
+                filename=(args.filename or inferred_filename).strip() or inferred_filename,
+                content=content,
+                pages=args.pages,
+            )
+        )
+    except PdfAgentKitError as exc:
+        print(str(exc), file=os.sys.stderr)
+        return EXIT_SERVER_ERROR if exc.is_server_error else EXIT_USER_ERROR
+
+    print(json.dumps(payload, ensure_ascii=False))
+    return 0
+
+
+def run_status() -> int:
+    try:
+        api_key = PdfAgentKitClient.require_api_key()
+        payload = asyncio.run(PdfAgentKitClient.from_env().account_status(api_key=api_key))
+    except PdfAgentKitError as exc:
+        print(str(exc), file=os.sys.stderr)
+        return EXIT_SERVER_ERROR if exc.is_server_error else EXIT_USER_ERROR
+
+    print(json.dumps(payload, ensure_ascii=False))
+    return 0
+
+
+def run_setup_command() -> int:
+    try:
+        api_key = prompt_for_api_key_if_missing()
+        payload = asyncio.run(PdfAgentKitClient.from_env().account_status(api_key=api_key))
+        if not payload.get("success"):
+            print("Invalid API key. Generate a new one at https://pdfagentkit.com/dashboard", file=os.sys.stderr)
+            return EXIT_USER_ERROR
+        result = run_setup(api_key)
+    except ValueError as exc:
+        print(str(exc), file=os.sys.stderr)
+        return EXIT_USER_ERROR
+    except PdfAgentKitError as exc:
+        print(str(exc), file=os.sys.stderr)
+        return EXIT_SERVER_ERROR if exc.is_server_error else EXIT_USER_ERROR
+
+    output = {
+        "success": True,
+        "configured": result.configured_targets,
+        "warnings": result.warnings,
+    }
+    print(json.dumps(output, ensure_ascii=False))
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "extract":
+        return run_extract(args)
+    if args.command == "status":
+        return run_status()
+    if args.command == "setup":
+        return run_setup_command()
+    parser.print_help()
+    return EXIT_USER_ERROR

pdf_agent_kit-0.1.0/src/pdf_agent_kit/client.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from pdf_agent_kit.config import API_KEY_ENV_VAR, DASHBOARD_URL, DEFAULT_API_BASE_URL
+
+EXTRACT_ENDPOINT = "/v1/extract/json"
+STATUS_ENDPOINT = "/v1/account/status"
+
+
+class PdfAgentKitError(Exception):
+    def __init__(self, message: str, *, is_server_error: bool = False) -> None:
+        super().__init__(message)
+        self.is_server_error = is_server_error
+
+
+@dataclass(slots=True)
+class PdfAgentKitClient:
+    base_url: str = DEFAULT_API_BASE_URL
+    timeout_seconds: float = 120.0
+
+    @classmethod
+    def from_env(cls) -> "PdfAgentKitClient":
+        return cls(base_url=os.getenv("PDF_EDITOR_API_BASE_URL", DEFAULT_API_BASE_URL).rstrip("/"))
+
+    @staticmethod
+    def require_api_key() -> str:
+        value = os.getenv(API_KEY_ENV_VAR, "").strip()
+        if not value:
+            raise PdfAgentKitError(f"{API_KEY_ENV_VAR} not set. Get your key at {DASHBOARD_URL}")
+        return value
+
+    async def extract_pdf(self, *, api_key: str, filename: str, content: bytes, pages: str = "all") -> dict[str, Any]:
+        timeout = httpx.Timeout(self.timeout_seconds, connect=10.0)
+        headers = {"Authorization": f"Bearer {api_key}"}
+        files = {"pdf_file": (filename, content, "application/pdf")}
+        data = {"pages": pages}
+
+        try:
+            async with httpx.AsyncClient(base_url=self.base_url, timeout=timeout) as client:
+                response = await client.post(EXTRACT_ENDPOINT, headers=headers, files=files, data=data)
+        except httpx.TimeoutException as exc:
+            raise PdfAgentKitError("Server error. Try again in a moment.", is_server_error=True) from exc
+        except httpx.RequestError as exc:
+            raise PdfAgentKitError("Cannot reach PDF processing server. Check internet connection.", is_server_error=True) from exc
+
+        return self._handle_response(response)
+
+    async def account_status(self, *, api_key: str) -> dict[str, Any]:
+        timeout = httpx.Timeout(self.timeout_seconds, connect=10.0)
+        headers = {"Authorization": f"Bearer {api_key}"}
+        try:
+            async with httpx.AsyncClient(base_url=self.base_url, timeout=timeout) as client:
+                response = await client.get(STATUS_ENDPOINT, headers=headers)
+        except httpx.TimeoutException as exc:
+            raise PdfAgentKitError("Server error. Try again in a moment.", is_server_error=True) from exc
+        except httpx.RequestError as exc:
+            raise PdfAgentKitError("Cannot reach PDF processing server. Check internet connection.", is_server_error=True) from exc
+
+        return self._handle_response(response)
+
+    def _handle_response(self, response: httpx.Response) -> dict[str, Any]:
+        if response.status_code == 401:
+            raise PdfAgentKitError(f"Invalid or expired API key. Generate a new one at {DASHBOARD_URL}")
+        if response.status_code == 402:
+            message = _extract_error_message(response) or "Insufficient credits. Top up at https://pdfagentkit.com/dashboard"
+            raise PdfAgentKitError(message)
+        if response.status_code == 429:
+            raise PdfAgentKitError("Rate limit exceeded. Retry shortly.")
+        if response.status_code >= 500:
+            raise PdfAgentKitError("Server error. Try again in a moment.", is_server_error=True)
+        if response.status_code >= 400:
+            message = _extract_error_message(response) or f"Request failed ({response.status_code})."
+            raise PdfAgentKitError(message)
+
+        try:
+            payload = response.json()
+        except ValueError as exc:
+            raise PdfAgentKitError("Server error. Try again in a moment.", is_server_error=True) from exc
+
+        if not isinstance(payload, dict):
+            raise PdfAgentKitError("Server error. Try again in a moment.", is_server_error=True)
+        return payload
+
+
+def _extract_error_message(response: httpx.Response) -> str | None:
+    try:
+        payload = response.json()
+    except ValueError:
+        return response.text.strip() or None
+
+    if isinstance(payload, dict):
+        detail = payload.get("detail")
+        if isinstance(detail, dict):
+            error = detail.get("error")
+            if isinstance(error, dict):
+                message = error.get("message")
+                if isinstance(message, str) and message.strip():
+                    return message.strip()
+        error = payload.get("error")
+        if isinstance(error, dict):
+            message = error.get("message")
+            if isinstance(message, str) and message.strip():
+                return message.strip()
+        message = payload.get("message")
+        if isinstance(message, str) and message.strip():
+            return message.strip()
+    return None

pdf_agent_kit-0.1.0/src/pdf_agent_kit/config.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import os
+import platform
+from pathlib import Path
+
+APP_NAME = "pdf-agent-kit"
+CLAUDE_SERVER_NAME = "pdf-agent-kit"
+DEFAULT_API_BASE_URL = "https://pdf-editor-api-production.up.railway.app"
+API_KEY_ENV_VAR = "PDF_EDITOR_API_KEY"
+DASHBOARD_URL = "https://pdfagentkit.com/dashboard"
+
+
+def _platform_config_root() -> Path:
+    if platform.system() == "Darwin":
+        return (Path.home() / "Library" / "Application Support").resolve()
+    if os.name == "nt":
+        return Path(os.getenv("APPDATA", str(Path.home() / "AppData" / "Roaming"))).resolve()
+    return Path(os.getenv("XDG_CONFIG_HOME", str(Path.home() / ".config"))).resolve()
+
+
+def get_claude_config_path() -> Path:
+    if platform.system() == "Darwin":
+        return (Path.home() / "Library" / "Application Support" / "Claude" / "claude_desktop_config.json").resolve()
+    if os.name == "nt":
+        return (
+            Path(os.getenv("APPDATA", str(Path.home() / "AppData" / "Roaming")))
+            / "Claude"
+            / "claude_desktop_config.json"
+        ).resolve()
+
+    return (Path.home() / ".config" / "Claude" / "claude_desktop_config.json").resolve()
+
+
+def get_cursor_config_path() -> Path:
+    if os.name == "nt":
+        return (_platform_config_root() / "Cursor" / "mcp.json").resolve()
+    return (Path.home() / ".cursor" / "mcp.json").resolve()
+
+
+def get_vscode_config_path() -> Path:
+    if os.name == "nt":
+        return (_platform_config_root() / "Code" / "User" / "mcp.json").resolve()
+    return (Path.home() / ".vscode" / "mcp.json").resolve()

pdf_agent_kit-0.1.0/src/pdf_agent_kit/server.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+import asyncio
+import logging
+from pathlib import Path
+from typing import Any
+
+from fastmcp import FastMCP
+
+from pdf_agent_kit.client import PdfAgentKitClient, PdfAgentKitError
+
+logger = logging.getLogger(__name__)
+
+mcp = FastMCP(
+    name="pdf-agent-kit",
+    instructions=(
+        "Extract structured text from a PDF file. Returns JSON with per-page text content, document metadata "
+        "(page count, title, author, scanned detection), and usage stats. Use for invoice processing, contract "
+        "analysis, financial statements, resume parsing, and report ingestion. Each page uses 1 credit. Use "
+        "the pages parameter (for example '1-5' or '1,3,7') to extract only what you need. Requires "
+        "PDF_EDITOR_API_KEY environment variable."
+    ),
+)
+
+
+def _read_pdf_file(file_path: str) -> tuple[str, bytes]:
+    if not file_path.strip():
+        raise PdfAgentKitError("File path is required.")
+
+    path = Path(file_path).expanduser()
+    if not path.exists():
+        raise PdfAgentKitError(f"File not found: {path}")
+    if not path.is_file():
+        raise PdfAgentKitError(f"File not found: {path}")
+
+    try:
+        content = path.read_bytes()
+    except OSError as exc:
+        raise PdfAgentKitError(f"File not found: {path}") from exc
+
+    if not content.startswith(b"%PDF"):
+        raise PdfAgentKitError(f"Not a valid PDF: {path}")
+
+    return path.name, content
+
+
+def _tool_error(message: str) -> dict[str, Any]:
+    return {"success": False, "error": message}
+
+
+@mcp.tool
+async def extract_pdf_to_json(file_path: str, pages: str = "all", filename: str | None = None) -> dict[str, Any]:
+    """Proxy a local PDF file to the cloud pdf-editor-api extraction endpoint."""
+
+    try:
+        api_key = PdfAgentKitClient.require_api_key()
+        inferred_filename, content = _read_pdf_file(file_path)
+        client = PdfAgentKitClient.from_env()
+        return await client.extract_pdf(
+            api_key=api_key,
+            filename=(filename or inferred_filename).strip() or inferred_filename,
+            content=content,
+            pages=pages,
+        )
+    except PdfAgentKitError as exc:
+        return _tool_error(str(exc))
+    except Exception:
+        logger.exception("Unexpected error while extracting PDF through MCP.")
+        return _tool_error("Server error. Try again in a moment.")
+
+
+def extract(file_path: str, *, pages: str = "all", filename: str | None = None) -> dict[str, Any]:
+    return asyncio.run(extract_pdf_to_json(file_path=file_path, pages=pages, filename=filename))
+
+
+def main() -> None:
+    mcp.run(transport="stdio", show_banner=False)

pdf_agent_kit-0.1.0/src/pdf_agent_kit/setup_cmd.py

@@ -0,0 +1,112 @@
+from __future__ import annotations
+
+import json
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from pdf_agent_kit.config import (
+    API_KEY_ENV_VAR,
+    APP_NAME,
+    CLAUDE_SERVER_NAME,
+    get_claude_config_path,
+    get_cursor_config_path,
+    get_vscode_config_path,
+)
+
+
+@dataclass(slots=True)
+class SetupResult:
+    configured_targets: list[str]
+    warnings: list[str]
+
+
+def build_server_entry(api_key: str) -> dict[str, Any]:
+    return {
+        "command": "uvx",
+        "args": [APP_NAME],
+        "env": {API_KEY_ENV_VAR: api_key},
+    }
+
+
+def merge_mcp_config(existing: dict[str, Any] | None, server_name: str, entry: dict[str, Any]) -> dict[str, Any]:
+    payload: dict[str, Any] = dict(existing or {})
+    mcp_servers = payload.get("mcpServers")
+    if not isinstance(mcp_servers, dict):
+        mcp_servers = {}
+    else:
+        mcp_servers = dict(mcp_servers)
+    mcp_servers[server_name] = entry
+    payload["mcpServers"] = mcp_servers
+    return payload
+
+
+def run_setup(api_key: str) -> SetupResult:
+    warnings: list[str] = []
+    configured: list[str] = []
+
+    entry = build_server_entry(api_key)
+    targets = {
+        "Claude Desktop": get_claude_config_path(),
+        "Cursor": get_cursor_config_path(),
+        "VS Code": get_vscode_config_path(),
+    }
+
+    for label, path in targets.items():
+        try:
+            write_mcp_config(path, CLAUDE_SERVER_NAME, entry)
+            configured.append(f"{label}: {path}")
+        except Exception as exc:  # noqa: BLE001
+            warnings.append(f"{label}: failed to update {path} ({exc})")
+
+    if shutil.which("claude"):
+        try:
+            payload = json.dumps(entry)
+            subprocess.run(
+                ["claude", "mcp", "add-json", CLAUDE_SERVER_NAME, payload],
+                check=True,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+            configured.append("Claude Code: added via `claude mcp add-json`")
+        except subprocess.CalledProcessError as exc:
+            warnings.append(f"Claude Code: failed to add server ({exc.stderr.strip() or exc.stdout.strip()})")
+    else:
+        warnings.append("Claude Code: `claude` CLI not found, skipped.")
+
+    return SetupResult(configured_targets=configured, warnings=warnings)
+
+
+def prompt_for_api_key_if_missing() -> str:
+    import os
+
+    api_key = os.getenv(API_KEY_ENV_VAR, "").strip()
+    if api_key:
+        return api_key
+
+    sys.stdout.write(f"{API_KEY_ENV_VAR} is not set. Enter your API key: ")
+    sys.stdout.flush()
+    value = sys.stdin.readline().strip()
+    if not value:
+        raise ValueError(f"{API_KEY_ENV_VAR} not set. Get your key at https://pdfagentkit.com/dashboard")
+    return value
+
+
+def write_mcp_config(path: Path, server_name: str, entry: dict[str, Any]) -> None:
+    existing = load_json(path)
+    merged = merge_mcp_config(existing, server_name, entry)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(merged, indent=2), encoding="utf-8")
+
+
+def load_json(path: Path) -> dict[str, Any] | None:
+    if not path.exists():
+        return None
+    payload = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(payload, dict):
+        raise ValueError(f"{path} must contain a JSON object.")
+    return payload

pdf_agent_kit-0.1.0/src/pdf_agent_kit.egg-info/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.4
+Name: pdf-agent-kit
+Version: 0.1.0
+Summary: Local MCP + CLI thin adapter for pdf_editor_api.
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.28.0
+Provides-Extra: dev
+Requires-Dist: pytest<9,>=8.0; extra == "dev"
+
+# pdf-agent-kit
+
+`pdf-agent-kit` is a local adapter package for the pdf-agent-kit cloud API.
+
+- MCP entrypoint: `pdf-agent-kit` (stdio, one tool: `extract_pdf_to_json`)
+- CLI entrypoint: `pdf-edit`
+- Python import: `from pdf_agent_kit import extract`
+
+The package is thin by design: it reads a local PDF file, attaches `PDF_EDITOR_API_KEY`, and forwards to the cloud API.
+
+## Install
+
+```bash
+pip install pdf-agent-kit
+```
+
+or:
+
+```bash
+uvx pdf-agent-kit
+```
+
+## Environment
+
+```bash
+export PDF_EDITOR_API_KEY="sk_live_..."
+```
+
+If missing, commands fail with:
+
+```text
+PDF_EDITOR_API_KEY not set. Get your key at https://pdfagentkit.com/dashboard
+```
+
+## MCP Tool
+
+Tool name: `extract_pdf_to_json`
+
+Parameters:
+
+- `file_path` (required)
+- `pages` (optional, default `all`)
+- `filename` (optional override)
+
+Returns API JSON: metadata + per-page text + usage stats.
+
+## CLI
+
+```bash
+pdf-edit extract /path/to/file.pdf
+pdf-edit extract /path/to/file.pdf --pages "1-5"
+pdf-edit status
+pdf-edit setup
+```
+
+CLI contract:
+
+- success JSON goes to stdout
+- errors go to stderr
+- exit code `0` success, `1` user error, `2` server/network error
+
+## Setup
+
+`pdf-edit setup`:
+
+1. Reads `PDF_EDITOR_API_KEY` (or prompts once if missing)
+2. Verifies key with `/v1/account/status`
+3. Patches MCP config for:
+   - Claude Desktop
+   - Cursor
+   - VS Code
+4. Tries to add Claude Code integration via `claude mcp add-json`
+
+Injected server entry:
+
+```json
+{
+  "mcpServers": {
+    "pdf-agent-kit": {
+      "command": "uvx",
+      "args": ["pdf-agent-kit"],
+      "env": {
+        "PDF_EDITOR_API_KEY": "sk_live_..."
+      }
+    }
+  }
+}
+```
+
+## Development
+
+```bash
+pip install -e .[dev]
+pytest -q
+```

pdf_agent_kit-0.1.0/src/pdf_agent_kit.egg-info/SOURCES.txt

@@ -0,0 +1,18 @@
+README.md
+pyproject.toml
+src/pdf_agent_kit/__init__.py
+src/pdf_agent_kit/__main__.py
+src/pdf_agent_kit/cli.py
+src/pdf_agent_kit/client.py
+src/pdf_agent_kit/config.py
+src/pdf_agent_kit/server.py
+src/pdf_agent_kit/setup_cmd.py
+src/pdf_agent_kit.egg-info/PKG-INFO
+src/pdf_agent_kit.egg-info/SOURCES.txt
+src/pdf_agent_kit.egg-info/dependency_links.txt
+src/pdf_agent_kit.egg-info/entry_points.txt
+src/pdf_agent_kit.egg-info/requires.txt
+src/pdf_agent_kit.egg-info/top_level.txt
+tests/test_cli.py
+tests/test_server.py
+tests/test_setup_cmd.py

pdf_agent_kit-0.1.0/src/pdf_agent_kit.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

pdf_agent_kit-0.1.0/src/pdf_agent_kit.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pdf-agent-kit = pdf_agent_kit.__main__:main
+pdf-edit = pdf_agent_kit.cli:main

pdf_agent_kit-0.1.0/src/pdf_agent_kit.egg-info/requires.txt

@@ -0,0 +1,5 @@
+fastmcp>=2.0.0
+httpx>=0.28.0
+
+[dev]
+pytest<9,>=8.0

pdf_agent_kit-0.1.0/src/pdf_agent_kit.egg-info/top_level.txt

@@ -0,0 +1 @@
+pdf_agent_kit

pdf_agent_kit-0.1.0/tests/test_cli.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pdf_agent_kit import cli
+from pdf_agent_kit.client import PdfAgentKitError
+
+
+def test_cli_extract_success(monkeypatch, tmp_path: Path, capsys) -> None:
+    pdf_path = tmp_path / "sample.pdf"
+    pdf_path.write_bytes(b"%PDF-1.7\nhello")
+
+    monkeypatch.setattr("pdf_agent_kit.cli.PdfAgentKitClient.require_api_key", lambda: "sk_live_123")
+    monkeypatch.setattr("pdf_agent_kit.cli._read_pdf_file", lambda path: ("sample.pdf", b"%PDF-1.7\nhello"))
+
+    async def fake_extract_pdf(*, api_key: str, filename: str, content: bytes, pages: str):
+        return {"success": True, "data": {"metadata": {"page_count": 1}}}
+
+    class FakeClient:
+        async def extract_pdf(self, **kwargs):
+            return await fake_extract_pdf(**kwargs)
+
+    monkeypatch.setattr("pdf_agent_kit.cli.PdfAgentKitClient.from_env", lambda: FakeClient())
+
+    code = cli.main(["extract", str(pdf_path)])
+    captured = capsys.readouterr()
+    assert code == 0
+    assert "\"success\": true" in captured.out.lower()
+
+
+def test_cli_extract_server_error_returns_exit_2(monkeypatch, tmp_path: Path, capsys) -> None:
+    pdf_path = tmp_path / "sample.pdf"
+    pdf_path.write_bytes(b"%PDF-1.7\nhello")
+    monkeypatch.setattr("pdf_agent_kit.cli.PdfAgentKitClient.require_api_key", lambda: "sk_live_123")
+    monkeypatch.setattr("pdf_agent_kit.cli._read_pdf_file", lambda path: ("sample.pdf", b"%PDF-1.7\nhello"))
+
+    class FakeClient:
+        async def extract_pdf(self, **kwargs):
+            raise PdfAgentKitError("Server error. Try again in a moment.", is_server_error=True)
+
+    monkeypatch.setattr("pdf_agent_kit.cli.PdfAgentKitClient.from_env", lambda: FakeClient())
+
+    code = cli.main(["extract", str(pdf_path)])
+    captured = capsys.readouterr()
+    assert code == 2
+    assert "Server error. Try again in a moment." in captured.err

pdf_agent_kit-0.1.0/tests/test_server.py

@@ -0,0 +1,61 @@
+from __future__ import annotations
+
+import asyncio
+from pathlib import Path
+
+from pdf_agent_kit.client import PdfAgentKitClient
+from pdf_agent_kit.server import extract_pdf_to_json
+
+
+def test_extract_pdf_to_json_reads_local_file_and_returns_payload(monkeypatch, tmp_path: Path) -> None:
+    pdf_path = tmp_path / "sample.pdf"
+    pdf_path.write_bytes(b"%PDF-1.7\nhello")
+    monkeypatch.setenv("PDF_EDITOR_API_KEY", "sk_live_123")
+
+    recorded: dict[str, object] = {}
+
+    async def fake_extract(
+        self: PdfAgentKitClient,
+        *,
+        api_key: str,
+        filename: str,
+        content: bytes,
+        pages: str = "all",
+    ) -> dict:
+        recorded["api_key"] = api_key
+        recorded["filename"] = filename
+        recorded["content"] = content
+        recorded["pages"] = pages
+        return {"success": True, "data": {"metadata": {"page_count": 1}}}
+
+    monkeypatch.setattr(PdfAgentKitClient, "extract_pdf", fake_extract)
+
+    result = asyncio.run(extract_pdf_to_json(file_path=str(pdf_path), pages="1"))
+
+    assert result["success"] is True
+    assert recorded["api_key"] == "sk_live_123"
+    assert recorded["filename"] == "sample.pdf"
+    assert recorded["content"] == b"%PDF-1.7\nhello"
+    assert recorded["pages"] == "1"
+
+
+def test_extract_pdf_to_json_requires_api_key(monkeypatch, tmp_path: Path) -> None:
+    pdf_path = tmp_path / "sample.pdf"
+    pdf_path.write_bytes(b"%PDF-1.7\nhello")
+    monkeypatch.delenv("PDF_EDITOR_API_KEY", raising=False)
+
+    result = asyncio.run(extract_pdf_to_json(file_path=str(pdf_path)))
+
+    assert result["success"] is False
+    assert result["error"] == "PDF_EDITOR_API_KEY not set. Get your key at https://pdfagentkit.com/dashboard"
+
+
+def test_extract_pdf_to_json_rejects_non_pdf_content(monkeypatch, tmp_path: Path) -> None:
+    pdf_path = tmp_path / "bad.pdf"
+    pdf_path.write_bytes(b"not-a-pdf")
+    monkeypatch.setenv("PDF_EDITOR_API_KEY", "sk_live_123")
+
+    result = asyncio.run(extract_pdf_to_json(file_path=str(pdf_path)))
+
+    assert result["success"] is False
+    assert "Not a valid PDF" in result["error"]

pdf_agent_kit-0.1.0/tests/test_setup_cmd.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pdf_agent_kit.setup_cmd import build_server_entry, merge_mcp_config, write_mcp_config
+
+
+def test_merge_mcp_config_preserves_existing_fields(tmp_path: Path) -> None:
+    entry = build_server_entry("sk_live_abc")
+    merged = merge_mcp_config(
+        {"preferences": {"mode": "task"}, "mcpServers": {"existing": {"command": "node"}}},
+        "pdf-agent-kit",
+        entry,
+    )
+
+    assert merged["preferences"] == {"mode": "task"}
+    assert merged["mcpServers"]["existing"]["command"] == "node"
+    assert merged["mcpServers"]["pdf-agent-kit"]["command"] == "uvx"
+    assert merged["mcpServers"]["pdf-agent-kit"]["args"] == ["pdf-agent-kit"]
+
+
+def test_write_mcp_config_creates_file(tmp_path: Path) -> None:
+    path = tmp_path / "claude_desktop_config.json"
+    write_mcp_config(path, "pdf-agent-kit", build_server_entry("sk_live_abc"))
+
+    content = path.read_text(encoding="utf-8")
+    assert "\"pdf-agent-kit\"" in content
+    assert "\"PDF_EDITOR_API_KEY\"" in content