Metadata-Version: 2.3
Name: karon-mcp
Version: 1.4.0
Summary: Karon API MCP server for Claude, Cursor, and other MCP clients. Retrieve web content from MCP-compatible tools.
Project-URL: Homepage, https://karonlabs.net/api/
Project-URL: Documentation, https://karonlabs.net/api/docs.html
Project-URL: Repository, https://github.com/pplar39/karon-mcp
Project-URL: Changelog, https://github.com/pplar39/karon-mcp/blob/main/CHANGELOG.md
Author-email: Karon Labs <ceo@karonlabs.net>
License: MIT
Keywords: claude,cursor,mcp,retrieval,web-content
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
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 :: Internet :: WWW/HTTP
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# karon-mcp

MCP server for the [Karon API](https://karonlabs.net/api/). Retrieve web content directly from Claude, Cursor, or any MCP-compatible client.

## Quick Start

### 1. Get your API key

Sign up at [karonlabs.net/api/signup.html](https://karonlabs.net/api/signup.html) (Google login, free tier: 1,000 credits).

### 2. Install

**Claude Desktop / Claude Code** — add to your MCP config (`claude_desktop_config.json` or `.mcp.json`):

```json
{
  "mcpServers": {
    "karon": {
      "command": "uvx",
      "args": ["karon-mcp"],
      "env": {
        "KARON_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

> `uvx` auto-fetches the latest version from PyPI on every run. No manual updates needed.

**Cursor** — go to Settings > MCP Servers > Add, then use the same config above.

**Manual install** (if you prefer pip):

```bash
pip install karon-mcp
```

### 3. Use

Once installed, eleven tools become available in your MCP client. The original `browse` and `crawl` tools are included alongside the expanded API surface.

#### `browse` — Fetch a single URL

```
browse(url="https://example.com", extract="markdown", readability=True)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | string | required | Target URL (http/https) |
| `extract` | string | `"markdown"` | Output format: `"markdown"`, `"text"`, or `"html"` |
| `readability` | bool | `True` | `True` = main content only, `False` = full page |

#### `crawl` — Fetch multiple URLs concurrently

```
crawl(urls=["https://a.com", "https://b.com"], extract="markdown", concurrency=3)
```

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `urls` | list[string] | required | Up to 20 URLs |
| `extract` | string | `"markdown"` | Output format: `"markdown"` or `"text"` |
| `readability` | bool | `True` | Main content only |
| `concurrency` | int | `3` | Parallel requests (1-5) |

#### Additional tools

| Tool | Purpose |
|------|---------|
| `scrape` | Retrieve one URL with format options |
| `fetch` | Retrieve raw page data |
| `extract` | Retrieve structured JSON data |
| `batch_scrape` | Retrieve multiple URLs in one request |
| `watch_snapshot` | Save a snapshot for one URL |
| `watch_diff` | Compare a URL with its previous saved snapshot |
| `watch_list` | List saved watch targets |
| `credits` | Show account credit and tier information |
| `pricing` | Show public pricing information |

### Credits

| Method | Cost |
|--------|------|
| Cache hit | 1 credit |
| Cache miss | 10 credits |

Free tier includes 1,000 credits. See [pricing](https://karonlabs.net/api/pricing.html) for tier details.

## Configuration

The only required configuration is the `KARON_API_KEY` environment variable. Get yours at [karonlabs.net/api/signup.html](https://karonlabs.net/api/signup.html).

## Updating

If you're using `uvx` (recommended), updates are automatic — every run fetches the latest version.

If you installed with pip:

```bash
pip install --upgrade karon-mcp
```

## Development

### Running Tests

```bash
# Setup
python3 -m venv .venv
source .venv/bin/activate
pip install -e .

# Run local tests
pytest tests/ -v
```

Tests cover:
- MCP protocol handshake (`initialize`)
- Tool discovery (`tools/list`)
- Tool schemas and local error handling
- Error handling (invalid URL, missing API key)

## Links

- [API Documentation](https://karonlabs.net/api/docs.html)
- [Pricing](https://karonlabs.net/api/pricing.html)
- [Changelog](CHANGELOG.md)

## License

MIT
