# ProtocolBox — The Standard Library for AI Agents

> Project: ProtocolBox
> Version: 0.1.4
> Website: https://protocolbox.in
> Repo: https://github.com/ianuragbhatt/protocolbox

## Installation

To use ProtocolBox, run:

```
pip install protocolbox
protocolbox init
```

Or with uv:

```
uv pip install protocolbox
uv run protocolbox init
```

## Starting the MCP Server

```
protocolbox start
```

Or:

```
uv run protocolbox start
```

## Available Tools

### scrape(url: str) -> str

Fetch a web page and return its content as clean Markdown.
Strips scripts, styles, and footers for token-efficient reading.

Use this tool for:
- Reading web pages without wasting tokens on HTML boilerplate.
- Extracting article content, documentation, or product info.

Example:
```json
{"url": "https://example.com/article"}
```

Returns: Markdown string of the page content.

---

### heal_json(broken_json: str) -> dict

Repair malformed JSON and return a valid Python dictionary.
Handles trailing commas, unquoted keys, single quotes, and truncated output.

Use this tool for:
- Fixing broken JSON from LLM outputs.
- Recovering data from malformed API responses.

Example:
```json
{"broken_json": "{'name': 'Alice', 'age': 30,}"}
```

Returns: `{"name": "Alice", "age": 30}`

---

### web_search(query: str, max_results: int = 3) -> str

Search the web using DuckDuckGo and return formatted Markdown results.
Privacy-focused — no API key required.

Use this tool for:
- Real-time web grounding to verify facts.
- Finding current information, documentation, or references.

Example:
```json
{"query": "Python MCP protocol", "max_results": 5}
```

Returns: Markdown with numbered results (title, link, snippet).

---

### safe_math(expression: str) -> str

Securely evaluate a mathematical expression without using eval().
Uses AST parsing for safety. Supports +, -, *, /, **, % and functions: sqrt, floor, ceil, abs, sin, cos, tan, log.

Use this tool for:
- Performing calculations safely within agent workflows.
- Evaluating user-provided math expressions without code injection risk.

Example:
```json
{"expression": "sqrt(16) + 2 ** 3"}
```

Returns: `"12.0"`

---

### get_time(timezone: str = "UTC") -> str

Get the current real-world time in a specified timezone.
Returns time in ISO 8601 format (YYYY-MM-DD HH:MM:SS TZ).

Use this tool for:
- Getting the current time in any timezone.
- Scheduling or time-aware agent decisions.

Example:
```json
{"timezone": "Asia/Kolkata"}
```

Returns: `"2026-02-15 23:30:00 IST"`

---

### get_transcript(video_url: str) -> str

Fetch the English transcript of a YouTube video as clean text.
Supports standard, short (youtu.be), and embed YouTube URLs.

Use this tool for:
- Summarizing YouTube video content.
- Extracting information from video tutorials or lectures.

Example:
```json
{"video_url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"}
```

Returns: The full transcript as a single text string.

---

### remember(key: str, value: str) -> str

Store a key-value pair in persistent local memory (~/.protocolbox/memory.json).

Use this tool for:
- Saving user preferences or context across sessions.
- Persisting data that the agent needs to recall later.

Example:
```json
{"key": "user_name", "value": "Alice"}
```

Returns: `"Remembered: 'user_name' has been saved."`

---

### recall(key: str) -> str

Retrieve a value from persistent local memory by key.

Use this tool for:
- Retrieving previously stored preferences or context.
- Accessing persistent data from earlier sessions.

Example:
```json
{"key": "user_name"}
```

Returns: `"Alice"` (or a "not found" message if the key doesn't exist).

---

## Support

Report issues: https://github.com/ianuragbhatt/protocolbox/issues