protocolbox 0.1.0__py3-none-any.whl

protocolbox/__init__.py

@@ -0,0 +1,3 @@
+"""ProtocolBox — The Standard Library for the Agentic Web."""
+
+__version__ = "0.1.0"

protocolbox/cli.py

@@ -0,0 +1,114 @@
+"""ProtocolBox CLI — auto-setup for AI Agent environments."""
+
+import os
+from pathlib import Path
+
+import typer
+
+app = typer.Typer(
+    name="protocolbox",
+    help="ProtocolBox — The Standard Library for the Agentic Web.",
+    no_args_is_help=True,
+)
+
+SKILL_TEMPLATE = """---
+name: protocolbox
+description: >
+  Standard Library of verified tools for AI Agents.
+  Tools: scrape(url), heal_json(str), generate_invoice(dict).
+---
+
+# ProtocolBox
+
+## Installation
+
+```bash
+pip install protocolbox
+```
+
+## Usage
+
+Start the MCP server:
+
+```bash
+protocolbox start
+```
+
+Or with uv:
+
+```bash
+uv run protocolbox start
+```
+
+## Available Tools
+
+- **scrape(url: str) -> str** — Fetch a web page and return clean Markdown.
+- **heal_json(broken_json: str) -> dict** — Fix malformed JSON from LLM output.
+- **generate_invoice(data: dict) -> str** — Generate a PDF invoice.
+  Requires `client_name` and `total` in data.
+"""
+
+
+def _detect_antigravity() -> Path | None:
+    """Detect if running in an Antigravity environment.
+
+    Returns the config directory path if detected, None otherwise.
+    """
+    # Check environment variable first
+    antigravity_home = os.environ.get("ANTIGRAVITY_HOME")
+    if antigravity_home:
+        return Path(antigravity_home)
+
+    # Check for ~/.antigravity directory
+    antigravity_dir = Path.home() / ".antigravity"
+    if antigravity_dir.exists():
+        return antigravity_dir
+
+    return None
+
+
+def _write_skill_file(target_dir: Path) -> Path:
+    """Write the SKILL.md file to the target directory.
+
+    Returns the path to the created file.
+    """
+    target_dir.mkdir(parents=True, exist_ok=True)
+    skill_path = target_dir / "SKILL.md"
+    skill_path.write_text(SKILL_TEMPLATE.strip() + "\n")
+    return skill_path
+
+
+@app.command()
+def init() -> None:
+    """Initialize ProtocolBox for your AI Agent environment."""
+    typer.echo("🔧 ProtocolBox Init")
+    typer.echo("=" * 40)
+
+    antigravity_dir = _detect_antigravity()
+
+    if antigravity_dir:
+        typer.echo(f"✅ Antigravity environment detected: {antigravity_dir}")
+        skill_path = _write_skill_file(antigravity_dir / "skills" / "protocolbox")
+        typer.echo(f"📄 SKILL.md written to: {skill_path}")
+    else:
+        typer.echo("ℹ️  No Antigravity environment detected.")
+        # Write to current directory as fallback
+        skill_path = _write_skill_file(Path.cwd() / ".protocolbox")
+        typer.echo(f"📄 SKILL.md written to: {skill_path}")
+
+    typer.echo()
+    typer.echo("🚀 Ready! Start the server with:")
+    typer.echo("   protocolbox start")
+
+
+@app.command()
+def start() -> None:
+    """Start the ProtocolBox MCP server."""
+    typer.echo("🚀 Starting ProtocolBox MCP Server...")
+    from protocolbox.server import main
+
+    main()
+
+
+if __name__ == "__main__":
+    app()

protocolbox/server.py

@@ -0,0 +1,20 @@
+"""ProtocolBox MCP Server — the engine that exposes all tools."""
+
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("ProtocolBox")
+
+# Import tools so they register with the MCP server.
+# Each tool module uses the `mcp` instance via import.
+import protocolbox.tools.invoice  # noqa: F401, E402
+import protocolbox.tools.json_healer  # noqa: F401, E402
+import protocolbox.tools.scraper  # noqa: F401, E402
+
+
+def main() -> None:
+    """Run the ProtocolBox MCP server."""
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

