Bildungly Mein NOW MCP

An AI-native Weiterbildung discovery layer over Mein NOW course data. The project keeps source ingestion, the independent Supabase intelligence layer, MCP, and the browser experience separate so the same capabilities can later serve Bildungly, hackathon clients, and partners.

Mein NOW API
    ↓ admin-only background sync
Independent Supabase / Postgres
    ↓ normalized providers, runs, chunks, pgvector + full-text search
MCP server (Streamable HTTP or stdio)
    ├── search_courses
    ├── get_course
    ├── match_courses_for_profile
    └── explain_course_fit
    ↓
Bildungly chat UI / MCP clients / future partners

What is included

• A production-oriented Node/TypeScript MCP server using the stable @modelcontextprotocol/sdk v1 line.
• Stateless Streamable HTTP at POST /mcp, plus a stdio entry point.
• Four narrow domain tools, course:// and provider:// resources, and the recommend_weiterbildung_path prompt.
• A responsive German-first React chat UI with profile context, tool activity, course cards, details, content-level fit evidence, loading, retry, and mobile states.
• An MCP-backed /api/chat host. It uses a deterministic advisor flow, so an LLM key is not required for the MVP; a generative host can be added later without changing the MCP tools.
• An independent Supabase schema with private tables, normalized course runs, content chunks, pgvector HNSW indexes, full-text/trigram indexes, and bounded hybrid-search RPCs.
• Protected Supabase Edge Functions for source sync and gte-small embedding jobs.
• A six-course demo repository that starts automatically until a complete independent Supabase configuration is present.
• Tests for ranking, fit evidence, MCP discovery, structured tool results, resources, and prompts.

Quick start

Requirements: Node.js 20.12 or newer.

npm install
npm run dev

Open http://localhost:5173. The UI proxies its API and MCP requests to the server on http://127.0.0.1:8787.

The existing .env is intentionally ignored by Git. The app safely starts in demo mode whenever the independent Supabase URL or secret is absent. Check the current mode at GET /health.

If you add a project URL before applying the migrations, temporarily set DEMO_MODE=true; live mode expects search_courses_hybrid and the rest of the schema to already exist.

Useful commands:

npm test
npm run typecheck
npm run build
npm start
npm run mcp:stdio

Connect the independent Supabase project

Copy the missing settings from .env.example into .env:

SUPABASE_URL=https://YOUR_PROJECT_REF.supabase.co
SUPABASE_SECRET=sb_secret_your_server_only_key
SYNC_SECRET=a-long-random-machine-to-machine-secret
DEMO_MODE=false

SUPABASE_SECRET and SYNC_SECRET are server-only. Never expose either through Vite variables or browser code.

Apply and deploy the Supabase layer from this repository:

npx supabase link --project-ref YOUR_PROJECT_REF
npx supabase db push
npx supabase secrets set SYNC_SECRET=YOUR_SYNC_SECRET
npx supabase functions deploy sync-courses --no-verify-jwt
npx supabase functions deploy embed-pending --no-verify-jwt

The functions disable gateway JWT verification because they use their own machine-to-machine SYNC_SECRET and fail closed without it. Invoke the source sync without filters or user-supplied keywords:

curl -X POST "https://YOUR_PROJECT_REF.supabase.co/functions/v1/sync-courses" \
  -H "Authorization: Bearer YOUR_SYNC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{}'

Then process pending course embeddings in bounded batches:

curl -X POST "https://YOUR_PROJECT_REF.supabase.co/functions/v1/embed-pending" \
  -H "Authorization: Bearer YOUR_SYNC_SECRET" \
  -H "Content-Type: application/json" \
  -d '{}'

Set EMBED_BATCH_SIZE (1–10) and EMBED_MAX_SECTIONS_PER_COURSE as Edge Function secrets/configuration when you need different bounded worker batches; callers cannot override those limits.

For semantic query vectors, point the Node server at that same protected function:

EMBEDDING_API_URL=https://YOUR_PROJECT_REF.supabase.co/functions/v1/embed-pending

Without EMBEDDING_API_URL, the database RPCs deliberately fall back to full-text/trigram ranking. Indexed course and section embeddings remain ready for semantic search once the query endpoint is configured.

