Performance Analysis MCP Server

Lightweight MCP server for collecting page performance metrics (Playwright + CDP + Lighthouse) and returning a normalized PerformanceReport.

Prerequisites

• Node.js (16+ recommended)

• npm

• Optional: network access to target URLs

Related MCP server: LightScout MCP

Install

npm install
# Install Playwright browsers (required for collectors)
npx playwright install

Build / Type-check / Test

npm run build
npm run lint
npm test

Run as MCP Server

The default command starts an MCP stdio server with an analyze_page tool.

npm start

The MCP tool accepts:

{ "url": "https://example.com" }

It returns a human-readable summary plus structured PerformanceReport content.

Run HTTP Compatibility Server

The HTTP server is available for local testing and non-MCP clients. You can provide a default URL via DEFAULT_URL or pass a URL in each request.

npm run start:http

With a default URL:

DEFAULT_URL=https://example.com npx ts-node src/index.ts http --no-prompt

Server API

• GET /health → returns { ok: true }

• POST /analyze with JSON { "url": "https://..." } → returns analysis JSON plus summary string.

Example using curl (returns JSON file):

curl -s -X POST http://localhost:3333/analyze \
  -H "Content-Type: application/json" \
  -d '{"url":"https://www.lowes.com"}' -o report.json

One-off analyze (CLI)

npx ts-node src/index.ts analyze https://www.lowes.com > report.json

The CLI prints JSON followed by a human-readable summary.

Files of interest

• src/schema/performance-report.ts — canonical schema and validator

• src/collectors/playwright.ts — Playwright collector

• src/collectors/cdp.ts — CDP network capture helper

• src/tools/analyze-page.ts — orchestrates collectors and adapts results

• src/tools/lighthouse.ts — Lighthouse runner (Phase 2)

• src/tools/format-report.ts — text formatter for human-friendly output

• src/server/mcp.ts — MCP stdio server and analyze_page tool

• src/server/http.ts — HTTP compatibility server

Troubleshooting

• If Playwright complains about missing browsers, run npx playwright install.

• If tsc not found, run npm install to install devDependencies.

Next steps

• Add automated recommendations, persistence, or LLM analysis integration.