Merge branch 'main' into feat/essence

Author: nunomaduro

.gitattributes.php

@@ -0,0 +1,18 @@
+* text=auto
+
+*.blade.php diff=html
+*.css diff=css
+*.html diff=html
+*.md diff=markdown
+*.php diff=php
+
+/.github export-ignore
+/art export-ignore
+/tests export-ignore
+.editorconfig export-ignore
+.gitattributes export-ignore
+.gitignore export-ignore
+CHANGELOG.md export-ignore
+phpstan.neon.dist export-ignore
+phpunit.xml.dist export-ignore
+UPGRADE.md export-ignore

README.md

@@ -67,7 +67,7 @@ Next, register your server in `routes/ai.php`:
 
 ```php
 use App\Mcp\Servers\DemoServer;
-use Laravel\Mcp\Server\Facades\Mcp;
+use Laravel\Mcp\Facades\Mcp;
 
 Mcp::local('demo', DemoServer::class);
 ```
@@ -247,22 +247,20 @@ To register a web-based MCP server that can be accessed via HTTP POST requests,
 
 ```php
 use App\Mcp\Servers\ExampleServer;
-use Laravel\Mcp\Server\Facades\Mcp;
+use Laravel\Mcp\Facades\Mcp;
 
-Mcp::web('demo', ExampleServer::class);
+Mcp::web('/mcp/demo', ExampleServer::class);
 ```
 
 This will make `ExampleServer` available at the `/mcp/demo` endpoint.
 
-> **Security Note:** Exposing a local development server via `Mcp::web()` can make your application vulnerable to DNS rebinding attacks. If you must expose a local MCP server over HTTP, it is critical to validate the `Host` and `Origin` headers on incoming requests to ensure they are coming from a trusted source.
-
 ### Local Servers
 
 To register a local MCP server that can be run as an Artisan command:
 
 ```php
 use App\Mcp\Servers\ExampleServer;
-use Laravel\Mcp\Server\Facades\Mcp;
+use Laravel\Mcp\Facades\Mcp;
 
 Mcp::local('demo', ExampleServer::class);
 ```
@@ -275,12 +273,12 @@ php artisan mcp:start demo
 
 ## Authentication
 
