open-index/open-npm huggingface dataset:
npm package: @percio/agent
Description: AI-powered usability testing agent — test any URL including localhost
Author: Percio
Latest version: 0.1.4

# Percio Agent (`@percio/agent`)

AI-powered usability testing agent — test any URL (including `localhost`) using a real browser.

This package ships:
- **CLI**: `percio`
- **MCP server**: `percio-mcp` (for Cursor/IDE integration)

## Install

```bash
npm install -g @percio/agent
```

Requires **Node.js >= 18**.

## Authenticate (API key)

### Option A: Login (recommended)

```bash
percio login
```

This stores your key at `~/.config/percio/credentials.json` and is used automatically by both the CLI and MCP server.

### Option B: Environment variable

```bash
export PERCIO_API_KEY="pk_..."
```

## Start the daemon

Percio uses a local daemon (HTTP on `127.0.0.1`) that powers the CLI commands.

### Foreground (recommended for integrated terminals)

```bash
percio start
```
Stop it later with:

```bash
percio stop
```

## Run a usability test

**Interactive (recommended)** — Percio helps you build the test scenario:

```bash
percio test --url https://example.com
# → Starts a conversation to refine your test scenario, then runs the test
```

**Direct** — provide the scenario yourself:

```bash
percio test --url https://example.com --flow "Sign up for an account"
```

Use cloud persona IDs (UUIDs):

```bash
percio personas list
percio test --url https://example.com --flow "Buy a product" --persona-id <uuid>
```

## Cursor MCP setup

### Recommended: `npx` + API key (no login)

Install nothing globally. Create (or edit) `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "percio": {
      "command": "npx",
      "args": ["percio-mcp", "--api-key", "YOUR_PERCIO_API_KEY"]
    }
  }
}
```

Replace `YOUR_PERCIO_API_KEY` with your key from the Percio dashboard. Restart Cursor (or reload MCP servers).

The `percio-mcp` package is on npm (`percio-mcp@0.1.2`+); it depends on `@percio/agent` and runs the same MCP server. Source lives in [`packages/percio-mcp`](packages/percio-mcp).

Restart Cursor (or reload MCP servers). You should see Percio tools like:
- `run_usability_test`
- `chat_scenario`
- `list_personas`
- `chat_persona`
- `create_persona`