Metadata-Version: 2.4
Name: agentyc
Version: 0.2.0
Summary: Deterministic MCP-first browser automation runtime for coding agents
Project-URL: Homepage, https://github.com/distillation-labs/agentyc
Project-URL: Documentation, https://github.com/distillation-labs/agentyc/tree/main/docs
Project-URL: Repository, https://github.com/distillation-labs/agentyc
Project-URL: Source, https://github.com/distillation-labs/agentyc
Project-URL: Issues, https://github.com/distillation-labs/agentyc/issues
Project-URL: Changelog, https://github.com/distillation-labs/agentyc/releases
Author: Gregor Zunic
License-File: LICENSE
Keywords: browser-automation,cdp,chromium,coding-agents,mcp,model-context-protocol
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: <4.0,>=3.11
Requires-Dist: aiohttp==3.13.4
Requires-Dist: anthropic==0.76.0
Requires-Dist: anyio==4.12.1
Requires-Dist: bubus==1.5.6
Requires-Dist: cdp-use==1.4.5
Requires-Dist: google-api-core==2.29.0
Requires-Dist: google-api-python-client==2.188.0
Requires-Dist: google-auth-oauthlib==1.2.4
Requires-Dist: google-auth==2.48.0
Requires-Dist: google-genai==1.65.0
Requires-Dist: groq==1.0.0
Requires-Dist: httpx==0.28.1
Requires-Dist: markdownify==1.2.2
Requires-Dist: mcp==1.26.0
Requires-Dist: ollama==0.6.1
Requires-Dist: openai==2.16.0
Requires-Dist: pillow==12.2.0
Requires-Dist: posthog==7.7.0
Requires-Dist: psutil==7.2.2
Requires-Dist: pydantic==2.12.5
Requires-Dist: pyobjc==12.1; platform_system == 'darwin'
Requires-Dist: pyotp==2.9.0
Requires-Dist: pypdf==6.10.2
Requires-Dist: python-docx==1.2.0
Requires-Dist: python-dotenv==1.2.1
Requires-Dist: reportlab==4.4.9
Requires-Dist: requests==2.33.0
Requires-Dist: screeninfo==0.8.1; platform_system != 'darwin'
Requires-Dist: typing-extensions==4.15.0
Requires-Dist: uuid7==0.1.0
Provides-Extra: all
Requires-Dist: boto3==1.42.37; extra == 'all'
Requires-Dist: oci==2.166.0; extra == 'all'
Provides-Extra: aws
Requires-Dist: boto3==1.42.37; extra == 'aws'
Provides-Extra: copilot
Requires-Dist: github-copilot-sdk<0.2.0,>=0.1.0; extra == 'copilot'
Provides-Extra: eval
Requires-Dist: anyio==4.12.1; extra == 'eval'
Requires-Dist: datamodel-code-generator==0.53.0; extra == 'eval'
Requires-Dist: lmnr[all]==0.7.42; extra == 'eval'
Requires-Dist: psutil==7.2.2; extra == 'eval'
Provides-Extra: oci
Requires-Dist: oci==2.166.0; extra == 'oci'
Provides-Extra: video
Requires-Dist: imageio[ffmpeg]==2.37.2; extra == 'video'
Requires-Dist: numpy==2.4.1; extra == 'video'
Description-Content-Type: text/markdown

# agentyc

Deterministic, MCP-first browser automation for coding agents.

`agentyc` ships a public stdio MCP server for Chrome or Chromium automation plus the Python session primitives that back that server. The public contract is centered on deterministic browser control, token-aware state snapshots, and deterministic extraction without LLM fallback.

## What It Is

- Public stdio MCP server exposed by the `agentyc` console script.
- Browser control over CDP through `agentyc.mcp.server`, `agentyc.tools.service`, `agentyc.mcp.state`, and `agentyc.browser.session`.
- Deterministic extraction routes in `agentyc.tools.extraction.router` for common page structures.
- Python imports such as `AgentycServer`, `BrowserSession`, `BrowserProfile`, and `Tools` for direct embedding.

The default MCP path does not require an API key for navigation, interaction, state inspection, screenshots, HTML access, cookies, or deterministic extraction.

## Install

```bash
uv tool install agentyc
```

From source:

```bash
uv venv --python 3.11
source .venv/bin/activate
uv sync --dev
```

## Bootstrap Your Agent

Run this once in your project directory to write a usage guide your coding agent can read:

```bash
agentyc init
```

This writes `agentyc-skill.md` — covering the read→ref→act loop, `since_hash` polling, extraction routes, auth persistence, and common pitfalls. Point Claude Code, Cursor, or Copilot at it.

