feat(mcp-student): add student practice MCP (#5090)

Author: rschlaefli

.github/workflows/v3_mcp-student-prd.yml

@@ -0,0 +1,91 @@
+name: Build Docker image for mcp-student (prd)
+
+on:
+  push:
+    tags: ['v*.*.*']
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref_name }}
+  cancel-in-progress: true
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}/mcp-student
+
+jobs:
+  build-arm:
+    runs-on: ubuntu-24.04-arm
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log into registry ${{ env.REGISTRY }}
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-arm
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: apps/mcp-student/Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          platforms: linux/arm64
+          no-cache: true
+          labels: ${{ steps.meta.outputs.labels }}
+
+  build-amd:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log into registry ${{ env.REGISTRY }}
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-amd
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: apps/mcp-student/Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          platforms: linux/amd64
+          labels: ${{ steps.meta.outputs.labels }}

.github/workflows/v3_mcp-student-stg.yml

@@ -0,0 +1,106 @@
+name: Build Docker image for mcp-student (stg)
+
+on:
+  push:
+    branches:
+      - 'v3'
+      - 'v3*'
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+    paths:
+      - 'apps/mcp-student/**'
+      - 'packages/graphql/**'
+      - 'packages/types/**'
+      - 'packages/util/**'
+      - 'package.json'
+      - 'pnpm-lock.yaml'
+      - 'turbo.json'
+      - '.github/workflows/v3_mcp-student**'
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref_name }}
+  cancel-in-progress: true
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}/mcp-student
+
+jobs:
+  build-arm:
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    runs-on: ubuntu-24.04-arm
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log into registry ${{ env.REGISTRY }}
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-arm
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: apps/mcp-student/Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          platforms: linux/arm64
+          no-cache: true
+          labels: ${{ steps.meta.outputs.labels }}
+
+  build-amd:
+    if: github.event_name != 'pull_request' || github.event.pull_request.draft == false
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up QEMU
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log into registry ${{ env.REGISTRY }}
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Extract Docker metadata
+        id: meta
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}-amd
+
+      - name: Build and push Docker image
+        uses: docker/build-push-action@v5
+        with:
+          context: .
+          file: apps/mcp-student/Dockerfile
+          push: ${{ github.event_name != 'pull_request' }}
+          tags: ${{ steps.meta.outputs.tags }}
+          platforms: linux/amd64
+          labels: ${{ steps.meta.outputs.labels }}

AGENTS.md

@@ -217,6 +217,16 @@ Without Traefik, use `http://localhost:<port>` directly. The `*.klicker.com` dom
 - **Local embed harness target**: `util/embed-harness/` is for local verification only and should target the branch-local PWA (`http://127.0.0.1:3101/...`), not `https://pwa.klicker.com/...`, because production CSP / `frame-ancestors` blocks localhost embedding. (`util/embed-harness/`)
 - **Chat PWA login redirects**: `apps/chat/src/app/noLogin/page.tsx` must pass an absolute chat URL to the PWA login `redirect_to`; a relative chatbot path makes the PWA redirect to its own domain and 404. Local chat dev also needs ignored local env values for the backend `APP_SECRET` and `DATABASE_URL` so participant cookies verify and Prisma can load chatbot data.
 - **Chat Vitest alias resolution**: `apps/chat/vitest.config.ts` mirrors the app `@/*` alias from `apps/chat/tsconfig.json`; keep this in sync when adding client tests for modules that import from `@/src/...`.
