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>

src/Mcp/Tool/DashboardStatsTool.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\Mcp\Tool;
+
+use App\Repository\ComposantRepository;
+use App\Repository\MachineRepository;
+use App\Repository\PieceRepository;
+use App\Repository\ProductRepository;
+use App\Repository\SiteRepository;
+use Doctrine\ORM\EntityManagerInterface;
+use Mcp\Capability\Attribute\McpTool;
+use Mcp\Schema\Content\TextContent;
+
+#[McpTool(
+    name: 'get_dashboard_stats',
+    description: 'Get global inventory statistics: count of machines, pieces, composants, products, sites, and unresolved comments. Takes no parameters.',
+)]
+class DashboardStatsTool
+{
+    public function __construct(
+        private readonly MachineRepository $machines,
+        private readonly PieceRepository $pieces,
+        private readonly ComposantRepository $composants,
+        private readonly ProductRepository $products,
+        private readonly SiteRepository $sites,
+        private readonly EntityManagerInterface $em,
+    ) {}
+
+    public function __invoke(): array
+    {
+        $unresolvedComments = (int) $this->em->createQuery(
+            "SELECT COUNT(c.id) FROM App\\Entity\\Comment c WHERE c.status = 'open'"
+        )->getSingleScalarResult();
+
+        return [
+            new TextContent(
+                text: json_encode([
+                    'machines'           => $this->machines->count([]),
+                    'pieces'             => $this->pieces->count([]),
+                    'composants'         => $this->composants->count([]),
+                    'products'           => $this->products->count([]),
+                    'sites'              => $this->sites->count([]),
+                    'unresolvedComments' => $unresolvedComments,
+                ], JSON_THROW_ON_ERROR)
+            ),
+        ];
+    }
+}

src/Mcp/Tool/McpToolHelper.php

@@ -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)),
+        ]);
+    }
+}