mcp_client

This is an MCP client and webapp you can run locally to visualize transcripts and calculate pass rates.

It should especially help for computer use / multimodal transcripts; you will see annotations of the next action on the result screenshot of the corresponding previous action.

Setup

Important

npm is required to build and run

Quick Start with Makefile

The easiest way to get started is using the provided Makefile:

# Install all dependencies (backend + frontend)
make setup

# Build the frontend for production
make build-frontend

# Start the combined server
make run

Access the app at: http://localhost:5000/app

Using a Different Port

To use a port other than the default 5000, set the SERVER_PORT environment variable for both build and run:

# Build frontend with custom port
SERVER_PORT=5001 make build-frontend

# Run server on the same port
SERVER_PORT=5001 make run

Important: The frontend is built with the port hardcoded, so you must use the same SERVER_PORT value for both make build-frontend and make run.

You can also load the frontend in dev mode and make changes by running npm run dev in the frontend folder.

Required Environment Variables

ANTHROPIC_API_KEY (Required) ❌

The MCP client requires an Anthropic API key to function. You'll see an error message if this is not set.

export ANTHROPIC_API_KEY=your_api_key_here
make run

Computer Use Dimensions (Optional)

For computer use problems, the client defaults to 1400x850 screen dimensions. You can override these defaults:

export COMPUTER_WIDTH_PX=1400
export COMPUTER_HEIGHT_PX=850
make run

Note: If not set, the client will automatically use 1400x850 for computer use problems.

Retry Configuration (Optional)

The MCP client implements exponential backoff retry for Anthropic API requests using the tenacity library. You can configure the retry behavior using command line arguments:

# Run with custom retry settings
uv run start --max-retries 10 --retry-base-delay 2.0 --retry-max-delay 120.0

# Or with make:
make run --max-retries 10 --retry-base-delay 2.0

# Available options:
# --max-retries: Maximum number of retry attempts (default: 10)
# --retry-base-delay: Initial delay between retries in seconds (default: 1.0)
# --retry-max-delay: Maximum delay between retries in seconds (default: 60.0)

The retry mechanism will automatically handle:

• API connection errors
• Timeout errors
• Rate limit errors

Each retry uses exponential backoff with the tenacity library for robust error handling.