-Web-based MCP servers can be protected using [Laravel Passport](laravel.com/docs/passport), turning your MCP server into an OAuth2 protected resource.
+Web-based MCP servers can be protected using [Laravel Passport](https://laravel.com/docs/passport), turning your MCP server into an OAuth2 protected resource.
 
 If you already have Passport set up for your app, all you need to do is add the `Mcp::oauthRoutes()` helper to your `routes/web.php` file. This registers the required OAuth2 discovery and client registration endpoints. The method accepts an optional route prefix, which defaults to `oauth`.
 
 ```php
-use Laravel\Mcp\Server\Facades\Mcp;
+use Laravel\Mcp\Facades\Mcp;
 
 Mcp::oauthRoutes();
 ```
@@ -289,9 +287,9 @@ Then, apply the `auth:api` middleware to your server registration in `routes/ai.
 
 ```php
 use App\Mcp\Servers\ExampleServer;
-use Laravel\Mcp\Server\Facades\Mcp;
+use Laravel\Mcp\Facades\Mcp;
 
-Mcp::web('demo', ExampleServer::class)
+Mcp::web('/mcp/demo', ExampleServer::class)
     ->middleware('auth:api');
 ```
 

routes/ai.php

@@ -1,6 +1,6 @@
 <?php
 
-use Laravel\Mcp\Server\Facades\Mcp;
+use Laravel\Mcp\Facades\Mcp;
 
-// Mcp::web('demo', \App\Mcp\Servers\PublicServer::class); // Available at /mcp/demo
-// Mcp::local('demo', \App\Mcp\Servers\LocalServer::class); // Start with ./artisan mcp:start demo
+// Mcp::web('/mcp/demo', \App\Mcp\Servers\PublicServer::class);
+// Mcp::local('demo', \App\Mcp\Servers\LocalServer::class);

src/Server/Facades/Mcp.php renamed to src/Facades/Mcp.php

@@ -2,7 +2,7 @@
 
 declare(strict_types=1);
 
-namespace Laravel\Mcp\Server\Facades;
+namespace Laravel\Mcp\Facades;
 
 use Illuminate\Support\Facades\Facade;
 

src/Server.php

@@ -50,18 +50,16 @@ abstract class Server
         ],
     ];
 
-    /**
-     * The name of the MCP server.
-     */
-    public string $serverName = 'Laravel MCP Server';
+    public string $name = 'Laravel MCP Server';
 
-    /**
-     * The version of the MCP server.
-     */
-    public string $serverVersion = '0.0.1';
+    public string $version = '0.0.1';
 
     /**
-     * The instructions for the AI.
+     * Instructions describing how to use the server and its features.
+     *
+     * This can be used by clients to improve the LLM’s understanding of available tools, resources, etc.
+     * It can be thought of like a "hint" to the model.
+     * For example, this information MAY be added to the system prompt.
      */
     public string $instructions = 'This MCP server lets AI agents interact with our Laravel application.';
 
@@ -149,8 +147,8 @@ public function handle(string $rawMessage)
         $context = new ServerContext(
             supportedProtocolVersions: $this->supportedProtocolVersion,
             serverCapabilities: $this->capabilities,
-            serverName: $this->serverName,
-            serverVersion: $this->serverVersion,
+            serverName: $this->name,
+            serverVersion: $this->version,
             instructions: $this->instructions,
             maxPaginationLength: $this->maxPaginationLength,
             defaultPaginationLength: $this->defaultPaginationLength,

src/Server/McpServiceProvider.php

@@ -14,12 +14,7 @@
 
 class McpServiceProvider extends ServiceProvider
 {
-    /**
-     * Register any application services.
-     *
-     * @return void
-     */
-    public function register()
+    public function register(): void
     {
         $this->app->singleton('mcp', fn () => new Registrar);
 
@@ -34,12 +29,7 @@ public function register()
         }
     }
 
-    /**
-     * Bootstrap any application services.
-     *
-     * @return void
-     */
-    public function boot()
+    public function boot(): void
     {
         if ($this->app->runningInConsole()) {
             $this->offerPublishing();
@@ -48,19 +38,13 @@ public function boot()
         $this->loadAiRoutes();
     }
 
-    /**
-     * Register the migrations and publishing for the package.
-     */
     protected function offerPublishing(): void
     {
         $this->publishes([
             __DIR__.'/../../routes/ai.php' => base_path('routes/ai.php'),
         ], 'ai-routes');
     }
 
-    /**
-     * Load the AI routes file if it exists.
-     */
     protected function loadAiRoutes(): void
     {
         $path = base_path('routes/ai.php');
@@ -73,6 +57,6 @@ protected function loadAiRoutes(): void
             return;
         }
 
-        Route::prefix('mcp')->group($path);
+        Route::group([], $path);
     }
 }

src/Server/Methods/Initialize.php

@@ -31,16 +31,21 @@ public function handle(JsonRpcRequest $request, ServerContext $context): JsonRpc
             );
         }
 
-        $protocol = $requestedVersion ?? $context->supportedProtocolVersions[0];
-
-        return JsonRpcResponse::create($request->id, [
-            'protocolVersion' => $protocol,
+        $protocolVersion = $requestedVersion ?? $context->supportedProtocolVersions[0];
+        $initResult = [
+            'protocolVersion' => $protocolVersion,
             'capabilities' => $context->serverCapabilities,
             'serverInfo' => [
                 'name' => $context->serverName,
                 'version' => $context->serverVersion,
             ],
             'instructions' => $context->instructions,
-        ]);
+        ];
+
+        if (in_array($protocolVersion, ['2024-11-05', '2025-03-26'], true)) {
+            unset($initResult['instructions']);
+        }
+
+        return JsonRpcResponse::create($request->id, $initResult);
     }
 }

src/Server/Prompt.php

@@ -18,13 +18,13 @@ abstract public function handle(array $arguments): PromptResult;
 
     public function arguments(): Arguments
     {
-        return (new Arguments)->add(
+        return new Arguments([
             new Argument(
                 name: 'best_cheese',
                 description: 'The best cheese',
                 required: false,
             ),
-        );
+        ]);
     }
 
     public function description(): string

src/Server/Registrar.php

@@ -20,16 +20,16 @@ class Registrar
     protected array $registeredWebServers = [];
 
     /**
-     * Register an web-based MCP server running over HTTP.
+     * Register a web-based MCP server running over HTTP.
      */
-    public function web(string $handle, string $serverClass): Route
+    public function web(string $route, string $serverClass): Route
     {
-        $this->registeredWebServers[$handle] = $serverClass;
+        $this->registeredWebServers[$route] = $serverClass;
 
-        return Router::post($handle, fn () => $this->bootServer(
+        return Router::post($route, fn () => $this->bootServer(
             $serverClass,
             fn () => new HttpTransport(request())
-        ))->name('mcp-server.'.$handle);
+        ))->name('mcp-server.'.$route);
     }
 
     /**
@@ -96,9 +96,6 @@ public function oauthRoutes($oauthPrefix = 'oauth')
         });
     }
 
-    /**
-     * Boot the MCP server.
-     */
     private function bootServer(string $serverClass, callable $transportFactory)
     {
         $transport = $transportFactory();

src/Server/Resource.php

@@ -13,7 +13,7 @@ abstract class Resource implements Arrayable
 {
     protected string $description = '';
 
-    protected $content;
+    protected string|Content $content;
 
     abstract public function read(): string|Content;