Playwright Filter MCP Server

A Model Context Protocol (MCP) server that provides intelligent web browsing capabilities with automatic content filtering and cleaning. This server acts as a proxy between AI clients and web content, applying site-specific CSS rules to remove unwanted elements like advertisements, sidebars, and other clutter.

🚀 Features

• Intelligent Web Navigation: Navigate to any URL with automatic content filtering
• Site-Specific CSS Rules: Custom CSS rules for different websites to clean up content
• MCP Integration: Full Model Context Protocol support for AI client integration
• NestJS Architecture: Built with NestJS for robust, scalable server architecture
• Streamable HTTP Transport: Modern MCP transport for efficient communication
• Automatic Content Cleaning: Remove ads, sidebars, and other unwanted elements
• Configurable CSS Rules: Easy to add new site-specific filtering rules

🏗️ Architecture

This MCP server acts as a bridge between AI clients and web content by:

1. Receiving navigation requests from AI clients via MCP
2. Connecting to a Playwright MCP server for actual web browsing
3. Applying site-specific CSS rules to clean up the content
4. Returning cleaned snapshots to the AI client

Components

• BrowserTool: Main MCP tool that handles navigation and content filtering
• CSSConfigService: Manages site-specific CSS rules and JavaScript generation
• MCP Module: NestJS module that exposes tools via Model Context Protocol

📋 Prerequisites

• Node.js 18+
• A running Playwright MCP server (for actual web browsing)
• npm or yarn

🛠️ Installation

1. Clone the repository

   git clone https://github.com/isachivka/playwright-filter.git
   cd playwright-filter

2. Install dependencies

   npm install

3. Configure environment

   cp .env.example .env
   # Edit .env with your configuration

⚙️ Configuration

Environment Variables

Create a .env file with the following variables:

# Playwright MCP Server URL
PLAYWRIGHT_MCP_URL=http://192.168.1.10:8931

# Server Configuration
PORT=3000

Rules Configuration

The server uses site-specific CSS and JavaScript rules to clean up web content. Rules are stored in two directories:

CSS Rules (css-rules/ directory)

• css-rules/default.css - Default CSS rules applied to all sites
• css-rules/{domain}.css - Site-specific CSS rules (e.g., rutracker.org.css)

JavaScript Rules (js-rules/ directory)

• js-rules/default.js - Default JavaScript rules applied to all sites
• js-rules/{domain}.js - Site-specific JavaScript rules (e.g., rutracker.org.js)

Adding New Site Rules

1. CSS Rules: Create a new CSS file in css-rules/ with the domain name:

   touch css-rules/example.com.css

2. JavaScript Rules: Create a new JS file in js-rules/ with the domain name:

   touch js-rules/example.com.js

3. Add CSS rules to hide unwanted elements:

   .advertisement,
   .ads,
   .sidebar,
   .footer {
     display: none !important;
   }

4. Add JavaScript rules for advanced manipulation:

   // Remove specific elements
   document.querySelectorAll('.unwanted').forEach(el => el.remove());
   
   // Modify page content
   const title = document.querySelector('h1');
   if (title) title.textContent = 'Cleaned Title';

5. The server will automatically detect and apply both CSS and JavaScript rules when navigating to that domain.

🚀 Usage

Development

# Start in development mode
npm run start:dev

# Build the project
npm run build

# Start production server
npm run start:prod

MCP Client Integration

The server exposes the following MCP tools:

browser_navigate

Navigate to a URL and return a cleaned snapshot of the page with automatic CSS filtering applied.

Parameters:

• url (string, required): The URL to navigate to

Example:

{
  "name": "browser_navigate",
  "arguments": {
    "url": "https://rutracker.org/forum/viewtopic.php?t=123456"
  }
}

Response: Returns a JSON snapshot of the cleaned page content with unwanted elements removed.

browser_close

Close the current browser page.

Parameters:

• None

Example:

{
  "name": "browser_close",
  "arguments": {}
}

browser_fill_form

