protocolbox 0.1.0__tar.gz

protocolbox-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,39 @@
+---
+name: Bug Report
+about: Report a bug or unexpected behavior
+title: "[BUG] "
+labels: bug
+assignees: ''
+---
+
+## Describe the Bug
+
+A clear and concise description of what the bug is.
+
+## To Reproduce
+
+Steps to reproduce the behavior:
+
+1. Install ProtocolBox: `pip install protocolbox`
+2. Run: `...`
+3. Call tool: `...`
+4. See error
+
+## Expected Behavior
+
+A clear description of what you expected to happen.
+
+## Actual Behavior
+
+What actually happened. Include any error messages or stack traces.
+
+## Environment
+
+- **OS**: [e.g., macOS 14, Ubuntu 22.04]
+- **Python version**: [e.g., 3.11.8]
+- **ProtocolBox version**: [e.g., 0.1.0]
+- **Agent**: [e.g., Claude, Gemini, Antigravity]
+
+## Additional Context
+
+Add any other context, screenshots, or logs here.

protocolbox-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,41 @@
+---
+name: Feature Request
+about: Suggest a new tool or improvement
+title: "[FEATURE] "
+labels: enhancement
+assignees: ''
+---
+
+## Summary
+
+A clear one-line description of the feature or tool you'd like.
+
+## Use Case
+
+Describe the problem this solves or the scenario where this would be useful.
+
+**Who benefits?** (e.g., agents doing web research, agents generating documents)
+
+## Proposed Solution
+
+Describe how you'd like this to work:
+
+- **Tool name**: `your_tool_name`
+- **Input**: What parameters does it take?
+- **Output**: What does it return?
+- **Dependencies**: Any new libraries needed?
+
+## Example Usage
+
+```python
+# How an agent would use this tool
+result = your_tool_name(param="value")
+```
+
+## Alternatives Considered
+
+List any alternative approaches you've considered.
+
+## Additional Context
+
+Any other context, mockups, or references.

protocolbox-0.1.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,38 @@
+## Description
+
+Brief description of what this PR does and why.
+
+Closes #<!-- issue number -->
+
+## Type of Change
+
+- [ ] 🐛 Bug fix (non-breaking change fixing an issue)
+- [ ] ✨ New feature / tool (non-breaking change adding functionality)
+- [ ] 💥 Breaking change (fix or feature that would break existing functionality)
+- [ ] 📝 Documentation update
+- [ ] 🧪 Test improvement
+- [ ] 🔧 Refactor / maintenance
+
+## Changes Made
+
+- 
+- 
+- 
+
+## Testing
+
+- [ ] All existing tests pass (`pytest tests/ -v`)
+- [ ] New tests added for this change
+- [ ] Edge cases covered (empty input, unicode, large data, errors)
+- [ ] Lint is clean (`ruff check .`)
+
+## Documentation
+
+- [ ] README updated (if adding a tool)
+- [ ] `docs/llms.txt` updated (if adding a tool)
+- [ ] Docstrings added with type hints
+- [ ] CONTRIBUTING.md followed
+
+## Screenshots / Output (if applicable)
+
+<!-- Add any relevant screenshots or command output here -->

protocolbox-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+
+on:
+  push:
+    branches: [ "main", "master" ]
+  pull_request:
+    branches: [ "main", "master" ]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12"]
+
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Install uv
+      uses: astral-sh/setup-uv@v5
+
+    - name: Set up Python ${{ matrix.python-version }}
+      uses: actions/setup-python@v5
+      with:
+        python-version: ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: uv sync --all-extras --dev
+
+    - name: Lint with Ruff
+      run: uv run ruff check .
+
+    - name: Test with pytest
+      run: uv run pytest tests/

protocolbox-0.1.0/.github/workflows/deploy_docs.yml

@@ -0,0 +1,37 @@
+name: Deploy Docs
+
+on:
+  push:
+    branches: ["main", "master"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: "pages"
+  cancel-in-progress: false
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs'
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

protocolbox-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,31 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  pypi-publish:
+    name: Upload release to PyPI
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/protocolbox
+    permissions:
+      id-token: write  # IMPORTANT: this permission is mandatory for trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

protocolbox-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+dist/
+build/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Ruff
+.ruff_cache/
+
+# Pytest
+.pytest_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temp
+/tmp/

protocolbox-0.1.0/.protocolbox/SKILL.md

@@ -0,0 +1,35 @@
+---
+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.

protocolbox-0.1.0/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2026-02-14
+
+### Added
+- **MCP Server**: FastMCP-based server implementation.
+- **Tools**:
+  - `scrape(url)`: Fetch web pages and return clean Markdown.
+  - `heal_json(broken_json)`: Repair malformed JSON output from LLMs.
+  - `generate_invoice(data)`: Create PDF invoices from structured data.
+- **CLI**: `protocolbox init` and `protocolbox start` commands.
+- **Documentation**:
+  - `README.md` with badges and quick start.
+  - `docs/llms.txt` for AI agent consumption.
+  - `docs/index.html` landing page.
+  - `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`.
+- **Testing**: Comprehensive test suite with 110+ tests.

protocolbox-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,56 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, religion, or sexual identity
+and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior:
+
+* The use of sexualized language or imagery, and sexual attention or advances of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the project maintainer at **anurag@protocolbox.in**.
+
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).