protocolbox/tools/__init__.py

@@ -0,0 +1,7 @@
+"""ProtocolBox Tools — the standard library of MCP tools."""
+
+from protocolbox.tools.invoice import generate_invoice
+from protocolbox.tools.json_healer import heal_json
+from protocolbox.tools.scraper import scrape
+
+__all__ = ["scrape", "heal_json", "generate_invoice"]

protocolbox/tools/invoice.py

@@ -0,0 +1,129 @@
+"""pb_invoice — Generate PDF invoices from structured data."""
+
+import uuid
+from typing import Any
+
+from reportlab.lib.pagesizes import A4
+from reportlab.lib.units import mm
+from reportlab.pdfgen import canvas
+
+from protocolbox.server import mcp
+
+
+@mcp.tool()
+def generate_invoice(data: dict[str, Any]) -> str:
+    """Generate a PDF invoice from structured data.
+
+    The data dict must contain at minimum:
+        - client_name (str): Name of the client.
+        - total (float | int): Invoice total amount.
+
+    Optional fields:
+        - invoice_number (str): Custom invoice number.
+        - items (list[dict]): Line items with 'description', 'qty', 'price'.
+        - currency (str): Currency symbol (default: "$").
+        - notes (str): Additional notes for the invoice.
+
+    Args:
+        data: Dictionary containing invoice details.
+
+    Returns:
+        The file path to the generated PDF, or an error message.
+    """
+    # --- Validate required fields ---
+    client_name = data.get("client_name")
+    total = data.get("total")
+
+    if not client_name:
+        return "Error: 'client_name' is required in the data dict."
+    if total is None:
+        return "Error: 'total' is required in the data dict."
+
+    try:
+        total = float(total)
+    except (TypeError, ValueError):
+        return "Error: 'total' must be a number."
+
+    # --- Set up defaults ---
+    invoice_number = data.get("invoice_number", f"INV-{uuid.uuid4().hex[:8].upper()}")
+    currency = data.get("currency", "$")
+    items: list[dict[str, Any]] = data.get("items", [])
+    notes: str = data.get("notes", "")
+
+    # --- Generate PDF ---
+    file_path = f"/tmp/invoice_{uuid.uuid4().hex}.pdf"
+    c = canvas.Canvas(file_path, pagesize=A4)
+    width, height = A4
+
+    # Header
+    c.setFont("Helvetica-Bold", 24)
+    c.drawString(30 * mm, height - 30 * mm, "INVOICE")
+
+    c.setFont("Helvetica", 10)
+    c.drawString(30 * mm, height - 40 * mm, f"Invoice #: {invoice_number}")
+
+    # Client info
+    c.setFont("Helvetica-Bold", 12)
+    c.drawString(30 * mm, height - 55 * mm, "Bill To:")
+    c.setFont("Helvetica", 11)
+    c.drawString(30 * mm, height - 62 * mm, str(client_name))
+
+    # Line items
+    y_pos = height - 80 * mm
+
+    if items:
+        # Table header
+        c.setFont("Helvetica-Bold", 10)
+        c.drawString(30 * mm, y_pos, "Description")
+        c.drawString(120 * mm, y_pos, "Qty")
+        c.drawString(145 * mm, y_pos, "Price")
+        c.drawString(170 * mm, y_pos, "Subtotal")
+        y_pos -= 7 * mm
+
+        # Draw a line
+        c.line(30 * mm, y_pos + 3 * mm, 190 * mm, y_pos + 3 * mm)
+
+        c.setFont("Helvetica", 10)
+        for item in items:
+            desc = str(item.get("description", "—"))
+            qty = item.get("qty", 1)
+            price = item.get("price", 0)
+            subtotal = float(qty) * float(price)
+
+            c.drawString(30 * mm, y_pos, desc[:40])
+            c.drawString(120 * mm, y_pos, str(qty))
+            c.drawString(145 * mm, y_pos, f"{currency}{price:.2f}")
+            c.drawString(170 * mm, y_pos, f"{currency}{subtotal:.2f}")
+            y_pos -= 6 * mm
+
+        y_pos -= 5 * mm
+
+    # Total
+    c.line(30 * mm, y_pos + 3 * mm, 190 * mm, y_pos + 3 * mm)
+    c.setFont("Helvetica-Bold", 14)
+    c.drawString(145 * mm, y_pos - 5 * mm, f"Total: {currency}{total:.2f}")
+    y_pos -= 20 * mm
+
+    # Notes
+    if notes:
+        c.setFont("Helvetica-Oblique", 9)
+        c.drawString(30 * mm, y_pos, f"Notes: {notes}")
+
+    # Footer
+    c.setFont("Helvetica", 8)
+    c.drawString(30 * mm, 15 * mm, "Generated by ProtocolBox — protocolbox.in")
+
+    c.save()
+
+    return file_path
+
+
+def _validate_invoice_data(data: dict[str, Any]) -> str | None:
+    """Validate invoice data, returning an error message or None."""
+    if not isinstance(data, dict):
+        return "Error: Input must be a dictionary."
+    if "client_name" not in data:
+        return "Error: 'client_name' is required."
+    if "total" not in data:
+        return "Error: 'total' is required."
+    return None