```bash
agentyc init --print          # print to stdout instead of writing a file
agentyc init --force          # overwrite an existing file
agentyc init --output my.md   # custom destination
```

## Run The MCP Server

Start the stdio MCP server:

```bash
agentyc
```

Equivalent explicit form:

```bash
agentyc mcp
```

Override the idle timeout for the browser session (default: never auto-close):

```bash
agentyc --session-timeout-minutes 20
```

Shared-browser collaboration flags are also available on `agentyc mcp` and the no-subcommand form:

- `--runtime-label`
- `--runtime-role`
- `--parent-runtime-id`
- `--shared-browser-mode`
- `--shared-browser-window-bounds`
- `--shared-browser-focus-policy`

## Shared Browser Mode

Launch a Chrome or Chromium instance with remote debugging enabled and print its CDP WebSocket URL:

```bash
agentyc browser --detach
```

Attach the MCP server to that browser instead of launching a separate browser process:

```bash
agentyc mcp --cdp-url ws://127.0.0.1:9222/devtools/browser/...
```

Current shared-browser behavior is intentionally narrow:

- Each attached MCP server creates a collaboration target in the shared browser: a tab by default, or a separate window when `--shared-browser-mode window` is used.
- Attach and `new_tab=true` flows update the runtime's focused target automatically.
- Visible browser activation is controlled by `--shared-browser-focus-policy`: `preserve` avoids stealing the human-focused surface, while `activate` explicitly foregrounds the runtime target.
- `browser_get_state` and `browser_list_tabs` surface ownership metadata, display titles, and optional window bounds for shared-browser targets.
- Stock Chrome and CDP do not provide reliable per-tab color ownership cues.
- Shared-browser workflows should be treated as best-effort collaboration, not hard isolation.

## MCP Tool Surface

Navigation and state:

- `browser_navigate`
- `browser_go_back`
- `browser_go_forward`
- `browser_refresh`
- `browser_wait`
- `browser_wait_for_network_idle`
- `browser_get_state`
- `browser_get_html`
- `browser_screenshot`

Interaction:

- `browser_click`
- `browser_right_click`
- `browser_double_click`
- `browser_hover`
- `browser_drag_to`
- `browser_type`
- `browser_press_key`
- `browser_scroll`
- `browser_scroll_to_text`
- `browser_select_option`
- `browser_get_dropdown_options`
- `browser_upload_file`

Inspection and extraction:

- `browser_extract_content`
- `browser_find_elements`
- `browser_search_page`
- `browser_wait_for_element`
- `browser_get_focused_element`
- `browser_evaluate`

Tabs, cookies, and session state:

- `browser_list_tabs`
- `browser_switch_tab`
- `browser_close_tab`
- `browser_get_cookies`
- `browser_set_cookies`
- `browser_clear_cookies`
- `browser_save_state`
- `browser_load_state`

Observability and lifecycle:

- `browser_get_console_logs`
- `browser_get_network_log`
- `browser_list_sessions`
- `browser_close_session`
- `browser_close_all`

The public server exposes tools only. It does not publish MCP resources or prompts.

## State And Element Targeting

`browser_get_state` is the primary inspection primitive.

- Stable element refs such as `e123` are derived from backend node ids.
- `mode` supports `auto`, `full`, `min`, and `focus`.
- `since_hash` allows unchanged-state checks without resending interactive element payloads.
- Compact state payloads can surface `compaction_strategy`, truncation counts, ownership, and runtime metadata when relevant.
- Screenshots are returned as MCP image content, with JSON metadata in a separate text payload.

Prefer refs from `browser_get_state` over legacy numeric `index` arguments.

## Deterministic Extraction

`browser_extract_content` in the public MCP server is deterministic-only.

- No LLM fallback is used in the public server.
- Compatible routes include links, link collections, images, tables, lists, form fields, and key-value blocks.
- `output_schema` is supported when the query matches a deterministic route.
- Unsupported free-form requests return an explicit error instead of silently degrading.
- Responses include `<extraction_metadata>` describing the route and truncation state.

This means the default extraction path works without any API key.

## Python Surface

The package also exposes Python imports for direct integration:

```python
from agentyc import AgentycServer, BrowserProfile, BrowserSession, Tools
```

The public product story is still MCP-first. Direct Python usage is available for embedding or lower-level control.

## Development

```bash
./scripts/lint.sh
./scripts/test.sh
uv build
```

## Docs

- `docs/overview.md`
- `docs/features.md`
- `docs/architecture.md`
- `docs/api.md`
- `docs/configuration.md`
- `docs/tech-stack.md`