Fill multiple form fields on the current page.

Parameters:

• fields (array, required): Array of form fields to fill

Example:

{
  "name": "browser_fill_form",
  "arguments": {
    "fields": [
      {
        "name": "Username",
        "type": "textbox",
        "ref": "input[name='username']",
        "value": "myusername"
      },
      {
        "name": "Remember me",
        "type": "checkbox",
        "ref": "input[type='checkbox']",
        "value": "true"
      }
    ]
  }
}

browser_click

Perform a click action on a web page element.

Parameters:

• element (string, required): Human-readable element description
• ref (string, required): Exact target element reference from page snapshot
• doubleClick (boolean, optional): Whether to perform double click
• button (string, optional): Button to click (left, right, middle)
• modifiers (array, optional): Modifier keys to press

Example:

{
  "name": "browser_click",
  "arguments": {
    "element": "Login button",
    "ref": "button[type='submit']",
    "button": "left"
  }
}

browser_evaluate

Evaluate JavaScript expression on page or element.

Parameters:

• function (string, required): JavaScript function to execute
• element (string, optional): Human-readable element description
• ref (string, optional): Exact target element reference from page snapshot

Example:

{
  "name": "browser_evaluate",
  "arguments": {
    "function": "() => { return document.title; }"
  }
}

Example with element:

{
  "name": "browser_evaluate",
  "arguments": {
    "function": "(element) => { return element.textContent; }",
    "element": "Main heading",
    "ref": "h1"
  }
}

Testing with MCP Inspector

You can test the server using the MCP Inspector:

npm run inspector

🏗️ Project Structure

playwright-filter/
├── src/
│   ├── config/                 # Configuration services
│   │   ├── css-config.service.ts
│   │   └── config.module.ts
│   ├── mcp/                    # MCP server implementation
│   │   ├── browser.tool.ts     # Main browser tool
│   │   └── mcp.module.ts       # MCP module configuration
│   ├── app.module.ts           # Main application module
│   └── main.ts                 # Application entry point
├── css-rules/                  # Site-specific CSS rules
│   ├── default.css            # Default cleaning rules
│   └── rutracker.org.css      # RuTracker-specific rules
├── docs/                       # Documentation
├── dist/                       # Compiled JavaScript
└── package.json

🔧 Development

Available Scripts

• npm run start - Start the application
• npm run start:dev - Start in development mode with hot reload
• npm run start:debug - Start in debug mode
• npm run build - Build the application
• npm run test - Run tests
• npm run lint - Run ESLint
• npm run format - Format code with Prettier
• npm run inspector - Start MCP Inspector for testing

Adding New CSS Rules

1. Identify the domain you want to clean
2. Create a CSS file: css-rules/{domain}.css
3. Add CSS selectors to hide unwanted elements
4. Test with the MCP Inspector

Example CSS Rule

/* Hide common unwanted elements */
.advertisement,
.ads,
.sidebar,
.footer,
.header {
  display: none !important;
}

/* Site-specific elements */
#sidebar1,
#main-nav,
#logo {
  display: none !important;
}

🐳 Docker Support

The project includes Docker configuration for easy deployment:

# Build Docker image
docker build -t playwright-filter .

# Run with Docker Compose
docker-compose up

🤝 Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make your changes
4. Add tests if applicable
5. Commit your changes: git commit -m 'Add new feature'
6. Push to the branch: git push origin feature/new-feature
7. Submit a pull request

📝 License

This project is licensed under the UNLICENSED license - see the package.json file for details.

🔗 Related Projects

• Model Context Protocol - The protocol this server implements
• NestJS MCP Module - The NestJS module used for MCP integration
• Playwright - The underlying browser automation tool

📞 Support

For support and questions:

• Create an issue on GitHub
• Check the documentation in the docs/ directory
• Review the MCP specification for protocol details

---

Note: This server requires a separate Playwright MCP server to function. Make sure you have a compatible Playwright MCP server running and accessible via the configured URL.