feat(mcp) : add stdio auth, dashboard stats PoC tool, and helper trait

- McpStdioAuthSubscriber for console transport auth via env vars - DashboardStatsTool as PoC (validates MCP protocol flow) - McpToolHelper trait for shared pagination/error utilities - Key learning: #[McpTool] must be on CLASS, not method for __invoke Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-16 14:18:09 +01:00
parent 46ea3ca8ad
commit e335f4c24c
4 changed files with 294 additions and 0 deletions
@@ -0,0 +1,58 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mcp\Tool;
+
+use Mcp\Schema\Content\TextContent;
+use RuntimeException;
+use Symfony\Bundle\SecurityBundle\Security;
+
+trait McpToolHelper
+{
+    private function requireRole(Security $security, string $role): void
+    {
+        if (!$security->isGranted($role)) {
+            throw new RuntimeException("Permission denied: {$role} required.");
+        }
+    }
+
+    /**
+     * @return array{TextContent}
+     */
+    private function jsonResponse(array $data): array
+    {
+        return [new TextContent(text: json_encode($data, JSON_THROW_ON_ERROR | JSON_UNESCAPED_UNICODE))];
+    }
+
+    private function mcpError(string $category, string $message): never
+    {
+        throw new RuntimeException("{$category}: {$message}");
+    }
+
+    /**
+     * @return array{page: int, limit: int, offset: int}
+     */
+    private function paginationParams(int $page = 1, int $limit = 30): array
+    {
+        $page   = max(1, $page);
+        $limit  = min(100, max(1, $limit));
+        $offset = ($page - 1) * $limit;
+
+        return ['page' => $page, 'limit' => $limit, 'offset' => $offset];
+    }
+
+    /**
+     * @return array{TextContent}
+     */
+    private function paginatedResponse(array $items, int $total, int $page, int $limit): array
+    {
+        return $this->jsonResponse([
+            'items'     => $items,
+            'total'     => $total,
+            'page'      => $page,
+            'limit'     => $limit,
+            'pageCount' => (int) ceil($total / max(1, $limit)),
+        ]);
+    }
+}