---
alwaysApply: true
---
## Frontend Development MCP Ecosystem — Overview and How It Works
This workspace provides a complete loop for AI-assisted frontend work across multiple projects using an MCP server, a browser tools server, and a Chrome extension.
See the full consolidated overview and tools quick-reference here: [PROJECT_OVERVIEW.md](mdc:docs/PROJECT_OVERVIEW.md)
### Components
- MCP server: [mcp-server.ts](mdc:browser-tools-mcp/mcp-server.ts)
- Browser tools server: [browser-connector.ts](mdc:browser-tools-server/browser-connector.ts)
- Server modules (selected):
- Project config/env: [shared.ts](mdc:browser-tools-server/modules/shared.ts)
- Semantic API index/search: [semantic-index.ts](mdc:browser-tools-server/modules/semantic-index.ts)
- Global logger: [logger.ts](mdc:browser-tools-server/modules/logger.ts)
- Chrome extension (DevTools panel, WS bridge, project config):
- Panel logic: [panel.js](mdc:chrome-extension/panel.js)
- Projects config: [projects.json](mdc:chrome-extension/projects.json)
### Active project resolution (multi-project support)
- The active project can differ across IDE instances:
- MCP side: `ACTIVE_PROJECT` env in Cursor MCP config governs config reads.
- Server side (semantic search only): Per-request header `X-ACTIVE-PROJECT` (or `active-project`) selects the project; falls back to server env/default.
- Each project has its own embedding index folder in `.vectra/<project>` and its own cached Swagger.
### API documentation search (semantic)
- Endpoint: `POST /api/embed/search` (server)
- Flow: `mcp-server.ts` → calls server with headers → [semantic-index.ts](mdc:browser-tools-server/modules/semantic-index.ts)
- Index is built per-project with Vectra. Minimal result fields (method, path, light req/resp hints). See [semantic-index.ts](mdc:browser-tools-server/modules/semantic-index.ts).
- Reindex/status endpoints (used by DevTools panel):
- `GET /api/embed/status?project=<name>`
- `POST /api/embed/reindex` with `{ project }`
### Tools (high level)
- `api.searchEndpoints`, `api.listTags`, `api.request`, `browser.screenshot`, `browser.navigate`, `browser.console.read`, `browser.network.inspect`, `ui.inspectElement` live in [mcp-server.ts](mdc:browser-tools-mcp/mcp-server.ts). See detailed rule “Tools Behavior and Business Logic”.
### Logging and observability
- Global colorized logging installed at server startup in [browser-connector.ts](mdc:browser-tools-server/browser-connector.ts) via [logger.ts](mdc:browser-tools-server/modules/logger.ts).
- Set `LOG_LEVEL` to `error|warn|info|debug` to reduce noise.
- Search logs include per-query embedding timing.
### Environment variables (common)
- Project selection: `ACTIVE_PROJECT`
- Server discovery (MCP → server): `BROWSER_TOOLS_HOST`, `BROWSER_TOOLS_PORT`
- Embeddings: `OPENAI_API_KEY` or `GEMINI_API_KEY` (+ optional model vars)
- Live API: `API_BASE_URL`, `API_AUTH_TOKEN`
- Logging: `LOG_LEVEL`
### Running
- Server: `node start-server.js` (loads `dotenv` in server). Or `cd browser-tools-server && pnpm start`.
- Chrome extension: load the `chrome-extension` folder as an unpacked extension in Chrome.
- MCP: configure in Cursor’s MCP settings pointing to `browser-tools-mcp/dist/mcp-server.js` with per-IDE `ACTIVE_PROJECT`.
### Cross-project isolation
- Preferred: One shared server; per-request header `X-ACTIVE-PROJECT` keeps project selection correct per IDE instance.
- Alternative: Run two servers on different ports and set `BROWSER_TOOLS_PORT` per IDE.
### Debugging checklist
- Wrong project docs? Check request header `X-ACTIVE-PROJECT`, server `ACTIVE_PROJECT`, and `defaultProject`.
- Index missing? Open DevTools panel → Reindex for the project.
- Model mismatch warning? Reindex for current embedding provider/model.
- 429 on embed? The server will back off; retry or switch provider/model.
### Working cadence (applied by the assistant)
- Plan: Create atomic todos; keep one active. Summarize scope, risks, and assumptions.
- Discover: Use semantic search to locate relevant modules; read key files before editing.
- Implement: Make focused edits; follow code style; guard clauses and meaningful names.
- Validate: Lints on changed files must pass; verify error/empty/loading states.
- Clean up: Remove dead code/unused imports; update localized docs.
- Documentation & rules: Update `.cursor/rules/*` and `docs/` to reflect new features/changes; ensure naming/endpoint/header consistency.
- Review: Provide concise summary and highlight impacted files and risks.
- Done: Definition below must be satisfied before marking complete.
### Definition of Done
- All todos completed; no lints on changed files; builds/tests pass when applicable.
- Edge cases and error handling implemented; external APIs align with official docs.
- Old logic that was replaced is removed; no dead references remain.
- Rules and docs updated for the change; superseded guidance removed; cross-file consistency verified.
- Brief change summary recorded in the conversation with citations to files/lines when useful.