+- **mcp-student build**: The TypeScript student MCP app uses plain `tsc -p tsconfig.build.json`; Rollup emitted `dist` but kept the process alive during initial setup, so keep this service unbundled unless there is a concrete reason to revisit. (`apps/mcp-student/`)
+- **mcp-student backend boundary**: `apps/mcp-student` must not use Prisma directly. Fetch practice pools through the participant-scoped GraphQL operation `studentMcpCoursePracticeQuiz`, which validates chatbot/course/enrollment and reuses `CourseService.getCoursePracticeQuiz` ordering. (`apps/mcp-student/src/graphqlClient.ts`, `packages/graphql/src/services/courses.ts`)
+- **mcp-student GraphQL transport**: Use `@apollo/client/core` with generated documents from `@klicker-uzh/graphql/dist/ops.js` and persisted hashes from `dist/client.json`; do not hard-code operation hashes or rely on non-persisted document POSTs for this service. (`apps/mcp-student/src/graphqlClient.ts`)
+- **Local dev Node TLS**: Node services must call local apps through the verified `https://*.klicker.com` Traefik domains. `_create_ssl_certificates.sh` copies the mkcert root to ignored `util/traefik/ssl/rootCA.pem`, and `_run_with_infisical.sh --env dev*` exports it as `NODE_EXTRA_CA_CERTS`. (`util/_create_ssl_certificates.sh`, `util/_run_with_infisical.sh`)
+- **Student practice MCP chat boundary**: `apps/chat` calls `apps/mcp-student` server-side via `MCP_STUDENT_URL`; only the answer-safe `start_student_practice_quiz` tool is exposed to the model, while answer submission stays behind the authenticated chat API route. (`apps/chat/src/services/studentPracticeMcp.ts`, `apps/chat/src/app/api/chatbots/[chatbotId]/practice/submit/route.ts`)
+- **Student practice history cards**: Signed MCP `questionRef` values expire, so chat history cards must be read-only after expiry. New quiz payloads include `expiresAt`; older payloads without it should be treated as archived. (`apps/chat/src/components/student-practice-quiz-card.tsx`, `apps/mcp-student/src/questionRef.ts`)
+- **mcp-student deployment boundary**: The Helm chart deploys `mcp-student` as an internal ClusterIP service and injects `MCP_STUDENT_URL` into chat. By default it reads `APP_SECRET` from the existing chat secret so participant MCP JWT validation and question refs use the same signing material. (`deploy/charts/klicker-uzh-v3/templates/deployment-mcp-student.yaml`, `deploy/charts/klicker-uzh-v3/templates/cm-chat.yaml`)
+- **Shared practice renderer in chat**: Do not wrap `StudentElement` in a chat-owned `<form>`; shared answer option buttons are regular buttons and can behave like implicit submit controls inside forms. Use an explicit chat submit button instead. (`apps/chat/src/components/student-practice-quiz-card.tsx`, `packages/shared-components/src/questions/`)
+- **Chat shared-component i18n**: Shared practice components use `next-intl` hooks, so `apps/chat` must wrap its App Router tree in `NextIntlClientProvider` before rendering them. (`apps/chat/src/app/layout.tsx`, `packages/shared-components/src/StudentElement.tsx`)
+- **Chat model reasoning effort changes**: Adding a reasoning effort requires updating chat validation, the GraphQL enum/schema, generated GraphQL artifacts, and the manage chatbot settings effort order; model-specific availability belongs in the chat and GraphQL model registries. (`apps/chat/src/lib/config/reasoning.ts`, `packages/graphql/src/schema/resource.ts`, `apps/frontend-manage/src/components/resources/chatbots/ChatbotDetails.tsx`)
 
 ## Factory Skills (AI Assistance)
 

apps/chat/package.json

@@ -12,9 +12,11 @@
     "@fortawesome/fontawesome-svg-core": "6.7.2",
     "@fortawesome/free-solid-svg-icons": "6.7.2",
     "@fortawesome/react-fontawesome": "0.2.2",
+    "@klicker-uzh/i18n": "workspace:*",
     "@klicker-uzh/next-config": "workspace:*",
     "@klicker-uzh/prisma": "workspace:*",
     "@klicker-uzh/shared-components": "workspace:*",
+    "@klicker-uzh/types": "workspace:*",
     "@langfuse/otel": "4.6.1",
     "@langfuse/tracing": "4.6.1",
     "@modelcontextprotocol/sdk": "1.17.5",
