Development Documentation

Development Documentation

Everything you need to know to develop and contribute to Puppeteer MCP.

Development Guides

Development Workflow

Standard development practices:

• Setup instructions
• Development cycle
• Code review process
• Release procedures
• Maintenance tasks

Coding Standards

William Zujkowski’s coding standards:

• TypeScript standards
• Testing requirements
• Security standards
• Documentation standards
• Code quality metrics

Testing Guide

Comprehensive testing practices:

• Unit testing
• Integration testing
• E2E testing
• Performance testing
• Test coverage requirements

AI Patterns

AI-assisted development patterns:

• Task delegation
• Subagent patterns
• Context management
• Code generation
• Review workflows

Quick Start Development

1. Clone Repository

git clone https://github.com/williamzujkowski/puppeteer-mcp.git
cd puppeteer-mcp

2. Install Dependencies

npm install

3. Set Up Environment

# Copy example environment
cp .env.example .env

# Edit with your settings
nano .env

4. Run Development Server

npm run dev

5. Run Tests

npm test
npm run test:watch  # Watch mode
npm run test:coverage  # With coverage

Development Commands

Build & Compile

npm run build       # Build project
npm run typecheck   # Check TypeScript
npm run lint        # Run ESLint
npm run lint:fix    # Fix ESLint issues

Testing

npm test                 # Run all tests
npm run test:unit       # Unit tests only
npm run test:integration # Integration tests
npm run test:e2e        # End-to-end tests

Development Tools

npm run dev         # Start dev server
npm run debug       # Start with debugging
npm run watch       # Watch for changes
npm run clean       # Clean build artifacts

Project Structure

puppeteer-mcp/
├── src/                 # Source code
│   ├── auth/           # Authentication
│   ├── grpc/           # gRPC implementation
│   ├── mcp/            # MCP server
│   ├── puppeteer/      # Browser automation
│   ├── routes/         # REST API routes
│   ├── store/          # Session management
│   ├── utils/          # Utilities
│   └── ws/             # WebSocket server
├── test/               # Test files
│   ├── unit/          # Unit tests
│   ├── integration/   # Integration tests
│   └── e2e/           # End-to-end tests
├── docs/               # Documentation
├── scripts/            # Build scripts
└── config/             # Configuration

Code Quality Standards

TypeScript Requirements

• ✅ Strict mode enabled
• ✅ No any types (migrate to unknown)
• ✅ All functions documented
• ✅ Interfaces over type aliases
• ✅ Explicit return types

Testing Requirements

• ✅ 85%+ code coverage
• ✅ Test-first development
• ✅ Descriptive test names
• ✅ Isolated unit tests
• ✅ Comprehensive E2E tests

Security Requirements

• ✅ Input validation (Zod)
• ✅ Authentication on all endpoints
• ✅ NIST control tags
• ✅ Security headers
• ✅ Rate limiting

Development Workflow

1. Feature Development

# Create feature branch
git checkout -b feature/your-feature

# Make changes
# Write tests first (TDD)
# Implement feature
# Update documentation

# Run checks
npm run typecheck
npm run lint
npm test

2. Code Review

• Create pull request
• Ensure CI passes
• Request review
• Address feedback
• Merge when approved

3. Release Process

# Update version
npm version patch|minor|major

# Build and test
npm run build
npm test

# Publish
npm publish

Common Development Tasks

Adding a New API Endpoint

1. Define route in src/routes/
2. Add validation schema (Zod)
3. Implement business logic
4. Add tests
5. Update OpenAPI spec
6. Document in API reference

Adding a New MCP Tool

1. Define tool in src/mcp/tools/
2. Add parameter schema
3. Implement tool logic
4. Add to tool registry
5. Write tests
6. Update MCP documentation

Fixing a Bug

1. Write failing test
2. Fix the bug
3. Ensure test passes
4. Check for regressions
5. Update changelog

Debugging

Enable Debug Logging

# All debug output
DEBUG=* npm run dev

# Specific namespaces
DEBUG=puppeteer:* npm run dev
DEBUG=mcp:*,session:* npm run dev

Chrome DevTools

// Enable DevTools in development
const browser = await puppeteer.launch({
  headless: false,
  devtools: true,
});

VS Code Debugging

.vscode/launch.json

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Server",
      "program": "${workspaceFolder}/src/index.ts",
      "preLaunchTask": "tsc: build",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "env": {
        "DEBUG": "*"
      }
    }
  ]
}

Contributing

Before Contributing

1. Read Contributing Guide
2. Review Coding Standards
3. Check existing issues
4. Discuss major changes

Contribution Process

1. Fork repository
2. Create feature branch
3. Make changes with tests
4. Submit pull request
5. Address review feedback

Resources

Internal Documentation

• Development Workflow - Detailed workflow
• Coding Standards - Code quality standards
• Testing Guide - Testing best practices
• AI Patterns - AI development

External Resources

• TypeScript Handbook
• Puppeteer Documentation
• Jest Documentation
• Node.js Best Practices

Getting Help

• Check existing documentation
• Search GitHub issues
• Ask in discussions
• Contact maintainers