docs(project): plan doc-query scoped MCP integration on the KB control plane by rschlaefli · Pull Request #5168 · uzh-bf/klicker-uzh

rschlaefli · 2026-07-13T10:18:07Z

What

Planning-only doc (no code, no migration, no seed change): project/plans_future/PLAN-doc-query-scoped-mcp-integration.md.

Documents how Klicker chatbots will query one shared, deployment-configured doc-query MCP endpoint through a single stable doc_query tool, with tenant isolation carried by a short-lived signed Scope Token (ES256 JWT, kb_id claim) minted per chat request. doc-query verifies the token and injects a mandatory kb_id retrieval filter server-side. The scope unit is the Knowledge Base from PR #5078 (KB/KBResource/KBChatbot), not the chatbot, so re-linking a KB to a different chatbot never triggers re-ingestion.

Why draft

Builds on feat(kb): add knowledge base management control plane #5078 (codex/kb-management-ui → v3-ai, still open) — the KB control plane this plan depends on. Implementation happens off v3-ai after feat(kb): add knowledge base management control plane #5078 merges.
This is the Klicker-side companion to the platform program (mcp-doc-query v3 adapter, now merged to dev; data-ingestion resource API; deployment dynamic workload).
Opened against v3 as a clean single-file planning artifact for review; not for merge until the dependency chain lands.

Scope

1 file, +553 lines, docs only.
Base v3. Full dependency/sequencing, current-state file:line audit, and open questions are in the doc.

Verification

None required — no code. Rendered-markdown review only.

…l plane Klicker-side child plan of the producer-neutral runtime-config umbrella (deployment repo). Builds on PR #5078 (KB management control plane): Scope Token (ES256, kb_id claim) via a new scope_token MCP auth type, follow-up migration for version/digest fences, ingestion API client replacing fire-and-forget webhooks, Source Gateway, upload SAS flow, and KB manager wiring. All open questions ruled 2026-07-12 (documents mode, opaque sub, v3-ai base, client digest, SNIPPET-as-blob).

coderabbitai · 2026-07-13T10:18:16Z

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 1609f708-23c4-4e1b-8b58-0494d284d2ca

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

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

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

greptile-apps · 2026-07-13T10:20:22Z

Confidence Score: 4/5

The planning document needs fixes around URL fetching, stale operation activation, and versioned blob reads before it guides implementation.

Website URL ingestion can fetch lecturer-controlled hosts without an explicit default-deny policy.
Late webhook success for an old operation can advance serving state after a newer desired version exists.
Versioned gateway URLs can read a moving storage pointer instead of immutable per-version content.

project/plans_future/PLAN-doc-query-scoped-mcp-integration.md

Security Review

The Scope Token design removes caller-controlled MCP scope headers, but URL-based website ingestion still needs a mandatory default-deny fetch policy to prevent SSRF-style access to internal hosts.

Important Files Changed

Filename	Overview
project/plans_future/PLAN-doc-query-scoped-mcp-integration.md	Adds the full design plan for KB-scoped doc-query MCP integration; the plan needs tighter URL-fetch, stale-operation, and versioned-blob rules before implementation.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
  participant Chat as Chat request
  participant Klicker as Klicker backend
  participant MCP as doc-query MCP
  participant Ingest as data-ingestion
  participant Gateway as Source Gateway
  Chat->>Klicker: authorized chatbot chat
  Klicker->>Klicker: resolve enabled KB link
  Klicker->>MCP: call doc_query with Scope Token
  MCP->>MCP: verify kb_id and inject filter
  Klicker->>Ingest: submit resource operation
  Ingest->>Gateway: fetch versioned blob URL
  Ingest-->>Klicker: signed status webhook
  Klicker->>Klicker: update operation and serving state

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
  participant Chat as Chat request
  participant Klicker as Klicker backend
  participant MCP as doc-query MCP
  participant Ingest as data-ingestion
  participant Gateway as Source Gateway
  Chat->>Klicker: authorized chatbot chat
  Klicker->>Klicker: resolve enabled KB link
  Klicker->>MCP: call doc_query with Scope Token
  MCP->>MCP: verify kb_id and inject filter
  Klicker->>Ingest: submit resource operation
  Ingest->>Gateway: fetch versioned blob URL
  Ingest-->>Klicker: signed status webhook
  Klicker->>Klicker: update operation and serving state

_{Reviews (1): Last reviewed commit: "docs(project): plan doc-query scoped MCP..." | Re-trigger Greptile}

greptile-apps · 2026-07-13T10:20:27Z

+- Calls (producer-neutral contract from the umbrella plan): create/update →
+  `POST /v1/resources` with `{project_id: "klicker-course-materials", producer: "klicker",
+  external_resource_id: <KBResource.id>, resource_version, scope: {kb_id: <KB.id>},
+  source: {kind, url: <gateway version URL or public URL>, mime_type, display_name},


Website Fetches Lack Guardrails

WEBSITE resources submit a lecturer-provided public URL for ingestion to fetch, but the plan only defines the SSRF restriction for blob sources. A URL like an internal service, link-local address, or redirect to a cluster-local host can be fetched by ingestion unless URL sources also have a mandatory default-deny policy.

Context Used: CLAUDE.md (source)

greptile-apps · 2026-07-13T10:20:27Z

+  - State-machine hardening: duplicate/out-of-order events must not regress terminal state; only
+    a `resource_version` ≥ the current `activeResourceVersion` may advance serving state
+    (`activeResourceVersion`/`activeContentSha256` set on `resource.processing_succeeded`).


Stale Operation Can Activate

The out-of-order guard only compares resource_version with activeResourceVersion. If version 2 is still running, version 3 is submitted, and the version 2 success arrives late, 2 >= 1 can still mark stale content active even though it is no longer the desired operation.

Context Used: CLAUDE.md (source)

greptile-apps · 2026-07-13T10:20:29Z

+- Behavior: stream the exact immutable blob for that resource version (`KBResource.storagePath`)
+  from Azure Blob using the server-side credential (never expose SAS); set `Content-Type`,
+  `Content-Length`, and `ETag: "<contentSha256>"`; 404/410 for unknown, soft-deleted (`deletedAt`),
+  or fenced resources; enforce size cap on read.


Version Route Reads Moving Pointer

The gateway URL includes :version, but the described read uses KBResource.storagePath, a single current pointer. After a replace, a retry for an older /versions/1 URL can stream the newer blob path and let ingestion process the wrong bytes for that operation.

Context Used: CLAUDE.md (source)

greptile-apps Bot reviewed Jul 13, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(project): plan doc-query scoped MCP integration on the KB control plane#5168

docs(project): plan doc-query scoped MCP integration on the KB control plane#5168
rschlaefli wants to merge 1 commit into
v3from
docs/doc-query-scoped-mcp-plan

rschlaefli commented Jul 13, 2026

Uh oh!

coderabbitai Bot commented Jul 13, 2026

Review skipped

Uh oh!

greptile-apps Bot commented Jul 13, 2026

Security Review

Important Files Changed

Uh oh!

greptile-apps Bot Jul 13, 2026

Uh oh!

greptile-apps Bot Jul 13, 2026

Uh oh!

greptile-apps Bot Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

rschlaefli commented Jul 13, 2026

What

Why draft

Scope

Verification

Uh oh!

coderabbitai Bot commented Jul 13, 2026

Review skipped

Uh oh!

greptile-apps Bot commented Jul 13, 2026

Confidence Score: 4/5

Security Review

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps Bot Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

1 participant