Change default MCP transport from stdio to driver. (#38)

Fresh installs now use in-process Bolt without the neo4j-mcp binary. Update setup messaging, env example, changelog, and README with a table of contents for quicker navigation.

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

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

@@ -54,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)),

src/Support/Neo4jMcpConfig.php

@@ -11,7 +11,7 @@ public static function transport(): string
         $transport = config('neo4j-boost.neo4j_mcp.transport');
 
         if (! is_string($transport) || $transport === '') {
-            $transport = config('neo4j-boost.transport.driver', 'stdio');
+            $transport = config('neo4j-boost.transport.driver', 'driver');
         }
 
         return strtolower((string) $transport);

tests/Integration/Neo4jBoostServiceProviderTest.php

@@ -6,6 +6,7 @@
 use Neo4j\LaravelBoost\Contracts\Neo4jMcpClientInterface;
 use Neo4j\LaravelBoost\Neo4jDriverClient;
 use Neo4j\LaravelBoost\Neo4jHttpClient;
+use Neo4j\LaravelBoost\Neo4jStdioClient;
 use Neo4j\LaravelBoost\Support\ContainerGraphConnection;
 use Neo4j\LaravelBoost\Support\Neo4jBoltClient;
 use Neo4j\LaravelBoost\Tests\TestCase;
@@ -19,6 +20,16 @@ public function test_resolves_neo4j_mcp_client_as_driver_by_default(): void
         $this->assertInstanceOf(Neo4jDriverClient::class, $client);
     }
 
+    public function test_resolves_neo4j_mcp_client_as_stdio_when_transport_is_stdio(): void
+    {
+        config(['neo4j-boost.neo4j_mcp.transport' => 'stdio']);
+
+        $this->app->forgetInstance(Neo4jMcpClientInterface::class);
+        $client = $this->app->make(Neo4jMcpClientInterface::class);
+
+        $this->assertInstanceOf(Neo4jStdioClient::class, $client);
+    }
+
     public function test_resolves_neo4j_mcp_client_as_http_when_transport_is_http(): void
     {
         config(['neo4j-boost.neo4j_mcp.transport' => 'http']);