Docs/Model Context Protocol

MCP Tools Reference

Detailed reference for assrt_test, assrt_plan, and assrt_diagnose parameters and responses.

Complete reference for all three MCP tools exposed by the Assrt server. Each tool can be called by any MCP-compatible coding agent.

assrt_test

Run AI-powered QA test scenarios against a URL. The tool launches a headless browser, executes each scenario step by step, and returns a structured report with pass/fail results, assertion evidence, and screenshots.

Parameters

Field	Type	Description
`url`required	`string`	The URL to test, including protocol and port (e.g. http://localhost:3000).
`plan`required	`string`	Test scenarios in plain text. Use the #Case N: format for multiple scenarios. Each case should have numbered steps describing actions and assertions.
`model`	`string`	LLM model override. Defaults to claude-haiku-4-5-20251001.

Response

Returns a JSON object followed by screenshot image blocks for each test step.

Response shapejson

{
  "passed": true,
  "passedCount": 3,
  "failedCount": 0,
  "duration": 32.8,
  "screenshotCount": 5,
  "scenarios": [
    {
      "name": "Homepage loads correctly",
      "passed": true,
      "summary": "All assertions passed.",
      "assertions": [
        {
          "description": "Page title contains 'Assrt'",
          "passed": true,
          "evidence": "Title is 'Assrt - AI QA Testing'"
        }
      ]
    }
  ],
  "improvements": [
    {
      "title": "Missing alt text on hero image",
      "severity": "medium",
      "description": "The hero image has no alt attribute.",
      "suggestion": "Add descriptive alt text for accessibility."
    }
  ]
}

After the JSON block, the response includes image content blocks (PNG screenshots) captured at each test step. Your coding agent can display these inline or save them to disk.

assrt_plan

Auto-generate QA test scenarios by analyzing a URL. The tool launches a headless browser, navigates to the page, takes screenshots at multiple scroll positions, reads the accessibility tree, and uses AI to produce executable test cases.

Parameters

Field	Type	Description
`url`required	`string`	The URL to analyze (e.g. http://localhost:3000).
`model`	`string`	LLM model override for plan generation. Defaults to claude-haiku-4-5-20251001.

Response

Response shapejson

{
  "plan": "#Case 1: Homepage loads\n1. Navigate to http://localhost:3000\n2. Verify the page title is visible\n...",
  "url": "http://localhost:3000"
}

The plan field contains test cases in the standard #Case N: format. You can review and edit them, then pass the plan directly to assrt_test.

Plan then test workflow

A common pattern is to call assrt_plan first, review the generated cases, then run them with assrt_test. Your coding agent handles this automatically when you say "generate and run tests for localhost:3000".

assrt_diagnose

Diagnose a failed test scenario. Analyzes the failure and provides root cause analysis, whether the issue is an application bug, a flawed test, or an environment problem. Returns a corrected test scenario you can run immediately.

Parameters

Field	Type	Description
`url`required	`string`	The URL that was tested when the failure occurred.
`scenario`required	`string`	The full test scenario that failed, including steps and assertions.
`error`required	`string`	The failure description, evidence, or error message from the test report.

Response

Response shapejson

{
  "diagnosis": "### Root Cause\nThe login form submits to /api/auth which returns 404...\n\n### Analysis\n...\n\n### Recommended Fix\n...\n\n### Corrected Test Scenario\n#Case 1: Login with valid credentials\n1. Navigate to /login\n...",
  "url": "http://localhost:3000",
  "scenario": "#Case 1: Login flow\n1. Navigate to /login..."
}

The diagnosis field contains structured markdown with four sections: Root Cause, Analysis, Recommended Fix, and a Corrected Test Scenario in #Case format ready to run.

Authentication

All three tools use your existing Claude API credentials automatically. The MCP server reads your Anthropic API key from the macOS Keychain (set during claude login) or from the ANTHROPIC_API_KEY environment variable.

Local development: No extra setup needed if you are logged into Claude Code.
CI environments: Set ANTHROPIC_API_KEY as a repository secret.

Error handling

If a tool encounters an error (browser launch failure, network timeout, API rate limit), it throws an MCP error with a descriptive message. Your coding agent will surface this as a tool call failure and can retry or ask you for guidance.

Common errors and fixes:

"No Anthropic credential found" — Run claude to log in, or set ANTHROPIC_API_KEY.
"Browser launch failed" — Run npx playwright install chromium to install the browser.
"429 rate limit"— You have hit the Anthropic API rate limit. Wait a moment and retry.