Replace attribute-based tool registration with abstract McpTool base (#62)

* Replace attribute-based tool registration with abstract McpTool base

* Collapse per-domain Detail+Summary schema classes into one

* Hide vendored MCP SDK behind Matomo-owned tool contracts

* Migrate plugin-internal throw sites to McpToolCallException

* Refresh AGENTS.md for McpTool base and current layer layout

Author: mneudert

AGENTS.md

@@ -28,9 +28,9 @@ This document is repo-specific. Prefer it over generic Matomo assumptions when w
 
 ### MCP capability surface
 
-- `McpTools/`: user-facing MCP tools. Start here for new capabilities or changes to tool behavior.
-- `Schemas/`: tool output schemas grouped by domain (`Sites`, `Reports`, `Goals`, `Segments`, `Dimensions`).
-- `Contracts/`: shared typed records and ports. Use these when a boundary needs an explicit typed contract.
+- `McpTools/`: user-facing MCP tools. Each tool is a class extending `Contracts\McpTool` with an `init()` that declares name/description/annotations/schemas and a public `execute(...)` method whose typed parameters define the input shape. Start here for new capabilities or changes to tool behavior.
+- `Schemas/`: tool input/output schemas grouped by domain (`Api`, `Sites`, `Reports`, `Goals`, `Segments`, `Dimensions`). Most domains expose a single combined `*ToolSchemas` class; `Api` and `Reports` still keep per-tool schema classes where the shape diverges between tools.
+- `Contracts/`: Matomo-owned types that bound the plugin's tool surface. Includes the `McpTool` base class, `McpToolAnnotations`, `McpToolIcon`, and `McpToolCallException`, plus shared typed records and ports under `Records/` and `Ports/`. Tool classes interact with these types only — they must not import the vendored MCP SDK directly.
 
 ### Domain and infrastructure layers
 
@@ -75,7 +75,7 @@ Preferred flow:
 
 ### If the task changes domain behavior
 
-Find the domain area under `Services/Sites`, `Services/Reports`, `Services/Goals`, `Services/Segments`, `Services/Dimensions`, or `Services/System`.
+Find the domain area under `Services/Api`, `Services/Sites`, `Services/Reports`, `Services/Goals`, `Services/Segments`, `Services/Dimensions`, or `Services/System`.
 
 Before editing:
 
@@ -87,10 +87,13 @@ Before editing:
 
 ### Adding new MCP capabilities
 
-- Add user-facing capability through a tool class in `McpTools/`.
+- Add user-facing capability through a tool class in `McpTools/` that extends `Contracts\McpTool`. Implement `init()` to set name, description, annotations, input schema, and (when applicable) title, output schema, icons, and meta. Declare a public `execute(...)` method whose typed parameters define the JSON-RPC input shape.
+- Register the new tool class in `McpServerFactory::BUILTIN_TOOL_CLASSES` so the factory resolves it from the container.
+- Abort tool execution via `$this->fail($message)` from `execute()`; downstream services and helpers in the call chain may throw `McpToolCallException` directly when surfacing client-facing failures.
+- Interact only with Matomo-owned tool types (`McpTool`, `McpToolAnnotations`, `McpToolIcon`, `McpToolCallException`) inside `McpTools/`. Do not import or expose vendored MCP SDK types from tool classes — translation to the SDK happens centrally in `McpServerFactory`.
 - Keep Matomo/core access in focused services or gateway classes under `Services/`.
-- Define or update output schemas in `Schemas/`.
-- Use `Contracts/` only when a shared typed record or service boundary improves clarity.
+- Define or update tool schemas in `Schemas/`, matching the domain layout.
+- Use `Contracts/Records` and `Contracts/Ports` only when a shared typed record or service boundary improves clarity.
 
 ### Keeping boundaries clean
 

Contracts/McpTool.php

@@ -0,0 +1,149 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\McpServer\Contracts;
+
+/**
+ * Base class for MCP tools registered by the McpServer plugin.
+ *
+ * Each subclass represents exactly one MCP tool and MUST define a public
+ * execute(...) method. Its typed parameters declare the tool's input shape
+ * and receive the bound JSON-RPC arguments at call time. The method name is
+ * intentionally fixed (no handlerMethod property) because there is no
+ * remaining value in per-tool configurability.
+ *
+ * Subclasses interact only with Matomo-owned types (McpToolAnnotations,
+ * McpToolIcon, the fail() helper).
+ */
+abstract class McpTool
+{
+    protected string $name;
+    protected string $description;
+    protected McpToolAnnotations $annotations;
+    protected ?string $title = null;
+
+    /** @var array<string, mixed> */
+    protected array $inputSchema;
+
+    /** @var array<string, mixed>|null */
+    protected ?array $outputSchema = null;
+
+    /** @var list<McpToolIcon>|null */
+    protected ?array $icons = null;
+
+    /** @var array<string, mixed>|null */
+    protected ?array $meta = null;
+
+    public function __construct()
+    {
+        // Placeholder defaults so static analysers can prove the typed properties are
+        // initialised. Subclasses MUST overwrite the required ones inside init().
+        $this->name = '';
+        $this->description = '';
+        $this->annotations = new McpToolAnnotations();
+        $this->inputSchema = [];
+
+        $this->init();
+
+        if ($this->name === '') {
+            throw new \LogicException(sprintf(
+                '%s::init() must set $this->name to a non-empty tool name.',
+                static::class,
+            ));
+        }
+        if ($this->inputSchema === []) {
+            throw new \LogicException(sprintf(
+                '%s::init() must set $this->inputSchema.',
+                static::class,
+            ));
+        }
+
+        // PHP cannot express "every subclass declares execute(...)" as an abstract
+        // method because the SDK binds JSON-RPC arguments to typed parameters whose
+        // signatures vary per tool — declaring abstract execute() with any concrete
+        // signature would violate LSP for those overrides. A runtime check at boot
+        // is the practical safety net; it fires the first time any tool is built.
+        if (!method_exists($this, 'execute')) {
+            throw new \LogicException(sprintf(
+                '%s must define a public execute() method.',
+                static::class,
+            ));
+        }
+    }
+
+    abstract protected function init(): void;
+
+    public function shouldRegister(): bool
+    {
+        return true;
+    }
+
+    public function getName(): string
+    {
+        return $this->name;
+    }
+
+    public function getDescription(): string
+    {
+        return $this->description;
+    }
+
+    public function getAnnotations(): McpToolAnnotations
+    {
+        return $this->annotations;
+    }
+
+    public function getTitle(): ?string
+    {
+        return $this->title;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function getInputSchema(): array
+    {
+        return $this->inputSchema;
+    }
+
+    /**
+     * @return array<string, mixed>|null
+     */
+    public function getOutputSchema(): ?array
+    {
+        return $this->outputSchema;
+    }
+
+    /**
+     * @return list<McpToolIcon>|null
+     */
+    public function getIcons(): ?array
+    {
+        return $this->icons;
+    }
+
+    /**
+     * @return array<string, mixed>|null
+     */
+    public function getMeta(): ?array
+    {
+        return $this->meta;
+    }
+
+    /**
+     * Abort execute() with a structured tool-call error returned to the
+     * MCP client.
+     */
+    protected function fail(string $message): never
+    {
+        throw new McpToolCallException($message);
+    }
+}

Contracts/McpToolAnnotations.php

@@ -0,0 +1,29 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\McpServer\Contracts;
+
+/**
+ * Behavioural hints attached to an McpTool, surfaced in tool listings so an
+ * MCP client can reason about whether a call is read-only, destructive,
+ * idempotent, or may reach beyond its declared inputs. Every field is
+ * optional — null means "not declared".
+ */
+final class McpToolAnnotations
+{
+    public function __construct(
+        public readonly ?bool $readOnlyHint = null,
+        public readonly ?bool $destructiveHint = null,
+        public readonly ?bool $idempotentHint = null,
+        public readonly ?bool $openWorldHint = null,
+    ) {
+    }
+}

Contracts/McpToolCallException.php

@@ -0,0 +1,22 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\McpServer\Contracts;
+
+/**
+ * Thrown to abort an MCP tool call with a structured error returned to the
+ * MCP client. Typically raised from an McpTool subclass via $this->fail(),
+ * but also thrown directly by supporting services and helpers (pagination,
+ * gateways, normalisers, etc.) invoked during the tool's call chain.
+ */
+final class McpToolCallException extends \RuntimeException
+{
+}

Contracts/McpToolIcon.php

@@ -0,0 +1,31 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\McpServer\Contracts;
+
+/**
+ * Optional icon advertised alongside an McpTool in tool listings. The src is
+ * the only required field (a URL or data URI); mimeType narrows how the
+ * client should decode it and sizes lists the available display dimensions
+ * (e.g. "32x32").
+ */
+final class McpToolIcon
+{
+    /**
+     * @param list<string>|null $sizes
+     */
+    public function __construct(
+        public readonly string $src,
+        public readonly ?string $mimeType = null,
+        public readonly ?array $sizes = null,
+    ) {
+    }
+}