protocolbox/tools/json_healer.py

@@ -0,0 +1,43 @@
+"""pb_heal_json — Fix malformed JSON from LLM output."""
+
+import json
+from typing import Any
+
+import json_repair
+
+from protocolbox.server import mcp
+
+
+@mcp.tool()
+def heal_json(broken_json: str) -> dict[str, Any]:
+    """Attempt to repair malformed JSON and return a valid Python dict.
+
+    Handles common LLM output issues: trailing commas, unquoted keys,
+    single quotes, truncated output, and more.
+
+    Args:
+        broken_json: A string containing malformed or broken JSON.
+
+    Returns:
+        A valid Python dictionary parsed from the repaired JSON,
+        or an error dict if repair is impossible.
+    """
+    try:
+        repaired = json_repair.repair_json(broken_json, return_objects=False)
+
+        if not isinstance(repaired, str):
+            repaired = str(repaired)
+
+        result = json.loads(repaired)
+
+        # Ensure we always return a dict.
+        if isinstance(result, dict):
+            return result
+        elif isinstance(result, list):
+            return {"data": result}
+        else:
+            return {"value": result}
+
+    except (json.JSONDecodeError, TypeError, ValueError):
+        snippet = broken_json[:100] + ("..." if len(broken_json) > 100 else "")
+        return {"error": "Failed", "input_snippet": snippet}

protocolbox/tools/scraper.py

