Skip to main content
Glama
LocalDev MCP

LocalDev MCP

by mehrdad03

LocalDev MCP

CI Node.js TypeScript License: MIT

A guarded Model Context Protocol server that lets AI assistants inspect, edit, test, and validate explicitly approved local software projects.

LocalDev MCP is designed for practical coding workflows without exposing a general-purpose terminal. File access, Git operations, process execution, Laravel integration testing, secrets, HTTP requests, and database inspection all use narrow, reviewable policies.

Highlights

  • 49 focused MCP tools for project discovery, centrally installed skills, code search, safe editing, binary file import, Git inspection, tests, builds, Laravel diagnostics, integration testing, and validation.

  • Project allowlisting through a local configuration file.

  • SHA-256 concurrency protection before modifying, replacing, renaming, deleting, or overwriting existing files.

  • Direct binary file import from mounted MCP file inputs without Base64 conversion, with source-root allowlisting and MIME/hash verification.

  • Batch operations for fast reads and multi-file patches with rollback attempts.

  • Guarded Git branch switching with clean-tree checks, branch-name validation, expected-HEAD verification, and dry-run support.

  • Risk-classified custom Artisan commands instead of unrestricted shell execution.

  • Guarded multiline Laravel Tinker execution through ephemeral scripts outside the target repository.

  • In-memory HMAC and digest operations using explicitly approved .env keys without returning the secret value.

  • Loopback-only HTTP requests with redirect revalidation and sensitive-header redaction.

  • Managed temporary Laravel servers that can automatically select an available loopback port and can stop only processes started by the same MCP instance.

  • Structured database snapshots and assertions without model-supplied raw SQL.

  • Secret-aware path blocking and output redaction.

  • MCP-native skill registry with progressive disclosure through list_skills, get_skill, and read_skill_reference.

  • Bundled Frontend Craft Director for design, redesign, implementation, responsive fixes, anti-AI-slop review, and rendered visual QA.

  • Configurable command timeouts up to 3,600 seconds for long-running builds, tests, installs, and validation workflows.

Related MCP server: MCP Server

Architecture

MCP Client
   |
   v
LocalDev MCP (stdio)
   |
   +-- Project configuration allowlist
   +-- Central MCP-native skill registry
   +-- Path, upload-source, and secret guards
   +-- SHA-256 write and binary-import protection
   +-- Command and Laravel risk policies
   +-- Loopback HTTP enforcement
   +-- Managed-process ownership
   +-- Audit, backup, and cache layers
   |
   v
Approved local repositories only

Tool groups

Skills

list_skills, get_skill, read_skill_reference

Project discovery and reading

list_projects, get_project_info, get_project_snapshot, get_project_tree, list_directory, read_file, batch_read_files, search_files, search_code

Safe file editing and import

import_file_to_project, write_file, create_file, replace_text, apply_patch, batch_apply_patches, rename_file, delete_file

Git and validation

git_status, git_diff, git_switch_branch, inspect_changed_files, run_command, run_tests, run_validation_plan

Laravel and PHP

read_laravel_logs, inspect_routes, inspect_database_schema, run_artisan, laravel_run_artisan, laravel_tinker_execute, laravel_database_snapshot, laravel_database_assert, run_phpunit, run_pest, composer_install, clear_laravel_cache, restart_queue_workers

Local Laravel integration testing

local_secret_operation, local_http_request, start_local_process, inspect_local_process, stop_local_process

Frontend and Node.js

run_npm, run_eslint, run_build, npm_install

Binary file import

import_file_to_project accepts a real MCP file input in source_file and copies the mounted file directly into an allowlisted project. Binary data is streamed as bytes; it is never converted to Base64 or passed through text encoding.

Inputs:

  • project: configured project key.

  • source_file: uploaded file input advertised to the MCP client with schema type: "file".

  • destination: project-relative destination. Absolute paths, .. traversal, secret-like destinations, and symlink escapes are rejected.

  • overwrite: defaults to false. Existing files are refused unless explicitly enabled.

  • createParents: defaults to true.

  • expectedSha256: optional concurrency check for the existing destination when overwriting.

