MCP Server v0.1.0 — Power Scraper tool, resources, and prompts

[Adriansillo]

Summary

• Implements a full MCP (Model Context Protocol) server for the Browserless.io power scraper API using FastMCP
• Supports both stdio (for Claude Desktop, Cursor, VS Code, Windsurf) and httpStream transports (for hosted/Docker deployments)
• Includes Docker multi-stage build, retry with exponential backoff, response caching, and comprehensive test suite (47 tests)

What's included

MCP Component	Name	Description
Tool	browserless_powerscraper	Scrape any URL with cascading strategies (HTTP fetch → proxy → headless browser → captcha solving). Returns markdown, optional screenshot (PNG) and PDF
Resource	browserless://api-docs	Power scraper API documentation
Resource	browserless://status	Live service health check
Prompt	scrape-url	Scrape and summarize a webpage
Prompt	extract-content	Extract specific information from a webpage

Auth model

• stdio: BROWSERLESS_TOKEN env var
• httpStream: Authorization: Bearer <token> header (per-request), with optional X-Browserless-Api-Url header for custom endpoints

Project structure

src/
├── config.ts              # Environment config + types
├── index.ts               # Server entry point (stdio / httpStream)
├── tools/
│   ├── schemas.ts         # Zod schemas for params + response
│   └── powerscraper.ts    # Main tool implementation
├── lib/
│   ├── api-client.ts      # HTTP client with retry + cache
│   ├── cache.ts           # TTL-based response cache
│   └── retry.ts           # Exponential backoff with jitter
├── resources/
│   ├── api-docs.ts        # API documentation resource
│   └── status.ts          # Health check resource
└── prompts/
    ├── scrape-url.ts      # Scrape + summarize prompt
    └── extract-content.ts # Extract info prompt

Test plan

• npm run build compiles with zero errors (strict mode, noUnusedLocals, noUnusedParameters)
• npm test — 47 tests passing (tools, api-client, cache, retry, prompts, resources, integration)
• No stale "superscraper" references remain in codebase
• Manual test: stdio mode with Claude Desktop / Cursor
• Manual test: httpStream mode with curl + Authorization header
• Docker build and run

🤖 Generated with Claude Code

[artiom]

• when it's a server over the internet, how does cache work? It will cache for everyone? I think it should cache per user / token, what do you think?
• any changes required based on https://github.com/browserless/enterprise/pull/1261 ?

[Adriansillo]

• when it's a server over the internet, how does cache work? It will cache for everyone? I think it should cache per user / token, what do you think?
• any changes required based on Format change + adding a route path enterprise#1261 ?

1. Yes it is single cache for all users, The cache key includes the full body we sent to the power scraper, in case two different users send the same request they should receive the same response. Am I omitting something ?
2. Updated, thank you

[artiom]

Yes it is single cache for all users, The cache key includes the full body we sent to the power scraper, in case two different users send the same request they should receive the same response. Am I omitting something ?

Thinking about permissions / PII data / proxy usage or anything else that might be wrong to cache it for other people. If I used proxy tokens scrapped the website, the next guy gets it for free?
Same with PII, if I logged in and got my data, for the same url someone else should get their own version. That's why I thought about caching per connection token or something similar.

What do you think? Logged in / used proxy or other params in the body is enough to create unique key?

[Adriansillo]

Thinking about permissions / PII data / proxy usage or anything else that might be wrong to cache it for other people. If I used proxy tokens scrapped the website, the next guy gets it for free? Same with PII, if I logged in and got my data, for the same url someone else should get their own version. That's why I thought about caching per connection token or something similar.

What do you think? Logged in / used proxy or other params in the body is enough to create unique key?

Good catch!!
Pushed a commit to address it