Metadata-Version: 2.4
Name: screenshotmcp
Version: 0.3.0
Summary: Official Python SDK for ScreenshotMCP.
Author: AgentForge Labs
License-Expression: AGPL-3.0-only
Project-URL: Homepage, https://snapforge.web-tasarimci.com
Project-URL: Documentation, https://github.com/AgentForge-Labs/site-screenshot-public#readme
Project-URL: Repository, https://github.com/AgentForge-Labs/site-screenshot-public
Project-URL: Issues, https://github.com/AgentForge-Labs/site-screenshot-public/issues
Keywords: screenshot,playwright,mcp,agent,api,snapforge
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# screenshotmcp

Zero-dependency synchronous Python SDK for ScreenshotMCP.

```bash
pip install screenshotmcp
```

## Hosted mode is the default

```python
import os
from screenshotmcp import SiteScreenshotClient

client = SiteScreenshotClient(access_token=os.environ["SCREENSHOTMCP_TOKEN"])
result = client.capture("https://example.com", device="both")
print(result["files"])
```

Omitting `base_url` targets `https://snapforge.web-tasarimci.com` and reports `mode=hosted`. Hosted use requires a free-account API key or account-bound OAuth token and shares the **500 capture credits/month** pool with REST, CLI, JavaScript and MCP.

Requests carry credential-free client metadata with package name, package version and hosted/self-hosted mode. A hosted failure is surfaced as `SiteScreenshotError`; the SDK never falls back to localhost or another origin.

## Explicit self-hosted/community mode

```python
self_hosted = SiteScreenshotClient("http://localhost:3010")
```

Any explicit non-managed HTTP(S) origin is `mode=self-hosted`. Origins containing credentials, paths, queries or fragments are rejected.

`get_job()`, `download_job()`, and `download_job_file()` map to persisted screenshot job routes. The previous `agentforge_site_screenshot` import remains available for compatibility.

## Forward-compatible raw requests

Compatible public endpoints can be called before a typed helper ships with `client.request('/api/v1/...', method='POST', json_body={...})`. Authentication, timeout, idempotency and error redaction remain enforced; private/admin paths are rejected.

## Migration from the previous default

If an earlier Python integration relied on implicit `http://localhost:3010`, pass `base_url="http://localhost:3010"` explicitly (or the first positional base URL). Omitting `base_url` now intentionally selects managed SnapForge.


## Hosted auth onboarding metadata

The Python library never opens a browser. Use `hosted_account_urls()` for safe account/login/signup/upgrade URLs. `SiteScreenshotError` exposes `code`, `account_url`, `login_url`, `signup_url`, and `upgrade_url` when returned by the hosted API. Configured bearer tokens and URL secrets are redacted from error messages and bodies.

```python
from screenshotmcp import hosted_account_urls
print(hosted_account_urls()["signupUrl"])
```
