# 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

## Install

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

## Build / Type-check / Test

```bash
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.

```bash
npm start
```

The MCP tool accepts:

```json
{ "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.

```bash
npm run start:http
```

With a default URL:

```bash
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):

```bash
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)

```bash
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.