Merge pull request #128 from devoption/codex/feat-32-mcp-foundation

feat: install and configure Laravel MCP

Author: ibourgeois

README.md

@@ -93,6 +93,17 @@ The Laravel AI SDK is installed and its conversation storage migrations are part
 
 The current AI foundation test uses agent fakes, so the repo test suite does not require live provider credentials just to verify the integration.
 
+### Laravel MCP Foundation
+
+Katra now includes Laravel MCP as an explicit application dependency.
+
+- The application publishes `config/mcp.php` and `routes/ai.php` so MCP setup lives in the same Laravel configuration surface as the rest of the app.
+- Katra registers a local MCP handle named `katra` that points at `App\Mcp\Servers\KatraServer`.
+- The current example tool, `App\Mcp\Tools\DescribeWorkspace`, is intentionally small and read-only. It exists as a smoke-tested interoperability example, not as a parallel product surface.
+- MCP matters for interoperability, tool exposure, and external integrations, but it should not become the center of Katra's architecture.
+- Start the local MCP server with `php artisan mcp:start katra`.
+- The current smoke coverage lives in `tests/Feature/McpSmokeTest.php`.
+
 ### Surreal-Backed Migrations
 
 Katra now includes a first Laravel-compatible Surreal schema driver for migration work.

app/Mcp/Servers/KatraServer.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace App\Mcp\Servers;
+
+use App\Mcp\Tools\DescribeWorkspace;
+use Laravel\Mcp\Server;
+use Laravel\Mcp\Server\Attributes\Instructions;
+use Laravel\Mcp\Server\Attributes\Name;
+use Laravel\Mcp\Server\Attributes\Version;
+
+#[Name('Katra MCP Server')]
+#[Version('0.0.1')]
+#[Instructions('Use this server for lightweight Katra interoperability tasks. It is intended to support integrations and tooling, not to become the center of Katra\'s product architecture.')]
+class KatraServer extends Server
+{
+    protected array $tools = [
+        DescribeWorkspace::class,
+    ];
+
+    protected array $resources = [
+        //
+    ];
+
+    protected array $prompts = [
+        //
+    ];
+}

app/Mcp/Tools/DescribeWorkspace.php

@@ -0,0 +1,48 @@
+<?php
+
+namespace App\Mcp\Tools;
+
+use Illuminate\Contracts\JsonSchema\JsonSchema;
+use Illuminate\Support\Arr;
+use Laravel\Mcp\Request;
+use Laravel\Mcp\Response;
+use Laravel\Mcp\Server\Attributes\Description;
+use Laravel\Mcp\Server\Tool;
+use Laravel\Mcp\Server\Tools\Annotations\IsIdempotent;
+use Laravel\Mcp\Server\Tools\Annotations\IsReadOnly;
+
+#[Description('Summarize the current Katra workspace configuration and MCP role.')]
+#[IsReadOnly]
+#[IsIdempotent]
+class DescribeWorkspace extends Tool
+{
+    public function handle(Request $request): Response
+    {
+        $workspaceName = (string) config('app.name');
+        $workspaceUrl = (string) config('app.url');
+        $runtimeTargets = Arr::join([
+            'desktop-local',
+            'server',
+            'container',
+            'kubernetes-oriented',
+        ], ', ', ', and ');
+
+        return Response::text(
+            "{$workspaceName} is available at {$workspaceUrl}. ".
+            'Laravel MCP is configured here as an interoperability layer for Katra v2, not the center of the product architecture. '.
+            "The current planned runtime targets are {$runtimeTargets}."
+        );
+    }
+
+    /**
+     * Get the tool's input schema.
+     *
+     * @return array<string, JsonSchema>
+     */
+    public function schema(JsonSchema $schema): array
+    {
+        return [
+            //
+        ];
+    }
+}

composer.json

@@ -13,6 +13,7 @@
         "laravel/ai": "^0.3.2",
         "laravel/fortify": "^1.36",
         "laravel/framework": "^13.0",
+        "laravel/mcp": "^0.6.3",
         "laravel/pennant": "^1.0",
         "laravel/tinker": "^3.0",
         "nativephp/desktop": "dev-l13-compatibility",

composer.lock

@@ -0,0 +1,26 @@
+<?php
+
+return [
+
+    /*
+    |--------------------------------------------------------------------------
+    | Redirect Domains
+    |--------------------------------------------------------------------------
+    |
+    | These domains are the domains that OAuth clients are permitted to use
+    | for redirect URIs. Each domain should be specified with its scheme
+    | and host. Domains not in this list will raise validation errors.
+    |
+    | An "*" may be used to allow all domains.
+    |
+    */
+
+    'redirect_domains' => [
+        // 'https://example.com',
+        'http://localhost',
+        'http://127.0.0.1',
+        'https://localhost',
+        'https://127.0.0.1',
+    ],
+
+];

config/mcp.php

@@ -0,0 +1,6 @@
+<?php
+
+use App\Mcp\Servers\KatraServer;
+use Laravel\Mcp\Facades\Mcp;
+
+Mcp::local('katra', KatraServer::class);

routes/ai.php

@@ -0,0 +1,18 @@
+<?php
+
+use App\Mcp\Servers\KatraServer;
+use App\Mcp\Tools\DescribeWorkspace;
+
+test('the katra mcp server exposes a lightweight workspace description tool', function () {
+    KatraServer::tool(DescribeWorkspace::class)
+        ->assertOk()
+        ->assertName('describe-workspace')
+        ->assertDescription('Summarize the current Katra workspace configuration and MCP role.')
+        ->assertSee([
+            config('app.name'),
+            config('app.url'),
+            'interoperability layer',
+            'not the center',
+            'desktop-local',
+        ]);
+});