PHPLARA-253: Create database-info Boost tool as alternative to database-schema (#3544)

* Create schema tool for Boost

Instead of using the default boost schema tool, we can register our own
tool in the service provider. The default boost schema tool only
supports SQL flavored databases and will not run properly for MongoDB
connections.

* Register tool in service provider

This will make it available in Boost after `artistan boost:install`

* Create third-party Boost guidelines

To encourage Boost to prefer our own database tools for MongoDB
connections

Author: paulinevos

composer.json

@@ -56,6 +56,7 @@
     },
     "require-dev": {
         "doctrine/coding-standard": "^12.0",
+        "laravel/boost": "^2.4",
         "laravel/scout": "^10.3",
         "league/flysystem-gridfs": "^3.28",
         "league/flysystem-read-only": "^3.0",

resources/boost/guidelines/core.blade.php

@@ -0,0 +1,13 @@
+# MongoDB Laravel
+
+This application uses the [MongoDB Laravel](https://github.com/mongodb/laravel-mongodb) package, so it likely has one or more `mongodb` driver connections. Boost's database tools assume a SQL database and won't work against those.
+
+## Before using Boost's database tools
+
+Before running any Boost database tool, check whether the target connection uses the `mongodb` driver. If the driver isn't already known, use Boost's `database-connections` tool to find out.
+
+If it does, you MUST use a MongoDB Laravel equivalent tool instead, if available:
+
+| Boost tool        | MongoDB Laravel tool |
+|-------------------|----------------------|
+| `database-schema` | `database-info`      |

src/MongoDBServiceProvider.php

@@ -14,6 +14,7 @@
 use Illuminate\Session\SessionManager;
 use Illuminate\Support\ServiceProvider;
 use InvalidArgumentException;
+use Laravel\Boost\BoostServiceProvider;
 use Laravel\Scout\EngineManager;
 use League\Flysystem\Filesystem;
 use League\Flysystem\GridFS\GridFSAdapter;
@@ -24,11 +25,14 @@
 use MongoDB\Laravel\Queue\MongoConnector;
 use MongoDB\Laravel\Scout\ScoutEngine;
 use MongoDB\Laravel\Session\MongoDbSessionHandler;
+use MongoDB\Laravel\Tools\DatabaseInfo;
 use Override;
 use RuntimeException;
 
+use function array_merge;
 use function assert;
 use function class_exists;
+use function config;
 use function get_debug_type;
 use function is_string;
 use function sprintf;
@@ -103,6 +107,7 @@ public function register()
 
         $this->registerFlysystemAdapter();
         $this->registerScoutEngine();
+        $this->registerBoostTools();
     }
 
     private function registerFlysystemAdapter(): void
@@ -157,6 +162,18 @@ private function registerFlysystemAdapter(): void
         });
     }
 