The result contains path, size, mimeType, and sha256. PNG, JPEG, WEBP, SVG, PDF, and common additional formats are detected from file signatures when available, with extension fallback for unknown data.

Uploaded source paths must be inside an approved mount root. By default, LocalDev MCP accepts files under the operating system temporary directory. Set one or more explicit roots when the tunnel mounts uploads elsewhere:

LOCALDEV_MCP_IMPORT_ROOTS=C:\path\to\tunnel\uploads

On Windows, separate multiple roots with ;; on macOS or Linux, use :. The default maximum import size is 100 MiB. It can be changed up to 1 GiB:

LOCALDEV_MCP_MAX_IMPORT_BYTES=209715200

Secret-like source names such as .env, private-key formats, and credential files are rejected. Overwrites create a local binary backup before replacement and verify the final destination hash.

Laravel integration workflow

Custom Artisan commands

laravel_run_artisan classifies commands as:

  • READ_ONLY

  • REVERSIBLE_LOCAL_WRITE

  • IRREVERSIBLE_LOCAL_WRITE

  • EXTERNAL_SIDE_EFFECT

Unknown project-specific commands are not assumed to be harmless. Add known read-only commands to readOnlyArtisanCommands; otherwise explicit approval is required for reversible local writes. Irreversible database commands and long-running or external-side-effect Artisan commands are blocked; dedicated MCP process tools must be used where available. Production flags such as --force and --env remain blocked.

Both run_artisan and laravel_run_artisan accept project-specific commands explicitly configured as read-only. Generic run_command deliberately keeps php artisan tinker and php -r blocked and directs callers to the dedicated Laravel tools instead.

JSON output mode accepts a valid JSON document even when the framework prints notices before or after it.

Guarded multiline Tinker

laravel_tinker_execute:

  • Executes multiline PHP through an ephemeral script outside the repository.

  • Removes the temporary script in finally.

  • Disables process, filesystem, network, dynamic-loading, and environment-access functions.

  • Blocks raw SQL and secret-file access patterns.

  • Detects common database-write operations and requires allowDatabaseWrite=true.

  • Supports none, rollback, and commit transaction modes.

  • Returns only sanitized output and a SHA-256 hash of the submitted code in audit records.

For tests that must expose a temporary database change to a second process, snapshot the original value, apply the reviewed change, and restore the exact snapshot in a finally step. For single-process temporary changes, use transactionMode: "rollback".

Secrets and HMAC

local_secret_operation can use only keys listed in allowedSecretEnvKeys for the selected project. The secret value:

  • Is read directly from .env into memory.

  • Is not returned to the MCP client.

  • Is not written to a temporary file.

  • Is not placed on the command line.

  • Is not included in audit logs.

  • Is used only for the requested presence check, HMAC, or digest operation.

Loopback-only HTTP

local_http_request accepts only:

localhost
127.0.0.1
::1

The host must resolve exclusively to loopback addresses. Redirect targets are validated again before following them. Requests to public domains, private-network addresses, or other IPs are rejected. Authorization, cookie, API-key, and webhook-signature headers are redacted from returned metadata.

Managed Laravel server

start_local_process starts only php artisan serve on a loopback host. Set port: 0 to select an available ephemeral port automatically. Explicit occupied ports are rejected.

stop_local_process accepts only a session ID created by the same MCP server instance for the same project. LocalDev MCP does not adopt or terminate unrelated operating-system processes.

Database assertions

laravel_database_snapshot and laravel_database_assert accept structured table, column, equality-filter, ordering, and bounded-limit inputs. Raw SQL is not accepted.

MCP-native skills

Skills live under skills/<skill-name>/ and are available to every configured project without copying them into application repositories.

The bundled skill is:

frontend-craft-director

Recommended frontend invocation:

@LocalDev

Project: <project-key>

Use the frontend-craft-director skill as the mandatory workflow for this frontend task.
Load the skill before editing files, inspect the real repository, produce a Design Read,
preserve routes/APIs/behavior, do not install packages without approval, run repository
validation, and report rendered visual-QA evidence honestly.