@@ -53,6 +55,8 @@
   },
   "devDependencies": {
     "@eslint/eslintrc": "~3",
+    "@tailwindcss/aspect-ratio": "~0.4.2",
+    "@tailwindcss/forms": "~0.5.10",
     "@tailwindcss/postcss": "~4.1.11",
     "@tailwindcss/typography": "~0.5.16",
     "@types/node": "^20.19.11",

apps/chat/src/app/api/chatbots/[chatbotId]/chat/route.ts

@@ -17,6 +17,7 @@ import {
   generateText,
   stepCountIs,
   streamText,
+  tool,
   type ModelMessage,
   type StepResult,
 } from 'ai'
@@ -29,6 +30,13 @@ import {
 } from 'src/lib/config/reasoning'
 import { CreditsService } from 'src/services/credits'
 import { DisclaimersService } from 'src/services/disclaimers'
+import {
+  formatPracticeCandidatesForPrompt,
+  getPracticeStackForQuiz,
+  lookupRelevantPracticeStacks,
+  STUDENT_PRACTICE_QUIZ_TOOL_NAME,
+  toPracticeCandidateId,
+} from 'src/services/studentPracticeMcp'
 import { ThreadService } from 'src/services/threads'
 import { z } from 'zod'
 
@@ -631,7 +639,7 @@ export async function POST(
   if ('response' in authResult) {
     return authResult.response
   }
-  const { participantId } = authResult
+  const { participantId, chatbot: authChatbot } = authResult
 
   // check disclaimer acceptance
   try {
@@ -845,13 +853,105 @@ export async function POST(
   }))
 
   // Load MCP tools from database configurations or fallback to legacy
-  const mcpTools = await getAggregatedMCPTools(mcpServersWithConfigs, chatbotId)
-  const toolNames = Object.keys(mcpTools || {})
+  const mcpTools = await getAggregatedMCPTools(
+    mcpServersWithConfigs,
+    chatbotId,
+    participantId
+  )
 
   if (!chatbot) {
     return NextResponse.json({ error: 'Chatbot not found' }, { status: 404 })
   }
 
+  let practiceCandidatePrompt = ''
+  let practiceCandidateCount = 0
+  const practiceCandidateRefs = new Map<string, string>()
+
+  if (selectedMode === 'tutor') {
+    try {
+      const lookupResult = await lookupRelevantPracticeStacks({
+        chatbotId,
+        courseId: authChatbot.courseId,
+        messages,
+        participantId,
+      })
+      const candidates = lookupResult?.candidates ?? []
+      practiceCandidateCount = candidates.length
+      candidates.forEach((candidate, index) => {
+        practiceCandidateRefs.set(
+          toPracticeCandidateId(index),
+          candidate.questionRef
+        )
+      })
+      practiceCandidatePrompt = formatPracticeCandidatesForPrompt(candidates)
+
+      logChatDev('studentPractice.lookup', {
+        requestId,
+        chatbotId,
+        participantId,
+        candidateCount: practiceCandidateCount,
+      })
+    } catch (error) {
+      console.warn(
+        'Student practice lookup failed; continuing without quiz candidates',
+        {
+          requestId,
+          chatbotId,
+          error,
+        }
+      )
+    }
+  }
+
+  const studentPracticeTools: Record<string, any> = {}
+  if (practiceCandidatePrompt) {
+    studentPracticeTools[STUDENT_PRACTICE_QUIZ_TOOL_NAME] = tool({
+      description:
+        'Show a selected answer-safe practice quiz question to the student. Use only candidateId values from the current relevant practice candidate context.',
+      inputSchema: z.object({
+        candidateId: z
+          .string()
+          .min(1)
+          .describe('Candidate id from the current practice candidate context'),
+      }),
+      execute: async ({ candidateId }) => {
+        const questionRef = practiceCandidateRefs.get(candidateId)
+        if (!questionRef) {
+          throw new Error('Unknown practice candidate id')
+        }
+
+        const payload = await getPracticeStackForQuiz({
+          chatbotId,
+          participantId,
+          questionRef,
+        })
+
+        if (!payload) {
+          throw new Error('Student practice MCP is not configured')
+        }
+
+        return {
+          kind: 'student-practice-quiz',
+          ...payload,
+        }
+      },
+      toModelOutput: () => ({
+        type: 'text' as const,
+        value:
+          'A practice quiz was shown to the student. Wait for the student answer or submission result before giving feedback.',
+      }),
+    })
+  }
+
+  const chatTools: Record<string, any> = {
+    ...(mcpTools || {}),
+    ...studentPracticeTools,
+  }
+  const toolNames = Object.keys(chatTools)
+  const effectiveSystemPrompt = practiceCandidatePrompt
+    ? `${systemPrompt}\n\n${practiceCandidatePrompt}`
+    : systemPrompt
+
   const modelRegistry = getChatModelRegistry()
   const allowedIds =
     chatbot.allowedModelIds.length > 0
@@ -1034,6 +1134,7 @@ export async function POST(
     maxOutputTokens: maxOutputTokens ?? null,
     toolCount: toolNames.length,
     toolNames,
+    practiceCandidateCount,
     systemPromptLength: systemPrompt.length,
     systemPromptHash: systemPrompt ? hashSnippet(systemPrompt) : null,
     userPromptLengthTotal: userPrompt.length,
@@ -1246,10 +1347,10 @@ export async function POST(
       },
     },
     messages: modelMessages as ModelMessage[],
-    tools: mcpTools,
+    tools: chatTools,
     toolChoice: 'auto',
     stopWhen: stepCountIs(5),
-    system: systemPrompt,
+    system: effectiveSystemPrompt,
 
     abortSignal: req.signal,