Add in-process tool catalogue and call API for other plugins (#64)

Author: mneudert

API.php

@@ -19,8 +19,11 @@
 use Piwik\API\Request as ApiRequest;
 use Piwik\Http\BadRequestException;
 use Piwik\NoAccessException;
-use Piwik\Piwik;
-use Piwik\Plugins\McpServer\Support\Access\McpAccessLevel;
+use Piwik\Plugins\McpServer\Support\Access\McpAccessGate;
+use Piwik\Plugins\McpServer\Support\Access\McpUnavailableException;
+use Piwik\Plugins\McpServer\Support\Api\InternalApiAccessGuard;
+use Piwik\Plugins\McpServer\Support\Api\InternalToolCaller;
+use Piwik\Plugins\McpServer\Support\Api\InternalToolCatalog;
 use Piwik\Plugins\McpServer\Support\Api\JsonRpcErrorResponseFactory;
 use Piwik\Plugins\McpServer\Support\Api\JsonRpcRequestIdExtractor;
 use Piwik\Plugins\McpServer\Support\Api\McpEndpointGuard;
@@ -34,7 +37,10 @@ public function __construct(
         private McpEndpointGuard $endpointGuard,
         private JsonRpcErrorResponseFactory $jsonRpcErrorResponseFactory,
         private JsonRpcRequestIdExtractor $jsonRpcRequestIdExtractor,
-        private SystemSettings $systemSettings,
+        private McpAccessGate $accessGate,
+        private InternalApiAccessGuard $internalAccessGuard,
+        private InternalToolCatalog $internalToolCatalog,
+        private InternalToolCaller $internalToolCaller,
     ) {
     }
 
@@ -79,8 +85,9 @@ public function mcp(): ResponseInterface
         }
 
         try {
-            $this->checkUserIsNotAnonymous();
-            $this->checkUserHasSomeViewAccess();
+            $this->accessGate->assertHttp();
+        } catch (McpUnavailableException | BadRequestException $e) {
+            return $this->createForbiddenResponse($requestMetadata['topLevelRequestId'], $e->getMessage());
         } catch (\Throwable $e) {
             if ($this->isUnauthorizedLike($e)) {
                 return $this->createUnauthorizedResponse($requestId);
@@ -94,14 +101,6 @@ public function mcp(): ResponseInterface
             );
         }
 
-        if (!$this->isMcpEnabled()) {
-            return $this->createDisabledResponse($requestMetadata['topLevelRequestId']);
-        }
-
-        if (!$this->isCurrentUserPrivilegeLevelAllowed()) {
-            return $this->createPrivilegeTooHighResponse($requestMetadata['topLevelRequestId']);
-        }
-
         try {
             $server = $this->factory->createServer();
             $transport = new StreamableHttpTransport($request);
@@ -117,19 +116,68 @@ public function mcp(): ResponseInterface
         }
     }
 
-    protected function createRequestFromGlobals(): ServerRequestInterface
+    /**
+     * Returns the registered MCP tool catalogue for in-process consumers.
+     *
+     * Throws {@see \Piwik\NoAccessException} when the caller is anonymous or
+     * lacks view access, and {@see McpUnavailableException} when MCP is
+     * disabled site-wide; consumers can branch on the latter to surface a
+     * "feature off" message instead of a generic access error.
+     *
+     * @internal
+     * @return list<array{
+     *     name: string,
+     *     title: string|null,
+     *     description: string,
+     *     inputSchema: array<string, mixed>,
+     *     outputSchema: array<string, mixed>|null,
+     *     readOnly: bool|null,
+     *     destructive: bool|null,
+     *     idempotent: bool|null,
+     *     openWorld: bool|null
+     * }> Registered MCP tools with schemas and behaviour hints.
+     */
+    public function getInternalToolCatalog(): array
     {
-        return (new Psr17Factory())->createServerRequestFromGlobals();
+        $this->internalAccessGuard->assertInternalContext();
+        $this->accessGate->assertBase();
+
+        return $this->internalToolCatalog->build($this->factory->createInternalAccess());
     }
 