Requirements

  • Node.js 22 or newer

  • npm

  • Git

  • Optional: PHP and Composer for Laravel/PHP projects

  • Optional: ripgrep (rg) for faster code search

Installation

git clone https://github.com/mehrdad03/localdev-mcp.git
cd localdev-mcp
npm ci
npm run typecheck
npm run build
npm run smoke

Configure approved projects

Copy the example to a private local configuration:

Windows PowerShell

Copy-Item projects.example.json projects.local.json

macOS or Linux

cp projects.example.json projects.local.json

projects.local.json is preferred automatically when it exists. Otherwise LocalDev MCP falls back to projects.json. Both names are ignored by Git.

Example Laravel project configuration:

{
  "projects": {
    "my-laravel-app": {
      "root": "C:\\Projects\\my-laravel-app",
      "stack": ["laravel", "vue", "vite"],
      "phpExecutable": "C:\\path\\to\\php.exe",
      "allowedSecretEnvKeys": ["WEBHOOK_APP_SECRET"],
      "readOnlyArtisanCommands": ["integration:readiness"]
    }
  }
}

Configuration fields:

  • root: approved project root.

  • stack: descriptive project stack.

  • phpExecutable: optional project-specific PHP executable.

  • allowedSecretEnvKeys: .env keys approved only for in-memory secret operations and output redaction.

  • readOnlyArtisanCommands: project-specific commands that are verified to be read-only.

An alternative configuration file can be supplied through:

LOCALDEV_MCP_PROJECTS=/absolute/path/to/projects.json

Run the server

npm start

The server communicates over MCP stdio. Configure the MCP client to launch:

command: node
args: [<absolute-path>/dist/index.js]

Validation

npm run typecheck
npm run build
npm run smoke
npm run integration-smoke
npm run laravel-tools-smoke
npm run file-import-smoke
npm run benchmark

The generic smoke suites are self-contained and do not depend on private application repositories.

Security defaults

  • Only roots listed in the selected local project configuration are accessible.

  • Absolute target paths and .. traversal are rejected.

  • File imports accept sources only from configured upload roots, reject source and destination symlinks, and stream bytes without Base64 conversion.

  • .env, credentials, private keys, .git, vendor, and node_modules are blocked from normal file tools and imports.

  • Existing-file changes require the SHA-256 value returned by a read tool; binary imports support the same check when overwriting.

  • Patch, replace, rename, and delete operations create local backups.

  • Batch patching validates every target before writing and attempts rollback after partial failure.

  • Arbitrary executables, shell operators, deployments, production flags, destructive database operations, and destructive Git commands are blocked or require explicit risk-specific confirmation.

  • Tinker code cannot directly access files, environment variables, network sockets, process functions, or raw SQL execution helpers.

  • HTTP integration requests are restricted to loopback hosts and revalidate redirects.

  • Commands and sensitive operations are audited locally under logs/audit.log without recording approved secret values.

See SECURITY.md for the security model and reporting guidance.

Deliberate limitations

LocalDev MCP is not an operating-system sandbox, deployment agent, browser automation platform, or unrestricted terminal. Run it only on a trusted development machine, keep the project allowlist narrow, and review write approvals before execution.

Example workflow

1. get_skill when a governing workflow applies
2. get_project_snapshot
3. search_code / batch_read_files
4. apply_patch / batch_apply_patches
5. laravel_run_artisan / laravel_tinker_execute when integration work requires them
6. start_local_process -> local_http_request -> database assertions -> stop_local_process
7. restore temporary state in finally
8. run_tests / run_validation_plan
9. inspect_changed_files
10. git_switch_branch when a clean branch transition is required

License

MIT License. See LICENSE.

Available Tools

49 tools
apply_patchApply a unified diff patch to one project fileA

Preferred write tool for focused code edits. Read the file first and pass expectedSha256.

Inputs: path (required), patch (required), project (required), expectedSha256 (required).

batch_apply_patchesApply verified patches to multiple filesA

