README

Neo4j Laravel Boost

Give your AI assistant x-ray vision into your Laravel app.

Your assistant can read your files. Now it can also query your live Neo4j database
and see how your whole Laravel app is wired together: routes, jobs, events, policies, and every dependency behind them.

Quick Start · Container Graph · Prompts · Troubleshooting · Changelog

A Laravel app's container graph explored in Neo4j Browser

_{Your Laravel app, as a graph your AI can walk.}

Ask your app questions it could never answer before

💬 "What does my Neo4j schema look like?" → the assistant runs get-schema against your live database, not a guess from your code.

💬 "Which classes end up being built when POST /checkout is hit?" → it walks route → controller → every dependency in the container graph.

💬 "Which queued jobs use the redis connection, and what do they depend on?" → one graph query instead of an afternoon of grepping.

💬 "What breaks if I change PaymentGateway?" → get-class-dependency-graph shows everything that depends on it, inbound and outbound.

More ready-to-paste prompts: docs/PROMPTS.md.

Why you'll love it

🔌 One MCP entry

Neo4j tools ride on your existing Laravel Boost server (php artisan boost:mcp). No second server to wire up.

⚡ Zero binaries

The default driver transport talks Bolt straight from PHP. Nothing to download, nothing to keep running.

🕸️ Your app as a graph

container:graph exports routes, middleware, jobs, events, policies, mail, notifications, broadcasting, and container wiring into Neo4j.

🧠 Live schema & Cypher

get-schema, read-cypher, and write-cypher work against your real database from any MCP client.

🩺 Built-in doctor

neo4j-boost:doctor checks transport, credentials, and connectivity, then tells you exactly what's wrong.

🐳 Neo4j in one command

neo4j-boost:start-neo4j boots a local Docker Neo4j with APOC ready to go.

Works with Cursor, Claude Code, and any other MCP-compatible client.

How it works

flowchart LR
    A["🤖 AI assistant<br/>Cursor · Claude Code · …"] -- MCP --> B["Laravel Boost<br/>php artisan boost:mcp"]
    B --> C["Neo4j Laravel Boost<br/>Neo4j tools"]
    C -- Bolt --> D[("Neo4j")]
    E["Your Laravel app"] -- "php artisan container:graph" --> D

The assistant gets these tools next to your usual Boost tools:

Tool	What your assistant can do with it
`get-schema`	See the labels, relationships, and properties in your live database
`read-cypher`	Run read-only Cypher queries
`write-cypher`	Create and update data
`get-class-dependency-graph`	Trace what a class depends on, and what depends on it
`contribute-graph-knowledge`	Record wiring it discovered so the graph gets smarter
`list-gds-procedures`	Discover Graph Data Science algorithms (needs the GDS plugin)

Architecture deep dive: docs/architecture.md · New to all this? What is Neo4j Boost?

Installation

Requirements: PHP 8.2+ and Laravel 12 or 13.

1. Install the package

composer require --dev neo4j/laravel-boost

2. Add your Neo4j credentials

The default driver transport runs the Neo4j tools in PHP over Bolt (via laudis/neo4j-php-client), so no neo4j-mcp binary is needed:

NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

Tip

NEO4J_MCP_TRANSPORT defaults to driver. You can switch to stdio (runs the neo4j-mcp binary) or http (remote MCP server). See Transport Modes. For env problems, see Troubleshooting.

3. Run the interactive setup

php artisan neo4j-boost:setup

It checks your connection, can install the neo4j-mcp binary, and can start a local Neo4j in Docker.

4. No Neo4j yet? Start one

php artisan neo4j-boost:start-neo4j

This starts Neo4j in Docker on bolt://localhost:7687 and http://localhost:7474, with the APOC plugins the schema tools need. If it doesn't come up, see Docker setup troubleshooting.

5-minute Quick Start

Connect your MCP client and you're done. In every client, the server entry is the same:

"mcpServers": {
  "laravel-boost": {
    "command": "php",
    "args": ["artisan", "boost:mcp"],
    "env": {
      "APP_ENV": "local"
    }
  }
}

Cursor

Add the entry above to .cursor/mcp.json in your project root, or let the package write it for you:

php artisan neo4j-boost:cursor-config

Open your Laravel application folder as the workspace, reload MCP settings, and enable the server. get-schema, read-cypher, and write-cypher appear next to your Boost tools.

_{Connect the tools}	_{Ask for the schema}
_{Read with Cypher}	_{Write with Cypher}

Claude Code

Add the entry to claude_code_config.json (or run claude mcp add with the same definition). Open your Laravel application folder as the workspace so artisan is reachable.

Now ask: "What does my Neo4j schema look like?" Your assistant should answer using get-schema against your live database.

