Laraguard MCP

A security audit MCP server for Laravel projects — built with TypeScript and stdio transport.

Overview

Laraguard MCP is a standalone Model Context Protocol (MCP) server that performs security audits on Laravel projects. It is implemented in pure TypeScript using the official @modelcontextprotocol/sdk and communicates over stdio, making it natively compatible with any MCP-capable IDE or client (Cursor, Claude Desktop, VS Code MCP extensions, etc.).

The server analyses a Laravel project as an external target — it does not require Laravel to be running. It returns structured JSON findings categorised by severity, covering configuration issues, risky code patterns, and dependency hygiene.

Features

• 🔍 Static code scanning — 15+ rules covering SQL injection, RCE, hardcoded credentials, weak crypto, mass assignment, and LFI
• 🎭 Blade XSS scanner — detects unescaped {!! !!} output and raw input rendering in templates
• 🛣️ Route & middleware audit — flags admin routes without auth, API routes without auth:sanctum, login routes without throttle, and CSRF exceptions
• 📦 Dependency CVE feed — queries the OSV.dev API for real CVEs across all composer.lock packages
• ⚙️ Configuration audit — inspects .env (DEBUG, APP_KEY, APP_ENV, secure cookies) and config/cors.php
• 🗂️ Project metadata — reads composer.json to identify Laravel and PHP version constraints
• 💥 Active attack simulation — fires HTTP probes (SQL injection, XSS, CSRF, auth bypass, rate limiting) against a running app
• 🔒 Path traversal prevention — strict allowlist enforcement for all file operations
• ✂️ Secret redaction — sensitive values are masked in textual output before reaching the MCP client
• 🚀 stdio transport — zero-config network; works inside any IDE that supports MCP

MCP Tools

The server exposes 8 tools. All static tools accept a single path parameter. attack_simulate additionally requires a baseUrl.

Code Scan — Detected Patterns

Audit Report Schema

Every tool returns a structured JSON report:

{
  "summary": {
    "critical": 0,
    "high": 1,
    "medium": 2,
    "low": 0,
    "info": 1
  },
  "findings": [
    {
      "severity": "high",
      "type": "SQL_INJECTION",
      "title": "Potential SQL injection via whereRaw",
      "file": "app/Http/Controllers/UserController.php",
      "line": 42,
      "evidence": "->whereRaw('email = ' . $email)",
      "recommendation": "Avoid raw SQL with user input. Use parameter binding/query builder."
    }
  ],
  "metadata": {
    "scannedPath": "/absolute/path/to/laravel-project",
    "engine": "Laraguard MCP",
    "version": "3.0.0",
    "timestamp": "2025-01-01T00:00:00.000Z",
    "durationMs": 312
  }
}

Architecture

src/
├── index.ts      — MCP server bootstrap and tool registration
├── config.ts     — Environment variable loading and validation
├── security.ts   — Path allowlist enforcement and secret redaction
├── files.ts      — Safe file enumeration and reading
├── tools.ts      — Audit tool implementations
├── reports.ts    — Report aggregation and severity summarization
└── types.ts      — Domain types (Finding, AuditReport, Severity, etc.)

Runtime stack:

Requirements

• Node.js 20 or higher
• npm 10 or higher

Verify your environment:

node -v
npm -v

Installation

Clone the repository and install dependencies:

git clone https://github.com/ecr17dev/Laraguard-MCP.git
cd "Laraguard MCP"
npm install

Configuration

Copy the example environment file and customise it:

cp .env.example .env

Environment Variables

Priority order: MCP_BASE_PATHS → MCP_BASE_PATH → current working directory.

Example .env

# Allow scanning two project roots
MCP_BASE_PATHS="/Users/yourname/projects/my-laravel-app,/srv/workspaces/api"

# Scan limits
MCP_MAX_FILES=5000
MCP_MAX_FILE_SIZE_BYTES=300000
MCP_TIMEOUT_SECONDS=30

Development

Available Scripts

Running in Development Mode

npm run dev

Building for Production

