# 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.

```text
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.

```bash
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:

```bash
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`:

```dotenv
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:

```bash
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:

```bash
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:

```bash
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:

```dotenv
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):

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

Local stdio configuration:

```json
{
  "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`:

```json
{
  "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:

```bash
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

```text
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.