Note

Wrong workspace, missing APP_ENV=local, or HTTP /mcp 404s? See MCP configuration troubleshooting.

Exploring Your Container Dependency Graph

This is the superpower. One command exports how your Laravel app is actually wired at runtime into Neo4j:

php artisan container:graph                 # export
php artisan container:graph --dry-run       # extract only, write nothing
php artisan container:graph --print-cypher  # show what gets written

What ends up in the graph:

(:Route)-[:HANDLED_BY]->(:Abstract)-[:RESOLVES_TO]->(:Instance)
  -[:DEPENDS_ON]->(:Dependency)-[:IDENTIFIED_AS]->(:Abstract)
(:Route)-[:USES_MIDDLEWARE {order,parameters}]->(:Middleware)-[:IDENTIFIED_AS]->(:Abstract)
(:Event)-[:HANDLED_BY]->(:Abstract)
(:Job)-[:HANDLED_BY]->(:Abstract)
(:Job)-[:USES_CONNECTION]->(:QueueConnection)
(:ScheduledTask)-[:HANDLED_BY]->(:Abstract)
(:AuthGuard)-[:USES_PROVIDER]->(:AuthProvider)
(:AuthProvider)-[:USES_MODEL]->(:Abstract)
(:PasswordBroker)-[:USES_PROVIDER]->(:AuthProvider)
(:Policy)-[:HANDLED_BY]->(:Abstract)
(:Policy)-[:FOR_MODEL]->(:Abstract)
(:GateAbility)-[:HANDLED_BY]->(:Abstract)
(:Notification)-[:HANDLED_BY]->(:Abstract)
(:Notification)-[:USES_CHANNEL]->(:NotificationChannel)
(:Mailable)-[:HANDLED_BY]->(:Abstract)
(:Mailable)-[:USES_MAILER]->(:Mailer)
(:Mailable)-[:USES_CONNECTION]->(:QueueConnection)
(:BroadcastChannel)-[:HANDLED_BY]->(:Abstract)
(:ArtisanCommand)-[:HANDLED_BY]->(:Abstract)
(:ServiceProvider)-[:REGISTERS]->(:Abstract)

:Abstract is the container lookup key (the same idea as make($abstract)), with a kind property (Class / Interface / AbstractType). Bindings use BINDS_TO between abstracts.

Then ask your assistant, or call get-class-dependency-graph directly:

{ "class": "App\\Services\\FooService", "direction": "outbound", "depth": 4 }

🔍 Ready-made Neo4j Browser queries (routes, jobs, scheduled tasks, auth, policies, gates, notifications, mail, broadcasting, Artisan commands, service providers)

Routes and their middleware

MATCH path = (r:Route)-[:USES_MIDDLEWARE]->(m:Middleware)-[:IDENTIFIED_AS]->(a:Abstract)
RETURN path
LIMIT 50

Jobs, their queue connection, and dependencies

MATCH (j:Job)-[:HANDLED_BY]->(:Abstract)-[:RESOLVES_TO]->(root:Instance)
OPTIONAL MATCH conn = (j)-[:USES_CONNECTION]->(:QueueConnection)
OPTIONAL MATCH path = (root)-[:DEPENDS_ON|IDENTIFIED_AS|RESOLVES_TO*0..8]->(n)
RETURN j, root, conn, path
LIMIT 50

Scheduled tasks

MATCH (t:ScheduledTask)-[:HANDLED_BY]->(:Abstract)-[:RESOLVES_TO]->(root:Instance)
OPTIONAL MATCH path = (root)-[:DEPENDS_ON|IDENTIFIED_AS|RESOLVES_TO*0..8]->(n)
RETURN t, root, path
LIMIT 50

Auth guards, providers, and models

MATCH (g:AuthGuard)-[:USES_PROVIDER]->(p:AuthProvider)
OPTIONAL MATCH model = (p)-[:USES_MODEL]->(:Abstract)-[:RESOLVES_TO]->(root:Instance)
OPTIONAL MATCH path = (root)-[:DEPENDS_ON|IDENTIFIED_AS|RESOLVES_TO*0..8]->(n)
RETURN g, p, root, model, path
LIMIT 50

Policies

MATCH (p:Policy)-[:HANDLED_BY]->(:Abstract)-[:RESOLVES_TO]->(root:Instance)
OPTIONAL MATCH model = (p)-[:FOR_MODEL]->(:Abstract)
OPTIONAL MATCH path = (root)-[:DEPENDS_ON|IDENTIFIED_AS|RESOLVES_TO*0..8]->(n)
RETURN p, root, model, path
LIMIT 50

Gate abilities

