melabidi/mcp_web_dev_server
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

init project

Browse Source
This commit is contained in:
root
2026-07-31 13:12:54 -04:00
parent 0da92d5e02
commit f3863f760c
7215 changed files with 1860260 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+249 -1
View File
@@ -1,2 +1,250 @@
# mcp_web_dev_server
# web-dev-mcp
An MCP (Model Context Protocol) server that gives AI coding agents a framework-aware toolkit for
web development: project/dependency workflow (install, dev server, lint, test, build), and
code/project scaffolding, with first-class support for **Laravel**, **CodeIgniter 4**,
**React**, **Vue**, and **Nuxt**, plus detection stubs for **Django**, **Rails**, and **Symfony**
— including combined backend+frontend setups.
See [`PLAN.md`](./PLAN.md) for the full design and roadmap. This README covers what's
implemented today and how to run it.
## Implementation status
Implemented **v1** (PLAN.md milestones 1–14) plus post-v1 **v1.1–v1.5**:
- **Framework detection & adapters** — `detect_framework` auto-detects Laravel (Sail-aware), CodeIgniter 4,
Symfony, Django, Rails backends and React / Vue / Nuxt frontends, including a PHP/Python/Ruby
backend + separate frontend living side-by-side (`frontend/`, `client/`, `web/`).
- **Core workflow tools** — `detect_framework`, `detect_workspace` (monorepo package scan),
`run_install`, `run_script`, `start_dev_server` (Sail `up` when present), `stop_process`,
`get_process_logs`, `list_processes`, `run_lint`, `run_tests`, `build_project`,
`deploy_project` (opt-in `confirm: true`; optional `registryPush`). Most workflow tools accept
an optional `package` argument to scope to a monorepo package.
- **Scaffolding tools** — `scaffold_project` (vite-react, vite-vue, next, express-api,
static-html, laravel, codeigniter, laravel-react, codeigniter-react), `generate_component`
(React TSX/JSX or Vue SFC), `generate_api_route`, `add_dependency`.
- **Laravel tools** — `artisan` (allow-listed subcommands; destructive ones need `confirm: true`;
`queue:work`/`queue:listen`/`reverb:start` run as tracked background processes), `generate_laravel_resource`,
`generate_eloquent_relation`, `generate_filament_resource`, `generate_nova_resource`, `laravel_queue_status`,
`composer_require` / `composer_remove` (shared with CodeIgniter backends), `run_phpunit` /
`run_pest`, `laravel_tinker_eval` (write-looking expressions need `confirm: true`).
- **CodeIgniter tools** — `spark` (allow-listed subcommands; `migrate:refresh` needs
`confirm: true`), `spark_discover`, `generate_codeigniter_resource` (optional `apiVersion` /
ResourceController), `generate_codeigniter_shield_auth` (`confirm: true`), `run_codeigniter_tests`.
- **Django / Rails / Symfony** — `generate_django_resource`, `generate_rails_resource`,
`generate_symfony_resource` (file-based stubs).
- **React tools** — `generate_react_hook`, `add_react_route` (Next.js / react-router /
TanStack Router), `generate_next_page` / `generate_next_layout` (App Router), `run_react_tests`,
`analyze_react_component` (incl. missing `"use client"` / server→client prop heuristics).
`generate_component` supports `clientComponent: true`.
- **Browser tools** — `browser_navigate`, `browser_screenshot`, `browser_screenshot_baseline`,
`browser_visual_diff`, `browser_get_console_logs`, `browser_inspect_dom`, `browser_click`,
`browser_fill`, `browser_eval` (Playwright-backed; Chromium binaries via `npx playwright install chromium`).
- **Git helpers** — `git_status`, `git_diff`, `git_diff_summarize`, `git_log`, `git_branch` (create needs
`confirm: true`), `git_commit` (`confirm: true`; no amend/force/push).
- **Lighthouse audit** — `lighthouse_audit` (category details, opportunities, `failingByCategory`).
- **Prompts** — `new-feature`, `new-laravel-resource`, `new-codeigniter-resource`, `new-react-component`,
`visual-diff-ci`.
- **Docker tools** — `docker_build_image`, `docker_run_container` (with workspace-confined volume
mounts, image allow-list, and resource limits), `docker_list_containers`, `docker_get_container_logs`,
`docker_exec`, `docker_stop_container`, `docker_remove_container`, `docker_compose_up`,
`docker_compose_down`, `generate_dockerfile`, `generate_compose`, `generate_sail` (`confirm: true`),
`docker_push_image` (`confirm: true`).
- **Docs & package lookup** — `search_package_docs` (npm README via unpkg, Composer metadata via
Packagist), `search_mdn`, `search_laravel_docs`, `search_codeigniter_docs`, `get_package_info`.
- **Resources & prompts** — `workspace://project.json`, `workspace://logs/{processId}`,
`workspace://containers/{containerId}/logs`, and reusable prompts `new-feature`,
`new-laravel-resource`, `new-codeigniter-resource`, `new-react-component`.
- **Safety** — every filesystem path is confined to `WORKSPACE_ROOT`
(`src/lib/sandbox.ts`), spawned binaries are restricted to an allow-list, and
destructive ops (`deploy_project`, `composer_remove`, `migrate:fresh`, `migrate:refresh`,
`git_commit`, …) require an explicit `confirm: true`. Docker containers are tracked and
force-removed on server shutdown.
- **Both transports work today**: stdio (for Cursor/Claude Desktop) and Streamable HTTP (for
remote/shared use), sharing one `createServer()` implementation. The HTTP transport includes
bearer-token auth and a production-ready `Dockerfile`.
- **Automated test suite** — Vitest tests for sandbox/path confinement, binary allow-list,
process management, Laravel/CodeIgniter subcommand allow-lists, destructive-command `confirm: true`
enforcement, Docker guardrails, framework detection, baselines/visual diff, and Lighthouse parsing.
- **Distribution-ready** — install via `npx web-dev-mcp` or add to your MCP client config.
Post-v1 roadmap (see `PLAN.md` §9): **v1.4** Vue/Nuxt adapters, **v1.5** Sail/polish.
## Requirements
- Node.js >= 18.17 (developed/tested on Node 24)
- For Laravel/CodeIgniter tools: PHP + Composer on `PATH`
- For scaffolding Laravel/CodeIgniter projects: Composer on `PATH`
- For browser tools: `npx playwright install chromium` (run once after `npm install`)
- For Docker tools: Docker Engine (Docker Desktop or `dockerd`) running and accessible to the current user
- For `lighthouse_audit`: Chrome/Chromium available (Lighthouse is pulled via `npx` on demand)
- For git tools: `git` on `PATH` and a git workspace under `WORKSPACE_ROOT`
## Setup
```bash
npm install
npm run build
```
## Running tests
```bash
npm run test
```
## Running
**stdio** (what Cursor/Claude Desktop use):
```bash
npm run dev # ts-node/tsx, no build step needed
# or, after `npm run build`:
npm start
```
**Streamable HTTP** (remote/shared use):
```bash
npm run build
npm run start:http
```
Environment variables:
| Variable | Default | Purpose |
|---|---|---|
| `WORKSPACE_ROOT` | current working directory | The project root every tool is confined to. |
| `MCP_HTTP_HOST` | `127.0.0.1` | Host the HTTP transport binds to. |
| `MCP_HTTP_PORT` | `3939` | Port the HTTP transport binds to. |
| `MCP_HTTP_TOKEN` | _(unset)_ | Bearer token required on `/mcp` when set. **Required** if binding to a non-localhost host. |
**Docker / containerization**:
```bash
docker build -t web-dev-mcp .
docker run -p 3939:3939 -e MCP_HTTP_TOKEN=change-me -v /path/to/project:/workspace web-dev-mcp
```
The image exposes the Streamable HTTP transport on port `3939` and uses `/workspace` as the confined `WORKSPACE_ROOT`. The `Dockerfile` uses a multi-stage build so the final image only contains production dependencies plus the compiled `dist/` directory.
## Using it from Cursor
Add to your MCP config (Cursor Settings → MCP, or `.cursor/mcp.json`):
```json
{
"mcpServers": {
"web-dev": {
"command": "node",
"args": ["/path/to/web-dev-mcp/dist/transports/stdio.js"],
"env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
}
}
}
```
### Published npm package (recommended)
```json
{
"mcpServers": {
"web-dev": {
"command": "npx",
"args": ["-y", "web-dev-mcp"],
"env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
}
}
}
```
### Claude Desktop config
Add to `claude_desktop_config.json`:
```json
{
"mcpServers": {
"web-dev": {
"command": "npx",
"args": ["-y", "web-dev-mcp"],
"env": { "WORKSPACE_ROOT": "/path/to/your/project" }
}
}
}
```
### Local checkout
```json
{
"mcpServers": {
"web-dev": {
"command": "node",
"args": ["/path/to/web-dev-mcp/dist/transports/stdio.js"],
"env": { "WORKSPACE_ROOT": "${workspaceFolder}" }
}
}
}
```
## Project layout
```
src/
config.ts # env vars, allow-lists, timeouts
server.ts # createServer(): registers all tools/resources
transports/
stdio.ts # stdio entrypoint (bin)
http.ts # Streamable HTTP entrypoint
lib/
logger.ts # stderr-only logging (stdout is reserved for JSON-RPC)
sandbox.ts # workspace path confinement + binary allow-list
runCommand.ts # foreground command execution with capped output
processManager.ts # tracks background processes (dev servers, backgrounded scripts)
strings.ts # pascal/camel/kebab-case helpers for codegen
frameworks/
types.ts # FrameworkAdapter interface
detect.ts # workspace inspection -> detected adapter(s)
resolve.ts # picks backend/frontend/primary adapter for a tool call
generic.ts, react.ts, vue.ts, djangoRailsSymfony.ts, laravel.ts, codeigniter.ts, phpBase.ts
packageManager.ts, composer.ts # npm/pnpm/yarn/bun and Composer helpers
tools/
shared.ts # zod schema + result helpers shared by tools
workflow/ # detect_framework, run_install, run_script, start_dev_server,
# stop_process, get_process_logs, list_processes, run_lint,
# run_tests, build_project, deploy_project
scaffold/ # scaffold_project (+ templates/), generate_component,
# generate_api_route, add_dependency
laravel/ # artisan, generate_laravel_resource, composer_require/remove,
# run_phpunit/run_pest, laravel_tinker_eval
codeigniter/ # spark, generate_codeigniter_resource, run_codeigniter_tests
react/ # generate_react_hook, add_react_route, run_react_tests,
# analyze_react_component
browser/ # browserManager, navigate, screenshot, consoleLogs,
# inspectDom, interact
docker/ # dockerManager, buildImage, runContainer, listContainers,
# containerLogs, exec, stopRemove, compose
docs/ # searchPackageDocs, searchMdn, searchLaravelDocs,
# searchCodeIgniterDocs, getPackageInfo
git/ # git_status, git_diff, git_log, git_branch, git_commit
audit/ # lighthouse_audit
resources/ # process/container log resources
prompts/ # new-feature / laravel / codeigniter / react prompts
```
Screenshot baselines for `browser_visual_diff` are stored under `.web-dev-mcp/baselines/` inside
the workspace (you may commit them for CI, or ignore them locally).
## Publishing
```bash
npm run build
npm run test
npm version <patch|minor|major>
npm publish
```
The package is published as `web-dev-mcp` and exposes `dist/transports/stdio.js` as the `bin` entry,
so `npx web-dev-mcp` launches the stdio transport directly.