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

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

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:

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