MATCH (a:GateAbility)
OPTIONAL MATCH (a)-[:HANDLED_BY]->(:Abstract)-[:RESOLVES_TO]->(root:Instance)
OPTIONAL MATCH path = (root)-[:DEPENDS_ON|IDENTIFIED_AS|RESOLVES_TO*0..8]->(n)
RETURN a, root, path
LIMIT 50

Notifications and channels

MATCH (n:Notification)-[:HANDLED_BY]->(:Abstract)-[:RESOLVES_TO]->(root:Instance)
OPTIONAL MATCH ch = (n)-[:USES_CHANNEL]->(:NotificationChannel)
OPTIONAL MATCH path = (root)-[:DEPENDS_ON|IDENTIFIED_AS|RESOLVES_TO*0..8]->(x)
RETURN n, root, ch, path
LIMIT 50

Mailables, mailers, and queue connections

MATCH (m:Mailable)-[:HANDLED_BY]->(:Abstract)-[:RESOLVES_TO]->(root:Instance)
OPTIONAL MATCH mailer = (m)-[:USES_MAILER]->(:Mailer)
OPTIONAL MATCH conn = (m)-[:USES_CONNECTION]->(:QueueConnection)
OPTIONAL MATCH path = (root)-[:DEPENDS_ON|IDENTIFIED_AS|RESOLVES_TO*0..8]->(n)
RETURN m, root, mailer, conn, path
LIMIT 50

Broadcast channels

MATCH (c:BroadcastChannel)-[:HANDLED_BY]->(:Abstract)-[:RESOLVES_TO]->(root:Instance)
OPTIONAL MATCH path = (root)-[:DEPENDS_ON|IDENTIFIED_AS|RESOLVES_TO*0..8]->(n)
RETURN c, root, path
LIMIT 50

Artisan commands

MATCH (c:ArtisanCommand {source: 'app'})-[:HANDLED_BY]->(:Abstract)-[:RESOLVES_TO]->(root:Instance)
OPTIONAL MATCH path = (root)-[:DEPENDS_ON|IDENTIFIED_AS|RESOLVES_TO*0..8]->(n)
RETURN c, root, path
LIMIT 50

Service providers

MATCH (p:ServiceProvider {source: 'app'})-[r:REGISTERS]->(a:Abstract)
OPTIONAL MATCH (a)-[:BINDS_TO]->(c:Abstract)
RETURN p, r, a, c
LIMIT 50

🕵️ Find hidden dependencies with static scanning

Runtime reflection can't see service-location calls, facade usage, or direct new instantiations. Point the static scanner at your app directories to catch them:

NEO4J_CONTAINER_GRAPH_STATIC_SCAN_PATHS=/absolute/path/to/app/Services,/absolute/path/to/app/Http

You can also publish the config and set container_graph.static_scan_paths. If unset, no PHP files are scanned and only runtime reflection edges are exported.

Note

The export maps every PSR-4 class in the container. On apps with hundreds of services it takes a little while and produces a big graph. That's expected.

Available Artisan Commands

Command	What it does
`neo4j-boost:setup`	Interactive setup: checks the connection, can configure Docker Neo4j, writes Cursor config
`neo4j-boost:start-neo4j`	Starts a local Neo4j Docker instance
`neo4j-boost:cursor-config`	Creates or updates `.cursor/mcp.json`
`neo4j-boost:install-mcp`	Downloads the official `neo4j-mcp` binary (only needed for STDIO)
`neo4j-boost:doctor`	Diagnoses transport, binary, password, and overall readiness
`neo4j-boost:test-stdio`	Verbose end-to-end test of the STDIO handshake and tools
`container:graph`	Exports routes, middleware, events, jobs, queue connections, scheduled tasks, auth config, policies, gates, notifications, mail, broadcasting, and container wiring into Neo4j (`--dry-run`, `--print-cypher`)

Configuration

Transport Modes

Mode	How it connects	When to use it
`driver` (default)	PHP talks to Neo4j over Bolt via `laudis/neo4j-php-client`	Almost always. No binary needed
`stdio`	Runs the official `neo4j-mcp` binary as a subprocess	You want the official binary. Install it with `php artisan neo4j-boost:install-mcp`, then set `NEO4J_MCP_TRANSPORT=stdio`
`http`	Calls a remote or containerized MCP server	Set `NEO4J_MCP_TRANSPORT=http` and `NEO4J_MCP_URL=http://localhost:8080/mcp`

Important

In HTTP mode this package sends your Neo4j credentials with every request, so don't set NEO4J_USERNAME or NEO4J_PASSWORD on the MCP server container itself.

Run php artisan config:clear after editing .env. Auth and env mistakes are covered in Authentication issues and Environment configuration.