npm run check   # Validate types first
npm run build   # Emit to dist/
npm run start   # Run compiled output

Integration with MCP Clients

Generic MCP Configuration (JSON)

Add the following to your MCP client's configuration file, replacing the path with the absolute path to your installation:

{
  "mcpServers": {
    "laraguard": {
      "command": "node",
      "args": ["/absolute/path/to/Laraguard MCP/dist/index.js"],
      "env": {
        "MCP_BASE_PATHS": "/absolute/path/to/your-laravel-project"
      }
    }
  }
}

Using Development Mode (tsx)

If you prefer to run without building first:

{
  "mcpServers": {
    "laraguard": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/Laraguard MCP/src/index.ts"],
      "env": {
        "MCP_BASE_PATHS": "/absolute/path/to/your-laravel-project"
      }
    }
  }
}

Cursor IDE

Open Settings → MCP and paste the JSON block above. Cursor will detect the server on the next reload.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) and add the laraguard entry under mcpServers.

Tool Usage Reference

project_info

{ "path": "/absolute/path/to/laravel-project" }

Returns basic project metadata without performing any security checks. Use it to confirm the target is a valid Laravel project and inspect framework and PHP version constraints before auditing.

dependency_audit

{ "path": "/absolute/path/to/laravel-project" }

Parses composer.lock, extracts all locked package names and versions, and queries the OSV.dev batch API for known CVEs. Each vulnerability is returned as a finding with:

• CVE/GHSA identifier and summary
• Severity (mapped from CVSS score)
• Affected package version and recommended fix version
• Direct link to the advisory page

config_audit

{ "path": "/absolute/path/to/laravel-project" }

code_scan

{ "path": "/absolute/path/to/laravel-project" }

Performs line-by-line static analysis across all PHP files. Returns every matching finding with file path, line number, and evidence snippet. See the Code Scan — Detected Patterns table above for the full rule set.

blade_scan

{ "path": "/absolute/path/to/laravel-project" }

Scans all .blade.php files under resources/views/ for XSS-prone output patterns:

route_audit

{ "path": "/absolute/path/to/laravel-project" }

Reads routes/web.php, routes/api.php, and app/Http/Middleware/VerifyCsrfToken.php:

attack_simulate

{
  "path": "/absolute/path/to/laravel-project",
  "baseUrl": "http://localhost:8000"
}

⚠️ Only use against local or staging environments. Never run against production.

Fires 6 live HTTP probes against the running application:

The report includes a probes metadata array with the status code, duration, and triggered state for every probe.

full_audit

{ "path": "/absolute/path/to/laravel-project" }

Runs dependency_audit, config_audit, code_scan, blade_scan, and route_audit in parallel and merges all findings into a single consolidated report. The metadata includes per-section summaries.

Security Design

Laraguard MCP implements the following controls to ensure it operates safely even when handling untrusted project paths:

• Strict path allowlisting — all file access is validated against MCP_BASE_PATHS / MCP_BASE_PATH; path traversal attempts are rejected immediately.
• File count limit — configurable cap (MCP_MAX_FILES) prevents runaway enumeration on large monorepos.
• File size limit — configurable cap (MCP_MAX_FILE_SIZE_BYTES) prevents memory exhaustion from binary or generated files.
• Directory and extension exclusions — vendor/, node_modules/, .git/, and binary file types are excluded from scans.
• Secret redaction — sensitive values (passwords, tokens, keys) are masked in textual output before being returned to the MCP client.
• Attack simulation guard — attack_simulate always targets only the explicitly provided baseUrl; no automated discovery or production detection is performed.

Important Notes

• Laraguard MCP analyses a Laravel project as an external auditor — the Laravel application itself does not need to be running for static tools.
• attack_simulate requires the application to be running and should never target production.
• The server is framework-agnostic at the transport level: any client that supports MCP stdio can use it.
• All findings are informational. Always combine automated scanning with manual code review and dedicated DAST/SAST tooling (OWASP ZAP, Burp Suite) for production security assessments.

License

This project is licensed under the MIT License. See LICENSE for details.