Verifies every file and patch before writing, creates backups, and rolls back written files if any batch write fails.

Inputs: edits (required), project (required), concurrency.

batch_read_filesRead multiple project files in parallelA
Read-only

Reads up to 30 approved text files in one call, returning line-numbered content and SHA-256 hashes while preserving the same path and secret protections as read_file.

Inputs: files (required), project (required), concurrency, maxTotalChars.

clear_laravel_cacheClear Laravel cachesA
DestructiveIdempotent

Runs php artisan optimize:clear in an auto-detected Laravel application.

Inputs: project (required), cwd, timeoutSeconds.

composer_installInstall Composer dependenciesB
Destructive

Runs composer install with safe non-interactive defaults inside an auto-detected Composer project.

Inputs: project (required), cwd, noDev, timeoutSeconds, +1 more.

create_fileCreate a new project fileA

Creates a new file and refuses to overwrite an existing path.

Inputs: path (required), project (required), content, createParents.

delete_fileDelete one project file with backupA
Destructive

Deletes one regular file after hash verification. A backup is retained under LocalDev MCP logs/backups.

Inputs: path (required), project (required), expectedSha256 (required).

get_project_infoInspect project metadata and detected app rootsA
Read-only

Returns configured stack, Git branch, manifests, package scripts, and auto-detected Laravel, npm, and Composer working directories.

Inputs: project (required).

get_project_snapshotGet a cached project development snapshotA
Read-only

Returns branch, working-tree state, recent commits, detected app roots, manifests, important docs, and top-level structure in one cached call. Cache invalidates when Git HEAD or status changes.

Inputs: project (required), forceRefresh, maxDocuments.

get_project_treeGet project directory treeA
Read-only

Use this to inspect a project structure. Generated, dependency, secret, and cache directories are excluded.

Inputs: project (required), path, maxDepth, maxEntries.

get_skillLoad an installed development skillA
Read-only

Loads the complete governing instructions for one centrally installed skill. For frontend design, redesign, UI implementation, responsive fixes, interface audits, or visual QA, call get_skill with 'frontend-craft-director' before inspecting or editing the target project.

Inputs: name (required).

git_diffGet Git diffA
Read-only

Reviews current unstaged or staged code changes. Optionally limit the diff to one project-relative path.

Inputs: project (required), path, staged.

git_statusGet Git working-tree statusA
Read-only

Use this after edits to see modified, added, deleted, and untracked files.

Inputs: project (required).

git_switch_branchSafely create or switch Git branchesA

Creates a new branch or switches to an existing branch after validating the branch name, optional expected HEAD, and clean working-tree requirement.

Inputs: branch (required), project (required), create, dryRun, +2 more.

import_file_to_projectImport an uploaded file into an allowlisted projectA
Destructive

Copies a real uploaded file into a project without Base64 conversion. The source must come from an approved mounted-file root, and the destination is restricted to the selected project root.

Inputs: project (required), destination (required), source_file (required), overwrite, +2 more.

inspect_changed_filesInspect all current Git changes in one callB
Read-only

Returns branch/status, changed file names, diff stats, diff checks, staged changes, last commit, and an optional compact diff without re-scanning the whole project.

Inputs: project (required), includeDiff, maxDiffChars, includeStaged.

inspect_database_schemaInspect Laravel database schemaA
Read-only

Runs Laravel's read-only db:show or db:table command. It does not run migrations or write data.

Inputs: project (required), cwd, table, views, +2 more.

inspect_local_processInspect a LocalDev-managed processA
Read-only

Returns status and sanitized output for a process previously started by this MCP server instance.

Inputs: project (required), sessionId (required).

inspect_routesInspect Laravel routesB
Read-only

Runs route:list with optional method, path, and name filters.

Inputs: project (required), cwd, json, name, +3 more.

laravel_database_assertRun a structured Laravel database assertionA
Read-only

Evaluates count, existence, column, or JSON-path assertions over a bounded read-only Laravel query without accepting raw SQL.

Inputs: query (required), project (required), assertion (required), cwd, +4 more.