Neo4j Aura? Use the Aura console URI (neo4j+s://...) with driver transport. See Neo4j Aura connectivity.

Using Docker Compose (HTTP mode)

🐳 Show the docker-compose.yml

services:
  neo4j:
    image: neo4j:5-community
    environment:
      NEO4J_AUTH: neo4j/your-password
      NEO4J_PLUGINS: '["apoc", "graph-data-science"]'
      NEO4J_dbms_security_procedures_unrestricted: 'apoc.*,gds.*'
      NEO4J_dbms_security_procedures_allowlist: 'apoc.*,gds.*'
    ports:
      - "7474:7474"
      - "7687:7687"
    healthcheck:
      test: ["CMD-SHELL", "wget -q -O /dev/null http://localhost:7474 || exit 1"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 15s

  # Official Neo4j MCP server (HTTP mode)
  neo4j-mcp:
    image: mcp/neo4j
    environment:
      NEO4J_URI: bolt://neo4j:7687
      NEO4J_DATABASE: neo4j
      NEO4J_READ_ONLY: "false"
      NEO4J_TELEMETRY: "false"
      NEO4J_TRANSPORT_MODE: http
      NEO4J_MCP_HTTP_HOST: 0.0.0.0
      NEO4J_MCP_HTTP_PORT: "8080"
    ports:
      - "8080:8080"
    depends_on:
      neo4j:
        condition: service_healthy

Then point Laravel at it:

NEO4J_MCP_TRANSPORT=http
NEO4J_MCP_URL=http://localhost:8080/mcp
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=your-password

Networking, plugin, and port issues: Docker setup troubleshooting.

Graph Data Science (GDS) Plugin

list-gds-procedures needs the Graph Data Science plugin. Without it, only that tool errors; get-schema, read-cypher, and write-cypher keep working. With Docker, add NEO4J_PLUGINS: '["apoc", "graph-data-science"]' and the NEO4J_dbms_security_procedures_* variables shown above.

⚙️ More options: publishing config, running setup after updates, binary platforms

Publish the config to tweak neo4j_mcp.transport, bolt.uri, bolt.username, http.url, and more in config/neo4j-boost.php:

php artisan vendor:publish --tag=neo4j-boost-config

Re-run setup after every composer update:

{
  "scripts": {
    "post-update-cmd": [
      "@php artisan neo4j-boost:setup --no-interaction"
    ]
  }
}

Binary platforms (neo4j-boost:install-mcp): Linux (x86_64, arm64, i386), macOS (x86_64, Apple Silicon), and Windows (x86_64, arm64, i386). Windows uses .zip archives (needs ext-zip); Linux and macOS use .tar.gz. If detection fails, set NEO4J_MCP_PLATFORM_ASSET in .env.

Common Issues & Troubleshooting

Something off? Start here, especially after any .env change (then php artisan config:clear):

php artisan neo4j-boost:doctor

Symptom	Fix
`Could not open input file: artisan`	Open your Laravel app folder as the workspace, not the package folder. More
`There are no commands defined in the "boost" namespace`	Add `"env": { "APP_ENV": "local" }` to your MCP server entry
STDIO: `Neo4j password is required`	Set `NEO4J_PASSWORD` in `.env`, then `php artisan config:clear`. More
APOC / meta errors	Recreate local Neo4j: `php artisan neo4j-boost:start-neo4j --recreate`. More
Docker: can't reach `bolt://localhost:7687`	When Laravel isn't on the host, use the Neo4j service hostname on the container network, then clear config cache
HTTP 404 `This server only handles requests to /mcp`	Prefer Laravel Boost (`php artisan boost:mcp`). Connecting directly? Make sure the URL ends in `/mcp` and HTTP transport is on
`Unknown function 'gds.version'`	Install the GDS plugin. Schema and Cypher tools still work without it
Aura connection failures	Use the Aura console URI (`neo4j+s://...`) with driver transport. More

The full step-by-step guide (Docker, Aura, MCP, auth, environment, error messages) lives in docs/TROUBLESHOOTING.md.

Learn more


📖 What is Neo4j Boost?	The big picture, in plain words
🚀 Getting started	Step-by-step first run
🕸️ Container graph tutorial	Everything `container:graph` can do
💬 Prompt library	Copy-paste prompts for common workflows
🏗️ Architecture	Components, MCP, and request flow
🎬 Demo media	All the GIFs and how they were made
📝 Changelog	What changed in each release

MIT licensed. Built for Laravel developers who want their AI to actually understand their app.

If it helps you, a ⭐ on GitHub helps others find it.

neo4j / laravel-boost

Package info

Security

Statistics