refactor(mcp-student): simplify persisted graphql transport

Author: rschlaefli

AGENTS.md

@@ -219,6 +219,7 @@ Without Traefik, use `http://localhost:<port>` directly. The `*.klicker.com` dom
 - **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`)
 - **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`)

apps/mcp-student/package.json

@@ -6,10 +6,12 @@
   "license": "AGPL-3.0",
   "main": "dist/index.js",
   "dependencies": {
+    "@apollo/client": "3.13.8",
     "@klicker-uzh/graphql": "workspace:*",
     "@klicker-uzh/types": "workspace:*",
     "@klicker-uzh/util": "workspace:*",
     "fastmcp": "3.15.2",
+    "graphql": "16.11.0",
     "zod": "3.25.76"
   },
   "devDependencies": {

apps/mcp-student/src/graphqlClient.ts

@@ -1,22 +1,30 @@
+import {
+  ApolloClient,
+  HttpLink,
+  InMemoryCache,
+  from,
+  type NormalizedCacheObject,
+  type OperationVariables,
+  type TypedDocumentNode,
+} from '@apollo/client/core'
+import { createPersistedQueryLink } from '@apollo/client/link/persisted-queries'
 import hashes from '@klicker-uzh/graphql/dist/client.json'
-import type {
-  GetCoursePracticeQuizWithoutSolutionsQuery,
-  GetCoursePracticeQuizWithoutSolutionsQueryVariables,
-  RespondToElementStackMutation,
-  RespondToElementStackMutationVariables,
+import {
+  GetCoursePracticeQuizWithoutSolutionsDocument,
+  RespondToElementStackDocument,
+  type GetCoursePracticeQuizWithoutSolutionsQuery,
+  type GetCoursePracticeQuizWithoutSolutionsQueryVariables,
+  type RespondToElementStackMutation,
+  type RespondToElementStackMutationVariables,
 } from '@klicker-uzh/graphql/dist/ops.js'
 import type {
   StudentMcpPracticeQuiz as PracticeQuiz,
   StudentMcpStackResponseInput as StackResponseInput,
 } from '@klicker-uzh/types'
+import type { DocumentNode, OperationDefinitionNode } from 'graphql'
 
 const PERSISTED_OPERATION_HASHES = hashes as Record<string, string>
 
-type GraphQLResponse<T> = {
-  data?: T
-  errors?: Array<{ message?: string }>
-}
-
 export type SubmitStackAnswerInput = {
   courseId: string
   responses: StackResponseInput[]
@@ -32,70 +40,127 @@ function operationHash(operationName: string): string {
   return hash
 }
 
+function documentOperationName(document: DocumentNode): string {
+  const definition = document.definitions.find(
+    (value): value is OperationDefinitionNode =>
+      value.kind === 'OperationDefinition'
+  )
+
+  if (!definition?.name?.value) {
+    throw new Error('GraphQL document is missing an operation name')
+  }
+
+  return definition.name.value
+}
+
 export class PersistedGraphQLClient {
-  constructor(
-    private readonly endpoint: string,
-    private readonly fetchImpl: typeof fetch = fetch
-  ) {}
+  private readonly client: ApolloClient<NormalizedCacheObject>
 
-  async execute<TData, TVariables extends Record<string, unknown>>(
-    operationName: string,
-    variables: TVariables,
-    bearerToken: string
-  ): Promise<TData> {
-    const response = await this.fetchImpl(this.endpoint, {
-      body: JSON.stringify({
-        operationName,
-        variables,
-        extensions: {
-          persistedQuery: {
-            version: 1,
-            sha256Hash: operationHash(operationName),
+  constructor(endpoint: string, fetchImpl: typeof fetch = fetch) {
+    this.client = new ApolloClient({
+      cache: new InMemoryCache(),
+      link: from([
+        createPersistedQueryLink({
+          generateHash: (document) =>
+            operationHash(documentOperationName(document)),
+          retry: () => false,
+        }),
+        new HttpLink({
+          fetch: fetchImpl,
+          headers: {
+            Accept: 'application/json',
+            'x-graphql-yoga-csrf': 'true',
           },
-        },
-      }),
+          uri: endpoint,
+        }),
+      ]),
+    })
+  }
+
+  private authContext(bearerToken: string) {
+    return {
       headers: {
-        Accept: 'application/json',
         Authorization: `Bearer ${bearerToken}`,
-        'Content-Type': 'application/json',
-        'x-graphql-yoga-csrf': 'true',
       },
-      method: 'POST',
-    })
-
-    if (!response.ok) {
-      const body = await response.text().catch(() => '')
-      const details = body ? `: ${body.slice(0, 500)}` : ''
-      throw new Error(
-        `GraphQL ${operationName} failed with HTTP ${response.status}${details}`
-      )
     }
+  }
 
-    const payload = (await response.json()) as GraphQLResponse<TData>
-    if (payload.errors?.length) {
-      throw new Error(
-        payload.errors
-          .map((error) => error.message ?? 'Unknown GraphQL error')
-          .join('; ')
-      )
+  private async query<
+    TData,
+    TVariables extends OperationVariables = OperationVariables,
+  >(
+    query: TypedDocumentNode<TData, TVariables>,
+    variables: TVariables,
+    bearerToken: string
+  ): Promise<TData> {
+    const operationName = documentOperationName(query)
+    const result = await this.withOperationError(
+      operationName,
+      this.client.query<TData, TVariables>({
+        context: this.authContext(bearerToken),
+        fetchPolicy: 'no-cache',
+        query,
+        variables,
+      })
+    )
+
+    return this.requireData(operationName, result)
+  }
+
+  private async mutate<
+    TData,
+    TVariables extends OperationVariables = OperationVariables,
+  >(
+    mutation: TypedDocumentNode<TData, TVariables>,
+    variables: TVariables,
+    bearerToken: string
+  ): Promise<TData> {
+    const operationName = documentOperationName(mutation)
+    const result = await this.withOperationError(
+      operationName,
+      this.client.mutate<TData, TVariables>({
+        context: this.authContext(bearerToken),
+        fetchPolicy: 'no-cache',
+        mutation,
+        variables,
+      })
+    )
+
+    return this.requireData(operationName, result)
+  }
+
+  private async withOperationError<T>(
+    operationName: string,
+    operation: Promise<T>
+  ): Promise<T> {
+    try {
+      return await operation
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error)
+      throw new Error(`GraphQL ${operationName} failed: ${message}`)
     }
+  }
 
-    if (!payload.data) {
+  private requireData<TData>(
+    operationName: string,
+    result: { data?: TData | null }
+  ): TData {
+    if (!result.data) {
       throw new Error(`GraphQL ${operationName} returned no data`)
     }
 
-    return payload.data
+    return result.data
   }
 
   async getCoursePracticeQuiz(
     input: { chatbotId: string; courseId: string },
     bearerToken: string
   ): Promise<PracticeQuiz | null> {
-    const data = await this.execute<
+    const data = await this.query<
       GetCoursePracticeQuizWithoutSolutionsQuery,
       GetCoursePracticeQuizWithoutSolutionsQueryVariables
     >(
-      'GetCoursePracticeQuizWithoutSolutions',
+      GetCoursePracticeQuizWithoutSolutionsDocument,
       {
         chatbotId: input.chatbotId,
         courseId: input.courseId,
@@ -113,11 +178,11 @@ export class PersistedGraphQLClient {
     input: SubmitStackAnswerInput,
     bearerToken: string
   ): Promise<unknown> {
-    const data = await this.execute<
+    const data = await this.mutate<
       RespondToElementStackMutation,
       RespondToElementStackMutationVariables
     >(
-      'RespondToElementStack',
+      RespondToElementStackDocument,
       {
         courseId: input.courseId,
         isOwner: false,