docs: plan Klicker MCP server and chat integration

[rschlaefli]

Summary

• Adds project/plans_wip/PLAN-mcp-server.md capturing the design for a Klicker-owned MCP server (we currently only have client-side MCP integration in apps/chat).
• Defines the v1 read-only tool surface (klicker_course_*, klicker_practice_quiz_*, klicker_element_get, klicker_progress_get, klicker_search_content, klicker_recommended_next).
• Proposes a two-layer auth model: static bearer for server-to-server trust + short-lived signed X-Klicker-Participant JWT for per-call participant scope (uses the passChatbotId pattern already supported in ChatbotMCPServer, plus a new passParticipantToken flag).
• Lays out two complementary rendering paths in chat: (A) iframe-embed of the existing ?embed=1 PWA practice quiz page (reuses the klicker:embed-init / klicker:quiz-state postMessage protocol that already shipped) and (B) extracting a headless QuestionCard into packages/shared-components for inline single-question rendering via makeAssistantToolUI.
• Sequences the work: scaffold apps/mcp-server/ → land 3 read tools + chat-side iframe tool UI → expand toolset → extract QuestionCard.

Context

• Branch was created clean off v3 — no MCP-server code yet.
• Existing assets the plan reuses: apps/chat/src/services/mcpClients.ts (client), apps/chat/src/components/tools-ui/rag-tool-ui.tsx (rendering primitive via @assistant-ui/react), apps/frontend-pwa/src/pages/course/[courseId]/practiceQuizzes/[id].tsx (already embed-friendly), and the per-element components in packages/shared-components/src/.
• Distinct from the orthogonal project/KB_PLAN.md (native KB / RAG ingestion) and project/plans_wip/PLAN-chat-pwa-integration.md (deep-link / side-panel chat) — plan calls those out and avoids duplication.

Test plan

• Review the proposed scope decisions in §"Locked decisions" with the team (read-only v1, workspace location, auth model).
• Confirm the participant-token signing approach against existing APP_SECRET usage.
• Verify the chat origin can be added to the PWA frame-ancestors directive (HAProxy in prod, Traefik in dev) before relying on Path A iframe rendering.
• Once Phase 1 lands, smoke-test with agent-browser against the seeded Testkurs chatbot.

https://claude.ai/code/session_01AVNNW9YUwSTsU44L6RqBN9

---

Generated by Claude Code

Summary by CodeRabbit

• Documentation
  • Planning documentation prepared for future MCP server infrastructure development.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 40d9306d-31ce-43e8-89f1-27a65fd5043d

📥 Commits

Reviewing files that changed from the base of the PR and between fb7a26f and 5fd3944.

📒 Files selected for processing (1)

• project/plans_wip/PLAN-mcp-server.md

---

📝 Walkthrough

Walkthrough

Added a planning document for the Klicker MCP server specifying architecture decisions, v1 tool surface with JSON output rules, two-layer authentication, quiz rendering approaches, and a phased implementation roadmap (phases 0–4).

Changes

MCP Server Planning

Layer / File(s)

Summary

Planning Document project/plans_wip/PLAN-mcp-server.md

Comprehensive planning document covering current context, server goals, tool definitions, authentication/authorization model, v1 tool surface (courses, quizzes, elements, progress, recommendations, search), two chat rendering approaches for quiz questions, architecture decisions (Streamable HTTP, Next.js workspace, JWT + bearer auth, read-only v1), and phased implementation roadmap (phases 0–4) with scaffolding, auth setup, tool registration, chat glue changes, deployment tasks, risks, and next steps.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Suggested labels

enhancement

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Review rate limit: 0/1 reviews remaining, refill in 60 minutes.}

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[greptile-apps]

Your free trial has ended. If you'd like to continue receiving code reviews, you can add a payment method here.

[Copilot]

Pull request overview

Adds a work-in-progress planning document that proposes how to introduce a Klicker-owned MCP server (read-only v1 tool surface) and integrate its tool results into the existing chat app, including an iframe-based quiz rendering path and a longer-term headless QuestionCard extraction.

Changes:

• Added a detailed design/roadmap for an apps/mcp-server/ service, including proposed auth/authorization and a v1 tool catalog.
• Documented two chat rendering approaches for quiz/question tool results (iframe embed first, shared component extraction later).
• Outlined phased delivery steps (scaffold → tools → seeding → chat UI glue → deployment).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.