-    protected function checkUserHasSomeViewAccess(): void
+    /**
+     * Calls a registered MCP tool for in-process consumers.
+     *
+     * Tool and protocol failures are returned as an `isError` payload; context
+     * and access failures throw as ordinary Matomo API exceptions
+     * ({@see \Piwik\NoAccessException} for anonymous / no-view callers,
+     * {@see McpUnavailableException} when MCP is disabled site-wide).
+     *
+     * @internal
+     * @unsanitized
+     * @param string $name Registered MCP tool name.
+     * @param array<string, mixed> $arguments Arguments validated against the tool input schema.
+     * @return array{
+     *     content: list<array<string, mixed>>,
+     *     structuredContent: array<string, mixed>|null,
+     *     isError: bool
+     * } Serialized MCP tool result payload.
+     */
+    public function callInternalTool(string $name, array $arguments = []): array
     {
-        Piwik::checkUserHasSomeViewAccess();
+        $this->internalAccessGuard->assertInternalContext();
+        $this->accessGate->assertBase();
+
+        return $this->internalToolCaller->call(
+            $this->factory->createInternalAccess(),
+            $name,
+            $arguments,
+        );
     }
 
-    protected function checkUserIsNotAnonymous(): void
+    protected function createRequestFromGlobals(): ServerRequestInterface
     {
-        Piwik::checkUserIsNotAnonymous();
+        return (new Psr17Factory())->createServerRequestFromGlobals();
     }
 
     protected function createUnauthorizedResponse(string|int $requestId = ''): ResponseInterface
@@ -143,19 +191,6 @@ protected function createUnauthorizedResponse(string|int $requestId = ''): Respo
         );
     }
 
-    protected function isMcpEnabled(): bool
-    {
-        return $this->systemSettings->isMcpEnabled();
-    }
-
-    protected function isCurrentUserPrivilegeLevelAllowed(): bool
-    {
-        return !McpAccessLevel::exceedsMaximumAllowed(
-            McpAccessLevel::resolveCurrentUserLevel(),
-            $this->systemSettings->getMaximumAllowedMcpAccessLevel(),
-        );
-    }
-
     protected function isCurrentApiRequestRoot(): bool
     {
         return ApiRequest::isCurrentApiRequestTheRootApiRequest();
@@ -181,21 +216,13 @@ private function isUnauthorizedLike(\Throwable $e): bool
         return false;
     }
 