Source sync behavior

The new sync-courses function is deployed into the independent Supabase project. It does not call the old Lovable database or accept public search filters. It:

• crawls a server-owned keyword catalog;
• validates and sanitizes upstream records;
• deduplicates repeated courses across keywords;
• upserts providers and courses using stable source keys;
• normalizes schedules into course_runs, prioritizing future dates;
• stores raw provenance and content hashes;
• marks changed content for re-embedding;
• records partial failures without treating a partial crawl as authoritative deletion.

Before a large production crawl, confirm Mein NOW usage terms and rate limits for scheduled ingestion.

MCP usage

Remote client configuration (exact field names vary by host):

{
  "mcpServers": {
    "bildungly-courses": {
      "url": "http://127.0.0.1:8787/mcp"
    }
  }
}

Local stdio configuration:

{
  "mcpServers": {
    "bildungly-courses": {
      "command": "npm",
      "args": ["run", "mcp:stdio"],
      "cwd": "/absolute/path/to/bildungly-mcp"
    }
  }
}

Set MCP_API_KEY before exposing the HTTP endpoint publicly. Clients then send Authorization: Bearer .... A partner-grade deployment should replace the shared key with MCP OAuth protected-resource metadata.

Tools

Tool	Purpose
search_courses	General hybrid course discovery with bounded, structured constraints.
get_course	Canonical course, provider, schedule, and optional section details.
match_courses_for_profile	Profile-aware ranking with evidence-backed match reasons.
explain_course_fit	Relevant stored sections, gaps, and provider questions; never invents modules.

The server does not expose raw SQL, arbitrary upstream API calls, or public refresh actions.

Resources and prompt

• course://{courseId}
• provider://{providerId}
• recommend_weiterbildung_path

Every tool supplies both MCP structuredContent and a JSON text fallback. All tools are annotated read-only and idempotent.

Chat API

The browser calls POST /api/chat:

{
  "messages": [
    { "role": "user", "content": "Ich möchte als Quereinsteiger Data Analyst werden" }
  ],
  "profile": {
    "goal": "Data Analyst",
    "location": "Berlin",
    "remote": true,
    "language": "de",
    "startTiming": "3_months"
  }
}

The chat host connects to /mcp with the official MCP client, invokes a domain tool, and maps its structured output to cards/evidence. Conversation state stays in the host; the MCP server receives only validated tool arguments.

Security and guidance boundaries

• Supabase tables have RLS enabled and no anon or authenticated policies. Only the server-side secret role can access them.
• Inputs are bounded with Zod, request bodies are size-limited, and /api/chat and /mcp are rate-limited.
• MCP validates allowed hosts/origins to reduce DNS-rebinding exposure. Set ALLOWED_HOSTS and PUBLIC_ORIGIN for deployment.
• Raw HTML from course sources is sanitized before display and embedding.
• Logs include request metadata, not learner profiles or secrets.
• The UI and tools say a course is marked as funding-eligible in source data. They never claim that a learner qualifies; approval remains with Agentur für Arbeit or Jobcenter.

Deployment

Build and run directly with npm run build && npm start, or use the included Dockerfile:

docker build -t bildungly-mcp .
docker run --rm -p 8787:8787 --env-file .env \
  -e ALLOWED_HOSTS=localhost:8787 \
  -e PUBLIC_ORIGIN=http://localhost:8787 \
  bildungly-mcp

For a public host, terminate TLS at the platform, set its public hostname/origin, protect /mcp, and keep the Supabase secret in the platform secret store.

Project layout

src/server/domain/       Course contracts, repositories, ranking and fit evidence
src/server/mcp/          Tools, resources and prompt registration
src/server/chat/         Browser-host MCP client and deterministic orchestration
src/server/http/         HTTP transport, API, security and static UI hosting
src/web/                 React chat UI
supabase/migrations/     Independent catalog, vector search and security
supabase/functions/      Source sync and embedding pipeline

The production MCP wire protocol follows the current stable specification (2025-11-25) and the stable TypeScript SDK v1 line; the SDK v2 line targets a newer, not-yet-stable spec.