protocolbox-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,206 @@
+# Contributing to ProtocolBox
+
+Thank you for your interest in contributing to ProtocolBox! We welcome contributions from everyone.
+
+## Table of Contents
+
+- [Getting Started](#getting-started)
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Adding a New Tool](#adding-a-new-tool)
+- [Code Standards](#code-standards)
+- [Testing](#testing)
+- [Pull Request Process](#pull-request-process)
+- [Reporting Issues](#reporting-issues)
+
+## Getting Started
+
+1. **Fork the repository** on GitHub.
+2. **Clone your fork** locally:
+   ```bash
+   git clone https://github.com/ianuragbhatt/protocolbox.git
+   cd protocolbox
+   ```
+3. **Create a branch** for your work:
+   ```bash
+   git checkout -b feature/your-feature-name
+   ```
+
+## Development Setup
+
+ProtocolBox requires **Python 3.11+**. We recommend using [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```bash
+# Install in editable mode with dev dependencies
+pip install -e ".[dev]"
+
+# Or with uv
+uv pip install -e ".[dev]"
+```
+
+Verify your setup:
+
+```bash
+pytest tests/ -v      # All tests should pass
+ruff check .          # No lint errors
+```
+
+## Project Structure
+
+```
+protocolbox/
+├── src/protocolbox/
+│   ├── __init__.py          # Package version
+│   ├── server.py            # FastMCP server engine
+│   ├── cli.py               # CLI (init + start commands)
+│   └── tools/
+│       ├── __init__.py      # Tool exports
+│       ├── utils.py         # Shared utilities (HTTP client)
+│       ├── scraper.py       # scrape() tool
+│       ├── json_healer.py   # heal_json() tool
+│       └── invoice.py       # generate_invoice() tool
+├── tests/                   # Test suite (mirrors tool structure)
+├── docs/                    # Documentation & landing page
+├── pyproject.toml           # Project config
+├── CONTRIBUTING.md          # ← You are here
+└── CODE_OF_CONDUCT.md
+```
+
+## Adding a New Tool
+
+ProtocolBox is designed to make adding new tools straightforward:
+
+### 1. Create the tool file
+
+Create `src/protocolbox/tools/your_tool.py`:
+
+```python
+"""Description of your tool."""
+
+from protocolbox.server import mcp
+
+
+@mcp.tool()
+def your_tool_name(param: str) -> str:
+    """Clear docstring describing what the tool does.
+
+    Args:
+        param: Description of the parameter.
+
+    Returns:
+        Description of the return value.
+    """
+    # Your implementation here
+    return result
+```
+
+### 2. Register the tool
+
+Add the import to `src/protocolbox/server.py`:
+
+```python
+import protocolbox.tools.your_tool  # noqa: F401, E402
+```
+
+And export it from `src/protocolbox/tools/__init__.py`.
+
+### 3. Write tests
+
+Create `tests/test_your_tool.py` with:
+- Happy-path tests
+- Edge cases (empty input, unicode, very large input)
+- Error handling tests
+
+### 4. Update documentation
+
+- Add the tool to `docs/llms.txt`
+- Add a card to `docs/index.html`
+- Update the `README.md` tool table
+
+## Code Standards
+
+We enforce consistent code quality with **Ruff**:
+
+| Rule | Setting |
+|------|---------|
+| Line length | 88 characters |
+| Target version | Python 3.11 |
+| Lint rules | `E` (pycodestyle), `F` (pyflakes), `I` (isort) |
+| Type hints | **Mandatory** on all public functions |
+
+### Before submitting
+
+```bash
+# Fix auto-fixable issues
+ruff check . --fix
+
+# Verify clean
+ruff check .
+```
+
+### Style guidelines
+
+- **Type hints are mandatory** on all function signatures.
+- **Docstrings** are required on all public functions (Google style).
+- **Error handling**: Tools should return error strings/dicts, not raise exceptions.
+- **No print statements**: Use `typer.echo()` in CLI code only.
+
+## Testing
+
+We use **pytest** for testing. Our test suite aims for comprehensive edge-case coverage.
+
+```bash
+# Run all tests
+pytest tests/ -v
+
+# Run a specific test file
+pytest tests/test_scraper.py -v
+
+# Run with coverage (install pytest-cov first)
+pytest tests/ --cov=protocolbox --cov-report=term-missing
+```
+
+### Test expectations
+
+- **Every tool must have tests** covering:
+  - Normal/happy path
+  - Edge cases (empty, unicode, very large, special characters)
+  - Error handling (invalid input, network errors)
+- **Mock external calls** (HTTP, filesystem) — never make real network requests in tests.
+- **Clean up** generated files (e.g., PDFs in `/tmp/`).
+
+## Pull Request Process
+
+1. **Ensure all tests pass** and **ruff is clean**.
+2. **Write clear commit messages** following conventional commits:
+   - `feat: add new_tool for X`
+   - `fix: handle edge case in scraper`
+   - `docs: update README with new tool`
+   - `test: add edge cases for json_healer`
+3. **Open a PR** against `main` with:
+   - A description of what changed and why.
+   - Link to any related issue.
+4. **Address review feedback** promptly.
+
+### PR checklist
+
+- [ ] All tests pass (`pytest tests/ -v`)
+- [ ] Lint is clean (`ruff check .`)
+- [ ] New tools have comprehensive tests
+- [ ] Documentation is updated (README, llms.txt)
+- [ ] Commit messages follow conventional format
+
+## Reporting Issues
+
+Use the [GitHub issue templates](.github/ISSUE_TEMPLATE/) to report:
+
+- **Bugs**: Include reproduction steps, expected vs actual behavior, and your environment.
+- **Feature requests**: Describe the tool or improvement and the use case.
+
+## Questions?
+
+Open a [discussion](https://github.com/ianuragbhatt/protocolbox/discussions) or reach out to the maintainers.
+
+---
+
+Thank you for helping build the Standard Library for the Agentic Web! 🚀

protocolbox-0.1.0/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.