Repository files navigation

Exposes basic browser automation through HTTP and MCP for generative UI apps.

• Methodology
• Authentication
  • 1. API Key Authentication (Default: Enabled)
  • 2. JWT Bearer Token Authentication (Default: Disabled)
    • Browser-Based JWT Verification
  • MCP Server testing
• Platforms
• Distribution
• Environment
• Development
  • Building Binaries
• Implementation
• References
• Installation
• License

This project on launch exposes the following endpoints:

• a RESTful API HTTP server
• a Swagger docs server
• a MCP server

For example:

• http://localhost:3000/api: the RESTful API
• http://localhost:3000/mcp: the MCP endpoint
• http://localhost:3000/docs: the Swagger docs endpoint
• http://localhost:3000/jose: Jose library browser modules (for JWT verification)
• http://localhost:3000/jwt-verify: Browser-based JWT verification page

Port is configurable with thePCS_PORT environment variable (default:3000).

On running the server, it attempts to find the first available Chrome or Chromeadjacent installation on the host machine. This setting can be updated over HTTPand MCP as well as a config file in the executable's current directory.

Assuming access to the path of the Chrome executable, the server offers this API:

• tabs/list: lists all open tabs with their IDs and URLs
• tabs/open: opens a new tab with an initial URL (optionally headless)
• tabs/goto/:tabId: navigates the tab with the given ID to a new URL
• tabs/screenshot/:tabId: takes a screenshot of the tab with the given ID
• tabs/click/:tabId: clicks at specified selector in the tab with the given ID
• tabs/hover/:tabId: hovers over specified selector in the tab with the given ID
• tabs/fill/:tabId: fills a form field at specified selector in the tab with the given ID
• tabs/select/:tabId: selects an option in a dropdown at specified selector in the tab with the given ID
• tabs/eval/:tabId: evaluates JavaScript in the context of the tab with the given ID
• tabs/close/:tabId: closes the tab with the given ID
• tabs/closeAll: closes all open tabs
• tabs/bringToFront/:tabId: brings the tab with the given ID to front
• tabs/focus/:tabId: focuses on a specific element via selector in the tab with the given ID
• tabs/goBack/:tabId: navigates back in browser history for the tab with the given ID
• tabs/goForward/:tabId: navigates forward in browser history for the tab with the given ID
• tabs/reload/:tabId: reloads the tab with the given ID
• tabs/waitForSelector/:tabId: waits for a selector to appear in the tab with the given ID
• tabs/waitForFunction/:tabId: waits for a function to return truthy value in the tab with the given ID
• tabs/waitForNavigation/:tabId: waits for navigation to complete in the tab with the given ID
• tabs/url/:tabId: gets the current URL of the tab with the given ID
• tabs/html/:tabId: gets the current HTML content of the tab with the given ID
• resources/clean: removes a specific screenshot resource by URI
• resources/cleanAll: removes all screenshot resources

Browser automation happens through Puppeteer. Session management is automatic.

The server is implemented in Express and Typescript. All routes are protectedwith configurable authentication strategies.

The server supports two optional authentication strategies:

On first run, the server generates a random API key and saves it to.secret inthe current working directory. Use this key in thex-api-key header:

curl -H"x-api-key: YOUR_API_KEY" http://localhost:3000/api/tabs/list

The server can verify external JWT tokens (issued by another service). ConfigureJWT verification inconfig.json (seeconfig.json.example for a template):

{"chromePath":"/path/to/chrome","port":3000,"auth": {"apiKey": {"enabled":true    },"jwt": {"enabled":true,"jwksUrl":"https://your-auth-server.com/.well-known/jwks.json","issuer":"https://your-auth-server.com","audience":"https://your-api-domain.com"    }  }}

Use JWT tokens in theAuthorization header:

curl -H"Authorization: Bearer YOUR_JWT_TOKEN" http://localhost:3000/api/tabs/list

For JWT verification that needs to happen in a browser context (e.g., for testing browser-side authentication flows), enable theproxy option:

{"auth": {"jwt": {"enabled":true,"proxy":true,"jwksUrl":"https://your-auth-server.com/.well-known/jwks.json","issuer":"https://your-auth-server.com","audience":"https://your-api-domain.com"    }  }}

Whenproxy: true is set, JWT verification happens in a browser tab using the Jose library loaded as an ES module. This allows verification to occur in the same environment as your browser automation, which can be useful for debugging or working around network restrictions.

The server automatically serves:

