Project 29: Chrome Hello World - Visual Page Analyzer

Project 29: Chrome Hello World - Visual Page Analyzer

Build a visual page analysis system that uses Claude’s Chrome integration to navigate websites, capture screenshots, analyze page structure, and generate detailed accessibility and usability reports.

Quick Reference

Attribute Value
Difficulty Intermediate
Time Estimate Weekend
Language TypeScript (Alternatives: JavaScript, Python)
Prerequisites HTML/DOM structure, basic MCP concepts
Key Topics Browser automation, accessibility testing, MCP tool integration
Main Book “Web Scraping with Python” by Ryan Mitchell

1. Learning Objectives

By completing this project, you will:

  1. Master MCP tool discovery and loading: Understand how to find and load Chrome MCP tools using MCPSearch
  2. Coordinate multiple browser automation tools: Chain navigate, read_page, get_page_text, and screenshot tools effectively
  3. Analyze DOM structure programmatically: Parse page elements to assess structure and accessibility
  4. Capture visual evidence: Use gif_creator and screenshot capabilities for documentation
  5. Generate actionable accessibility reports: Quantify accessibility issues with scoring and recommendations
  6. Understand Claude’s browser integration model: Grasp how Claude “sees” web pages through MCP

2. Theoretical Foundation

2.1 How Claude Sees Web Pages

Claude doesn’t have an internal browser. Instead, the Chrome MCP extension acts as Claude’s eyes and hands:

