# chrome-workflows

A local **MCP server** (stdio, TypeScript) that acts as a **QA scenario store and credential vault** for browser-based usability tests. The agent (Claude Code + Claude in Chrome) executes the tests; this server stores targets, encrypted credentials, workflows, and run history.

## Prerequisites

- **Node.js 24+** — verify with `node --version`
- **Docker** and **Docker Compose** — for the local MongoDB instance

## Quick Start

```bash
# 1. Start MongoDB
docker compose up -d

# 2. Install dependencies
npm install

# 3. Run the test suite
npm test
```

## MCP Registration in Claude Code

Register the server so Claude Code can use it as a tool provider.

Replace `<absolute-path>` with the full path to this repository (e.g. `/home/you/chrome-workflows`):

```bash
claude mcp add chrome-workflows \
  -e MONGODB_URI=mongodb://localhost:27017/chrome-workflows \
  -- npx tsx <absolute-path>/src/index.ts
```

The server communicates over stdio. Once registered, Claude Code has access to the following tools:

| Tool | Purpose |
|---|---|
| `upsert_target` | Create or update a target application |
| `list_targets` | List all targets with masked credentials |
| `set_active_environment` | Switch a target's active environment |
| `delete_target` | Delete a target (cascades to workflows and runs) |
| `upsert_credential` | Store an encrypted credential for a target+environment |
| `delete_credential` | Remove a credential |
| `upsert_workflow` | Create or update a QA workflow (test scenario) |
| `delete_workflow` | Delete a workflow |
| `search_workflows` | Search workflows by text and/or target |
| `get_workflow_bundle` | Get everything needed to execute a workflow (decrypts credentials) |
| `report_run` | Record the result of a workflow execution |
| `list_runs` | List execution runs with agent info |
| `get_run` | Get full details of a single run |
| `get_config_overview` | Snapshot of all targets, workflows, and recent runs |

## Evidence Directory

Screenshots and GIFs captured during test execution are stored at:

```
~/.local/share/chrome-workflows/evidence/
```

The `report_run` tool records evidence file paths and checks whether each file exists at report time (`fileExists: true/false`).

## Environment Variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `MONGODB_URI` | Yes | — | MongoDB connection string |
| `CHROME_WORKFLOWS_MASTER_KEY` | No | Read from `~/.config/chrome-workflows/master.key` | AES-256-GCM master key for credential encryption |

Copy `.env.example` for reference:

```bash
cp .env.example .env
```

## Development

```bash
# Type checking
npm run typecheck

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage
```

## Typical Workflow

1. **Register a target** — `upsert_target` with name, environments, and URLs
2. **Add credentials** — `upsert_credential` for each environment
3. **Create a workflow** — `upsert_workflow` with intent-based steps
4. **Execute** — `get_workflow_bundle` returns everything the agent needs; the agent runs the test via Claude in Chrome
5. **Report** — `report_run` records per-step verdicts and evidence
6. **Review** — `get_config_overview` shows the full configuration; ask Claude to render it as an HTML artifact

## Architecture

- **TypeScript + ESM** with NodeNext module resolution
- **Mongoose** for MongoDB access (3 collections: `targets`, `workflows`, `runs`)
- **Zod** for input validation on every tool
- **AES-256-GCM** encryption for credential secrets at rest
- **Vitest** + `mongodb-memory-server` for testing (no external MongoDB needed for tests)
- Secrets are decrypted **only** in `get_workflow_bundle` — every other tool returns masked usernames and zero secret data