laravel_database_snapshotRead a structured Laravel database snapshotA
Read-only

Reads a count and bounded rows through Laravel's query builder. Table, columns, filters, ordering, and limit are structured; model-provided raw SQL is not accepted.

Inputs: query (required), project (required), cwd, timeoutSeconds.

laravel_run_artisanRun a risk-classified Laravel Artisan commandA
Destructive

Runs built-in or project-specific Artisan commands through a risk classifier. Unknown custom commands require explicit write approval unless listed as read-only in the project configuration.

Inputs: command (required), project (required), cwd, options, +4 more.

laravel_tinker_executeExecute guarded multiline Laravel Tinker codeA
Destructive

Runs reviewed PHP code through Laravel Tinker using an ephemeral script outside the repository. Process, filesystem, network, raw-SQL, and secret access are blocked; database writes require explicit approval.

Inputs: code (required), project (required), cwd, outputMode, +4 more.

list_directoryList one project directoryA
Read-only

Lists immediate files and folders with type, size, and modification time. Secret and dependency paths remain blocked.

Inputs: project (required), path, maxEntries, includeHidden.

list_projectsList configured local projectsA
Read-only

Use this first to discover project keys, roots, stacks, and whether each root exists.

Inputs: no named parameters.

list_skillsList installed development skillsA
Read-only

Lists centrally installed LocalDev MCP skills with descriptions and their available references/templates. Use this when the user asks what workflows or skills are available.

Inputs: no named parameters.

local_http_requestSend a loopback-only HTTP integration requestA

Sends an HTTP request only to approved hosts that resolve exclusively to loopback addresses. Redirects are revalidated and sensitive headers are redacted.

Inputs: url (required), project (required), body, method, +5 more.

local_secret_operationUse an approved local environment secret in memoryB
Read-only

Checks an approved Laravel .env key or computes a digest/HMAC without returning, logging, placing on the command line, or writing the secret value.

Inputs: envKey (required), project (required), operation (required), cwd, +2 more.

npm_installInstall npm dependenciesB
Destructive

Runs npm ci or npm install with no-audit/no-fund defaults inside an auto-detected npm project.

Inputs: project (required), cwd, mode, ignoreScripts, +1 more.

read_fileRead a project fileA
Read-only

Use this to read a text file with line numbers and a SHA-256 version hash. Secret-like and dependency files are blocked.

Inputs: path (required), project (required), endLine, maxLines, +1 more.

read_laravel_logsRead recent Laravel log linesA
Read-only

Reads and redacts recent lines from the newest Laravel log or a selected log file.

Inputs: project (required), cwd, file, contains, +1 more.

read_skill_referenceRead a skill reference or templateA
Read-only

Reads one supporting file declared by get_skill from that skill's references/ or templates/ directory. Use progressive disclosure: load the main skill first, then read only the supporting file needed for the current task.

Inputs: skill (required), reference (required).

rename_fileRename or move one project fileB
Destructive

Moves a file inside the same configured project. Source hash is required and destination overwrite is refused.

Inputs: source (required), project (required), destination (required), expectedSha256 (required), +1 more.

replace_textReplace exact text safely in one fileA

Performs a precise text replacement with SHA-256 verification, exact occurrence counting, backup, and no shell or script execution.

Inputs: path (required), newText (required), oldText (required), project (required), +2 more.

restart_queue_workersRestart Laravel queue workersA
Destructive

Runs php artisan queue:restart so local workers restart gracefully after their current job.

Inputs: project (required), cwd, timeoutSeconds.

run_artisanRun an allowlisted or configured read-only Artisan commandB
Destructive

Runs a built-in allowlisted Artisan command or a project-specific command explicitly configured as read-only. Use laravel_run_artisan for reviewed write-capable custom commands.

Inputs: command (required), project (required), cwd, args, +1 more.

run_buildRun the project's npm buildB

Runs an existing build script, normally npm run build.

Inputs: project (required), cwd, args, script, +1 more.

run_commandRun an allowlisted development commandC
Destructive