┌─────────────────────────────────────────────────────────────────────────────┐
│                     Claude-in-Chrome Architecture                            │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐         ┌──────────────────┐         ┌─────────────────┐  │
│  │    Claude    │◀───────▶│  MCP Transport   │◀───────▶│ Chrome Browser  │  │
│  │   (LLM)      │  JSON   │   (Extension)    │   DOM   │  (User's Tab)   │  │
│  └──────────────┘         └──────────────────┘         └─────────────────┘  │
│         │                         │                           │             │
│         │                         │                           │             │
│         ▼                         ▼                           ▼             │
│  Reasoning about      Serializing/Deserializing       Capturing state,      │
│  what to do next      tool calls and results          executing actions     │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Key insight: When Claude calls mcp__claude-in-chrome__read_page, the extension captures the current DOM state and sends it back as structured data. Claude then reasons about this data to understand the page.

2.2 The MCP Tool Ecosystem

The Chrome MCP extension provides these core tools:

Tool Purpose Returns
tabs_context_mcp Get available browser tabs Tab IDs and metadata
navigate Open a URL or navigate history Navigation status
read_page Capture DOM accessibility tree Element hierarchy with refs
get_page_text Extract text content Plain text from page
computer Mouse/keyboard interactions Action confirmation
screenshot Capture visual state Image data
gif_creator Record interactions GIF animation
find Locate elements by description Element references

2.3 Accessibility Tree vs DOM Tree

The Chrome MCP returns an accessibility tree, not a raw DOM:

DOM Tree:                           Accessibility Tree:
<div class="header">               heading "Welcome" (level 1)
  <h1>Welcome</h1>                   ├─ link "Home"
  <nav>                              ├─ link "About"
    <a href="/">Home</a>             └─ link "Contact"
    <a href="/about">About</a>
    <a href="/contact">Contact</a>   button "Sign In"
  </nav>
</div>                              main content region
<button>Sign In</button>             └─ paragraph "Lorem ipsum..."
<main>
  <p>Lorem ipsum...</p>
</main>

The accessibility tree is what screen readers see - it strips away visual presentation and exposes the semantic structure.

2.4 Core Accessibility Concepts

Understanding accessibility requires knowing these principles:

WCAG Guidelines (Web Content Accessibility Guidelines):

  • Perceivable: Information must be presentable (alt text, captions)
  • Operable: Interface must be navigable (keyboard access)
  • Understandable: Content must be readable (clear language)
  • Robust: Content must work with assistive technologies

Common Issues to Detect: | Issue | Impact | Detection Method | |——-|——–|——————| | Missing alt text | Images invisible to screen readers | Check img elements for alt attribute | | Poor heading hierarchy | Navigation confusion | Verify h1 → h2 → h3 sequence | | Missing form labels | Input purpose unclear | Check input elements for labels | | Low contrast | Text unreadable | Calculate color contrast ratios | | Missing skip links | Keyboard users stuck in nav | Look for skip-to-content links |

2.5 Why This Matters

This project teaches patterns applicable to:

  • Automated accessibility auditing: Catch issues before users report them
  • Visual regression testing: Ensure UI changes don’t break functionality
  • Content scraping: Extract structured data from any web page
  • QA automation: Verify page structure matches expectations
  • SEO analysis: Check heading structure and semantic markup

3. Project Specification

3.1 What You Will Build

A visual page analyzer that Claude can use to:

  1. Navigate to any web page
  2. Capture the page structure and content
  3. Analyze accessibility and usability
  4. Generate a detailed report with scores and recommendations
  5. Optionally record interactions as GIFs

3.2 Functional Requirements

  1. Page Navigation
    • Accept a URL and navigate to it
    • Handle navigation errors gracefully
    • Wait for page load completion
  2. Structure Analysis
    • Count and categorize all elements (links, images, forms, headings)
    • Extract heading hierarchy
    • Identify form elements and their labels
  3. Accessibility Scoring
    • Check for alt text on images
    • Verify heading hierarchy (h1 before h2, etc.)
    • Detect missing form labels
    • Identify interactive elements without accessible names
    • Generate an overall score (0-100)
  4. Content Extraction
    • Extract main text content
    • Identify primary language
    • Detect reading level (stretch goal)
  5. Visual Documentation
    • Capture screenshots
    • Record interaction GIFs (optional)

3.3 Example Usage / Output

You: Analyze the accessibility of https://example.com

Claude: Let me analyze this page for you.

[Uses mcp__claude-in-chrome__tabs_context_mcp to get tab context]
[Uses mcp__claude-in-chrome__navigate to open the page]
[Uses mcp__claude-in-chrome__read_page to capture structure]
[Uses mcp__claude-in-chrome__get_page_text for content analysis]

================================================================================
                    PAGE ANALYSIS REPORT: example.com
================================================================================

STRUCTURE OVERVIEW
------------------
  Total Elements:    24
  Links:             1 (all descriptive)
  Images:            0
  Forms:             0
  Headings:          1
    - h1: "Example Domain"

HEADING HIERARCHY
-----------------
  h1: Example Domain ...................... [OK]
  (No subheadings found)

ACCESSIBILITY AUDIT
-------------------
  Score: 92/100

  [PASS] All images have alt text (0 images, 0 issues)
  [PASS] Heading hierarchy is correct
  [PASS] All links have descriptive text
  [PASS] Color contrast appears adequate
  [WARN] No skip-to-content link found
  [WARN] No landmark regions defined (main, nav, etc.)

CONTENT SUMMARY
---------------
  Primary Language: English
  Word Count: 42
  Reading Level: Grade 6 (Easy)

RECOMMENDATIONS
---------------
  1. Add a skip-to-content link for keyboard users
  2. Add ARIA landmark regions (main, navigation)
  3. Consider adding more descriptive metadata

================================================================================
Would you like me to record a GIF of the page interaction?

4. Solution Architecture

4.1 High-Level Design

┌─────────────────────────────────────────────────────────────────────────────┐
│                          Visual Page Analyzer                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐   ┌──────────────┐   ┌──────────────┐   ┌──────────────┐  │
│  │  Navigation  │──▶│   Structure  │──▶│ Accessibility│──▶│    Report    │  │
│  │   Module     │   │   Analyzer   │   │   Auditor    │   │  Generator   │  │
│  └──────────────┘   └──────────────┘   └──────────────┘   └──────────────┘  │
│         │                  │                  │                  │          │
│         │                  │                  │                  │          │
│         ▼                  ▼                  ▼                  ▼          │
│  tabs_context_mcp    read_page          Scoring Logic       Formatted      │
│  navigate            get_page_text      WCAG Rules          Output         │
│  computer (wait)     find               Heuristics          Recommendations│
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

4.2 Tool Flow Diagram

User Request: "Analyze https://example.com"
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 1: Get Browser Context                                                  │
│ mcp__claude-in-chrome__tabs_context_mcp(createIfEmpty: true)                │
│ Returns: { tabs: [{ id: 12345, url: "about:blank" }] }                      │
└─────────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 2: Navigate to Target URL                                               │
│ mcp__claude-in-chrome__navigate(url: "https://example.com", tabId: 12345)   │
│ Returns: Navigation confirmation                                             │
└─────────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 3: Wait for Page Load                                                   │
│ mcp__claude-in-chrome__computer(action: "wait", duration: 2, tabId: 12345)  │
│ Returns: Wait confirmation                                                   │
└─────────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 4: Capture Page Structure                                               │
│ mcp__claude-in-chrome__read_page(tabId: 12345, filter: "all")               │
│ Returns: Accessibility tree with element references                          │
└─────────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 5: Extract Text Content                                                 │
│ mcp__claude-in-chrome__get_page_text(tabId: 12345)                          │
│ Returns: Plain text content of the page                                      │
└─────────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 6: Optional Screenshot                                                  │
│ mcp__claude-in-chrome__computer(action: "screenshot", tabId: 12345)         │
│ Returns: Screenshot image                                                    │
└─────────────────────────────────────────────────────────────────────────────┘
                    │
                    ▼
┌─────────────────────────────────────────────────────────────────────────────┐
│ Step 7: Analysis & Reporting                                                 │
│ Claude analyzes the collected data and generates the report                  │
│ No tool call - pure reasoning over the collected information                 │
└─────────────────────────────────────────────────────────────────────────────┘

4.3 Accessibility Scoring Algorithm

Score Calculation:

Base Score: 100

Deductions:
  - Missing alt text on image: -5 per instance
  - Broken heading hierarchy: -10
  - Missing form labels: -5 per instance
  - No skip link: -5
  - No landmark regions: -5
  - Non-descriptive links ("click here"): -3 per instance
  - Missing page title: -10
  - Missing lang attribute: -5

Minimum Score: 0

Severity Levels:
  90-100: Excellent - Minor improvements possible
  70-89:  Good - Some issues to address
  50-69:  Fair - Significant accessibility barriers
  0-49:   Poor - Major accessibility problems

5. Implementation Guide

5.1 Chrome MCP Tool Reference

tabs_context_mcp - Get Browser Context

// Get current tab group context
mcp__claude-in-chrome__tabs_context_mcp({
  createIfEmpty: true  // Create new window if no MCP group exists
})

// Response:
{
  tabs: [
    { id: 12345, url: "https://example.com", title: "Example" }
  ]
}

navigate - Open URL

// Navigate to a URL
mcp__claude-in-chrome__navigate({
  url: "https://example.com",
  tabId: 12345
})

// Also supports: "back", "forward" for history navigation

read_page - Capture Structure

// Get accessibility tree
mcp__claude-in-chrome__read_page({
  tabId: 12345,
  filter: "all",     // "all" for everything, "interactive" for buttons/links/inputs
  depth: 15          // How deep to traverse (default: 15)
})

// Response includes elements like:
// heading "Page Title" (level 1) [ref_1]
// link "Home" [ref_2]
// button "Submit" [ref_3]

get_page_text - Extract Content

// Get plain text content
mcp__claude-in-chrome__get_page_text({
  tabId: 12345
})

// Returns: Plain text extracted from the page, prioritizing article content

find - Locate Elements

// Find elements by description
mcp__claude-in-chrome__find({
  tabId: 12345,
  query: "login button"
})

// Returns: Up to 20 matching elements with references

computer - Interact and Capture

// Take a screenshot
mcp__claude-in-chrome__computer({
  action: "screenshot",
  tabId: 12345
})

// Wait for content to load
mcp__claude-in-chrome__computer({
  action: "wait",
  duration: 2,  // seconds (max 30)
  tabId: 12345
})

// Scroll the page
mcp__claude-in-chrome__computer({
  action: "scroll",
  scroll_direction: "down",
  scroll_amount: 3,  // wheel ticks
  coordinate: [500, 400],
  tabId: 12345
})

gif_creator - Record Interactions

// Start recording
mcp__claude-in-chrome__gif_creator({
  action: "start_recording",
  tabId: 12345
})

// ... perform actions ...

// Stop and export
mcp__claude-in-chrome__gif_creator({
  action: "stop_recording",
  tabId: 12345
})

mcp__claude-in-chrome__gif_creator({
  action: "export",
  tabId: 12345,
  download: true,
  options: {
    showClickIndicators: true,
    showActionLabels: true,
    showProgressBar: true
  }
})

5.2 Implementation Phases

Phase 1: Basic Navigation (Day 1)

Goal: Navigate to a URL and confirm the page loaded.

Tasks:

  1. Get tab context with tabs_context_mcp
  2. Navigate to a test URL
  3. Wait for page load
  4. Take a screenshot to confirm

Checkpoint: Successfully navigate to example.com and capture a screenshot.

Phase 2: Structure Extraction (Day 1-2)

Goal: Parse the page structure into useful categories.

Tasks:

  1. Use read_page to get the accessibility tree
  2. Count elements by type (headings, links, images, forms)
  3. Extract heading hierarchy
  4. Identify form elements and their labels

Checkpoint: Output a structured summary of page elements.

Phase 3: Accessibility Analysis (Day 2)

Goal: Implement accessibility checks and scoring.

Tasks:

  1. Check alt text on images
  2. Verify heading order (h1 before h2, etc.)
  3. Detect missing form labels
  4. Look for skip links and landmarks
  5. Calculate overall score

Checkpoint: Generate an accessibility score with specific findings.

Phase 4: Report Generation (Day 2)

Goal: Format findings into an actionable report.

Tasks:

  1. Design report layout
  2. Add recommendations based on findings
  3. Include visual indicators (checkmarks, warnings)
  4. Add optional GIF recording capability

Checkpoint: Complete analysis produces a formatted report.

6. Testing Strategy

6.1 Test URLs

URL Purpose Expected Findings
https://example.com Minimal page Few elements, simple structure
https://www.w3.org/ Good accessibility High score, proper landmarks
Any complex site Real-world test Multiple issues to find

6.2 Validation Approach

  1. Compare with manual inspection: Open the same page and verify element counts
  2. Cross-reference with tools: Compare findings with Lighthouse or axe DevTools
  3. Test edge cases: Empty pages, pages with errors, SPAs

7. Common Pitfalls & Debugging

7.1 Frequent Issues

Issue Symptom Solution
Tab not found “Invalid tab ID” error Always get fresh context with tabs_context_mcp first
Page not loaded Empty accessibility tree Add wait time with computer(action: "wait")
SPA content missing Elements not in tree Wait for dynamic content or trigger load
Output too large Character limit exceeded Use smaller depth parameter in read_page

7.2 Debugging Strategies

  • Check console messages: Use read_console_messages to see JavaScript errors
  • Take screenshots: Verify the page looks as expected
  • Use find tool: Locate specific elements you expect to see
  • Reduce depth: If read_page output is too large, lower the depth parameter

8. Real World Outcome

When you complete this project, here’s what a full analysis session looks like:

You: Analyze https://news.ycombinator.com for accessibility

Claude: I'll analyze the Hacker News homepage for accessibility issues.

[Gets tab context...]
[Navigating to https://news.ycombinator.com...]
[Waiting for page load...]
[Capturing page structure...]
[Extracting text content...]

================================================================================
              PAGE ANALYSIS REPORT: news.ycombinator.com
================================================================================

STRUCTURE OVERVIEW
------------------
  Total Elements:    187
  Links:             92 (mostly news story titles)
  Images:            1 (logo)
  Forms:             0
  Headings:          0 [ISSUE]

HEADING HIERARCHY
-----------------
  [FAIL] No heading elements found on page

  This page uses table-based layout without semantic headings.
  Screen reader users cannot quickly navigate between sections.

ACCESSIBILITY AUDIT
-------------------
  Score: 45/100

  [PASS] Logo image has alt text ("Hacker News")
  [FAIL] No heading structure
  [FAIL] No landmark regions (main, nav, article)
  [FAIL] No skip-to-content link
  [WARN] Table used for layout instead of CSS grid/flexbox
  [WARN] Links lack context without visual cues
  [PASS] Text appears to have adequate contrast

CONTENT SUMMARY
---------------
  Primary Language: English (detected)
  Word Count: 847
  Reading Level: Grade 8

DETAILED FINDINGS
-----------------
  1. Table-based layout (deprecated)
     The page structure uses nested tables which don't convey
     semantic meaning to assistive technologies.

  2. Missing page regions
     No <main>, <nav>, <header>, or <article> elements.
     Users cannot use landmark navigation.

  3. Link context
     Story links like "Show HN: Something" are clear,
     but "hide" and "past" links need more context.

RECOMMENDATIONS
---------------
  1. Add semantic heading structure:
     - h1: "Hacker News"
     - h2 for each section (Top, New, Ask, etc.)
     - h3 for individual story titles

  2. Convert to semantic HTML:
     - Replace tables with CSS grid layout
     - Add <main>, <nav>, <header> landmarks

  3. Add skip link:
     - Allow keyboard users to bypass navigation

  4. Improve link context:
     - Use aria-label for action links like "hide"

================================================================================

Would you like me to:
1. Record a GIF showing how a screen reader would experience this page?
2. Compare this with another news site's accessibility?
3. Generate a detailed WCAG 2.1 compliance checklist?

9. The Core Question You’re Answering

“How does Claude actually ‘see’ and interact with web pages through MCP?”

Before this project, browser automation might seem like magic. After completing it, you’ll understand:

  1. MCP is a communication protocol - Claude sends JSON requests, gets structured responses
  2. The browser extension is the bridge - It translates requests into browser actions
  3. Claude reasons about data, not pixels - The accessibility tree provides semantic structure
  4. Visual analysis is multimodal - Screenshots give Claude visual context to reason about
  5. This is different from Puppeteer - Claude is reasoning about what to do, not following scripts

10. Concepts You Must Understand First

Before starting this project, ensure you understand:

Concept Why It Matters Where to Learn
HTML DOM structure You’ll parse and analyze DOM trees MDN Web Docs - Introduction to the DOM
Accessibility tree basics Core output of read_page MDN - Accessibility Object Model
CSS selectors Understanding element references MDN - CSS Selectors
WCAG guidelines overview You’ll implement accessibility checks WebAIM - WCAG 2 Overview
MCP protocol basics How Claude communicates with tools Previous MCP projects
Async tool patterns Browser tools are async Claude Code documentation

11. Questions to Guide Your Design

Work through these questions BEFORE implementing:

  1. Tool Ordering: What order should you call the MCP tools? Why does order matter?

  2. Error Handling: What happens if navigation fails? How do you detect and report it?

  3. Dynamic Content: How do you know when a page is “fully loaded”? What about JavaScript-rendered content?

  4. Scoring Weights: Which accessibility issues are most severe? How should they affect the score?

  5. Report Format: What information is most actionable for developers? What can be skipped?

  6. GIF Recording: When is it useful to record interactions? What should trigger recording?

12. Thinking Exercise

Before implementing, work through this scenario:

You’re analyzing a login page with:

  • A logo image
  • A heading “Sign In”
  • Email input with no visible label (just placeholder text)
  • Password input with no visible label
  • “Remember me” checkbox with label
  • “Sign In” button
  • “Forgot password?” link

Questions to answer on paper:

  1. What will the accessibility tree look like?
  2. Which elements have accessibility issues?
  3. What score would you assign and why?
  4. What specific recommendations would you make?

Verify your understanding by analyzing a real login page with your tool.

13. The Interview Questions They’ll Ask

After completing this project, you’ll be ready for:

  1. “How would you automate accessibility testing for a web application?”
    • Expected: Explain DOM inspection, WCAG rules, scoring systems
    • Bonus: Discuss integration with CI/CD, handling dynamic content
  2. “What’s the difference between Puppeteer-style automation and Claude’s MCP approach?”
    • Expected: Script-based vs reasoning-based, flexibility vs predictability
    • Bonus: Discuss when each approach is appropriate
  3. “How do you handle dynamic content that loads asynchronously?”
    • Expected: Wait strategies, mutation observers, network idle detection
    • Bonus: Discuss SPAs, infinite scroll, lazy loading
  4. “What security considerations apply to browser automation?”
    • Expected: Same-origin policy, credential handling, injection risks
    • Bonus: Discuss content script isolation, permission models
  5. “How would you make accessibility analysis reproducible and comparable over time?”
    • Expected: Baseline snapshots, scoring normalization, change detection
    • Bonus: Discuss CI integration, historical tracking

14. Hints in Layers

If you get stuck, reveal hints progressively:

Hint 1: Getting Started

Start with just navigation and screenshot. Before analyzing anything:

1. tabs_context_mcp(createIfEmpty: true)  // Get a tab
2. navigate(url, tabId)                    // Open the page
3. computer(action: "wait", duration: 2)   // Let it load
4. computer(action: "screenshot")          // Verify it worked

Once you can reliably navigate and capture, add analysis.

Hint 2: Reading the Page

The read_page output is an accessibility tree. Look for patterns:

  • “heading … (level N)” indicates h1-h6 elements
  • “link …” indicates anchor elements
  • “img …” or “image …” indicates images
  • “button …” indicates interactive buttons
  • “[ref_N]” gives you element references for interaction

Parse this structure to count and categorize elements.

Hint 3: Accessibility Checks

Focus on these high-impact checks first:

  1. Heading hierarchy: Extract all headings, verify h1 comes before h2, h2 before h3
  2. Alt text: Images should have descriptive text in their accessible name
  3. Form labels: Inputs should have associated labels (check for “textbox” with label vs without)
  4. Link text: Links should describe their destination (not “click here”)
Hint 4: Debugging Tool Failures

If tools aren’t working as expected:

  • Use read_console_messages to check for JavaScript errors
  • Take screenshots to verify page state
  • Try find to locate specific elements you expect
  • Check if the page is in an error state (404, 500, etc.)

15. Books That Will Help

Topic Book Chapter/Section
Web scraping fundamentals “Web Scraping with Python” by Ryan Mitchell Ch. 1-2
Accessibility principles “A Web for Everyone” by Sarah Horton Ch. 3-5
Browser internals “How Browsers Work” by Tali Garsiel All (online article)
DOM structure “DOM Enlightenment” by Cody Lindley Ch. 1-3
Testing strategies “The Art of Software Testing” by Myers Ch. 5-6
Accessible design “Designing for Accessibility” by Derek Featherstone Ch. 4-6

16. Extensions & Challenges

16.1 Beginner Extensions

  • JSON output: Export analysis results as JSON for tooling integration
  • Multiple viewports: Analyze at different screen sizes (mobile, tablet, desktop)
  • Page comparison: Compare two URLs’ accessibility scores

16.2 Intermediate Extensions

  • WCAG compliance mapping: Map findings to specific WCAG success criteria
  • Automated remediation hints: Suggest specific code fixes for issues
  • Historical tracking: Store and compare scores over time

16.3 Advanced Extensions

  • Full WCAG audit: Implement all Level A and AA criteria
  • CI/CD integration: Run analysis as part of deployment pipeline
  • Lighthouse comparison: Cross-reference with Lighthouse accessibility scores

17. Learning Milestones

Track your progress through these checkpoints:

Milestone Description Verification
1. Navigation works Can open any URL and capture screenshot Screenshot shows expected page
2. Structure extraction Can count and categorize page elements Element counts match manual inspection
3. Accessibility scoring Generate scores with specific findings Score changes based on issues present
4. Report generation Produce formatted, actionable reports Report includes all required sections
5. Full integration Complete analysis in single interaction End-to-end demo works reliably

This guide was expanded from CLAUDE_CODE_MASTERY_40_PROJECTS.md. For the complete learning path, see the project index.