Bug fixes under v1.0.0 (#37)

Bug fixes under v1.0.0

Author: cod3xa

.env.example

@@ -7,11 +7,12 @@ APP_DEBUG=true
 APP_KEY=
 
 # Neo4j MCP transport mode:
-# - stdio (default): runs the local neo4j-mcp binary.
+# - driver (default): in-process Bolt via laudis/neo4j-php-client — no neo4j-mcp binary required.
+# - stdio: runs the local neo4j-mcp binary (set NEO4J_MCP_TRANSPORT=stdio).
 # - http: use when the MCP server runs elsewhere and NEO4J_MCP_URL points to it.
-NEO4J_MCP_TRANSPORT=stdio
+# NEO4J_MCP_TRANSPORT=driver
 
-# Neo4j database credentials (required for STDIO mode — passed to the neo4j-mcp subprocess)
+# Neo4j database credentials (used by driver, stdio, and container:graph)
 NEO4J_URI=bolt://localhost:7687
 NEO4J_USERNAME=neo4j
 NEO4J_PASSWORD=

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Default `NEO4J_MCP_TRANSPORT` is now **`driver`** (in-process Bolt) instead of `stdio`. Set `NEO4J_MCP_TRANSPORT=stdio` explicitly to use the `neo4j-mcp` binary.
+
 ## [1.0.0] - 2026-07-06
 
 ### Added

README.md

@@ -8,6 +8,33 @@ Release notes: [CHANGELOG.md](CHANGELOG.md).
 
 ---
 
+## Table of contents
+
+- [Why Use It?](#why-use-it)
+- [Installation & Setup](#installation--setup)
+  - [1. Install the Package](#1-install-the-package)
+  - [2. Update Your Environment Variables](#2-update-your-environment-variables)
+  - [3. Run the Interactive Setup](#3-run-the-interactive-setup)
+  - [4. Start a Local Neo4j Instance (Optional)](#4-start-a-local-neo4j-instance-optional)
+  - [5. Connect Your MCP Client](#5-connect-your-mcp-client)
+- [Usage](#usage)
+  - [MCP Client Configuration](#mcp-client-configuration)
+    - [Cursor](#cursor)
+    - [Claude Code](#claude-code)
+  - [Exploring Your Container Dependency Graph](#exploring-your-container-dependency-graph)
+  - [Available Artisan Commands](#available-artisan-commands)
+- [Important Notes & Advanced Configuration](#important-notes--advanced-configuration)
+  - [Transport Modes](#transport-modes)
+  - [Using Docker Compose (HTTP mode)](#using-docker-compose-http-mode)
+  - [Graph Data Science (GDS) Plugin](#graph-data-science-gds-plugin)
+  - [Automating Setup After Updates](#automating-setup-after-updates)
+  - [Publishing Configuration (Optional)](#publishing-configuration-optional)
+  - [Binary Platform Support](#binary-platform-support)
+  - [Common Issues & Troubleshooting](#common-issues--troubleshooting)
+- [License](#license)
+
+---
+
 ## Why Use It?
 
 Out of the box, AI coding assistants can only read your local files, they can't inspect your live database schema or run Cypher queries. This package bridges that gap by connecting the official Neo4j MCP server directly into Laravel Boost. This allows your assistant to:
@@ -42,7 +69,7 @@ NEO4J_PASSWORD=your-password
 
 ```
 
-> **Note:** `NEO4J_MCP_TRANSPORT` defaults to `driver`. You can switch to `stdio` (spawns the `neo4j-mcp` binary as a subprocess) or `http` (remote MCP server) — see the Notes section below.
+> **Note:** `NEO4J_MCP_TRANSPORT` defaults to `driver`. You can switch to `stdio` (spawns the `neo4j-mcp` binary as a subprocess) or `http` (remote MCP server) — see [Transport Modes](#transport-modes) below.
 
 ### 3. Run the Interactive Setup
 
@@ -149,15 +176,17 @@ Once exported, you can use the **get-class-dependency-graph** MCP tool to query
 
 ## Important Notes & Advanced Configuration
 
-**Transport Modes**
+### Transport Modes
+
 The default is `driver`, which runs Neo4j tools in PHP over Bolt via `laudis/neo4j-php-client`. No binary needed. You have two other options:
 
 * **STDIO:** Spawns the official `neo4j-mcp` binary as a subprocess. Install it with `php artisan neo4j-boost:install-mcp`, then set `NEO4J_MCP_TRANSPORT=stdio` in your `.env`.
 * **HTTP:** Connects to a remote or containerized MCP server. Set `NEO4J_MCP_TRANSPORT=http` and `NEO4J_MCP_URL=http://localhost:8080/mcp`. In HTTP mode, this package sends your Neo4j credentials with every request, so do not set `NEO4J_USERNAME` or `NEO4J_PASSWORD` on the MCP server container itself.
 
 Remember to run `php artisan config:clear` after editing your `.env` file so Laravel picks up the change.
 
-**Using Docker Compose (HTTP mode, Neo4j + MCP server)**
+### Using Docker Compose (HTTP mode)
+
 Here is a quick setup guide if you prefer Docker:
 
 ```yaml
@@ -209,10 +238,12 @@ NEO4J_PASSWORD=your-password
 
 ```
 
-**Graph Data Science (GDS) Plugin**
+### Graph Data Science (GDS) Plugin
+
 The `list-gds-procedures` tool specifically requires the [Graph Data Science](https://neo4j.com/docs/graph-data-science/current/) plugin. If you don't have it installed, that specific tool will throw an error, but don't worry—`get-schema`, `read-cypher`, and `write-cypher` will still work perfectly. For Docker setups, just add `NEO4J_PLUGINS: '["apoc", "graph-data-science"]'` and the necessary `NEO4J_dbms_security_procedures_*` variables to your Neo4j service.
 
-**Automating Setup After Updates**
+### Automating Setup After Updates
+
 To keep everything running smoothly when you update your dependencies, you can add this script to your `composer.json`:
 
 ```json
@@ -226,7 +257,8 @@ To keep everything running smoothly when you update your dependencies, you can a
 
 ```
 
-**Publishing Configuration (Optional)**
+### Publishing Configuration (Optional)
+
 If you want to tweak the underlying config directly, publish it using:
 
 ```bash
@@ -236,7 +268,8 @@ php artisan vendor:publish --tag=neo4j-boost-config
 
 This lets you configure options in `config/neo4j-boost.php` like `neo4j_mcp.transport` (`driver`, `stdio`, or `http`), `bolt.uri`, `bolt.username`, `http.url`, and more.
 
-**Binary Platform Support**
+### Binary Platform Support
+
 If you're using `neo4j-boost:install-mcp`, the binary supports Linux (x86_64, arm64, i386), macOS (x86_64, Apple Silicon), and Windows (x86_64, arm64, i386). Windows uses `.zip` archives (requiring `ext-zip`), while Linux and macOS use `.tar.gz`. If auto-detection fails, you can manually override it by setting `NEO4J_MCP_PLATFORM_ASSET` in your `.env`.
 
 ### Common Issues & Troubleshooting
@@ -245,14 +278,14 @@ If you're using `neo4j-boost:install-mcp`, the binary supports Linux (x86_64, ar
 * **"There are no commands defined in the 'boost' namespace"** — Laravel Boost only registers its commands when your app is in a local environment. Make sure `"env": { "APP_ENV": "local" }` is included in your MCP server entry.
 * **STDIO fails with "Neo4j password is required"** — You need to set `NEO4J_PASSWORD` in your `.env` file, and then run `php artisan config:clear`.
 * **APOC/meta errors** — Your Neo4j instance might be missing the required plugins. Recreate it by running `php artisan neo4j-boost:start-neo4j --recreate`.
-* **Docker: cannot connect to `bolt://localhost:7687**` — Ensure `NEO4J_URI` is pointing to the Neo4j service hostname on your container network (for example, `neo4j://neo4j:password@neo4j-core1:7687`). If you use config caching, remember to clear it with `php artisan config:clear`.
+* **Docker: cannot connect to `bolt://localhost:7687`** — Ensure `NEO4J_URI` is pointing to the Neo4j service hostname on your container network (for example, `neo4j://neo4j:password@neo4j-core1:7687`). If you use config caching, remember to clear it with `php artisan config:clear`.
 * **HTTP 404 "This server only handles requests to /mcp"** — Some MCP clients send GET requests, but the Neo4j MCP server strictly accepts POST requests on `/mcp`. The best fix is to use Laravel Boost (`php artisan boost:mcp`) so the client talks to one STDIO server, and this package handles talking to Neo4j internally. If you *must* connect a client directly, ensure the URL ends exactly with `/mcp` and that `NEO4J_TRANSPORT_MODE=http` is set on your server.
-* **"Unknown function 'gds.version'"** — The GDS plugin is missing. Please see the GDS note above. (Your schema and Cypher tools will still function normally).
+* **"Unknown function 'gds.version'"** — The GDS plugin is missing. Please see the [GDS Plugin](#graph-data-science-gds-plugin) section above. (Your schema and Cypher tools will still function normally).
 
 ---
 
 ## License
 
 MIT.
 
----
+---

composer.json

@@ -31,11 +31,11 @@
         "php": "^8.2",
         "laravel/framework": "^12.0|^13.0",
         "laravel/boost": "^2.0",
-        "laravel/mcp": "^0.5.1",
         "laudis/neo4j-php-client": "^3.4"
     },
     "require-dev": {
         "larastan/larastan": "^3.0",
+        "laravel/mcp": "^0.5.1",
         "laravel/pint": "^1.18",
         "nikic/php-parser": "^5.4",
         "orchestra/testbench": "^10.11|^11.0",

config/neo4j-boost.php

@@ -8,18 +8,18 @@
     |
     | How this package talks to the Neo4j MCP server:
     |
-    | - http  : Connect to a remote MCP server over HTTP (e.g. a separate
-    |           neo4j-mcp process or container). Set NEO4J_MCP_TRANSPORT=http
-    |           and configure the "http" section below.
+    | - driver : Run MCP tools in PHP via laudis/neo4j-php-client (Bolt). No
+    |           neo4j-mcp binary required. This is the default. Set
+    |           NEO4J_URI / NEO4J_USERNAME / NEO4J_PASSWORD (or DSN).
     |
     | - stdio  : Run the MCP server as a subprocess and talk over stdin/stdout.
     |           Set NEO4J_MCP_TRANSPORT=stdio and configure the "stdio" section.
     |           The subprocess receives NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD
     |           from transport.stdio.env so it can connect to Neo4j.
     |
-    | - driver : Run MCP tools in PHP via laudis/neo4j-php-client (Bolt). No
-    |           neo4j-mcp binary required. Set NEO4J_MCP_TRANSPORT=driver and
-    |           NEO4J_URI / NEO4J_USERNAME / NEO4J_PASSWORD (or DSN).
+    | - http   : Connect to a remote MCP server over HTTP (e.g. a separate
+    |           neo4j-mcp process or container). Set NEO4J_MCP_TRANSPORT=http
+    |           and configure the "http" section below.
     |
     */
     'transport' => [

resources/boost/guidelines/core.blade.php

@@ -2,9 +2,18 @@
 
 This package integrates the official [Neo4j MCP](https://github.com/neo4j/mcp/releases) server into Laravel so you can use Neo4j tools from MCP clients (Cursor, Claude, etc.).
 
+### Index
+
+- [Transport modes](#transport-modes)
+- [Cursor config](#cursor-config)
+- [Run the MCP server](#run-the-mcp-server)
+- [Config](#config)
+- [Container graph POC](#container-graph-poc)
+- [Cursor: "Loading tools" stuck or HTTP 404](#cursor-loading-tools-stuck-or-http-404)
+
 ### Transport modes
 
-The package supports **STDIO** (default — local `neo4j-mcp` binary), **HTTP** (remote MCP server), and **driver** (in-process Bolt via `NEO4J_MCP_TRANSPORT=driver`). For HTTP-only setups, run the Neo4j MCP server elsewhere (e.g. Docker) with HTTP transport, then set in `.env`:
+The package supports **driver** (default — in-process Bolt via `laudis/neo4j-php-client`, no `neo4j-mcp` binary), **STDIO** (`NEO4J_MCP_TRANSPORT=stdio` — local `neo4j-mcp` binary), and **HTTP** (remote MCP server). For HTTP-only setups, run the Neo4j MCP server elsewhere (e.g. Docker) with HTTP transport, then set in `.env`:
 
 ```env
 NEO4J_MCP_URL=http://localhost:8080/mcp
@@ -24,7 +33,7 @@
 
 ### Run the MCP server
 
-- **With Laravel Boost:** Use a single MCP server: run `php artisan boost:mcp`. This package adds the official Neo4j tools (get-schema, read-cypher, write-cypher, list-gds-procedures, **get-class-dependency-graph**, **contribute-graph-knowledge**) to Boost’s server automatically. Tools call the HTTP MCP URL from `config/neo4j-boost.http` except **get-class-dependency-graph** and **contribute-graph-knowledge**, which read/write the container graph directly from Neo4j using `config/neo4j-boost.container_graph`.
+- **With Laravel Boost:** Use a single MCP server: run `php artisan boost:mcp`. This package adds the official Neo4j tools (get-schema, read-cypher, write-cypher, list-gds-procedures, **get-class-dependency-graph**, **contribute-graph-knowledge**) to Boost’s server automatically. By default, tools use **driver** transport (Bolt in PHP). Set `NEO4J_MCP_TRANSPORT=http` or `stdio` to change that. **get-class-dependency-graph** and **contribute-graph-knowledge** always read/write the container graph directly from Neo4j using `config/neo4j-boost.container_graph`.
 - **Without Boost:** Add the Neo4j MCP server to Cursor as an HTTP server. Run `php artisan neo4j-boost:cursor-config` so `.cursor/mcp.json` includes the `neo4j-boost` server with the configured URL.
 
 Set `NEO4J_URI`, `NEO4J_USERNAME`, and `NEO4J_PASSWORD` where the Neo4j MCP server runs (and in Laravel if you use the Neo4j driver).
@@ -74,4 +83,4 @@
 - Open your **Laravel app folder** (the project where you ran `composer require neo4j/laravel-boost`) as the Cursor workspace, not the neo4j-boost package folder.
 - If `.cursor/mcp.json` is missing, run `php artisan neo4j-boost:cursor-config` to create it.
 - Ensure the Neo4j MCP server is running at the URL set in `NEO4J_MCP_URL` and that it is started with HTTP transport.
-- If you see **404 "This server only handles requests to /mcp"**: Cursor may send GET requests (e.g. for SSE); the Neo4j MCP server only accepts POST on `/mcp`. Using **Boost** (one server: `boost:mcp`) avoids this—Cursor uses stdio and this package calls Neo4j MCP over HTTP. Otherwise ensure the URL ends with `/mcp` and the server is running with HTTP transport.
+- If you see **404 "This server only handles requests to /mcp"**: Cursor may send GET requests (e.g. for SSE); the Neo4j MCP server only accepts POST on `/mcp`. Using **Boost** (one server: `boost:mcp`) avoids this—Cursor uses stdio to Laravel and this package talks to Neo4j via driver (default), HTTP, or STDIO. Otherwise ensure the URL ends with `/mcp` and the server is running with HTTP transport.

src/Console/SetupCommand.php

@@ -13,7 +13,7 @@ class SetupCommand extends Command
                             {--skip-mcp : Skip Neo4j MCP binary installation}
                             {--no-cursor-config : Skip running neo4j-boost:cursor-config}';
 
-    protected $description = 'Interactive setup for Neo4j Laravel Boost (Cursor config, optional STDIO binary). Use -n/--no-interaction for manual steps only.';
+    protected $description = 'Interactive setup for Neo4j Laravel Boost (Neo4j, optional MCP binary, Cursor config). Use -n/--no-interaction for manual steps only.';
 
     public function handle(): int
     {
@@ -60,6 +60,14 @@ public function handle(): int
 
         $this->newLine();
 
+        $transport = Neo4jMcpConfig::transport();
+
+        if ($transport === 'driver' && Neo4jMcpConfig::hasNeo4jPassword()) {
+            $this->components->info('Neo4j Laravel Boost setup complete. Driver transport is ready (Bolt — no neo4j-mcp binary required).');
+
+            return self::SUCCESS;
+        }
+
         if ($installer->isInstalled() && Neo4jMcpConfig::hasNeo4jPassword()) {
             $this->components->info('Neo4j Laravel Boost setup complete. STDIO transport is ready with the local neo4j-mcp binary.');
 
@@ -81,33 +89,36 @@ protected function printProxyModelDescription(): void
     {
         $this->newLine();
         $this->components->info('Neo4j Laravel Boost setup');
-        $this->line('Default proxy path: <fg=cyan>Boost MCP -> driver -> laudis/neo4j-php-client (Bolt)</>');
-        $this->line('Driver transport is the default — no neo4j-mcp binary required.');
+        $this->line('Default path: <fg=cyan>Boost MCP -> driver transport (in-process Bolt)</>');
+        $this->line('No neo4j-mcp binary is required unless you set <fg=cyan>NEO4J_MCP_TRANSPORT=stdio</>.');
         $this->newLine();
         $this->line('Add these lines to your <fg=cyan>.env</> (reminder):');
         $this->line('  <fg=gray>NEO4J_URI=bolt://localhost:7687</>');
         $this->line('  <fg=gray>NEO4J_USERNAME=neo4j</>');
         $this->line('  <fg=gray>NEO4J_PASSWORD=password</>');
-        $this->line('  <fg=gray># Optional: set NEO4J_MCP_TRANSPORT=stdio to use the neo4j-mcp binary instead</>');
         $this->newLine();
     }
 
     protected function printManualInstructions(): void
     {
         $this->components->warn('Non-interactive mode: run these steps manually.');
         $this->newLine();
-        $this->line('  1. Ensure .env contains:');
+        $this->line('  1. Install the Neo4j MCP binary:');
+        $this->line('     <fg=gray>php artisan neo4j-boost:install-mcp</>');
+        $this->newLine();
+        $this->line('  2. Start local Neo4j:');
+        $this->line('     <fg=gray>php artisan neo4j-boost:start-neo4j</>');
+        $this->newLine();
+        $this->line('  3. Ensure .env contains:');
         $this->line('     <fg=gray>NEO4J_URI=bolt://localhost:7687</>');
         $this->line('     <fg=gray>NEO4J_USERNAME=neo4j</>');
         $this->line('     <fg=gray>NEO4J_PASSWORD=password</>');
         $this->newLine();
-        $this->line('  2. Configure Cursor MCP:');
-        $this->line('     <fg=gray>php artisan neo4j-boost:cursor-config</>');
+        $this->line('  4. (Optional) For STDIO transport, also run install-mcp and set:');
+        $this->line('     <fg=gray>NEO4J_MCP_TRANSPORT=stdio</>');
         $this->newLine();
-        $this->line('  Optional (STDIO transport only):');
-        $this->line('     <fg=gray>php artisan neo4j-boost:install-mcp</>');
-        $this->line('     <fg=gray>php artisan neo4j-boost:start-neo4j</>');
-        $this->line('     Set NEO4J_MCP_TRANSPORT=stdio in .env');
+        $this->line('  5. Configure Cursor MCP:');
+        $this->line('     <fg=gray>php artisan neo4j-boost:cursor-config</>');
         $this->newLine();
     }
 
@@ -125,6 +136,13 @@ protected function shouldInstallMcpBinary(): bool
             return false;
         }
 
+        if (Neo4jMcpConfig::transport() === 'driver') {
+            return $this->confirm(
+                'Install the official Neo4j MCP server binary? (only required for NEO4J_MCP_TRANSPORT=stdio)',
+                false
+            );
+        }
+
         return $this->confirm(
             'Install the official Neo4j MCP server binary for this project?',
             true

src/Neo4jBoostServiceProvider.php

@@ -41,6 +41,7 @@
 use Neo4j\LaravelBoost\StaticAnalysis\InstantiationEdgeFinder;
 use Neo4j\LaravelBoost\StaticAnalysis\ServiceLocationEdgeFinder;
 use Neo4j\LaravelBoost\Support\ContainerGraphConnection;
+use Neo4j\LaravelBoost\Support\DevDependencyConfigPublisher;
 use Neo4j\LaravelBoost\Support\Neo4jBoltClient;
 
 class Neo4jBoostServiceProvider extends ServiceProvider
@@ -53,7 +54,7 @@ public function register(): void
         $this->app->singleton(BoltExecutorInterface::class, Neo4jBoltExecutor::class);
 
         $this->app->singleton(Neo4jMcpClientInterface::class, function ($app) {
-            $driver = strtolower((string) config('neo4j-boost.neo4j_mcp.transport', 'stdio'));
+            $driver = strtolower((string) config('neo4j-boost.neo4j_mcp.transport', 'driver'));
 
             return match ($driver) {
                 'driver' => new Neo4jDriverClient($app->make(BoltExecutorInterface::class)),
@@ -90,10 +91,19 @@ public function register(): void
 
     public function boot(): void
     {
+        $configSource = __DIR__.'/../config/neo4j-boost.php';
+        $configDestination = config_path('neo4j-boost.php');
+
         $this->publishes([
-            __DIR__.'/../config/neo4j-boost.php' => config_path('neo4j-boost.php'),
+            $configSource => $configDestination,
         ], 'neo4j-boost-config');
 
+        (new DevDependencyConfigPublisher)->publishIfMissing(
+            $configSource,
+            $configDestination,
+            $this->app->basePath(),
+        );
+
         $this->mergeBoostTools();
 
         if ($this->app->runningInConsole()) {