Release 5.0.0 (#31)

mneudert · web-flow · commit 7f6c6ecbafed · 2026-03-12T12:38:33.000+01:00
* Prepare release

* Configure .gitattributes

* Add guidance for coding agents

* Use consistent 403 error descriptions

* Flag as early preview release

* Restructure documentation for Marketplace
diff --git a/.gitattributes b/.gitattributes
@@ -0,0 +1,11 @@
+/.github/ export-ignore
+/tests/ export-ignore
+
+/.gitattributes export-ignore
+/AGENTS.md export-ignore
+/bootstrap-phpstan.php export-ignore
+/composer.lock export-ignore
+/config/test.php export-ignore
+/phpcs.xml export-ignore
+/phpstan.neon export-ignore
+/scoper.inc.php export-ignore
diff --git a/AGENTS.md b/AGENTS.md
@@ -0,0 +1,130 @@
+# AGENTS.md
+
+## Purpose
+
+This file is the agent-facing guide for the `McpServer` Matomo plugin.
+
+Use it to discover the codebase quickly, make targeted changes, and extend the plugin without breaking existing MCP behavior or drifting from the current structure.
+
+This document is repo-specific. Prefer it over generic Matomo assumptions when working in this repository.
+
+## Scope And Defaults
+
+- Optimize for small, targeted changes.
+- Preserve existing structure and naming unless a refactor is explicitly requested.
+- Treat checked-in `vendor/` code as read-only unless the task is explicitly about dependency or vendor refresh.
+- Do not duplicate README setup/product documentation unless the change requires agent execution context.
+- Treat `README.md` as public-facing documentation. Keep the `## Description` section suitable for Matomo Marketplace display, and keep repository-structure or agent workflow guidance in `AGENTS.md` instead.
+
+## Repository Map
+
+### Plugin entrypoints and metadata
+
+- `API.php`: main MCP API endpoint, request validation flow, auth/error handling, and hand-off into the server.
+- `McpServer.php`: plugin lifecycle hooks, stylesheet registration, install/uninstall table setup.
+- `McpServerFactory.php`: server/container wiring and MCP server construction.
+- `SystemSettings.php`: plugin settings, including MCP enablement.
+- `plugin.json`, `composer.json`: plugin metadata and PHP dependency constraints.
+
+### 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.
+
+### Domain and infrastructure layers
+
+- `Services/`: domain/query logic and Matomo-facing gateways, grouped by feature area.
+- `Support/Api/`: endpoint boundary helpers, request-id extraction, JSON-RPC error responses, and MCP endpoint rules.
+- `Support/`: shared pagination, normalization, logging, tooling helpers, and error mapping.
+- `Server/`: MCP server handler support.
+- `Session/`: MCP session persistence and session table management.
+
+### Verification and maintenance
+
+- `tests/Integration/`: primary coverage for externally visible behavior and cross-layer plugin behavior.
+- `tests/Unit/`: focused unit coverage for isolated logic.
+- `tests/Framework/`: shared test helpers and contract assertions.
+- `.github/workflows/`: CI expectations for plugin tests, PHPCS, PHPStan, and checklist gates.
+- `phpcs.xml`, `phpstan.neon`: local code-quality configuration for this plugin.
+
+## Where To Start
+
+### If the task touches endpoint behavior, auth, or request boundaries
+
+Start with `API.php` and `Support/Api/`. Follow the current request flow before editing:
+
+1. request format and endpoint validation
+2. request parsing / JSON-RPC metadata extraction
+3. auth and access checks
+4. MCP enabled/disabled behavior
+5. server transport hand-off
+
+Check existing integration tests before changing any of these behaviors. Start with `tests/Integration/McpApiEndpointBoundaryTest.php`.
+
+### If the task adds or changes an MCP tool
+
+Start in `McpTools/`, then trace the matching implementation in `Services/` and `Schemas/`.
+
+Preferred flow:
+
+1. tool class defines the user-facing capability
+2. service or gateway code fetches/transforms Matomo data
+3. schema defines the output contract
+4. tests cover the visible behavior
+
+### If the task changes domain behavior
+
+Find the domain area under `Services/Sites`, `Services/Reports`, `Services/Goals`, `Services/Segments`, `Services/Dimensions`, or `Services/System`.
+
+Before editing:
+
+- find the integration tests that currently cover the behavior
+- check for matching records or ports in `Contracts/`
+- check for supporting pagination, normalization, or error helpers in `Support/`
+
+## Extension Rules
+
+### Adding new MCP capabilities
+
+- Add user-facing capability through a tool class in `McpTools/`.
+- 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.
+
+### Keeping boundaries clean
+
+- Do not move Matomo access logic into tool classes when it belongs in services.
+- Do not bypass existing support helpers if pagination, normalization, logging, or error mapping already has a home.
+- Prefer matching existing domain grouping and naming patterns over inventing a new layout for a small feature.
+
+### Testing expectations for new behavior
+
+- Cover externally visible behavior with integration tests first.
+- Add unit tests for isolated logic where they provide fast, focused regression coverage.
+- Do not introduce new public behavior without matching tests.
+
+## Verification Expectations
+
+### For code changes
+
+Treat all of the following as the default verification bar:
+
+- run the full plugin test suite
+- run targeted tests for the touched behavior when focused coverage exists
+- run PHPStan with this plugin's configuration
+- run PHPCS with this plugin's rules
+
+The full plugin suite is required for code changes to reduce the chance of breaking unrelated MCP tools or shared plugin behavior.
+
+### For docs-only changes
+
+Lighter verification is acceptable. Full plugin-suite execution is not required for product or README copy edits unless the documentation change affects engineering instructions that should be validated against the codebase.
+
+## Guardrails
+
+- Prefer small, reviewable changes over cross-cutting rewrites.
+- Avoid broad refactors during feature work unless explicitly requested.
+- Preserve existing public behavior unless the task explicitly changes it.
+- Keep agent guidance and implementation guidance aligned with current repo truth.
+- When unsure where code belongs, choose the existing nearest feature area instead of creating a new abstraction layer by default.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1 +1,8 @@
 ## Changelog
+
+### 5.0.0
+
+- Initial release
+- Added MCP over HTTP endpoint
+- Added tools for sites, reports, goals, segments, and dimensions
+- Added admin page for MCP client setup
diff --git a/README.md b/README.md
@@ -1,41 +1,36 @@
 # Matomo MCP Server Plugin
 
-## Endpoint
+## Description
 
-Use the API endpoint:
+McpServer is an early preview plugin that adds a secure Model Context Protocol (MCP) endpoint to Matomo so AI assistants and MCP-compatible clients can work with analytics context directly from your Matomo instance.
 
-`index.php?module=API&method=McpServer.mcp&format=mcp`
+It provides read-oriented tools for sites, reports, processed report data, goals, segments, and dimensions using the same Matomo authentication and access rules you already use in Matomo.
 
-- `format=mcp` is required.
-- The endpoint is root-request only and rejects nested/proxy access (including `API.getBulkRequest`) with `400`.
-- Unauthenticated requests return `401` with `WWW-Authenticate: Bearer realm="mcp"`.
+### Setup
 
-## Configuration
+1. Install the plugin in Matomo.
+2. Activate **McpServer** in **Administration -> Plugins**.
+3. Enable MCP in **Administration -> System -> Plugin Settings -> McpServer**.
+4. Configure your MCP client with the endpoint and a Matomo `token_auth` that already has access to the data you want to expose.
 
-Configure options in `config/config.ini.php`:
+For the recommended end-user setup flow, use the in-product connect guide at **Administration -> Platform -> MCP Server**.
 
-```ini
-[McpServer]
-session_ttl = 3600
-log_tool_calls = 0
-log_tool_call_level = DEBUG
-log_tool_call_parameters_full = 0
-```
+### Security And Access Model
 
-- `session_ttl`: Session TTL in seconds. Default is `3600` if missing or invalid.
-- `log_tool_calls`: Enables tool-call logging when set to `1`. Default is disabled when missing or set to `0`.
-- `log_tool_call_level`: Tool-call logging level when `log_tool_calls = 1`. Accepted values: `ERROR`, `WARN`/`WARNING`, `INFO`, `DEBUG`, `VERBOSE` (case-insensitive). Missing or invalid values default to `DEBUG`. `VERBOSE` is logged via debug-level logger calls.
-- `log_tool_call_parameters_full`: Logs full tool-call parameter values when set to `1`. Default is redacted parameter logging when set to `0` (may expose sensitive input data when enabled).
+- MCP access is disabled by default.
+- The plugin uses Matomo authentication.
+- Data access is limited to the same sites and reports the Matomo user can already access.
+- If features such as the Visitor Log are available to that user, MCP clients may access the same underlying data scope.
 
-## Enabling MCP
+### Additional Documentation
 
-MCP access is disabled by default and must be enabled in **Administration -> System -> Plugin Settings -> McpServer**.
+The FAQ includes additional technical documentation for endpoint details, configuration, MCP enablement behavior, supported capabilities, and troubleshooting.
 
-When disabled, requests to `index.php?module=API&method=McpServer.mcp&format=mcp` behave as follows:
+## Support
 
-- Unauthenticated requests receive `401 Unauthorized` with `WWW-Authenticate: Bearer realm="mcp"`.
-- Authenticated requests with a top-level JSON-RPC `id` receive `403 Forbidden` with a JSON-RPC error response instructing the user to contact their Matomo administrator.
-- Authenticated requests without a top-level `id` (for example notifications, invalid JSON, or batch payloads) receive `403 Forbidden` with an empty body.
+- Issues: <https://github.com/matomo-org/plugin-McpServer/issues>
+- Forum: <https://forum.matomo.org>
+- Source: <https://github.com/matomo-org/plugin-McpServer>
 
 ## License
 
diff --git a/docs/faq.md b/docs/faq.md
@@ -0,0 +1,55 @@
+# McpServer FAQ
+
+## Endpoint
+
+Use the API endpoint:
+
+`index.php?module=API&method=McpServer.mcp&format=mcp`
+
+- `format=mcp` is required.
+- The endpoint is root-request only and rejects nested/proxy access (including `API.getBulkRequest`) with `400`.
+- Unauthenticated requests return `401` with `WWW-Authenticate: Bearer realm="mcp"`.
+
+## Configuration
+
+Configure options in `config/config.ini.php`:
+
+```ini
+[McpServer]
+session_ttl = 3600
+log_tool_calls = 0
+log_tool_call_level = DEBUG
+log_tool_call_parameters_full = 0
+```
+
+- `session_ttl`: Session TTL in seconds. Default is `3600` if missing or invalid.
+- `log_tool_calls`: Enables tool-call logging when set to `1`. Default is disabled when missing or set to `0`.
+- `log_tool_call_level`: Tool-call logging level when `log_tool_calls = 1`. Accepted values: `ERROR`, `WARN`/`WARNING`, `INFO`, `DEBUG`, `VERBOSE` (case-insensitive). Missing or invalid values default to `DEBUG`. `VERBOSE` is logged via debug-level logger calls.
+- `log_tool_call_parameters_full`: Logs full tool-call parameter values when set to `1`. Default is redacted parameter logging when set to `0` (may expose sensitive input data when enabled).
+
+## Enabling MCP
+
+MCP access is disabled by default and must be enabled in **Administration -> System -> Plugin Settings -> McpServer**.
+
+When disabled, requests to `index.php?module=API&method=McpServer.mcp&format=mcp` behave as follows:
+
+- Unauthenticated requests receive `401 Unauthorized` with `WWW-Authenticate: Bearer realm="mcp"`.
+- Authenticated requests with a top-level JSON-RPC `id` receive `403 Forbidden` with a JSON-RPC error response instructing the user to contact their Matomo administrator.
+- Authenticated requests without a top-level `id` (for example notifications, invalid JSON, or batch payloads) receive `403 Forbidden` with an empty body.
+
+## Supported MCP Capabilities
+
+The plugin is focused on read-oriented analytics workflows. The exact tool surface may expand over time, but the initial release includes tools around:
+
+- sites
+- reports and report metadata
+- processed report data
+- goals
+- segments
+- dimensions
+
+## Troubleshooting
+
+- `401 Unauthorized`: verify the Bearer token is present, active, and belongs to a user with access to the requested site data.
+- `403 Forbidden`: if MCP is disabled, enable MCP in **Administration -> System -> Plugin Settings -> McpServer**. If MCP is already enabled, verify the authenticated Matomo user has access to the requested site or report data.
+- `400 Bad Request`: verify the client is using the exact MCP endpoint and is not proxying requests through `API.getBulkRequest`.
diff --git a/lang/en.json b/lang/en.json
@@ -19,8 +19,8 @@
         "ConnectTroubleshooting400Action": "Re-check the endpoint URL and that your client sends valid MCP requests.",
         "ConnectTroubleshooting401": "Missing or invalid authentication token.",
         "ConnectTroubleshooting401Action": "Verify you are sending %1$sAuthorization: Bearer &lt;token_auth&gt;%2$s and that the token is active.",
-        "ConnectTroubleshooting403": "MCP Server is disabled by configuration.",
-        "ConnectTroubleshooting403Action": "Confirm MCP is enabled in your Matomo instance.",
+        "ConnectTroubleshooting403": "MCP Server is disabled or the authenticated Matomo user does not have access to the requested data.",
+        "ConnectTroubleshooting403Action": "Confirm MCP is enabled in your Matomo instance. If it is already enabled, verify the token belongs to a user with access to the requested site or report data.",
         "ConnectTroubleshootingTitle": "Troubleshooting",
         "ConnectTokenTitle": "Get a Matomo Token",
         "ConnectWhatYouNeedTitle": "What You'll Need",
diff --git a/plugin.json b/plugin.json
@@ -1,6 +1,6 @@
 {
     "name": "McpServer",
-    "description": "Matomo MCP Server",
+    "description": "Early preview: connect AI assistants and MCP clients to Matomo with secure access to sites, reports, goals, segments, and dimensions.",
     "version": "5.0.0",
     "theme": false,
     "require": {
@@ -19,7 +19,14 @@
         "forum": "https://forum.matomo.org",
         "source": "https://github.com/matomo-org/plugin-McpServer"
     },
-    "homepage": "",
+    "homepage": "https://github.com/matomo-org/plugin-McpServer",
     "license": "GPL v3+",
-    "keywords": []
+    "keywords": [
+        "mcp",
+        "ai",
+        "assistant",
+        "analytics",
+        "integration"
+    ],
+    "category": "integration"
 }
diff --git a/screenshots/_cover.png b/screenshots/_cover.png