@@ -0,0 +1,61 @@
+"""pb_scrape — Token-efficient web page scraper."""
+
+import re
+
+import html2text
+import httpx
+
+from protocolbox.server import mcp
+from protocolbox.tools.utils import DEFAULT_TIMEOUT, DEFAULT_USER_AGENT
+
+
+@mcp.tool()
+def scrape(url: str) -> str:
+    """Fetch a web page and return its content as clean Markdown.
+
+    Strips scripts, styles, and footers for token-efficient reading.
+
+    Args:
+        url: The URL of the web page to scrape.
+
+    Returns:
+        The page content as Markdown, or an error message.
+    """
+    try:
+        response = httpx.get(
+            url,
+            timeout=DEFAULT_TIMEOUT,
+            headers={"User-Agent": DEFAULT_USER_AGENT},
+            follow_redirects=True,
+        )
+        response.raise_for_status()
+    except httpx.HTTPStatusError as e:
+        return f"Error: Unable to access page. HTTP {e.response.status_code}."
+    except httpx.RequestError as e:
+        return f"Error: Unable to access page. {type(e).__name__}: {e}"
+
+    html = response.text
+
+    # Strip <script>, <style>, and <footer> tags and their contents.
+    html = re.sub(
+        r"<script[^>]*>.*?</script>", "", html, flags=re.DOTALL | re.IGNORECASE
+    )
+    html = re.sub(
+        r"<style[^>]*>.*?</style>", "", html, flags=re.DOTALL | re.IGNORECASE
+    )
+    html = re.sub(
+        r"<footer[^>]*>.*?</footer>", "", html, flags=re.DOTALL | re.IGNORECASE
+    )
+
+    # Convert to Markdown.
+    converter = html2text.HTML2Text()
+    converter.ignore_links = False
+    converter.ignore_images = True
+    converter.body_width = 0  # No line wrapping
+
+    markdown = converter.handle(html)
+
+    # Clean up excessive blank lines.
+    markdown = re.sub(r"\n{3,}", "\n\n", markdown).strip()
+
+    return markdown

protocolbox/tools/utils.py

@@ -0,0 +1,26 @@
+"""Shared utilities for ProtocolBox tools."""
+
+import httpx
+
+# Standard timeout for HTTP requests (seconds).
+DEFAULT_TIMEOUT = 10.0
+
+# Generic User-Agent to avoid bot detection.
+DEFAULT_USER_AGENT = (
+    "Mozilla/5.0 (compatible; ProtocolBox/0.1; +https://protocolbox.in)"
+)
+
+
+def get_http_client(**kwargs: object) -> httpx.Client:
+    """Create a pre-configured httpx Client.
+
+    Uses standard timeout and User-Agent defaults.
+    Additional kwargs are passed through to httpx.Client.
+    """
+    headers = {"User-Agent": DEFAULT_USER_AGENT}
+    return httpx.Client(
+        timeout=DEFAULT_TIMEOUT,
+        headers=headers,
+        follow_redirects=True,
+        **kwargs,  # type: ignore[arg-type]
+    )

protocolbox-0.1.0.dist-info/METADATA