-    protected function createDisabledResponse(string|int|null $topLevelRequestId): ResponseInterface
-    {
-        if ($topLevelRequestId === null) {
-            return (new Psr17Factory())->createResponse(403);
-        }
-
-        return $this->jsonRpcErrorResponseFactory->create(
-            403,
-            JsonRpcError::INVALID_REQUEST,
-            McpEndpointSpec::DISABLED_ERROR,
-            $topLevelRequestId,
-        );
-    }
-
-    protected function createPrivilegeTooHighResponse(string|int|null $topLevelRequestId): ResponseInterface
+    /**
+     * Shape a 403 response for the HTTP mcp() path when {@see McpAccessGate::assertHttp()}
+     * rejected the request via {@see McpUnavailableException} (MCP disabled) or
+     * {@see BadRequestException} (privilege ceiling exceeded). The exception's
+     * message is the canonical text.
+     */
+    protected function createForbiddenResponse(string|int|null $topLevelRequestId, string $message): ResponseInterface
     {
         if ($topLevelRequestId === null) {
             return (new Psr17Factory())->createResponse(403);
@@ -204,7 +231,7 @@ protected function createPrivilegeTooHighResponse(string|int|null $topLevelReque
         return $this->jsonRpcErrorResponseFactory->create(
             403,
             JsonRpcError::INVALID_REQUEST,
-            McpAccessLevel::createTooHighPrivilegeMessage($this->systemSettings->getMaximumAllowedMcpAccessLevel()),
+            $message,
             $topLevelRequestId,
         );
     }

McpServerFactory.php

@@ -18,6 +18,7 @@
 use Matomo\Dependencies\McpServer\Mcp\Schema\ToolAnnotations;
 use Matomo\Dependencies\McpServer\Mcp\Server;
 use Matomo\Dependencies\McpServer\Mcp\Server\Builder;
+use Matomo\Dependencies\McpServer\Mcp\Server\Handler\Request\RequestHandlerInterface;
 use Matomo\Dependencies\McpServer\Mcp\Server\Session\SessionStoreInterface;
 use Piwik\Config;
 use Piwik\Log\LoggerInterface;
@@ -46,6 +47,7 @@
 use Piwik\Plugins\McpServer\McpTools\SiteSearch;
 use Piwik\Plugins\McpServer\Server\Handler\Request\CompatibleCallToolHandler;
 use Piwik\Plugins\McpServer\Server\Handler\Request\ObservedCallToolHandler;
+use Piwik\Plugins\McpServer\Server\InternalAccess;
 use Piwik\Plugins\McpServer\Support\Logging\ToolCallParameterFormatter;
 use Psr\Container\ContainerInterface;
 use Psr\Log\NullLogger;
@@ -84,6 +86,9 @@ final class McpServerFactory
         SiteSearch::class,
     ];
 
+    /** @var array{server: Server, registry: Registry, callToolHandler: RequestHandlerInterface<mixed>}|null */
+    private ?array $runtimeCache = null;
+
     public function __construct(
         private LoggerInterface $logger,
         private SessionStoreInterface $sessionStore,
@@ -97,8 +102,73 @@ public function __construct(
      *                                  the factory resolves the shipped tool
      *                                  set via its container. Tests inject an
      *                                  explicit list to bypass DI.
+     *                                  An explicit list bypasses the runtime
+     *                                  cache and always builds a fresh server;
+     *                                  it is never written back to the cache,
+     *                                  so production calls (which pass null)
+     *                                  keep seeing the shipped tool set.
      */
     public function createServer(?array $tools = null): Server
+    {
+        if ($tools !== null) {
+            return $this->buildRuntime($tools)['server'];
+        }
+
+        return $this->resolveRuntime()['server'];
+    }
+
+    public function createInternalAccess(): InternalAccess
+    {
+        $runtime = $this->resolveRuntime();
+
+        return new InternalAccess(
+            $runtime['registry'],
+            $runtime['callToolHandler'],
+        );
+    }
+
+    /**
+     * Discard the memoised runtime so the next {@see createServer} or
+     * {@see createInternalAccess} call rebuilds against the current settings.
+     *
+     * The factory is a container singleton, so the cached runtime lives for the
+     * whole PHP process — one request under PHP-FPM, but potentially many logical
+     * operations in a long-running CLI worker. Production code still does not need
+     * to clear it: MCP settings and tool registration are stable for the process
+     * lifetime, and per-call state is isolated separately by the fresh in-memory
+     * session {@see InternalToolCaller} builds on every call. Tests that toggle
+     * settings affecting tool registration between builds must call this to drop
+     * the now-stale runtime.
+     *
+     * @internal
+     */
+    public function clearRuntimeCache(): void
+    {
+        $this->runtimeCache = null;
+    }
+
+    /**
+     * Memoise the MCP runtime so callers that hit the factory multiple times in
+     * one request (e.g. {@see getInternalToolCatalog} followed by repeated
+     * {@see callInternalTool} dispatches) reuse the same registry and handler
+     * chain.
+     *
+     * @return array{server: Server, registry: Registry, callToolHandler: RequestHandlerInterface<mixed>}
+     */
+    private function resolveRuntime(): array
+    {
+        if ($this->runtimeCache !== null) {
+            return $this->runtimeCache;
+        }
+
+        return $this->runtimeCache = $this->buildRuntime();
+    }
+
+    /**
+     * @param list<McpTool>|null $tools
+     * @return array{server: Server, registry: Registry, callToolHandler: RequestHandlerInterface<mixed>}
+     */
+    private function buildRuntime(?array $tools = null): array
     {
         $tools ??= $this->buildBuiltinTools();
 
@@ -140,19 +210,25 @@ public function createServer(?array $tools = null): Server
             new NullLogger(),
         );
 
+        $activeCallToolHandler = $callToolHandler;
         if ($loggingConfig['logToolCalls']) {
-            $builder->addRequestHandler(new ObservedCallToolHandler(
+            $activeCallToolHandler = new ObservedCallToolHandler(
                 $callToolHandler,
                 $this->logger,
                 $this->toolCallParameterFormatter,
                 $loggingConfig['logFullParameters'],
                 $loggingConfig['logLevel'],
-            ));
-        } else {
-            $builder->addRequestHandler($callToolHandler);
+            );
         }
+        $builder->addRequestHandler($activeCallToolHandler);
+
+        $server = $builder->build();
 
-        return $builder->build();
+        return [
+            'server' => $server,
+            'registry' => $registry,
+            'callToolHandler' => $activeCallToolHandler,
+        ];
     }
 
     private function registerTool(Builder $builder, McpTool $tool): void

Server/Handler/Request/ObservedCallToolHandler.php

@@ -20,6 +20,7 @@
 use Matomo\Dependencies\McpServer\Mcp\Server\Handler\Request\RequestHandlerInterface;
 use Matomo\Dependencies\McpServer\Mcp\Server\Session\SessionInterface;
 use Piwik\Log\LoggerInterface;
+use Piwik\Plugins\McpServer\Support\Logging\McpToolCallOrigin;
 use Piwik\Plugins\McpServer\Support\Logging\ToolCallParameterFormatter;
 
 /**
@@ -59,6 +60,7 @@ public function handle(Request $request, SessionInterface $session): Response|Er
             'mcp_session_id' => $this->resolveSessionId($session),
             'mcp_tool_name' => $toolName,
             'mcp_params_mode' => $loggingMode,
+            McpToolCallOrigin::LOG_CONTEXT_KEY => $this->resolveCallOrigin($session),
         ];
 
         $result = $this->delegate->handle($request, $session);
@@ -144,6 +146,21 @@ private function resolveSessionId(SessionInterface $session): string
         }
     }
 
+    private function resolveCallOrigin(SessionInterface $session): string
+    {
+        try {
+            $origin = $session->get(McpToolCallOrigin::SESSION_KEY, McpToolCallOrigin::ORIGIN_HTTP);
+        } catch (\Throwable) {
+            return McpToolCallOrigin::ORIGIN_HTTP;
+        }
+
+        if ($origin === McpToolCallOrigin::ORIGIN_INTERNAL) {
+            return McpToolCallOrigin::ORIGIN_INTERNAL;
+        }
+
+        return McpToolCallOrigin::ORIGIN_HTTP;
+    }
+
     /**
      * @param Response<mixed> $response
      */

Server/InternalAccess.php

@@ -0,0 +1,44 @@
+<?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\Server;
+
+use Matomo\Dependencies\McpServer\Mcp\Capability\RegistryInterface;
+use Matomo\Dependencies\McpServer\Mcp\Server\Handler\Request\RequestHandlerInterface;
+
+/**
+ * Internal handle on the populated MCP runtime exposed to other Matomo
+ * plugins via API.php. Holds the same registry and call-tool handler that
+ * back the public HTTP endpoint, so internal in-process callers see the
+ * exact same tool catalogue and execution semantics.
+ *
+ * Deliberately does not expose the production session store: internal callers
+ * dispatch a single tool per call with an ephemeral in-memory session, so a
+ * persistent session store would only be a footgun if a tool ever called
+ * Session::save().
+ *
+ * Not part of any public SDK contract; safe to evolve alongside this plugin.
+ * The constructor-promoted readonly properties are likewise internal and may
+ * be reshaped without notice.
+ *
+ * @internal
+ */
+final class InternalAccess
+{
+    /**
+     * @param RequestHandlerInterface<mixed> $callToolHandler
+     */
+    public function __construct(
+        public readonly RegistryInterface $registry,
+        public readonly RequestHandlerInterface $callToolHandler,
+    ) {
+    }
+}