+    private function registerBoostTools(): void
+    {
+        if (! class_exists(BoostServiceProvider::class)) {
+            return;
+        }
+
+        config()->set('boost.mcp.tools.include', array_merge(
+            config('boost.mcp.tools.include', []),
+            [DatabaseInfo::class],
+        ));
+    }
+
     private function registerScoutEngine(): void
     {
         $this->app->resolving(EngineManager::class, function (EngineManager $engineManager) {

src/Tools/DatabaseInfo.php

@@ -0,0 +1,175 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MongoDB\Laravel\Tools;
+
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\JsonSchema\Types\Type;
+use Illuminate\Support\Facades\Cache;
+use Illuminate\Support\Facades\DB;
+use Illuminate\Support\Facades\Log;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
+use MongoDB\Database;
+use MongoDB\Laravel\Connection;
+use MongoDB\Model\CollectionInfo;
+use Throwable;
+
+use function assert;
+use function rescue;
+use function sprintf;
+use function str_contains;
+use function strtolower;
+
+/**
+ * MongoDB equivalent of Boost's DatabaseSchema tool.
+ */
+#[IsReadOnly]
+class DatabaseInfo extends Tool
+{
+    /**
+     * The tool's description.
+     */
+    protected string $description = 'Read information about a MongoDB database. MongoDB does not use tables and columns, so this returns a summary of the collections. Use "summary" mode first (the default) to get an overview (collection names, types, and estimated document counts), then call again with "summary" set to false and a "filter" to get full details for specific collections (indexes and options). Only use this tool with a connection you already know uses the "mongodb" driver. Params: "connection" (required) - the name of a MongoDB database connection to inspect; "summary" (default true) - collection names, types, and estimated document counts only; "filter" - substring match on collection names.';
+
+    /**
+     * Get the tool's input schema.
+     *
+     * @return array<string, Type>
+     */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            'summary' => $schema->boolean()
+                ->description('Return only collection names, types, and estimated document counts. Use this first to understand the database, then request full details for specific collections using "filter". Defaults to false.'),
+            'connection' => $schema->string()
+                ->description('Name of the MongoDB database connection to inspect. Must be a connection that uses the "mongodb" driver.')
+                ->required(),
+            'filter' => $schema->string()
+                ->description('Filter collections by name (substring match).'),
+        ];
+    }
+
+    /**
+     * Handle the tool request.
+     */
+    public function handle(Request $request): Response
+    {
+        $summary = (bool) $request->get('summary', false);
+        $connectionName = (string) $request->get('connection');
+        $filter = (string) ($request->get('filter') ?? '');
+
+        $connection = DB::connection($connectionName);
+
+        if (! $connection instanceof Connection) {
+            return Response::error(sprintf('The [%s] connection is not a MongoDB connection.', $connectionName));
+        }
+
+        $cacheKey = sprintf(
+            'mongodb:mcp:database-info:%s:%s:%d',
+            $connectionName,
+            $filter,
+            (int) $summary,
+        );
+
+        try {
+            $info = rescue(
+                fn (): array => Cache::remember($cacheKey, 20, fn (): array => $this->getDatabaseInfo($connection, $connectionName, $filter, $summary)),
+                fn (): array => $this->getDatabaseInfo($connection, $connectionName, $filter, $summary),
+                report: false,
+            );
+        } catch (Throwable $exception) {
+            Log::error('Failed to read information for MongoDB connection: ' . $connectionName, [
+                'error' => $exception->getMessage(),
+            ]);
+
+            return Response::error(sprintf('Failed to read information for the [%s] connection.', $connectionName));
+        }
+
+        return Response::json($info);
+    }
+
+    /** @return array{database: string, connection: string, collections: array<string, mixed>} */
+    protected function getDatabaseInfo(Connection $connection, string $connectionName, string $filter, bool $summary): array
+    {
+        $database = $connection->getDatabase();
+
+        $collections = [];
+
+        foreach ($database->listCollections() as $collectionInfo) {
+            assert($collectionInfo instanceof CollectionInfo);
+            $name = $collectionInfo->getName();
+
+            if ($filter !== '' && ! str_contains(strtolower($name), strtolower($filter))) {
+                continue;
+            }
+
+            $collections[$name] = $summary
+                ? $this->getCollectionSummary($database, $collectionInfo)
+                : $this->getCollectionDetails($database, $collectionInfo);
+        }
+
+        return [
+            'database' => $database->getDatabaseName(),
+            'connection' => $connectionName,
+            'collections' => $collections,
+        ];
+    }
+
+    /** @return array{type: string, estimated_document_count: int} */
+    protected function getCollectionSummary(Database $database, CollectionInfo $collectionInfo): array
+    {
+        return [
+            'type' => $collectionInfo->getType(),
+            'estimated_document_count' => $this->estimatedDocumentCount($database, $collectionInfo->getName()),
+        ];
+    }
+
+    /** @return array<string, mixed> */
+    protected function getCollectionDetails(Database $database, CollectionInfo $collectionInfo): array
+    {
+        $name = $collectionInfo->getName();
+
+        try {
+            return [
+                'type' => $collectionInfo->getType(),
+                'estimated_document_count' => $this->estimatedDocumentCount($database, $name),
+                'options' => $collectionInfo->getOptions(),
+                'indexes' => $this->getIndexes($database, $name),
+            ];
+        } catch (Throwable $exception) {
+            Log::error('Failed to get details for MongoDB collection: ' . $name, [
+                'error' => $exception->getMessage(),
+            ]);
+
+            return ['error' => sprintf('Failed to get details for collection [%s].', $name)];
+        }
+    }
+
+    protected function estimatedDocumentCount(Database $database, string $collection): int
+    {
+        try {
+            return $database->getCollection($collection)->estimatedDocumentCount();
+        } catch (Throwable) {
+            return 0;
+        }
+    }
+
+    /** @return array<string, array{keys: array<string, mixed>, unique: bool}> */
+    protected function getIndexes(Database $database, string $collection): array
+    {
+        $indexes = [];
+
+        foreach ($database->getCollection($collection)->listIndexes() as $index) {
+            $indexes[$index->getName()] = [
+                'keys' => $index->getKey(),
+                'unique' => $index->isUnique(),
+            ];
+        }
+
+        return $indexes;
+    }
+}

tests/Tools/DatabaseInfoTest.php

@@ -0,0 +1,133 @@
+<?php
+
+declare(strict_types=1);
+
+namespace MongoDB\Laravel\Tests\Tools;
+
+use ArrayIterator;
+use Illuminate\Database\ConnectionInterface;
+use Illuminate\Support\Facades\DB;
+use Mockery;
+use Mockery\MockInterface;
+use MongoDB\Collection;
+use MongoDB\Database;
+use MongoDB\Laravel\Connection;
+use MongoDB\Laravel\Tests\TestCase;
+use MongoDB\Laravel\Tools\DatabaseInfo;
+use MongoDB\Model\CollectionInfo;
+use MongoDB\Model\IndexInfo;
+use RuntimeException;
+
+class DatabaseInfoTest extends TestCase
+{
+    use InteractsWithTools;
+
+    public function testSummaryListsCollectionsWithCounts(): void
+    {
+        $this->fakeMongoConnection(
+            collections: [new CollectionInfo(['name' => 'books', 'type' => 'collection'])],
+            counts: ['books' => 3],
+        );
+
+        $info = $this->toolJson(new DatabaseInfo(), ['connection' => 'mongodb', 'summary' => true]);
+
+        $this->assertSame('unittest', $info['database']);
+        $this->assertSame('mongodb', $info['connection']);
+
+        $collection = $info['collections']['books'];
+        $this->assertSame('collection', $collection['type']);
+        $this->assertSame(3, $collection['estimated_document_count']);
+        $this->assertArrayNotHasKey('indexes', $collection);
+    }
+
+    public function testFilterExcludesNonMatchingCollections(): void
+    {
+        $this->fakeMongoConnection(
+            collections: [
+                new CollectionInfo(['name' => 'books', 'type' => 'collection']),
+                new CollectionInfo(['name' => 'authors', 'type' => 'collection']),
+            ],
+            counts: ['books' => 1, 'authors' => 1],
+        );
+
+        $info = $this->toolJson(new DatabaseInfo(), ['filter' => 'book']);
+
+        $this->assertArrayHasKey('books', $info['collections']);
+        $this->assertArrayNotHasKey('authors', $info['collections']);
+    }
+
+    public function testFullDetailsIncludeIndexesAndOptions(): void
+    {
+        $this->fakeMongoConnection(
+            collections: [new CollectionInfo(['name' => 'books', 'type' => 'collection', 'options' => ['capped' => true]])],
+            counts: ['books' => 1],
+            indexes: ['books' => [new IndexInfo(['name' => '_id_', 'key' => ['_id' => 1], 'v' => 2])]],
+        );
+
+        $info = $this->toolJson(new DatabaseInfo());
+
+        $collection = $info['collections']['books'];
+        $this->assertSame('collection', $collection['type']);
+        $this->assertSame(1, $collection['estimated_document_count']);
+        $this->assertSame(['capped' => true], $collection['options']);
+        $this->assertSame(['_id' => 1], $collection['indexes']['_id_']['keys']);
+        $this->assertFalse($collection['indexes']['_id_']['unique']);
+    }
+
+    public function testErrorsWhenConnectionIsNotMongoDB(): void
+    {
+        DB::shouldReceive('connection')->andReturn(Mockery::mock(ConnectionInterface::class));
+
+        $response = $this->runTool(new DatabaseInfo(), ['connection' => 'sqlite']);
+
+        $this->assertToolHasError($response);
+        $this->assertToolTextContains($response, 'The [sqlite] connection is not a MongoDB connection.');
+    }
+
+    public function testReturnsErrorWhenListingCollectionsFails(): void
+    {
+        $database = Mockery::mock(Database::class);
+        $database->shouldReceive('listCollections')->andThrow(new RuntimeException('super sekrit server error'));
+
+        $connection = Mockery::mock(Connection::class);
+        $connection->shouldReceive('getDatabase')->andReturn($database);
+
+        DB::shouldReceive('connection')->andReturn($connection);
+
+        $response = $this->runTool(new DatabaseInfo(), ['connection' => 'mongodb']);
+
+        $this->assertToolHasError($response);
+        $this->assertToolTextContains($response, 'Failed to read information for the [mongodb] connection.');
+        // The underlying driver message must not leak to the caller.
+        $this->assertStringNotContainsString('super sekrit', (string) $response->content());
+    }
+
+    /**
+     * Bind a fully mocked MongoDB connection so the tool never touches a real server.
+     *
+     * @param list<CollectionInfo>           $collections
+     * @param array<string, int>             $counts      collection name => estimated document count
+     * @param array<string, list<IndexInfo>> $indexes     collection name => indexes
+     */
+    private function fakeMongoConnection(array $collections, array $counts, array $indexes = []): void
+    {
+        $database = Mockery::mock(Database::class);
+        $database->shouldReceive('getDatabaseName')->andReturn('unittest');
+        $database->shouldReceive('listCollections')->andReturn(new ArrayIterator($collections));
+
+        $database->shouldReceive('getCollection')->andReturnUsing(
+            function (string $name) use ($counts, $indexes): MockInterface {
+                $collection = Mockery::mock(Collection::class);
+                $collection->shouldReceive('estimatedDocumentCount')->andReturn($counts[$name] ?? 0);
+                $collection->shouldReceive('listIndexes')->andReturn(new ArrayIterator($indexes[$name] ?? []));
+
+                return $collection;
+            },
+        );
+
+        $connection = Mockery::mock(Connection::class);
+        $connection->shouldReceive('getDatabase')->andReturn($database);
+
+        DB::shouldReceive('connection')->andReturn($connection);
+    }
+}