Runs guarded PHP/Laravel, Composer, npm, or allowlisted Git commands. Shell operators and arbitrary executables are blocked.

Inputs: project (required), executable (required), cwd, args, +1 more.

run_eslintRun the project's ESLint npm scriptB

Runs an existing lint script, normally npm run lint, with optional extra arguments.

Inputs: project (required), cwd, args, script, +1 more.

run_npmRun an npm package scriptA
Destructive

Runs one script declared in package.json from an auto-detected or specified npm app root.

Inputs: script (required), project (required), cwd, args, +1 more.

run_pestRun Pest directlyB

Runs vendor/bin/pest with optional filter and path from a Laravel/Composer app root.

Inputs: project (required), cwd, path, filter, +2 more.

run_phpunitRun PHPUnit directlyB

Runs vendor/bin/phpunit with optional filter, test suite, and path from a Laravel/Composer app root.

Inputs: project (required), cwd, path, filter, +2 more.

run_testsRun the detected project test suiteB

Auto-detects Laravel or npm tests, with optional working directory and test filter.

Inputs: project (required), cwd, filter, target, +2 more.

run_validation_planRun a compact multi-step validation planB

Runs Git diff checks plus selected Composer, Laravel test, and npm script validations in one local call, returning compact step summaries to reduce round-trips and context size.

Inputs: project (required), npmCwd, profile, phpFilter, +4 more.

search_codeSearch text or regex across project codeA
Read-only

High-speed code search using ripgrep when available, with a safe built-in fallback. Generated, dependency, and secret files are ignored.

Inputs: query (required), project (required), glob, regex, +2 more.

search_filesSearch project file names or glob patternsA
Read-only

Finds files by name substring or safe glob without reading file contents.

Inputs: query (required), project (required), mode, path, +2 more.

start_local_processStart a managed local Laravel processA
Destructive

Starts only a LocalDev-managed Laravel development server on a loopback host. Port 0 selects an available ephemeral port automatically; occupied explicit ports are refused, and unrelated processes are never adopted or stopped.

Inputs: project (required), cwd, host, kind, +2 more.

stop_local_processStop a LocalDev-managed processA
DestructiveIdempotent

Stops only a process session created by start_local_process for the same project.

Inputs: project (required), sessionId (required), timeoutSeconds.

write_fileCreate or replace a project fileA
Idempotent

Use only when a complete file replacement is appropriate. Existing files require expectedSha256 from read_file.

Inputs: path (required), content (required), project (required), createParents, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 49 tools

    Disambiguation4/5

    Descriptions are detailed enough to distinguish tools, even those in overlapping domains like test runners (run_phpunit, run_pest) or file modification (replace_text, apply_patch). Some confusion is possible between multiple database-inspection tools, but their scopes are clearly defined.

    Naming Consistency4/5

    Most tools use a consistent verb_noun pattern (e.g., list_projects, read_file, create_file). There are minor deviations like 'laravel_tinker_execute' (should be execute_laravel_tinker) and 'local_secret_operation', but overall the pattern is predictable.

    Tool Count3/5

    49 tools is high for a server, but the broad scope of local development (file ops, Laravel, Node, Git, testing) justifies the count. It borders on too many, but each tool serves a specific purpose and the set is well-organized.

    Completeness4/5

    The server covers a comprehensive range: file CRUD, Git operations, project inspection, Laravel artisan and database commands, testing (PHPUnit, Pest), and more. Minor gaps exist (e.g., no tool for custom linters beyond ESLint), but core development workflows are fully supported.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A comprehensive Model Context Protocol server implementation that enables AI assistants to interact with file systems, databases, GitHub repositories, web resources, and system tools while maintaining security and control.
      36 npm
      2
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      A secure Model Context Protocol server providing HTTP endpoints for AI agent tool execution, including file system operations, shell commands, and LLM-based code generation.
      1
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A universal AI-powered testing server built on the Model Context Protocol (MCP). Allows AI agents to inspect, execute, test, monitor, debug, and report on software projects.
      3
      GNU Lesser General Public v2.1 only