diff --git a/.biome.json b/.biome.json new file mode 100644 index 0000000..e4b17c1 --- /dev/null +++ b/.biome.json @@ -0,0 +1,17 @@ +{ + "$schema": "https://biomejs.dev/schemas/1.8.0/schema.json", + "files": { + "ignore": [ + "**/node_modules/**", + "dist/**", + "coverage/**", + "src/__tests__/**", + "tests/**" + ] + }, + "linter": { + "rules": { + "recommended": true + } + } +} diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml new file mode 100644 index 0000000..d6d5ef0 --- /dev/null +++ b/.github/workflows/build.yml @@ -0,0 +1,109 @@ +name: Lint/Test/Build + +on: + push: + branches: ["**"] + tags: [ 'v*.*.*' ] + pull_request: + branches: ["**"] + +jobs: + test-and-build: + name: Lint/Test/Build (Node 20) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Detect file changes + id: changes + uses: dorny/paths-filter@v3 + with: + filters: | + docker: + - 'Dockerfile' + - 'docker-compose.yml' + - 'docker-compose.yaml' + - '.dockerignore' + docs: + - 'docs/**' + + - name: Show change filters + run: | + echo "Docker files changed: ${{ steps.changes.outputs.docker }}" + echo "Docs files changed: ${{ steps.changes.outputs.docs }}" + + - name: Use Node 20 + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + + - name: Install dependencies + run: npm ci + + - name: Check commit message (conventional commits) + run: npx commitlint --from=HEAD~1 --to=HEAD + + - name: Run lint (Node 20) + run: npm run lint + + - name: Run tests (Node 20) + run: npm test + + - name: Run coverage (Node 20) + run: npm run test:coverage + + - name: Upload coverage to CodeCov + uses: codecov/codecov-action@v5 + with: + fail_ci_if_error: false + + - name: Build (Node 20) + run: npm run build + + - name: Build Docker image (no push, on Docker changes) + if: steps.changes.outputs.docker == 'true' + run: docker build -t mcp-playwright-ci:latest . + + docs-build: + name: Docs Build (Docusaurus) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 + + - name: Detect docs changes + id: changes + uses: dorny/paths-filter@v3 + with: + filters: | + docs: + - 'docs/**' + + - name: Show change filters + run: | + echo "Docker files changed: ${{ steps.changes.outputs.docker }}" + echo "Docs files changed: ${{ steps.changes.outputs.docs }}" + + - name: Use Node 20 + uses: actions/setup-node@v4 + with: + node-version: 20 + cache: npm + + - name: Build docs (Docusaurus) + if: steps.changes.outputs.docs == 'true' + env: + DOCS_ORG: ${{ github.repository_owner }} + DOCS_PROJECT: ${{ github.event.repository.name }} + DOCS_URL: https://${{ github.repository_owner }}.github.io + DOCS_BASE_URL: /${{ github.event.repository.name }}/ + run: | + cd docs + npm ci + npm run build diff --git a/.github/workflows/docker-publish.yml b/.github/workflows/docker-publish.yml new file mode 100644 index 0000000..b1438a1 --- /dev/null +++ b/.github/workflows/docker-publish.yml @@ -0,0 +1,99 @@ +name: Docker Image Build/Push + +on: + push: + branches: ["**"] + tags: + - "v*.*.*" + pull_request: + branches: ["**"] + release: + types: [published, created] + workflow_dispatch: + inputs: + push_image: + description: "Set to true to force a push on manual runs" + required: false + default: "false" + workflow_call: {} + +env: + REGISTRY: ghcr.io + IMAGE_NAME: ${{ github.repository }} + +jobs: + build-and-push: + name: Docker Image (build/push) + runs-on: ubuntu-latest + permissions: + contents: read + packages: write + + env: + PUSH_IMAGE: ${{ github.event_name == 'release' || startsWith(github.ref, 'refs/tags/v') || github.ref == 'refs/heads/main' || github.event.inputs.push_image == 'true' }} + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + ref: ${{ github.event.release.tag_name || github.ref }} + + - name: Detect docker file changes + id: changes + uses: dorny/paths-filter@v3 + with: + filters: | + docker: + - 'Dockerfile' + - 'docker-compose.yml' + - 'docker-compose.yaml' + - '.dockerignore' + + - name: Show docker change filters + run: 'echo "Docker files changed: ${{ steps.changes.outputs.docker }}"' + + - name: Set up QEMU + uses: docker/setup-qemu-action@v3 + with: + platforms: arm64,amd64 + + - name: Set up Docker Buildx + uses: docker/setup-buildx-action@v3 + + - name: Extract Docker metadata + id: meta + uses: docker/metadata-action@v5 + with: + images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }} + tags: | + type=semver,pattern=v{{version}},enable=${{ startsWith(github.ref, 'refs/tags/v') }} + type=semver,pattern=v{{major}}.{{minor}},enable=${{ startsWith(github.ref, 'refs/tags/v') }} + type=semver,pattern=v{{major}},enable=${{ startsWith(github.ref, 'refs/tags/v') }} + type=raw,value=latest,enable=${{ startsWith(github.ref, 'refs/tags/v') }} + type=ref,event=branch,enable=${{ !startsWith(github.ref, 'refs/tags/v') && github.event_name != 'release' }} + + - name: Log in to GitHub Container Registry (main/tags only) + uses: docker/login-action@v3 + if: env.PUSH_IMAGE == 'true' + with: + registry: ${{ env.REGISTRY }} + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} + + - name: Image build/push (GHCR) + if: ${{ steps.changes.outputs.docker == 'true' || env.PUSH_IMAGE == 'true' || github.event_name == 'release' || startsWith(github.ref, 'refs/tags/v') }} + uses: docker/build-push-action@v5 + env: + DOCS_ORG: ${{ github.repository_owner }} + DOCS_PROJECT: ${{ github.event.repository.name }} + DOCS_URL: https://${{ github.repository_owner }}.github.io + DOCS_BASE_URL: /${{ github.event.repository.name }}/ + with: + context: . + platforms: linux/amd64,linux/arm64 + push: ${{ env.PUSH_IMAGE == 'true' }} + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} + cache-from: type=gha + cache-to: type=gha,mode=max diff --git a/.github/workflows/docusaurus-gh-pages.yml b/.github/workflows/docusaurus-gh-pages.yml index 50fa5a2..b633e34 100644 --- a/.github/workflows/docusaurus-gh-pages.yml +++ b/.github/workflows/docusaurus-gh-pages.yml @@ -1,13 +1,8 @@ name: Deploy Docusaurus documentation to GH Pages on: - # Runs on pushes targeting the default branch push: branches: ["main"] - pull_request: - branches: [ "main" ] - - # Allows you to run this workflow manually from the Actions tab workflow_dispatch: # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages diff --git a/.github/workflows/node.js.yml b/.github/workflows/node.js.yml deleted file mode 100644 index 4dbd422..0000000 --- a/.github/workflows/node.js.yml +++ /dev/null @@ -1,30 +0,0 @@ -# This workflow will do a clean installation of node dependencies, cache/restore them, build the source code and run tests across different versions of node -# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-nodejs - -name: Node.js CI - -on: - push: - branches: [ "main" ] - pull_request: - branches: [ "main" ] - -jobs: - build: - - runs-on: ubuntu-latest - - strategy: - matrix: - node-version: [18.x, 20.x, 22.x] - # See supported Node.js release schedule at https://nodejs.org/en/about/releases/ - - steps: - - uses: actions/checkout@v4 - - name: Use Node.js ${{ matrix.node-version }} - uses: actions/setup-node@v4 - with: - node-version: ${{ matrix.node-version }} - cache: 'npm' - - run: npm ci - - run: npm run build --if-present diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml new file mode 100644 index 0000000..541b3c1 --- /dev/null +++ b/.github/workflows/release-please.yml @@ -0,0 +1,22 @@ +name: Release Please + +on: + push: + branches: + - main + workflow_dispatch: {} + +jobs: + release-please: + runs-on: ubuntu-latest + permissions: + contents: write + pull-requests: write + steps: + - name: Release Please + uses: googleapis/release-please-action@v4 + with: + token: ${{ secrets.GITHUB_TOKEN }} + command: manifest-pr + config-file: release-please-config.json + manifest-file: .release-please-manifest.json diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml deleted file mode 100644 index f59084f..0000000 --- a/.github/workflows/test.yml +++ /dev/null @@ -1,40 +0,0 @@ -name: Test - -on: - push: - pull_request: - -jobs: - build: - runs-on: ubuntu-latest - - steps: - - uses: actions/checkout@v3 - - - name: Set up Node.js - uses: actions/setup-node@v3 - with: - node-version: 22 # Use current LTS version - cache: 'npm' - - - name: Install dependencies - run: npm install - - - name: Build project - run: npm run build - - - name: Run tests with coverage (custom script) - run: node run-tests.cjs - continue-on-error: true - id: custom-test - - - name: Run tests with coverage (npm script) - if: steps.custom-test.outcome == 'failure' - run: npm run test:coverage -- --testMatch="/src/__tests__/**/*.test.ts" - - - name: Upload coverage report - uses: actions/upload-artifact@v4 - with: - name: coverage-report - path: coverage/ - if-no-files-found: warn diff --git a/.husky/commit-msg b/.husky/commit-msg new file mode 100644 index 0000000..e81b051 --- /dev/null +++ b/.husky/commit-msg @@ -0,0 +1 @@ +npx commitlint --edit "$1" diff --git a/.husky/pre-commit b/.husky/pre-commit new file mode 100644 index 0000000..72c4429 --- /dev/null +++ b/.husky/pre-commit @@ -0,0 +1 @@ +npm test diff --git a/.release-please-manifest.json b/.release-please-manifest.json new file mode 100644 index 0000000..a915e8c --- /dev/null +++ b/.release-please-manifest.json @@ -0,0 +1,3 @@ +{ + ".": "0.1.1" +} diff --git a/.release-please-template.hbs b/.release-please-template.hbs new file mode 100644 index 0000000..e86caff --- /dev/null +++ b/.release-please-template.hbs @@ -0,0 +1,13 @@ +{{> header}} + +## What's Changed + +{{#each entries}} +### {{title}} + +{{#each commits}} +* {{subject}}{{#if scope}} ({{scope}}){{/if}}{{#if author}} by @{{author.login}}{{/if}} +{{/each}} + +{{/each}} + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3a03b47 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,48 @@ +--- +description: 'Automates browser-based workflows and helps users perform tasks that may require a browser or research using a browser. Uses the Playwright MCP server.' +tools: ['search', 'runCommands', 'runTasks', 'mcp-playwright/*', 'openSimpleBrowser', 'todos'] +--- + +# Agent Playbook + +## Plan First +- Write a brief todo list before acting (use a todo tool if available; otherwise outline in chat). Include evidence steps (screenshots on key actions). + +## Navigation & Interaction +- Use the Playwright MCP server for browser tasks. After navigation, inspect the page before acting. +- Ensure targets are visible; if hidden, reveal via JS (`display/visibility/opacity`) or trigger the parent/label. Try alternative triggers if still blocked. +- Use sensible waits/timeouts and glance at console logs after major steps. + +## Evidence (Screenshots/Logs/PDFs/Tests) +- Take and name screenshots for important actions (navigate, click, upload/download, script/DOM changes). Note download URLs. +- When a downloadable URL/resource_link is available, present it as a clickable link, mention it is under Resources, and ask if the user wants a local download. If yes, run the platform command below. + +Downloads: +- **Windows PowerShell** +``` +$uri = "https://gateway.example.com/resources/abc123/report.pdf" +$out = "$HOME\Downloads\report.pdf" +Invoke-WebRequest -Uri $uri -OutFile $out +``` +- **Linux/macOS shell** +``` +uri="https://gateway.example.com/resources/abc123/report.png" +out="$HOME/Downloads/report.png" +curl -L "$uri" -o "$out" +# or: wget -O "$out" "$uri" +``` + +## File Uploads +- If **HTTP mode**: call `construct_upload_url`, upload via curl/PowerShell, then call `playwright_upload_file` with the returned resource URI. + - PowerShell: + `$filePath="/tmp/filepath.png"; $uploadUrl="http://host.com:8000/mcp/uploads/session-id"; $sessionId="session-id"; & 'C:\Windows\System32\curl.exe' -X POST -F "file=@$filePath" -H "X-MCP-Session-ID: $sessionId" $uploadUrl; Start-Sleep -Seconds 3` + - Unix shell: + `filePath="/tmp/filepath.png"; uploadUrl="http://host.com:8000/mcp/uploads/session-id"; sessionId="session-id"; curl -X POST -F "file=@${filePath}" -H "X-MCP-Session-ID: ${sessionId}" "${uploadUrl}" && sleep 3` +- If **stdio mode**: call `playwright_upload_file` with a local `filePath`. + +## Quick Checklist +- [ ] Plan/todo (with evidence steps) is written. +- [ ] Page inspected; targets visible/ready. +- [ ] Screenshots captured for key actions and links surfaced. +- [ ] Correct upload flow used for the current mode. +- [ ] Offer local download when a resource link is returned; remind files are under Resources. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..74c0e59 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,24 @@ +# Changelog + +## 0.1.1 (2025-12-03) + +## What's Changed +* docs: update docker usage instruction by @aakashH242 in https://github.com/aakashH242/mcp-playwright/pull/23 +* docs: rearrange and improve docs by @aakashH242 in https://github.com/aakashH242/mcp-playwright/pull/25 +* docs: prettify by @aakashH242 in https://github.com/aakashH242/mcp-playwright/pull/27 +* docs: change http icon by @aakashH242 in https://github.com/aakashH242/mcp-playwright/pull/29 +* fix: resources not shown (#31) by @aakashH242 in https://github.com/aakashH242/mcp-playwright/pull/32 + + +**Full Changelog**: https://github.com/aakashH242/mcp-playwright/compare/v0.1.0...v0.1.1 + +## 0.1.0 (2025-11-23) + +## What's Changed +* feat: #1 add streamable HTTP support by @aakashH242 in https://github.com/aakashH242/mcp-playwright/pull/2 + +## New Contributors +* @aakashH242 made their first contribution in https://github.com/aakashH242/mcp-playwright/pull/2 +* @github-actions[bot] made their first contribution in https://github.com/aakashH242/mcp-playwright/pull/10 + +**Full Changelog**: https://github.com/aakashH242/mcp-playwright/commits/v0.1.0 diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..fe41ba1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,193 @@ +# Contributing + +Thanks for your interest in contributing! Please follow the standards below to keep the project healthy. + +## 1. Setup pre-commit hooks + +After installing dependencies (`npm ci`), run: + +```bash +npm run prepare +``` + +This installs the Husky pre-commit hook that runs lint, tests, and build before each commit. + +## 2. Use Conventional Commits + +All commits **and PR titles** must follow [Conventional Commits](https://www.conventionalcommits.org/) format. This is critical because the project uses [Release Please](https://github.com/googleapis/release-please) to: +- Automatically version releases +- Generate CHANGELOG.md +- Categorize changes in release notes + +### Commit Format + +``` +(): + +[optional body] + +[optional footer] +``` + +### Commit Types + +Choose the appropriate type for your changes: + +- `feat:` - A new feature (bumps minor version: 0.1.0 β†’ 0.2.0) +- `fix:` - A bug fix (bumps patch version: 0.1.0 β†’ 0.1.1) +- `docs:` - Documentation only changes +- `style:` - Code style changes (formatting, missing semicolons, etc.) +- `refactor:` - Code change that neither fixes a bug nor adds a feature +- `perf:` - Performance improvement +- `test:` - Adding or updating tests +- `build:` - Changes to build system or dependencies +- `ci:` - Changes to CI configuration files and scripts +- `chore:` - Other changes that don't modify src or test files +- `revert:` - Reverts a previous commit + +### Breaking Changes + +For breaking changes, add `BREAKING CHANGE:` in the commit footer or add `!` after the type: + +```bash +feat!: change API response format + +BREAKING CHANGE: The API now returns JSON instead of XML +``` + +This will bump the major version (0.1.0 β†’ 1.0.0). + +### Examples + +```bash +# Feature commit +feat: add support for multiple browser tabs +feat(navigation): add go back and forward tools + +# Bug fix commit +fix: resolve screenshot timeout issue +fix(upload): handle large file uploads correctly + +# Documentation commit +docs: update installation instructions +docs(api): add examples for HTTP tools + +# Test commit +test: add integration tests for browser tools +``` + +### Why This Matters + +The commit format directly affects: +- **Version numbering** - `feat` vs `fix` vs `BREAKING CHANGE` +- **CHANGELOG categories** - Each type appears in a different section +- **Release notes** - Your changes are automatically categorized with emojis: + - πŸš€ Features + - πŸ› Bug Fixes + - πŸ“š Documentation + - πŸ§ͺ Tests + - And more... + +**Important**: CI validates commit messages using commitlint, so improperly formatted commits will fail the build. + +## 3. Update docs for user-facing changes + +If you add or modify functionality that affects users (new tools, flags, features), update the relevant documentation in `README.md` and/or `docs/`. Documentation must stay in sync with the behavior. + +## 4. Lint and run pre-commit hooks + +Before pushing, ensure: + +```bash +npm run lint +npm test +npm run build +``` + +The Husky hook enforces this on commits, but double-check locally to avoid CI failures. + +## 5. Pull Request Guidelines + +- Ensure all tests pass and lint checks succeed +- Add tests for new functionality +- Update documentation for user-facing changes +- Keep commits atomic and well-described +- Reference related issues in your PR description +- Use conventional commit format for PR titles + +--- + +## For Maintainers: Release Process + +This section is for project maintainers who manage releases. + +### Automated Release Workflow + +The project uses **Release Please** to automate the release process: + +1. **Release Please monitors commits** to the `main` branch +2. **Creates/updates a Release PR** with: + - Version bump in `package.json` (following semantic versioning) + - Updated `CHANGELOG.md` with categorized changes + - All unreleased commits grouped by type +3. **When the Release PR is merged**: + - A **draft GitHub Release** is created (not auto-published) + - Version tag is created (e.g., `v0.2.0`) + - CHANGELOG.md is committed to the repository + +### Publishing a Release + +After merging the Release Please PR: + +1. Go to [GitHub Releases](https://github.com/executeautomation/mcp-playwright/releases) +2. Find the draft release created by Release Please +3. Review the release notes: + - Verify all changes are categorized correctly + - Check that the version number is appropriate + - Add any additional context or migration notes if needed +4. Click **"Publish release"** when ready +5. The release will be published and users will be notified + +### Release Categories + +Changes are automatically grouped with emojis based on commit type: + +- πŸš€ **Features** (`feat:`) - New features or enhancements +- πŸ› **Bug Fixes** (`fix:`) - Bug fixes +- ⚑ **Performance Improvements** (`perf:`) - Performance optimizations +- πŸ“š **Documentation** (`docs:`) - Documentation updates +- πŸ§ͺ **Tests** (`test:`) - Test additions or updates +- ♻️ **Code Refactoring** (`refactor:`) - Code restructuring +- πŸ›  **Miscellaneous Chores** (`chore:`) - Maintenance tasks +- πŸ“¦ **Build System** (`build:`) - Build configuration changes +- πŸ”§ **Continuous Integration** (`ci:`) - CI/CD updates + +### Version Bumping Strategy + +Release Please determines version bumps based on commit types: + +- **Major** (1.0.0 β†’ 2.0.0): Commits with `BREAKING CHANGE:` in footer or `!` after type +- **Minor** (1.0.0 β†’ 1.1.0): Commits with `feat:` type +- **Patch** (1.0.0 β†’ 1.0.1): Commits with `fix:` type +- **No bump**: Other commit types (included in next feature/fix release) + +### Configuration Files + +- `release-please-config.json` - Release Please configuration +- `.release-please-manifest.json` - Tracks current version +- `.github/workflows/release-please.yml` - GitHub Actions workflow + +### Manual Release (Emergency) + +If you need to create a release manually: + +1. Update version in `package.json` +2. Update `CHANGELOG.md` +3. Commit: `chore: release v0.2.0` +4. Push to main +5. Manually create a GitHub Release with the tag +6. Update `.release-please-manifest.json` with the new version + +--- + +By contributing, you agree to follow these standards. We appreciate your help! diff --git a/DOCKER.md b/DOCKER.md index 11416a0..a28577a 100644 --- a/DOCKER.md +++ b/DOCKER.md @@ -1,89 +1,59 @@ # Docker Support for Playwright MCP Server -This document provides detailed instructions for running the Playwright MCP Server in Docker. +This document explains how to build and run the Playwright MCP Server in Docker. ## Overview - -The Playwright MCP Server can be containerized using Docker, providing: -- Isolated execution environment -- Consistent runtime across different systems -- Easy deployment and distribution -- Simplified dependency management +- Isolated, reproducible runtime with browsers and system deps included +- Easy deployment behind MCP gateways via Streamable HTTP transport +- Minimal host setup: only Docker/Compose required ## Prerequisites - -- Docker installed on your system ([Install Docker](https://docs.docker.com/get-docker/)) -- Docker Compose (optional, usually included with Docker Desktop) -- The project built locally (`npm run build`) +- Docker installed ([Install Docker](https://docs.docker.com/get-docker/)) +- Docker Compose (optional, usually bundled with Docker Desktop) ## Building the Docker Image +The provided multi-stage Dockerfile builds the app inside the container using the official Playwright base image (browsers and native deps preinstalled). -The Dockerfile is designed to work with pre-built artifacts and dependencies from your local build. Follow these steps: - -1. **Install production dependencies and build the project:** - ```bash - npm install --omit=dev - npm run build - ``` - - Or use the provided build script: - ```bash - chmod +x docker-build.sh - ./docker-build.sh - ``` - -2. **Manually build the Docker image:** - ```bash - docker build -t mcp-playwright:latest . - ``` - - Or with a specific tag: - ```bash - docker build -t mcp-playwright:1.0.6 . - ``` +```bash +docker build -t mcp-playwright:latest . +# or with a specific tag +docker build -t mcp-playwright:1.0.6 . +``` -**Important**: The Dockerfile copies `node_modules` and `dist` from your local build directory. Make sure you have installed dependencies with `--omit=dev` flag before building the Docker image to keep the image size minimal. +Why the official Playwright image? +- Browsers are already there—no slow first-run downloads +- Matches Playwright's supported environment for stable, reproducible runs +- Simpler Dockerfile: no extra `playwright install` or system packages ## Running the Server -### Interactive Mode (Recommended for MCP) - -Since MCP servers communicate via stdin/stdout, run the container in interactive mode: - +### STDIO (default MCP transport) +Run interactively so stdin/stdout stay open: ```bash docker run -i --rm mcp-playwright:latest ``` +Flags: `-i` keeps stdin open; `--rm` cleans up the container. -Flags explained: -- `-i`: Keep STDIN open for interactive communication -- `--rm`: Automatically remove the container when it exits -- `mcp-playwright:latest`: The image name and tag - -### Using Docker Compose - -A `docker-compose.yml` file is provided for convenience: - +### Docker Compose +A `docker-compose.yml` is included: ```bash -# Start the server docker compose run --rm playwright-mcp +``` -# Build and run -docker compose build -docker compose run --rm playwright-mcp +### Streamable HTTP mode +Expose the HTTP transport (default port `8000`, path `/mcp`): +```bash +docker run --rm -p 8000:8000 -v /data:/data \ + mcp-playwright:latest \ + node dist/index.js --http --insecure --host-name localhost --listen 0.0.0.0 --path /mcp ``` +- `--host-name` should match the public hostname clients/gateways use; `--insecure` keeps links `http`, omit for `https` behind a proxy. +- Resource URLs look like `http://:8000/mcp/resources///`. +- Mount `/data` if you want session-scoped artifacts persisted outside the container. ## Integration with MCP Clients -### Claude Desktop Configuration - -To use the Dockerized MCP server with Claude Desktop, update your configuration file: - -**Location**: -- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` -- Windows: `%APPDATA%\Claude\claude_desktop_config.json` -- Linux: `~/.config/Claude/claude_desktop_config.json` - -**Configuration:** +### Claude Desktop ```json { "mcpServers": { @@ -95,10 +65,7 @@ To use the Dockerized MCP server with Claude Desktop, update your configuration } ``` -### VS Code MCP Extension - -For VS Code with MCP extension: - +### VS Code MCP extension ```json { "name": "playwright-docker", @@ -108,175 +75,34 @@ For VS Code with MCP extension: ``` ## Environment Variables - -You can pass environment variables to configure the server: - -```bash -docker run -i --rm \ - -e PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 \ - mcp-playwright:latest -``` - -In docker-compose.yml: -```yaml -services: - playwright-mcp: - environment: - - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 - - NODE_ENV=production -``` +- `PLAYWRIGHT_HEADLESS=1` is set in the image by default; override it to see a headed browser if you add a display. +- Pass additional env vars with `-e` or via Compose `environment` entries. ## Volume Mounts - -If you need to persist data or share files with the container: - +Persist or inspect generated artifacts by mounting `/data`: ```bash -docker run -i --rm \ - -v $(pwd)/data:/app/data \ - mcp-playwright:latest -``` - -In docker-compose.yml: -```yaml -services: - playwright-mcp: - volumes: - - ./data:/app/data - - ./screenshots:/app/screenshots +docker run -i --rm -v $(pwd)/data:/data mcp-playwright:latest ``` ## Troubleshooting +- **Container exits immediately**: run with `-i` so stdin stays open (`docker run -i --rm ...`). +- **No download URL in HTTP mode**: ensure you started with `--http` and set `--host-name`/`--insecure` appropriately; check the exposed port/path. +- **Port already in use**: change `--port` (and publish it) when starting in HTTP mode. +- **Permission issues on volumes**: mount with a user id/group that can write to the host path (e.g., `--user $(id -u):$(id -g)` on Linux). -### Container Exits Immediately - -MCP servers wait for input on stdin. Ensure you're running with `-i` flag: -```bash -docker run -i --rm mcp-playwright:latest -``` - -### Browser Not Found - -The Docker image skips browser downloads by default to reduce size. Playwright will download browsers on first use. To pre-install browsers, create a custom Dockerfile: - -```dockerfile -FROM mcp-playwright:latest - -# Install Playwright browsers -RUN npx playwright install chromium --with-deps -``` - -### Permission Issues - -If you encounter permission issues with mounted volumes: -```bash -docker run -i --rm \ - -v $(pwd)/data:/app/data \ - --user $(id -u):$(id -g) \ - mcp-playwright:latest -``` - -## Advanced Usage - -### Custom Network Configuration - -To run the server on a custom network: - -```bash -docker network create mcp-network -docker run -i --rm --network mcp-network mcp-playwright:latest -``` - -### Resource Limits - -Limit CPU and memory usage: - -```bash -docker run -i --rm \ - --cpus="2.0" \ - --memory="2g" \ - mcp-playwright:latest -``` - -In docker-compose.yml: -```yaml -services: - playwright-mcp: - deploy: - resources: - limits: - cpus: '2.0' - memory: 2G -``` - -### Health Checks - -Add a health check to your docker-compose.yml: - -```yaml -services: - playwright-mcp: - healthcheck: - test: ["CMD", "node", "-e", "process.exit(0)"] - interval: 30s - timeout: 10s - retries: 3 -``` - -## Image Size Optimization - -The current Dockerfile is optimized for size: -- Uses Debian-based slim Node.js image (~200MB) -- Copies pre-built artifacts from host -- Production dependencies only -- Skips browser downloads by default - -Current image size: ~200MB (without browsers) +## Image Notes +- Built from the official Playwright base image with browsers preinstalled. +- Multi-stage build prunes dev dependencies for a lean runtime layer. ## Security Considerations - -1. **Run as non-root user** (optional but recommended): - ```dockerfile - FROM mcp-playwright:latest - USER node - ``` - -2. **Read-only root filesystem** (if applicable): - ```bash - docker run -i --rm --read-only mcp-playwright:latest - ``` - -3. **Scan for vulnerabilities:** - ```bash - docker scan mcp-playwright:latest - ``` - -## Building from Source in Docker - -If you prefer to build inside Docker (not using pre-built dist): - -```dockerfile -FROM node:20-alpine AS builder - -WORKDIR /app -COPY package*.json ./ -ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 -RUN npm ci - -COPY src ./src -COPY tsconfig.json ./ -RUN npm run build - -FROM node:20-alpine -WORKDIR /app -COPY --from=builder /app/dist ./dist -COPY --from=builder /app/package*.json ./ -RUN npm ci --only=production -CMD ["node", "dist/index.js"] -``` +- Run as a non-root user if your environment requires it: + ```dockerfile + FROM mcp-playwright:latest + USER pwuser + ``` +- Consider read-only root fs when suitable: `docker run -i --rm --read-only mcp-playwright:latest` +- Scan images regularly (`docker scan mcp-playwright:latest`). ## Support - -For issues related to Docker: -- Check the main [README.md](./README.md) for general information -- Report Docker-specific issues on [GitHub Issues](https://github.com/executeautomation/mcp-playwright/issues) -- Tag your issue with `docker` label +- See the main README for general usage +- File Docker-specific issues on GitHub with the `docker` label \ No newline at end of file diff --git a/Dockerfile b/Dockerfile index 70e7e62..e068a1d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,24 +1,32 @@ -# Multi-stage Dockerfile for MCP Playwright Server -# This Dockerfile expects the project to be built before running docker build -# Run `npm install --omit=dev && npm run build` before building the image +FROM mcr.microsoft.com/playwright:v1.56.1-noble AS build +WORKDIR /app -FROM node:20-slim AS base +# 1) Copy manifests first for cacheable deps layer +COPY package.json package-lock.json tsconfig*.json ./ -# Set working directory -WORKDIR /app +# 2) Install deps INCLUDING dev deps, but DO NOT run lifecycle scripts yet +RUN npm ci --include=dev --ignore-scripts + +# 3) Now copy sources +COPY src ./src -# Copy package files for reference -COPY package*.json ./ +# 4) Build explicitly +RUN npm run build -# Copy node_modules from host (production dependencies only) -# Make sure to run `npm install --omit=dev` before building -COPY node_modules ./node_modules +# 5) Prune dev deps for slim runtime node_modules +RUN npm prune --omit=dev && npm cache clean --force + + +FROM mcr.microsoft.com/playwright:v1.56.1-noble AS runtime +WORKDIR /app +ENV PLAYWRIGHT_HEADLESS=1 -# Copy the pre-built application -COPY dist ./dist +# Data dir for resources (mount a volume here in prod) +RUN mkdir -p /data -# Expose stdio for MCP communication -# MCP servers communicate via stdio, so no port exposure needed +COPY --from=build /app/package.json /app/package-lock.json ./ +COPY --from=build /app/node_modules ./node_modules +COPY --from=build /app/dist ./dist -# Run the server -CMD ["node", "dist/index.js"] \ No newline at end of file +EXPOSE 8000 +ENTRYPOINT ["node", "dist/index.js"] diff --git a/README.md b/README.md index 4acdbc9..4cc0148 100644 --- a/README.md +++ b/README.md @@ -22,16 +22,28 @@ # Playwright MCP Server 🎭 -[![smithery badge](https://smithery.ai/badge/@executeautomation/playwright-mcp-server)](https://smithery.ai/server/@executeautomation/playwright-mcp-server) +> πŸš€ Active Fork of executeautomation/mcp-playwright +> This repository is an actively maintained continuation of the original MCP Playwright server: +> πŸ‘‰ https://github.com/executeautomation/mcp-playwright + +![Release](https://img.shields.io/github/v/release/aakashh242/mcp-playwright?sort=semver) +![Latest Tag](https://img.shields.io/github/v/tag/aakashh242/mcp-playwright?label=tag) +![Build](https://img.shields.io/github/actions/workflow/status/aakashh242/mcp-playwright/build.yml?branch=main&label=build) +![Lint](https://img.shields.io/github/actions/workflow/status/aakashh242/mcp-playwright/build.yml?branch=main&label=lint) +![Unit Tests](https://img.shields.io/github/actions/workflow/status/aakashh242/mcp-playwright/build.yml?branch=main&label=tests) +[![Coverage](https://codecov.io/gh/aakashh242/mcp-playwright/graph/badge.svg)](https://codecov.io/gh/aakashh242/mcp-playwright) +[![Release Please](https://img.shields.io/github/actions/workflow/status/aakashh242/mcp-playwright/release-please.yml?branch=main&label=release-please)](https://github.com/aakashh242/mcp-playwright/actions/workflows/release-please.yml) +[![Docker Publish](https://img.shields.io/github/actions/workflow/status/aakashh242/mcp-playwright/docker-publish.yml?branch=main&label=docker)](https://github.com/aakashh242/mcp-playwright/actions/workflows/docker-publish.yml) A Model Context Protocol server that provides browser automation capabilities using Playwright. This server enables LLMs to interact with web pages, take screenshots, generate test code, web scraps the page and execute JavaScript in a real browser environment. +It is optimized for QA and E2E automation: screenshots, logs, assertions, API testing, plus full MCP HTTP/gateway support β€” built on the same Playwright foundations, complementary to Microsoft’s server. mcp-playwright MCP server ## Screenshot ![Playwright + Claude](image/playwright_claude.png) -## [Documentation](https://executeautomation.github.io/mcp-playwright/) | [API reference](https://executeautomation.github.io/mcp-playwright/docs/playwright-web/Supported-Tools) +## [Documentation](https://aakashh242.github.io/mcp-playwright/) | [API reference](https://aakashh242.github.io/mcp-playwright/docs/playwright-web/Supported-Tools) ## Installation @@ -96,50 +108,137 @@ Here's the Claude Desktop configuration to use the Playwright server: } ``` -## Docker Support +## Streamable HTTP mode -The Playwright MCP Server can be run in Docker for isolated and containerized execution. +The server supports the MCP Streamable HTTP transport so it can run behind gateways. -### Building the Docker Image +- Start in HTTP mode (defaults to port `8000` and path `/mcp`): + ```bash + npx @executeautomation/playwright-mcp-server --http + ``` +- Override the port or path: + ```bash + npx @executeautomation/playwright-mcp-server --http --port 3000 --path /custom-mcp + ``` -Before building the Docker image, you need to build the TypeScript project with production dependencies: +### How files are shared in HTTP mode +- Generated artifacts (screenshots, PDFs, console logs, generated tests) are written into `/data//.` on the server. +- Each Streamable HTTP session gets its own isolated resource namespace; links are only valid for that session and expire after the configured TTL (`--resource-ttl`, default 600s). Session close or TTL expiry removes the files and their directories. +- Tool results return `resourceLinks` pointing to download URLs: + `{scheme}://{host}:{port}{path}/resources/{sessionId}/{resourceId}/{filename}` + (host from `--host-name`, scheme from `--insecure`, path from `--path`, default `/mcp`). +- In stdio mode, resource linking is disabled; tools only emit local paths. -```bash -# Install production dependencies and build -npm install --omit=dev -npm run build +This scope-based sharing prevents content leakage between sessions/clients while still giving HTTP clients and gateways stable download URIs. -# Build the Docker image -docker build -t mcp-playwright . +### Uploads in HTTP mode +- The `playwright_upload_file` tool accepts a local `filePath` only in stdio mode. In HTTP mode, you must first upload the file and pass `uploadResourceUri`. +- Get the session-scoped upload URL by calling `construct_upload_url` (HTTP mode only). It returns a POST multipart endpoint like `{path}/uploads/{sessionId}`; the session ID is embedded in the URL so no header is usually needed. +- Upload with `multipart/form-data` (field `file`). On success, the server responds with a session-scoped `resourceUri` such as `mcp-uploads:///`. +- Then call `playwright_upload_file` with `uploadResourceUri` to attach the uploaded file to the file input. Uploads are isolated per session/client like other resources. +- Agents must be able to run terminal/CLI commands (curl on Linux/macOS, `Invoke-WebRequest`/`iwr` on Windows) to upload the file before calling `playwright_upload_file` in HTTP mode. +- Stdio mode continues to use local `filePath`; HTTP mode prefers uploaded resources. + +### Client Configuration + +Claude Desktop / VS Code (`mcp.json`): +```json +{ + "mcpServers": { + "playwright": { + "transport": { + "type": "http", + "url": "http://localhost:8000/mcp" + } + } + } +} ``` +Adjust `url` to match your host/port/path and use `https` if terminated by a proxy. + + +## CLI flags +- `--http`: Enable Streamable HTTP transport (default: off; stdio is used when omitted). +- `--port `: HTTP port (default: `8000`, only relevant when `--http` is set). +- `--path `: Base HTTP path (default: `/mcp`, only relevant when `--http` is set). +- `--host-name `: Hostname used in generated download URLs (default: system hostname, only relevant when `--http` is set). +- `--listen
`: Bind address for the HTTP server (default: `0.0.0.0`, only relevant when `--http` is set). +- `--insecure`: Use `http` scheme for download links; omit to use `https` (only relevant when `--http` is set). +- `--resource-ttl `: TTL for generated resources (default: `600` seconds; only affects HTTP mode). +- `--static-user-agent`: Disable the default randomized User-Agent rotation (by default, each new browser launch picks a modern UA to reduce bot detection/CAPTCHAs). -Or use the provided convenience script: +## Agents / Prompts +- A starter agent prompt is provided in [`AGENTS.md`](AGENTS.md). Create an agent in VS Code (or your client) using that prompt as a template; customize as needed. +- For file uploads in HTTP mode, ensure the agent has permission to run terminal/CLI commands (curl on Linux/macOS, `Invoke-WebRequest`/`iwr` on Windows) because uploads are performed via the session-specific HTTP endpoint before calling `playwright_upload_file`. + +## Contributing +- Read the [CONTRIBUTING.md](CONTRIBUTING.md) guidelines for required tooling (pre-commit hooks, lint/test/build steps, conventional commits, documentation updates). +- The CI workflow enforces the same standards; please mirror them locally before opening a PR. + +## Available Tools +| Tool | Purpose | Notes | +| --- | --- | --- | +| `playwright_navigate` | Open a URL with optional viewport/headless/browser type | Browser launched if needed | +| `playwright_screenshot` | Capture screenshot of page/element | HTTP mode returns resource link | +| `playwright_save_as_pdf` | Save page as PDF | HTTP mode returns resource link | +| `playwright_console_logs` | Retrieve browser console logs with filters | Log file registered when saved | +| `playwright_upload_file` | Set a file into an `` | In HTTP mode, upload file via `construct_upload_url` then pass `uploadResourceUri`; stdio uses `filePath` | +| `construct_upload_url` (HTTP) | Return session-scoped upload URL/instructions | Use POST multipart (`file` field) to get `uploadResourceUri` | +| `playwright_click` / `playwright_fill` / `playwright_select` / `playwright_hover` / `playwright_drag` / `playwright_press_key` | Core page interactions | Browser required | +| `playwright_iframe_click` / `playwright_iframe_fill` | Interact inside iframes | Provide iframe selector | +| `playwright_get_visible_text` / `playwright_get_visible_html` | Read visible page content | HTML tool supports cleaning options | +| `playwright_custom_user_agent` | Override User-Agent for browser context | | +| `playwright_go_back` / `playwright_go_forward` / `playwright_close` | Navigation or close browser | | +| `playwright_evaluate` | Execute JS in page | | +| `playwright_expect_response` / `playwright_assert_response` | Wait for and assert network responses | | +| `playwright_get` / `playwright_post` / `playwright_put` / `playwright_patch` / `playwright_delete` | HTTP API helpers | | +| `start_codegen_session` / `end_codegen_session` / `get_codegen_session` / `clear_codegen_session` | Record and generate Playwright tests | Generated tests are exposed as resources in HTTP mode | + +## Docker Support + +The Playwright MCP Server is available as a pre-built Docker image with all browsers and system dependencies included. This avoids slow first-run downloads and version drift. + +### Using Docker + +To use Docker, pull the latest image from GitHub Container Registry: ```bash -chmod +x docker-build.sh -./docker-build.sh +docker pull ghcr.io/aakashh242/mcp-playwright:latest ``` -### Running with Docker +#### Running with Docker directly -You can run the MCP server using Docker in several ways: +```bash +# Run the server (stdin/stdout communication) +docker run -i --rm ghcr.io/aakashh242/mcp-playwright:latest +``` -#### Using Docker directly +#### Streamable HTTP mode in Docker ```bash -# Run the server (stdin/stdout communication) -docker run -i mcp-playwright +docker run --rm -p 8000:8000 -v /data:/data \ + ghcr.io/aakashh242/mcp-playwright:latest \ + node dist/index.js --http --insecure --host-name localhost --listen 0.0.0.0 --path /mcp ``` -#### Using Docker Compose +- Mount `/data` to persist session-scoped artifacts if desired. +- Adjust `--host-name` to the public hostname your clients/gateways use. Use `--insecure` for `http`; omit it for `https` behind a terminating proxy. +- Resource download URLs will be `http://:8000/mcp/resources///` by default. +- The container default is headless (`PLAYWRIGHT_HEADLESS=1`) and the Playwright base image already includes browsers. -A `docker-compose.yml` file is provided for easier management: +#### Using Docker Compose (recommended for production HTTP) + +Use the provided `docker-compose.yml` to run streamable HTTP with sensible defaults: ```bash -# Run the server with docker-compose -docker compose run --rm playwright-mcp +docker compose up -d ``` +Defaults: +- HTTP mode with `--path=/mcp`, `--listen=0.0.0.0`, `--port=8000`, and a `--host-name` placeholder (replace with your public hostname). +- Ports: `8000:8000` +- Volumes: `./data/app-data:/app/data` and `./data/resource-data:/data` for persisted session artifacts. + ### Using Docker with MCP Clients To use the Dockerized server with Claude Desktop or other MCP clients, you can configure them to use Docker: @@ -149,13 +248,24 @@ To use the Dockerized server with Claude Desktop or other MCP clients, you can c "mcpServers": { "playwright": { "command": "docker", - "args": ["run", "-i", "--rm", "mcp-playwright"] + "args": ["run", "-i", "--rm", "ghcr.io/aakashh242/mcp-playwright:latest"] } } } ``` -**Note**: The Docker image uses a Debian-based slim Node.js image and includes only the core dependencies. Playwright browsers are not pre-installed in the container to keep the image size small. The browsers will be downloaded on first use if needed. +### Building Locally + +If you need to build the Docker image locally: + +The Docker build handles dependencies and the TypeScript build for you: + +```bash +docker build -t mcp-playwright . +``` + +Then use `mcp-playwright` instead of `ghcr.io/aakashh242/mcp-playwright:latest` in the commands above. + ## Testing @@ -193,4 +303,4 @@ Our server name is `playwright-mcp`. Please ensure your tool names are short eno ## Star History -[![Star History Chart](https://api.star-history.com/svg?repos=executeautomation/mcp-playwright&type=Date)](https://star-history.com/#executeautomation/mcp-playwright&Date) +[![Star History Chart](https://api.star-history.com/svg?repos=aakashh242/mcp-playwright&type=Date)](https://star-history.com/#aakashh242/mcp-playwright&Date) diff --git a/RELEASES.md b/RELEASES.md new file mode 100644 index 0000000..5ae95e6 --- /dev/null +++ b/RELEASES.md @@ -0,0 +1,164 @@ +# Release Management + +This project uses [Conventional Commits](https://www.conventionalcommits.org/), [Release Please](https://github.com/googleapis/release-please), and GitHub Actions to automate versions, changelog generation, and releases. + +## How Releases Work + +### 1. Conventional Commits Drive Automation + +All commits and PR titles must follow conventional commit format: + +``` +(): +``` + +**Version Bumps**: +- `feat:` β†’ Minor version bump (0.1.0 β†’ 0.2.0) +- `fix:` β†’ Patch version bump (0.1.0 β†’ 0.1.1) +- `BREAKING CHANGE:` or `feat!:` β†’ Major version bump (0.1.0 β†’ 1.0.0) +- `chore:`, `docs:`, `test:`, etc. β†’ No version bump (included in next release) + +### 2. Release Please Creates Release PRs + +When commits are pushed to `main`, Release Please: +- Analyzes commits since the last release +- Determines the next version based on commit types +- Creates or updates a **Release PR** (e.g., `chore: release mcp-playwright 0.2.0`) with: + - Updated `CHANGELOG.md` with categorized changes + - Bumped version in `package.json` + - Tag proposal (e.g., `v0.2.0`) + +### 3. Merging the Release PR + +When the Release PR is merged: +- A **draft GitHub Release** is created (NOT auto-published) +- A Git tag is created (e.g., `v0.2.0`) +- `CHANGELOG.md` is committed to the repository +- Docker build workflow is triggered (if configured) + +### 4. Publishing the Release + +**Important**: Releases are created as **drafts** and require manual publishing: + +1. Go to [GitHub Releases](https://github.com/executeautomation/mcp-playwright/releases) +2. Find the draft release created by Release Please +3. Review the release notes +4. Add any additional context or migration notes if needed +5. Click **"Publish release"** when ready + +This ensures you have full control over when releases go live. + +## Changelog Categories + +Changes are automatically grouped with emojis based on commit type: + +- πŸš€ **Features** - `feat:` commits +- πŸ› **Bug Fixes** - `fix:` commits +- ⚑ **Performance Improvements** - `perf:` commits +- βͺ **Reverts** - `revert:` commits +- πŸ“š **Documentation** - `docs:` commits +- πŸ’Ž **Styles** - `style:` commits +- πŸ›  **Miscellaneous Chores** - `chore:` commits +- ♻️ **Code Refactoring** - `refactor:` commits +- πŸ§ͺ **Tests** - `test:` commits +- πŸ“¦ **Build System** - `build:` commits +- πŸ”§ **Continuous Integration** - `ci:` commits + +## Contributor Guidelines + +### Writing Commits + +Use conventional commit format for all commits: + +```bash +# Good examples +feat: add browser navigation tool +feat(api): add support for custom headers +fix: resolve timeout in screenshot capture +fix(upload): handle large files correctly +docs: update installation instructions +test: add integration tests for browser tools + +# Breaking changes +feat!: change API response format +# OR +feat: change API response format + +BREAKING CHANGE: The API now returns JSON instead of XML +``` + +### Pull Request Titles + +PR titles must also follow conventional commit format: + +``` +feat: add new browser automation features +fix: resolve navigation timeout issues +docs: update API documentation +``` + +CI will validate commit messages and PR titles using commitlint. + +## Admin Notes for Release PRs + +### Reviewing Release PRs + +Before merging a Release Please PR: +- βœ… Verify the version bump is appropriate (major/minor/patch) +- βœ… Review the CHANGELOG.md updates +- βœ… Check that all changes since last release are included +- βœ… Ensure categorization is correct +- βœ… Edit the release PR description if needed + +### Adjusting Releases + +If you need to modify the release: +- Edit the CHANGELOG.md in the Release PR +- Adjust the version number if needed +- Update the PR title to match the new version +- Commit changes directly to the release PR branch + +### After Merging + +Once the Release PR is merged: +1. A draft release is automatically created +2. Review the draft on GitHub Releases page +3. Add any additional release notes or migration guides +4. Publish the release manually when ready +5. Docker images will be built and tagged automatically (if applicable) + +### Emergency/Manual Releases + +If you need to create a release manually: + +1. Update version in `package.json` +2. Update `CHANGELOG.md` with changes +3. Commit: `chore: release v0.2.0` +4. Push to `main` +5. Manually create GitHub Release with the tag +6. Update `.release-please-manifest.json` with new version + +## Configuration Files + +- **`release-please-config.json`** - Main configuration with changelog sections and versioning strategy +- **`.release-please-manifest.json`** - Tracks current version (updated by Release Please) +- **`.github/workflows/release-please.yml`** - GitHub Actions workflow + +## CI/CD Integration + +- **Build workflow** (`build.yml`) runs on all pushes and validates commits +- **Release Please workflow** (`release-please.yml`) runs on pushes to `main` +- **Docker workflow** (if configured) builds images when releases are published + +## Best Practices + +βœ… **Always use conventional commits** - Enables automatic versioning +βœ… **Keep commits atomic** - One logical change per commit +βœ… **Write descriptive commit bodies** - Explain the "why" not just the "what" +βœ… **Review Release PRs carefully** - They determine what users see +βœ… **Test before publishing** - Drafts give you time to verify everything works +βœ… **Update docs with features** - Keep documentation in sync with releases + +--- + +For more details on contributing and commit format, see [CONTRIBUTING.md](CONTRIBUTING.md). diff --git a/biome.json b/biome.json new file mode 100644 index 0000000..1c40096 --- /dev/null +++ b/biome.json @@ -0,0 +1,20 @@ +{ + "$schema": "https://biomejs.dev/schemas/2.3.7/schema.json", + "files": { + "ignoreUnknown": false + }, + "linter": { + "enabled": true, + "rules": { + "recommended": true + } + }, + "formatter": { + "enabled": true, + "formatWithErrors": false, + "indentStyle": "space", + "indentWidth": 2, + "lineWidth": 120 + } +} + diff --git a/commitlint.config.js b/commitlint.config.js new file mode 100644 index 0000000..3f5e287 --- /dev/null +++ b/commitlint.config.js @@ -0,0 +1 @@ +export default { extends: ['@commitlint/config-conventional'] }; diff --git a/docker-build.sh b/docker-build.sh deleted file mode 100755 index 65ba3d4..0000000 --- a/docker-build.sh +++ /dev/null @@ -1,23 +0,0 @@ -#!/bin/bash -# Build script for Docker image -# This ensures the project and dependencies are properly prepared - -set -e - -echo "Building MCP Playwright Server for Docker..." - -# Clean and install production dependencies -echo "Installing production dependencies..." -npm install --omit=dev - -# Build the TypeScript project -echo "Building TypeScript project..." -npm run build - -# Build the Docker image -echo "Building Docker image..." -docker build -t mcp-playwright:latest . - -echo "Build complete! Image: mcp-playwright:latest" -echo "" -echo "Run with: docker run -i --rm mcp-playwright:latest" diff --git a/docker-compose.yml b/docker-compose.yml index 3608919..dfa5cd8 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -1,18 +1,18 @@ +# Recommended production deployment (Streamable HTTP mode) services: playwright-mcp: build: context: . dockerfile: Dockerfile - image: mcp-playwright:latest + image: ghcr.io/aakashh242/mcp-playwright:latest container_name: playwright-mcp-server stdin_open: true tty: true - # MCP servers communicate via stdio - # You can interact with this container using: - # docker compose run --rm playwright-mcp + command: ["--http", "--listen", "0.0.0.0", "--port", "8000", "--path", "/mcp", "--host-name", ""] + ports: + - "8000:8000" environment: - # Skip browser download in container - PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 - # Optionally mount a volume for persistent data - # volumes: - # - ./data:/app/data + volumes: + - ./data/app-data:/app/data + - ./data/resource-data:/data diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..487d4d0 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1,3 @@ +CHANGELOG.md +docker-compose.yml + diff --git a/docs/docs/ai-courses/AIAgents.mdx b/docs/docs/ai-courses/AIAgents.mdx deleted file mode 100644 index 2380ed2..0000000 --- a/docs/docs/ai-courses/AIAgents.mdx +++ /dev/null @@ -1,74 +0,0 @@ ---- -sidebar_position: 3 ---- - -import YouTubeVideoEmbed from '@site/src/components/HomepageFeatures/YouTubeVideoEmbed'; - -# πŸ§ πŸ€– Build & Test AI Agents, ChatBots, and RAG with Ollama & Local LLM - -
- -
- ---- - -:::info πŸ’‘ **Note** -All the courses are available on **Udemy**, and they almost always have a **`coupon code`** available. -For discounts, please feel free to reach out at **[karthik@techgeek.co.in](mailto:karthik@techgeek.co.in)**. - -🎯 **Course Link:** -[Build & Test AI Agents, ChatBots, and RAG with Ollama & Local LLM](https://www.udemy.com/course/build-ai-agent-chatbot-rag-langchain-local-llm/) -::: - ---- - -## πŸ“š **Course Description** - -This course is designed for complete beginnersβ€”even if you have **zero knowledge of LangChain**, you’ll learn step-by-step how to build **LLM-based applications** using **local Large Language Models (LLMs)**. - -We’ll go beyond development and dive into **evaluating and testing AI agents**, **RAG applications**, and **chatbots** using **RAGAs** to ensure they deliver **accurate** and **reliable results**, following key industry metrics for **AI performance**. - ---- - -### πŸš€ **What You’ll Learn** - -- **🧠 Fundamentals of LangChain & LangSmith** - Get a solid foundation in building and testing **LLM-based applications**. - -- **πŸ’¬ Chat Message History in LangChain** - Learn how to store conversation data for **chatbots** and **AI agents**. - -- **βš™οΈ Running Parallel & Multiple Chains** - Master advanced techniques like **RunnableParallels** to optimize your **LLM workflows**. - -- **πŸ€– Building Chatbots with LangChain & Streamlit** - Create chatbots with **message history** and an interactive **UI**. - -- **πŸ› οΈ Tools & Tool Chains in LLMs** - Understand the power of **Tooling**, **Custom Tools**, and how to build **Tool Chains** for **AI applications**. - -- **πŸ§‘β€πŸ’» Creating AI Agents with LangChain** - Implement **AI agents** that can interact dynamically with **RAG applications**. - -- **πŸ“š Implementing RAG with Vector Stores & Local Embeddings** - Develop robust **RAG solutions** with local **LLM embeddings**. - -- **πŸ”§ Using AI Agents & RAG with Tooling** - Learn how to integrate **Tooling** effectively while building **LLM Apps**. - -- **🚦 Optimizing & Debugging AI Applications with LangSmith** - Enhance your **AI models** and **applications** with **LangSmith's debugging** and **optimization tools**. - -- **πŸ§ͺ Evaluating & Testing LLM Applications with RAGAs** - Apply **hands-on testing strategies** to validate **RAG** and **AI agent** performance. - -- **πŸ“Š Real-world Projects & Assessments** - Gain practical experience with **RAGAs** and learn to assess the quality and reliability of **AI solutions**. - ---- - -## 🎯 **Learning Experience** - -This entire course is taught inside a **Jupyter Notebook** with **Visual Studio**, offering an **interactive**, **guided experience** where you can **run the code seamlessly** and **follow along effortlessly**. - -By the end of this course, you’ll have the **confidence** to **build**, **test**, and **optimize AI-powered applications** with ease! \ No newline at end of file diff --git a/docs/docs/ai-courses/GenAICourse.mdx b/docs/docs/ai-courses/GenAICourse.mdx deleted file mode 100644 index 50f0452..0000000 --- a/docs/docs/ai-courses/GenAICourse.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -sidebar_position: 1 ---- - -import YouTubeVideoEmbed from '@site/src/components/HomepageFeatures/YouTubeVideoEmbed'; - -# πŸ€– Using Generative AI in Software Automation Testing - -
- -
---- - -:::info πŸ’‘ **Note** -All the courses are available on Udemy, and they almost always have a `coupon code` available. -For discounts, please feel free to reach out at **[karthik@techgeek.co.in](mailto:karthik@techgeek.co.in)**. - -🎯 **Course Link:** -[Generative AI in Software Automation Testing](https://www.udemy.com/course/generative-ai-in-software-automation-testing/) -::: - ---- - -## πŸ“š **Course Description** - -This course is crafted for everyone, whether you're new to Software Testing or an experienced professional. Unlock the full potential of **Generative AI** and transform your testing process into something **faster**, **smarter**, and **more efficient**. - -### πŸš€ **What You’ll Master** - -- **🧠 Introduction to Generative AI:** - Understand the foundations of Gen AI and its role in Software Testing. - -- **πŸ’» Running Large Language Models (LLMs) Locally:** - Learn how to run models on your machine without paying for external services. - -- **πŸ“ Manual Testing with Gen AI:** - Generate manual test cases, test data, and test requirements using grounded Models with the power of AI and RAG. - -- **πŸ€– Automated UI Testing:** - Leverage AI to write, refactor, and optimize automated tests for UI applications. - -- **🎭 Playwright UI Testing:** - Use Playwright and AI-driven tools to create smart test scripts and handle complex workflows. - -- **🚫 No-code Automation with TestRigor:** - Create powerful automation suites in plain English, even automating SMS, phone calls, and intricate tables. - -- **πŸ”— API Testing:** - Harness PostBots and Gen AI to streamline API testing. - -- **🧬 Using Gen AI APIs:** - Add intelligence to your Test Automation code using OpenAI APIs. - -- **πŸ“ Model Context Protocol (MCP):** - Run Playwright tests for UI and APIs by leveraging the power of MCP. - ---- - -By the end of this course, you'll have a deep understanding of how **Generative AI** can supercharge your testing process. With hands-on experience, you'll be able to use **AI-enhanced tools** and **LLMs** to simplify complex testing tasks, making your work smoother and more efficient. - - diff --git a/docs/docs/ai-courses/MachineLearning.mdx b/docs/docs/ai-courses/MachineLearning.mdx deleted file mode 100644 index 63b00fd..0000000 --- a/docs/docs/ai-courses/MachineLearning.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -sidebar_position: 2 ---- - -import YouTubeVideoEmbed from '@site/src/components/HomepageFeatures/YouTubeVideoEmbed'; - -# 🧠 Understand, Test, and Fine-tune AI Models with Hugging Face - -
- -
- ---- - -:::info πŸ’‘ **Note** -All the courses are available on **Udemy**, and they almost always have a **`coupon code`** available. -For discounts, please feel free to reach out at **[karthik@techgeek.co.in](mailto:karthik@techgeek.co.in)**. - -🎯 **Course Link:** -[Understand, Test, and Fine-tune AI Models with Hugging Face](https://www.udemy.com/course/ai-with-huggingface/) -::: - ---- - -## πŸ“š **Course Description** - -This course provides a complete journey into **Understanding, Testing, and Fine-tuning AI Models** using the **Hugging Face** library. Whether you are a beginner or an experienced engineer, this course equips you with **hands-on expertise** in every step of the **machine learning pipeline**, from **basic concepts** to **advanced model testing**, **fine-tuning**, and **deployment**. - ---- - -### πŸš€ **What You’ll Learn** - -1. **πŸ“ˆ Introduction to Machine Learning:** - Lay a strong foundation by exploring key ML concepts and essential terminology. - -2. **πŸ“Š Working with Natural Language Processing (NLP) Libraries:** - Learn how to process, analyze, and derive insights from textual data using popular NLP tools. - -3. **πŸ’‘ Deep Dive into the Transformers Library:** - Master Hugging Face’s Transformers, the industry standard for building state-of-the-art **NLP** and **LLM** solutions. - -4. **🧠 Working with Large Language Models (LLMs):** - Explore multiple methods to interact with and utilize **LLMs** for diverse real-world applications. - -5. **πŸ§ͺ Functional Testing of AI Models:** - Ensure your models perform reliably across different scenarios using systematic testing strategies. - -6. **βš–οΈ Bias and Fairness Testing:** - Implement techniques to detect and mitigate unintended bias, promoting ethical and fair **AI practices**. - -7. **πŸ“ Evaluating AI Models:** - Measure performance with robust metrics and refine your models for optimal results. - -8. **πŸ€– Working with AI Agents:** - Build, configure, and integrate **intelligent agents** into your workflows. - -9. **πŸ”¬ Fine-tuning and Training AI Models:** - Customize pre-trained models or create your own from scratch to meet specific project requirements. - ---- - -By the end of this course, you’ll gain the **knowledge** and **practical experience** needed to confidently **develop**, **test**, and **optimize** your own **Transformer-based models** and **LLMs**, empowering you to thrive in the rapidly evolving world of **AI**. \ No newline at end of file diff --git a/docs/docs/ai-courses/_category_.json b/docs/docs/ai-courses/_category_.json deleted file mode 100644 index d0fede2..0000000 --- a/docs/docs/ai-courses/_category_.json +++ /dev/null @@ -1,9 +0,0 @@ -{ - "label": "AI Courses to Learn", - "position": 6, - "collapsed": false, - "link": { - "type": "generated-index", - "description": "AI Courses which helps you learn more on Using it for Testing and Development" - } -} diff --git a/docs/docs/ai-courses/img/GenAI.png b/docs/docs/ai-courses/img/GenAI.png deleted file mode 100644 index 6becf9e..0000000 Binary files a/docs/docs/ai-courses/img/GenAI.png and /dev/null differ diff --git a/docs/docs/getting-started/_category_.json b/docs/docs/getting-started/_category_.json new file mode 100644 index 0000000..1162872 --- /dev/null +++ b/docs/docs/getting-started/_category_.json @@ -0,0 +1,9 @@ +{ + "label": "Getting Started", + "position": 2, + "collapsed": false, + "link": { + "type": "generated-index", + "title": "Getting Started" + } +} diff --git a/docs/docs/getting-started/cli-flags.mdx b/docs/docs/getting-started/cli-flags.mdx new file mode 100644 index 0000000..788928f --- /dev/null +++ b/docs/docs/getting-started/cli-flags.mdx @@ -0,0 +1,36 @@ +--- +sidebar_position: 3 +title: CLI Flags +--- + +# CLI Flags + +| Flag | Description | +| --- | --- | +| `--http` | Enable Streamable HTTP transport instead of STDIO. | +| `--port ` | HTTP port (default `8000`). | +| `--path ` | Base HTTP path (default `/mcp`). | +| `--host-name ` | Host used in download URLs (defaults to system hostname). | +| `--listen
` | Address to bind (default `0.0.0.0`). | +| `--insecure` | Use `http` scheme for resource links instead of `https`. | +| `--resource-ttl ` | TTL for generated resources (default 600s). | +| `--host-name` | Hostname embedded in URLs. | +| `--static-user-agent` | Disable randomized user-agents. | + +## Examples + +### NPX + +```bash +npx @aakashh242/playwright-mcp-server --http --port 9000 --path /gateway +``` + +### Docker + +```bash +docker run --rm -p 9000:9000 ghcr.io/aakashh242/mcp-playwright:latest \ + node dist/index.js --http --port 9000 --host-name example.com +``` + +Remember that HTTP mode requires CLI access to upload files (curl / `Invoke-WebRequest`) before calling `playwright_upload_file`. + diff --git a/docs/docs/getting-started/install-with-docker.mdx b/docs/docs/getting-started/install-with-docker.mdx new file mode 100644 index 0000000..bb81eaf --- /dev/null +++ b/docs/docs/getting-started/install-with-docker.mdx @@ -0,0 +1,81 @@ +--- +sidebar_position: 2 +title: Install with Docker +--- + +import composeYml from '!!raw-loader!@site/docker-compose.yml'; +import CodeBlock from '@theme/CodeBlock'; + +# Install with Docker + +Use the prebuilt container image for isolated or server deployments. + +## Prerequisites + +- Docker Engine (desktop or server) +- Optional: ability to map volumes for `/data` + +## Pull & Run + +```bash +docker pull ghcr.io/aakashh242/mcp-playwright:latest +docker run -i --rm ghcr.io/aakashh242/mcp-playwright:latest +``` + +### Streamable HTTP mode + +```bash +docker run --rm -p 8000:8000 \ + ghcr.io/aakashh242/mcp-playwright:latest \ + node dist/index.js --http --listen 0.0.0.0 --host-name localhost +``` + +Mount `/data` if you want to persist generated resources: + +```bash +docker run --rm -p 8000:8000 -v /data:/data ghcr.io/aakashh242/mcp-playwright:latest ... +``` + +## Running with Docker Compose (recommended for production HTTP) + +Use the provided `docker-compose.yml` for streamable HTTP with sensible defaults: + +```bash +docker compose up -d +``` + +This exposes `http://localhost:8000/mcp`, binds to `0.0.0.0:8000`, and mounts `./data/app-data` β†’ `/app/data` plus `./data/resource-data` β†’ `/data` for persisted resources. Replace the `--host-name` placeholder in the compose file with your public hostname. + + + {composeYml} + + +## VS Code configuration + +### STDIO transport + +```json +{ + "mcpServers": { + "playwright": { + "command": "docker", + "args": ["run", "-i", "--rm", "ghcr.io/aakashh242/mcp-playwright:latest"] + } + } +} +``` + +### HTTP transport + +```json +{ + "mcpServers": { + "playwright": { + "transport": { + "type": "http", + "url": "http://localhost:8000/mcp" + } + } + } +} +``` diff --git a/docs/docs/getting-started/install-with-npx.mdx b/docs/docs/getting-started/install-with-npx.mdx new file mode 100644 index 0000000..2395a5b --- /dev/null +++ b/docs/docs/getting-started/install-with-npx.mdx @@ -0,0 +1,70 @@ +--- +sidebar_position: 1 +title: Install with npx +--- + +# Install with npx + +This is the quickest way to run the Playwright MCP server locally. + +## Prerequisites + +- Node.js 18+ (20+ recommended) +- `npx` (bundled with recent Node.js releases) +- Playwright browsers (installed automatically on first run or via `npx playwright install`) + +## Install & Run + +```bash +npx @aakashh242/playwright-mcp-server +``` + +To keep a global install: + +```bash +npm install -g @aakashh242/playwright-mcp-server +playwright-mcp-server +``` + +## Streamable HTTP mode + +```bash +npx @aakashh242/playwright-mcp-server --http \ + --port 8000 \ + --path /mcp \ + --host-name localhost \ + --listen 0.0.0.0 +``` + +This enables the server to run behind MCP gateways. When HTTP mode is on, file uploads must go through the `construct_upload_url` tool before calling `playwright_upload_file`. + +## VS Code configuration + +Add the server to `mcp.json`: + +```json +{ + "mcpServers": { + "playwright": { + "command": "npx", + "args": ["-y", "@aakashh242/playwright-mcp-server"] + } + } +} +``` + +For HTTP transport: + +```json +{ + "mcpServers": { + "playwright": { + "transport": { + "type": "http", + "url": "http://localhost:8000/mcp" + } + } + } +} +``` + diff --git a/docs/docs/intro.mdx b/docs/docs/intro.mdx index e2112d1..d87df67 100644 --- a/docs/docs/intro.mdx +++ b/docs/docs/intro.mdx @@ -18,55 +18,11 @@ With the Playwright MCP server, you can: ## Installation -You can install Playwright MCP Server package using either **npm**, **mcp-get**, or **Smithery**: -:::info Playwright MCP Tips - -To get started more quickly on Playwright MCP Server, watch the videos mentioned in the footer of this page under `Docs` - -::: - - -### Installing via NPM -To install Playwright MCP for Claude Desktop automatically via Smithery: - -```bash -npm install -g @executeautomation/playwright-mcp-server -``` - -### Installing via Smithery -To install Playwright MCP for Claude Desktop automatically via Smithery: - -```bash -npx @smithery/cli install @executeautomation/playwright-mcp-server --client claude -``` - -You can type this command into Command Prompt, Powershell, Terminal, or any other integrated terminal of your code editor. - -### Installing via MCP-GET -To install Playwright MCP for Claude Desktop automatically via Smithery: - -```bash -npx @michaellatman/mcp-get@latest install @executeautomation/playwright-mcp-server -``` - -### Configuring Playwright MCP in Claude Desktop -Here's the Claude Desktop configuration to use the Playwright MCP server. - -Modify your `claude-desktop-config.json` file as shown below - -```json -{ - "mcpServers": { - "playwright": { - "command": "npx", - "args": ["-y", "@executeautomation/playwright-mcp-server"] - } - } -} -``` +See [Getting Started](./getting-started/install-with-npx.mdx) for installation instructions. ### What is Model Context Protocol This video should give you an high level overview of what Claude's MCP is and how helpful it will soon become for AI agents + diff --git a/docs/docs/local-setup/Installation.mdx b/docs/docs/local-setup/Installation.mdx index 5b9f2c5..489c69b 100644 --- a/docs/docs/local-setup/Installation.mdx +++ b/docs/docs/local-setup/Installation.mdx @@ -8,7 +8,7 @@ To build/run Playwright MCP Server in your local machine follow the below steps ### Step 1 : Clone Repository ```bash -git clone https://github.com/executeautomation/mcp-playwright.git +git clone https://github.com/aakashh242/mcp-playwright.git ``` ## Step 2: Install Dependencies @@ -38,7 +38,7 @@ The file is generally located at `C:\Users\{yourusername}\AppData\Roaming\Claude "--directory", "/your-playwright-mcp-server-clone-directory", "run", - "@executeautomation/playwright-mcp-server" + "@aakashh242/playwright-mcp-server" ] } } @@ -60,3 +60,4 @@ If your setup is all correct, you should see Playwright MCP Server pointing your ![Playwright MCP Server](./img/mcp-server.png) ![Playwright MCP Server running](./img/mcp-server-running.png) + diff --git a/docs/docs/local-setup/_category_.json b/docs/docs/local-setup/_category_.json index bfce9fc..2af72bc 100644 --- a/docs/docs/local-setup/_category_.json +++ b/docs/docs/local-setup/_category_.json @@ -1,7 +1,7 @@ { "label": "Local Development", "position": 3, - "collapsed": false, + "collapsed": true, "link": { "type": "generated-index", "description": "Understand how to setup Playwright MCP Server to run in your local machine." diff --git a/docs/docs/playwright-web/Console-Logging.mdx b/docs/docs/playwright-web/Console-Logging.mdx index 400cf4f..97c7884 100644 --- a/docs/docs/playwright-web/Console-Logging.mdx +++ b/docs/docs/playwright-web/Console-Logging.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 2 +sidebar_position: 3 --- # πŸ“ Support of Console Logs diff --git a/docs/docs/playwright-web/Recording-Actions.mdx b/docs/docs/playwright-web/Recording-Actions.mdx index 5358eb5..ff37553 100644 --- a/docs/docs/playwright-web/Recording-Actions.mdx +++ b/docs/docs/playwright-web/Recording-Actions.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 5 +sidebar_position: 6 --- import YouTubeVideoEmbed from '@site/src/components/HomepageFeatures/YouTubeVideoEmbed'; diff --git a/docs/docs/playwright-web/Support-of-Cline-Cursor.mdx b/docs/docs/playwright-web/Support-of-Cline-Cursor.mdx index 5977767..44c9946 100644 --- a/docs/docs/playwright-web/Support-of-Cline-Cursor.mdx +++ b/docs/docs/playwright-web/Support-of-Cline-Cursor.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 3 +sidebar_position: 4 --- import YouTubeVideoEmbed from '@site/src/components/HomepageFeatures/YouTubeVideoEmbed'; diff --git a/docs/docs/playwright-web/Supported-Tools.mdx b/docs/docs/playwright-web/Supported-Tools.mdx index 859bbc6..caf6132 100644 --- a/docs/docs/playwright-web/Supported-Tools.mdx +++ b/docs/docs/playwright-web/Supported-Tools.mdx @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +sidebar_position: 2 --- import YouTubeVideoEmbed from '@site/src/components/HomepageFeatures/YouTubeVideoEmbed'; diff --git a/docs/docs/playwright-web/streamable-http.mdx b/docs/docs/playwright-web/streamable-http.mdx new file mode 100644 index 0000000..6247468 --- /dev/null +++ b/docs/docs/playwright-web/streamable-http.mdx @@ -0,0 +1,54 @@ +--- +sidebar_position: 1 +title: πŸ“Ά Streamable HTTP Mode +--- + +import CodeBlock from '@theme/CodeBlock'; +import composeYml from '!!raw-loader!@site/docker-compose.yml'; + +# πŸ“Ά Streamable HTTP Mode + +Streamable HTTP allows the server to run behind gateways and lets clients download generated artifacts through signed URLs. + +## Enabling + +```bash +npx @aakashh242/playwright-mcp-server --http --port 8000 --path /mcp --host-name your.host +``` + +Or Docker: + +```bash +docker run --rm -p 8000:8000 ghcr.io/aakashh242/mcp-playwright:latest \ + node dist/index.js --http --listen 0.0.0.0 --host-name your.host +``` + +Or with Docker Compose (recommended for production HTTP): +```bash +docker compose up -d +``` +The provided `docker-compose.yml` exposes `http://localhost:8000/mcp`, binds to `0.0.0.0:8000`, persists data to `./data` β†’ `/app/data`, and runs streamable HTTP mode by default. + + + {composeYml} + + +## Remote resources + +When HTTP mode is enabled, tools that create files register session-scoped resources and return download URLs: + +- `playwright_screenshot` +- `playwright_save_as_pdf` +- Codegen outputs (`end_codegen_session`) +- `playwright_console_logs` + +Resources live under `/resources/{sessionId}/{resourceId}/{filename}` and expire after the configured TTL (default 600 seconds). + +## File uploads + +1. Call `construct_upload_url` to get a session-specific HTTP endpoint (e.g. `http://host:8000/mcp/uploads/{sessionId}`). +2. The MCP client uploads the file via `multipart/form-data` (field `file`). CLI permissions are required (curl or `Invoke-WebRequest`). +3. The server responds with `resourceUri` such as `mcp-uploads://{sessionId}/{id}`. +4. Call `playwright_upload_file` with `uploadResourceUri`. If no URI/path is provided the tool returns an error instructing the agent to upload first. + +This loop prevents large base64 payloads in tool arguments and keeps uploads isolated per session. diff --git a/docs/docs/release.mdx b/docs/docs/release.mdx index 916d5d5..1e2e041 100644 --- a/docs/docs/release.mdx +++ b/docs/docs/release.mdx @@ -1,176 +1,10 @@ --- -sidebar_position: 2 +sidebar_position: 99 --- -import YouTubeVideoEmbed from '@site/src/components/HomepageFeatures/YouTubeVideoEmbed'; +import Changelog from '@site/CHANGELOG.md'; # Release Notes -## Version 1.0.6 -- **New Tool: `playwright_upload_file`**: Added a new tool to upload files to an `input[type='file']` element. -- **Enhanced Content Extraction**: - - Significantly improved `playwright_get_visible_text` tool for more accurate text extraction. - - Added `playwright_get_visible_html` tool to retrieve the full HTML content of the page. - - **By default, all `