web-developer-mcp: Instructions file for Claude Code

Claude Instructions for WebDev MCP Server

This is a Model Context Protocol (MCP) server for web development that provides browser automation tools using Playwright.

Development Guidelines

Code Style & Organization

• Use TypeScript with strict type checking
• Follow alphabetical sorting for object properties and interface fields
• Use early returns to reduce nesting
• Add blank lines between methods and logical sections
• Prefer as const for literal types to ensure proper MCP content typing
• Use globalThis as any for browser globals in Playwright evaluation contexts

Project Structure

src/
├── index.ts                    # Entry point with error handling
├── server.ts                   # MCP server setup and tool registration
├── browser/
│   └── BrowserManager.ts      # Singleton browser management
└── tools/
    ├── click.ts               # Element clicking
    ├── console.ts             # Console output retrieval
    ├── fill.ts                # Form input filling
    ├── navigate.ts            # Browser navigation
    ├── query-dom.ts           # DOM element inspection
    ├── query-html.ts          # HTML extraction
    └── submit.ts              # Form submission

Browser Management

• Uses singleton pattern for consistent browser state
• Single browser instance with single page (replaces page on navigation)
• Captures console logs automatically on page load
• Supports graceful shutdown via signal handlers
• Navigation State Management: Uses isNavigating state to coordinate timing between tools
• Automatic Waiting: Tools wait for navigation completion before executing to ensure dynamic content is captured

Tool Development

• Each tool is a separate module exporting a handler function
• All handlers must return MCP-compatible content with type: 'text' as const
• Include proper error handling with descriptive messages
• Add parameter validation and helpful error messages for missing page state
• Navigation-Dependent Tools: Console, DOM query, and HTML extraction tools must call waitForNavigationComplete() before execution
• Timing Considerations: Allow additional time (1s) after navigation for JavaScript execution and dynamic content creation