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

Related MCP server: Playwright Pool

Quick Start

# 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):

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:

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

Copy .env.example for reference:

cp .env.example .env

Development

# 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