Metadata-Version: 2.4
Name: ghostcrawl-mcp-server
Version: 2.2.3
Summary: MCP server for GhostCrawl — managed browser automation via Claude Desktop and agent runtimes
Author: GhostCrawl
License: Proprietary — see LICENSE
Keywords: mcp,browser,automation,ghostcrawl,claude
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp==1.27.1
Requires-Dist: httpx<1,>=0.28
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
Requires-Dist: respx>=0.20; extra == "dev"
Requires-Dist: jsonschema>=4; extra == "dev"
Requires-Dist: deepdiff>=6; extra == "dev"
Dynamic: license-file

# ghostcrawl-mcp-server

MCP server for GhostCrawl — managed browser automation via Claude Desktop and agent runtimes.

ghostcrawl-mcp-server exposes 8 tools (`start`, `end`, `navigate`, `act`, `observe`, `extract`,
`screenshot`, `network`) over the Model Context Protocol so Claude Desktop, Cursor, and cloud
agent runtimes can drive GhostCrawl's managed browser engines. Tool names follow the
canonical GhostCrawl agent vocabulary; `screenshot` and `network` are GhostCrawl additions over
the six-primitive baseline. Capability profiles let operators ship a narrower tool
surface to clients that only need a subset — see `GHOSTCRAWL_MCP_CAPABILITIES`.

---

## Quick Start — stdio (Claude Desktop / local agents)

The fastest way to get started is `uvx`, which installs and runs the server in one command
without polluting your Python environment:

```bash
uvx ghostcrawl-mcp-server
```

Or with explicit stdio transport flag:

```bash
uvx ghostcrawl-mcp-server --stdio
```

Set `GHOSTCRAWL_API_KEY` and `GHOSTCRAWL_API_URL` in your shell or via the Claude Desktop
config (see below).

---

## Claude Desktop Configuration (stdio)

Add this block to your Claude Desktop config file (`claude_desktop_config.json`):

```json
{
 "mcpServers": {
 "ghostcrawl": {
 "command": "uvx",
 "args": ["ghostcrawl-mcp-server"],
 "env": {
 "GHOSTCRAWL_API_KEY": "your-key-here",
 "GHOSTCRAWL_API_URL": "http://localhost:8080"
 }
 }
 }
}
```

**Step-by-step walkthrough:** See [docs/claude-desktop-config.md](docs/claude-desktop-config.md).

---

## Quick Start — HTTP (cloud agent runtimes)

Run the server over streamable-HTTP for cloud agent runtimes:

```bash
uvx ghostcrawl-mcp-server --http --port 8090
```

Or run standalone for local testing:

```bash
docker build -t ghostcrawl-mcp-server ghostcrawl-mcp-server/
docker run -p 8090:8090 \
 -e GHOSTCRAWL_API_URL=http://localhost:8080 \
 -e GHOSTCRAWL_API_KEY=your-key \
 ghostcrawl-mcp-server
```

Once running, point Cursor / Continue.dev / any MCP-capable agent at:

```json
{
 "mcpServers": {
 "ghostcrawl": {
 "type": "http",
 "url": "http://localhost:8090/mcp"
 }
 }
}
```

**Full SSE/HTTP setup guide:** See [docs/sse-http-config.md](docs/sse-http-config.md).

---

## Tool Reference

All 8 tools are registered automatically when the server starts. Each tool call is routed to
the ghostcrawl REST API (`GHOSTCRAWL_API_URL`) or debug sidecar (`GHOSTCRAWL_SIDECAR_URL`).

| Tool | Key Inputs | Description |
|------|-----------|-------------|
| `start` | `profile_id?: string` | Start a browsing session. Pins a profile to this MCP connection. If `profile_id` is omitted, a fresh profile is minted automatically. |
| `end` | _(none)_ | End the current session and release the pinned profile. |
| `navigate` | `url: string` | Navigate the active browser profile to a URL. |
| `act` | `action: string` | Perform a natural-language browser action (click, type, submit, etc.) via the agent executor. |
| `observe` | `instruction: string` | Observe the current page state and return a structured description. |
| `extract` | `instruction?: string`, `schema?: object` | Extract structured data from the current page. Pass a JSON Schema via `schema` for typed output. |
| `screenshot` | `full_page?: bool`, `selector?: string` | Capture a screenshot of the current page (or a CSS selector). Returns base64-encoded PNG via the debug sidecar. |
| `network` | `filter?: string`, `since?: timestamp` | Return recent network events captured by the browser sidecar. Optionally filter by URL pattern or start timestamp. |

---

## Configuration

| Variable | Default | Description |
|---|---|---|
| `GHOSTCRAWL_API_URL` | `http://localhost:8080` | ghostcrawl REST API base URL |
| `GHOSTCRAWL_SIDECAR_URL` | `http://localhost:8081` | ghostcrawl debug sidecar base URL (screenshot/network) |
| `GHOSTCRAWL_API_KEY` | _(empty)_ | Bearer token forwarded to ghostcrawl API. Never logged or echoed. |

In the fleet compose stack, `GHOSTCRAWL_API_URL` defaults to `http://ghostcrawl-api-master:8001`
and `GHOSTCRAWL_SIDECAR_URL` defaults to the same address (the sidecar endpoints live in the
same FastAPI app in the current fleet deployment).

---

## Demo

A live screen-capture recording and raw JSONL session transcript are in
[docs/demo/](docs/demo/) (populated in coming soon).

---

## Development

```bash
cd ghostcrawl-mcp-server
pip install -e ".[dev]"
pytest tests/ -x -q
```

The test suite (53 tests) covers tool schemas, session pin/isolation, both stdio and
streamable-HTTP transports, and packaging validation. All tests use mock REST servers
(real TCP sockets, not respx patches) for process-boundary correctness.

---

## Packaging

- Distribution name: `ghostcrawl-mcp-server`
- Entry point: `ghostcrawl-mcp-server` (console_scripts → `ghostcrawl_mcp_server.cli:main`)
- Dependencies: `mcp==1.27.1`, `httpx>=0.28,<1`
- `uvx ghostcrawl-mcp-server` works out of the box — no local Python install required.
- Pin with `uv` for reproducible lockfile.