@@ -0,0 +1,112 @@
+Metadata-Version: 2.4
+Name: protocolbox
+Version: 0.1.0
+Summary: The Standard Library for the Agentic Web — verified MCP tools for any AI Agent.
+Project-URL: Homepage, https://protocolbox.in
+Project-URL: Repository, https://github.com/ianuragbhatt/protocolbox
+Project-URL: Issues, https://github.com/ianuragbhatt/protocolbox/issues
+Author-email: Anurag Bhatt <anurag@protocolbox.in>
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: html2text
+Requires-Dist: httpx
+Requires-Dist: json-repair
+Requires-Dist: mcp>=0.1.0
+Requires-Dist: reportlab
+Requires-Dist: typer
+Provides-Extra: dev
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# ProtocolBox 📦
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-white.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-white.svg)](https://python.org)
+[![Ruff](https://img.shields.io/badge/linting-ruff-white.svg)](https://docs.astral.sh/ruff/)
+[![MCP](https://img.shields.io/badge/protocol-MCP-white.svg)](https://modelcontextprotocol.io/)
+
+> **The Standard Library for the Agentic Web.**  
+> https://protocolbox.in
+
+ProtocolBox is a collection of high-reliability **[MCP (Model Context Protocol)](https://modelcontextprotocol.io/)** tools designed for AI Agents. It provides verified, token-efficient utilities that work out-of-the-box with Claude, Gemini, and other MCP-compliant agents.
+
+## 🚀 Installation
+
+```bash
+pip install protocolbox
+```
+
+Initialize the configuration for your agent:
+
+```bash
+protocolbox init
+```
+
+## 🛠️ Tools
+
+ProtocolBox currently exports 3 core tools optimized for agent workflows:
+
+| Tool | Signature | Description |
+| :--- | :--- | :--- |
+| **Scrape** | `scrape(url: str) -> str` | Fetches a webpage and converts it to clean, token-saving Markdown. Removes ads, scripts, and clutter automatically. |
+| **Heal JSON** | `heal_json(json_str: str) -> dict` | repairs malformed JSON strings often produced by LLMs (trailing commas, missing quotes, etc.) into valid Python dictionaries. |
+| **Invoice** | `generate_invoice(data: dict) -> str` | Generates a professional PDF invoice from structured data in milliseconds. |
+
+## ⚡ Usage
+
+Start the MCP server to expose these tools to your agent:
+
+```bash
+protocolbox start
+```
+
+Or using `uv`:
+
+```bash
+uv run protocolbox start
+```
+
+## 📦 Project Structure
+
+```text
+protocolbox/
+├── src/protocolbox/      # Core package
+│   ├── server.py         # FastMCP server
+│   ├── cli.py            # CLI entry point
+│   └── tools/            # Tool implementations
+├── tests/                # 115+ edge-case tests
+├── docs/                 # Documentation site
+└── pyproject.toml        # Project config
+```
+
+## 👨‍💻 Development
+
+We recommend [uv](https://docs.astral.sh/uv/) for a fast, reliable dev environment.
+
+```bash
+# Clone and setup
+git clone https://github.com/ianuragbhatt/protocolbox.git
+cd protocolbox
+uv pip install -e ".[dev]"
+
+# Run tests (100% pass rate required)
+pytest tests/ -v
+
+# Linting
+ruff check .
+```
+
+## 🤝 Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to add new tools.
+
+**Maintainer:** [Anurag Bhatt (@ianuragbhatt)](https://github.com/ianuragbhatt)
+
+## License
+
+MIT © 2026 ProtocolBox.

protocolbox-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+protocolbox/__init__.py,sha256=yRIuWez8clGaDQvLIIvPRgp6R2WyxYN4-SDq5AyEVWo,87
+protocolbox/cli.py,sha256=5CIf2GRUr5rLBGdAIEPDoz5YUwUlNWqabjYhM1d4i5U,2812
+protocolbox/server.py,sha256=hBr3WbfwPLB8j6LJcpzvqfYC6ZEZJ3fGajgokoG3M-Y,528
+protocolbox/tools/__init__.py,sha256=q3NL-ftBR8K-hWLOMORpIECUTT6hbRyHK4iz6z1waU4,271
+protocolbox/tools/invoice.py,sha256=Pc0OSLcG7omo5FBbQ4V9KyNGSrxMj6E7qtzFtS_XTTU,4032
+protocolbox/tools/json_healer.py,sha256=l5ZRcBIGrGyZ6dh_QX0cMqlADBo3jszg7chViHh5Mls,1259
+protocolbox/tools/scraper.py,sha256=zGqSkSTWls7R1-yJPSJFauNwbe7adaKPZRtVR3jLuRY,1731
+protocolbox/tools/utils.py,sha256=nRIojE-7A9rzoSzkNfvHS63Ne44g1J7dmFDT4FQFOUg,709
+protocolbox-0.1.0.dist-info/METADATA,sha256=WQ75WE9Hgh4dPev-uZlozEn-ROSmPTaZnYhtfhtTIDo,3572
+protocolbox-0.1.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+protocolbox-0.1.0.dist-info/entry_points.txt,sha256=E8JWSJCLiE9mdZVXT-ufHxrEAXLliuLRY7RhuFx5_WQ,52
+protocolbox-0.1.0.dist-info/licenses/LICENSE,sha256=kn261Rb1pbwzB0zRWTFmInRd95RKhgDaxjKRuhVqf4Y,1069
+protocolbox-0.1.0.dist-info/RECORD,,

protocolbox-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

protocolbox-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+protocolbox = protocolbox.cli:app

protocolbox-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anurag Bhatt
+
+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.