feat(mcp): adopt agent's newer copies of the eleven shared Core\Mcp classes

composer.json

@@ -46,6 +46,7 @@
         "lthn/php-mcp": "self.version"
     },
     "require-dev": {
+        "dappcore/php-content": "*",
         "dappcore/php-tenant": "^0.1",
         "dappcore/php-uptelligence": "*",
         "laravel/pint": "^1.18",

php/src/Mcp/Controllers/McpApiController.php

@@ -11,7 +11,6 @@
 use Core\Mcp\Resources\Contracts\AgentResourceProvider;
 use Core\Mcp\Services\McpQuotaService;
 use Core\Mcp\Services\McpWebhookDispatcher;
-use Core\Mod\Agentic\Services\AgentToolRegistry;
 use Core\Mod\Content\Models\ContentItem;
 use Core\Tenant\Models\Workspace;
 use Illuminate\Http\JsonResponse;
@@ -430,7 +429,12 @@ protected function agentResourceProvider(): ?object
      */
     protected function executeTool(string $tool, array $arguments, ?ApiKey $apiKey): mixed
     {
-        $registryClass = AgentToolRegistry::class;
+        // A string literal, not ::class with an import: this is a late-bound,
+        // optional lookup into the consumer, and pint's
+        // fully_qualified_strict_types fixer rewrites an inline FQCN into a
+        // top-of-file `use` — which is how a package whose whole point is not
+        // to import its consumer ended up importing it.
+        $registryClass = 'Core\\Mod\\Agentic\\Services\\AgentToolRegistry';
 
         if (! app()->bound($registryClass)) {
             throw new \RuntimeException('AgentToolRegistry not available — is the agentic module installed?');

php/src/Mcp/Exceptions/CircuitOpenException.php

@@ -1,27 +1,44 @@
 <?php
 
+// SPDX-License-Identifier: EUPL-1.2
+
 declare(strict_types=1);
 
 namespace Core\Mcp\Exceptions;
 
 use RuntimeException;
 
 /**
- * Exception thrown when the circuit breaker is open and no fallback is provided.
+ * Thrown by CircuitBreaker when a downstream service has tripped its
+ * failure threshold and the circuit is open. The exception carries the
+ * service identifier so callers can produce a user-readable retry hint
+ * without parsing the message.
+ *
+ * Example:
  *
- * This indicates the target service is temporarily unavailable due to repeated failures.
+ *   try {
+ *       $breaker->call('openbrain', fn () => $client->dispatch(...));
+ *   } catch (CircuitOpenException $e) {
+ *       return ['error' => "service '{$e->service}' temporarily unavailable"];
+ *   }
  */
-class CircuitOpenException extends RuntimeException
+final class CircuitOpenException extends RuntimeException
 {
+    /**
+     * Construct an open-circuit exception. When $message is empty, a
+     * default human-readable message is generated from $service.
+     *
+     * Example:
+     *
+     *   throw new CircuitOpenException('openbrain');
+     */
     public function __construct(
         public readonly string $service,
         string $message = '',
     ) {
-        $message = $message ?: sprintf(
+        parent::__construct($message !== '' ? $message : sprintf(
             "Service '%s' is temporarily unavailable. Please try again later.",
-            $service
-        );
-
-        parent::__construct($message);
+            $service,
+        ));
     }
 }

php/src/Mcp/Resources/AppConfig.php

@@ -1,24 +1,26 @@
 <?php
 
+// SPDX-License-Identifier: EUPL-1.2
+
+declare(strict_types=1);
+
 namespace Core\Mcp\Resources;
 
 use Laravel\Mcp\Request;
 use Laravel\Mcp\Response;
 use Laravel\Mcp\Server\Resource;
 
-class AppConfig extends Resource
+final class AppConfig extends Resource
 {
     protected string $description = 'Application configuration for Host Hub';
 
     public function handle(Request $request): Response
     {
-        $config = [
+        return Response::text((string) json_encode([
             'name' => config('app.name'),
             'env' => config('app.env'),
             'debug' => config('app.debug'),
             'url' => config('app.url'),
-        ];
-
-        return Response::text(json_encode($config, JSON_PRETTY_PRINT));
+        ], JSON_PRETTY_PRINT | JSON_UNESCAPED_SLASHES));
     }
 }