• /jose/* - Jose library browser modules fromnode_modules
• /jwt-verify - HTML page that implements browser-based JWT verification

Both strategies can be enabled simultaneously. If both are enabled, either validAPI key OR valid JWT token will grant access.

To interact and test the MCP server, you can use:

npx @modelcontextprotocol/inspector

In the UI, ensure "Transport Type" is set toStreamable HTTP and addauthentication headers:

• For API Key: Addx-api-key header with the key from.secret
• For JWT: AddAuthorization header with valueBearer YOUR_JWT_TOKEN

Windows, WSL, Linux, and MacOS.

• pcs.exe for Windows
• pcs for WSL, Linux, and MacOS

The project is coded in Typescript and compiled into native binaries using PKG.

When PKG is used to compile the project, executables are generated for Windows,Linux, and MacOS operating systems. The Linux binary runs on WSL as well.

After that, the executables are compressed and obfuscated to reduce size andcreate unique signatures for production.

Resulting binaries are entirely self-contained and do not require any externaldependencies beyond the target platform's standard libraries.

• Node.js version 18+ andnpm
• Go version 1.16+ (for signature generation)
• lipo (MacOS only) orllvm-lipo (non MacOS)
• upx (for executable compression)
• Docker (to buildldid if you don't have MacOS)

Compile the project into native binaries:

npm run compile

Flags:

• --fast: Fast build mode (skips Brotli compression, uses UPX level 1)
• --linux: Build Linux binaries only
• --mac: Build macOS binaries only
• --win: Build Windows binaries only

Platform flags can be combined. Without any platform flag, all platforms are built.

Examples:

# Fast build for Linux onlynpm run compile -- --linux --fast# Build for Windows and macOSnpm run compile -- --win --mac# Full build (all platforms, maximum compression)npm run compile

Code is organized in Object Oriented manner with classes. Logic is maintained ata level that the code is readable and easy to reason about.

• https://github.com/expressjs/express - To build the HTTP server
• https://www.npmjs.com/package/puppeteer-core - To control Chrome browser
• https://www.npmjs.com/package/puppeteer-extra - Puppeteer plugins framework
• https://github.com/panva/jose - JWT verification library
• https://github.com/vercel/pkg - To compile Node.js project into binaries
• https://github.com/upx/upx - Executable compressor

{"mcpServers": {"pcs": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

claude mcp add --transport http pcs http://localhost:3000/mcp --header"x-api-key: YOUR_API_KEY"

amp mcp add pcs --header"x-api-key=YOUR_API_KEY" http://localhost:3000/mcp

{"mcpServers": {"pcs": {"serverUrl":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

"mcp": {"servers": {"pcs": {"type":"http","url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"mcpServers": {"pcs": {"url":"http://localhost:3000/mcp","type":"streamableHttp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"context_servers": {"pcs": {"source":"url","url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

"augment.advanced": {"mcpServers": [    {"name":"pcs","url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  ]}

{"mcpServers": {"pcs": {"type":"streamable-http","url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"mcpServers": {"pcs": {"httpUrl":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY","Accept":"application/json, text/event-stream"      }    }  }}

{"mcpServers": {"pcs": {"httpUrl":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY","Accept":"application/json, text/event-stream"      }    }  }}

{"mcpServers": {"pcs": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

"mcp": {"pcs": {"type":"remote","url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"    },"enabled":true  }}

[mcp_servers.pcs]url ="http://localhost:3000/mcp"http_headers = {"x-api-key" ="YOUR_API_KEY" }

{"mcpServers": {"pcs": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"mcpServers": {"PCS": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      },"env": {},"disabled":false,"autoApprove": []    }  }}

{"mcpServers": {"pcs": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"mcpServers": {"pcs": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"PCS": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"    },"env": {},"working_directory":null,"start_on_launch":true  }}

{"mcpServers": {"pcs": {"type":"http","url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"mcpServers": {"pcs": {"type":"http","url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"mcpServers": {"PCS": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"inputs": [],"servers": {"context7": {"type":"http","url":"https://mcp.context7.com/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"mcp": {"servers": {"pcs": {"type":"http","url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"        }      }    }  }}

{"$schema":"https://charm.land/crush.json","mcp": {"pcs": {"type":"http","url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"mcpServers": {"pcs": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

acli rovodev mcp

{"mcpServers": {"pcs": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"  }}

{"mcpServers": {"pcs": {"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"      }    }  }}

{"url":"http://localhost:3000/mcp","headers": {"x-api-key":"YOUR_API_KEY"  },"env": {}}

droid mcp add pcs http://localhost:3000/mcp --type http --header"x-api-key: YOUR_API_KEY"

MIT License