feat(analytics): add mcp server.

Author: xdanielsb

README.md

@@ -33,7 +33,7 @@ _Cloud‑native survey engine with end‑to‑end observability._
 -  **Monitoring** | Prometheus + Grafana (Latency, Error Rate, Traffic, Saturation) 
 -  **Unit/Integration Test** | Vitest + JaCoCo + Codecov + TestContainers
 -  **Stress tests** with k6 (nightly via GitHub Actions)
--  **LLMs** | analytics service exposes an AI chat endpoint to talk about the surveys.
+-  **MCP** | analytics service with MCP connected to an LLM (feature available for premium users).
 -  **Delivery** GitHub Actions · Docker · Caddy reverse‑proxy
 
 
@@ -48,16 +48,10 @@ _Cloud‑native survey engine with end‑to‑end observability._
 .github/workflows
 ├── dependabot.yml
 └── workflows
-    ├── cd-keycloak.yml
-    ├── cd-monitoring.yml
-    ├── cd-prod.yml
-    ├── cd-staging.yml
-    ├── ci-analytics.yml
-    ├── ci-backend.yml
-    ├── ci-backoffice.yml
-    ├── ci-code-vulnerabilities.yml
-    ├── ci-coverage.yml
-    ├── ci-frontend.yml
+    ├── cd
+        ├── ...
+    ├── ci
+        ├── ...
     ├── nightly-stress.yml
     ├── release-changelog.yml
     └── security.yml

services/analytics/README.md

@@ -38,6 +38,9 @@ Runtime dependencies are defined in `pyproject.toml`. To generate a
 `requirements.txt` file, install `pip-tools` and run:
 
 ```bash
-pip install pip-tools
-pip-compile --output-file=requirements.txt pyproject.toml
+uv pip install pip-tools
+```
+
+```bash
+uv pip compile pyproject.toml -o requirements.txt
 ```

services/analytics/pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "httpx>=0.27",
     "python-logstash>=0.4.8",
     "sentry-sdk>=2",
+    "mcp>=1.11",
 ]
 
 [project.optional-dependencies]

services/analytics/requirements.txt

@@ -1,15 +1,17 @@
-#
-# This file is autogenerated by pip-compile with Python 3.12
-# by the following command:
-#
-#    pip-compile --output-file=requirements.txt pyproject.toml
-#
+# This file was autogenerated by uv via the following command:
+#    uv pip compile pyproject.toml -o requirements.txt
 annotated-types==0.7.0
     # via pydantic
 anyio==4.9.0
     # via
     #   httpx
+    #   mcp
+    #   sse-starlette
     #   starlette
+attrs==25.3.0
+    # via
+    #   jsonschema
+    #   referencing
 certifi==2025.4.26
     # via
     #   httpcore
@@ -26,35 +28,70 @@ h11==0.16.0
 httpcore==1.0.9
     # via httpx
 httpx==0.28.1
-    # via analytics (pyproject.toml)
+    # via
+    #   analytics (pyproject.toml)
+    #   mcp
+httpx-sse==0.4.1
+    # via mcp
 idna==3.10
     # via
     #   anyio
     #   httpx
+jsonschema==4.24.0
+    # via mcp
+jsonschema-specifications==2025.4.1
+    # via jsonschema
+mcp==1.11.0
+    # via analytics (pyproject.toml)
 pydantic==2.11.5
     # via
     #   analytics (pyproject.toml)
     #   fastapi
+    #   mcp
+    #   pydantic-settings
 pydantic-core==2.33.2
     # via pydantic
+pydantic-settings==2.10.1
+    # via mcp
+python-dotenv==1.1.1
+    # via pydantic-settings
 python-logstash==0.4.8
     # via analytics (pyproject.toml)
+python-multipart==0.0.20
+    # via mcp
+referencing==0.36.2
+    # via
+    #   jsonschema
+    #   jsonschema-specifications
+rpds-py==0.26.0
+    # via
+    #   jsonschema
+    #   referencing
 sentry-sdk==2.30.0
     # via analytics (pyproject.toml)
 sniffio==1.3.1
     # via anyio
+sse-starlette==2.4.1
+    # via mcp
 starlette==0.46.2
-    # via fastapi
+    # via
+    #   fastapi
+    #   mcp
 typing-extensions==4.14.0
     # via
     #   anyio
     #   fastapi
     #   pydantic
     #   pydantic-core
+    #   referencing
     #   typing-inspection
 typing-inspection==0.4.1
-    # via pydantic
+    # via
+    #   pydantic
+    #   pydantic-settings
 urllib3==2.4.0
     # via sentry-sdk
 uvicorn==0.34.3
-    # via analytics (pyproject.toml)
+    # via
+    #   analytics (pyproject.toml)
+    #   mcp

services/analytics/src/analytics/mcp_server.py

@@ -0,0 +1,31 @@
+"""Minimal MCP server exposing a summary tool."""
+
+import os
+
+from mcp.server import FastMCP
+
+from analytics.exceptions import AnalyticException
+from analytics.logger import get_logger
+from analytics.ollama import OllamaClient
+
+logger = get_logger("mcp")
+
+OLLAMA_URL: str = os.getenv("OLLAMA_URL", "http://localhost:11434")
+OLLAMA_MODEL: str = "tinyllama"
+ollama_client = OllamaClient(OLLAMA_URL, OLLAMA_MODEL, logger=logger)
+
+server = FastMCP(name="analytics")
+
+
+@server.tool(name="summarize")
+def summarize(question: str) -> str:
+    """Return a summary for ``question`` using Ollama."""
+    try:
+        return ollama_client.summarize(question)
+    except AnalyticException as exc:  # noqa: BLE001
+        logger.error("Failed to summarize", exc_info=exc)
+        return f"Received question: {question}"
+
+
+if __name__ == "__main__":  # pragma: no cover
+    server.run("sse")

services/analytics/tests/test_mcp_server.py

@@ -0,0 +1,13 @@
+import anyio
+
+from analytics import mcp_server
+
+
+def test_summarize_tool(monkeypatch):
+    def fake_summary(prompt: str) -> str:
+        return f"echo:{prompt}"
+
+    monkeypatch.setattr(mcp_server.ollama_client, "summarize", fake_summary)
+    result = anyio.run(mcp_server.server.call_tool, "summarize", {"question": "hi"})
+    content, data = result
+    assert content[0].text == "echo:hi"