Knowledge MCP

Hinweis: Dieses Repository ist ein eigenständiger Demo-Aufbau. Das produktive System, das ich bei meinem aktuellen Arbeitgeber (Hydra Software GmbH) entwickelt und betrieben habe, kann ich aus Vertraulichkeitsgründen (NDA) nicht teilen. Dieses Projekt bildet dieselbe Architektur verinfacht nach — MCP-Server mit OAuth, RAG-Pipeline über pgvector, Playwright-Crawler und GitHub-Actions-Sync — ist jedoch vollständig neu gebaut und enthält keine proprietären Inhalte.

Damit ihr die Suche direkt ausprobieren könnt, habe ich Supabase-URL und publishable Key in der .env.example hinterlegt. Die Datenbank enthält bereits einige Demo-Einträge — das Frontend funktioniert damit out of the box. Um selbst Dokumentationen zu crawlen, Embeddings zu generieren und in eine eigene Datenbank einzufügen, braucht ihr einen eigenen Google API Key sowie ein eigenes Supabase-Projekt.

Ein Model Context Protocol-Server, der Cursor (oder jedem anderen MCP-Client) semantische Suche über eine private Wissensdatenbank ermöglicht — authentifiziert via GitHub OAuth und gespeichert in Supabase pgvector.

Architektur

┌─────────────────────────────────────────────────────────────────────┐
│                         Cursor / IDE                                │
│                      (MCP Client, JSON-RPC)                         │
└──────────────────┬──────────────────────────┬───────────────────────┘
                   │                          │
        1. install deeplink          3. tool calls
        (cursor:// URI)              (Bearer token)
                   │                          │
                   ▼                          ▼
   ┌───────────────────────┐    ┌─────────────────────────────────┐
   │      Web App          │    │          MCP Server             │
   │     (Next.js)         │    │        (Node.js / TS)           │
   │                       │    │                                 │
   │  /install/mcp         │    │  search_knowledge(query)        │
   │  /auth/mcp ───────────┤    │  list_topics()                  │
   │    GitHub OAuth       │    │  get_entry(content_id)          │
   │    Supabase session   │    │  search_by_tag(tags)            │
   │                       │    │                                 │
   │  2. access_token ─────┼───►│  ● Rate limit: 60 req/min      │
   └───────────────────────┘    │  ● Auth: Supabase JWT verify   │
                                │  ● Input: Zod-Schemas          │
                                │  ● Sessions: In-Memory-Map     │
                                └──────────────┬──────────────────┘
                                               │
                               ┌───────────────┴───────────────┐
                               │                               │
                      ┌────────▼────────┐           ┌──────────▼────────┐
                      │    pgvector     │           │   mcp_usage_logs  │
                      │   (Supabase)    │           │   (Analytics)     │
                      │                │           └───────────────────-┘
                      │  1536-dim       │
                      │  Gemini-Embeds  │
                      │  Cosine-Search  │
                      └────────────────┘

Datenpipeline

  Dokumentationsseite         dataset.jsonl            Supabase pgvector
  ───────────────────         ─────────────            ─────────────────
       (beliebige URL)
           │                       │                          │
           │   scripts/crawl.py    │   scripts/embed.py       │
           │   ─────────────────►  │   ──────────────────►    │
           │   Playwright          │   Gemini-Embedding        │
           │   extrahiert Inhalt   │   LLM-Titel/Summary       │
           │   dedupliziert URLs   │   Upsert bei Konflikt     │
                                                        ▲
                                           GitHub Actions Cron
                                           (täglich @ 03:00 UTC)
                                           oder manueller Dispatch

MCP-Tools

Tool	Beschreibung
list_topics	Überblick über die Wissensdatenbank — Inhaltstypen, Anzahl, häufigste Tags. Sinnvoll als erster Aufruf zur Orientierung.
search_knowledge	Semantische Vektorsuche. Natürlichsprachliche Anfrage → Cosine-Similarity → progressiver Threshold-Fallback (0.7 → 0.6 → 0.5 → 0.0).
get_entry	Einzelnen Eintrag per content_id abrufen. Spart einen zweiten Embedding-Aufruf nach search_knowledge.
search_by_tag	Exakter Tag-Filter — schneller und präziser als semantische Suche, wenn der Tag bereits bekannt ist.

Sicherheit

• Auth: Jeder Tool-Aufruf erfordert ein gültiges Supabase-JWT, das serverseitig via auth.getUser() geprüft wird — nicht über den clientseitigen Session-Cache
• Rate Limiting: 60 Anfragen / Minute pro Nutzer, in-memory mit automatischem Bereinigen abgelaufener Einträge
• Input-Validierung: Zod-Schemas auf allen Tool-Inputs — max. 500 Zeichen Query, max. 10 Ergebnisse, content_id-Allowlist-Regex mit Path-Traversal-Schutz
• Content-Trimming: Antworten werden auf 3.000 Zeichen begrenzt, um Datendumps zu verhindern
• Enumeration-Schutz: get_entry gibt bei fehlendem und bei nicht authorisiertem Zugriff dieselbe Meldung zurück
• Payload-Größe: Express Body-Parser auf 64 KB begrenzt
• SDK-Workaround: Das MCP-SDK lässt /.well-known/oauth-protected-resource weg — manuell ergänzt, damit Cursor den korrekten WWW-Authenticate-Header aufbaut

Quick Start

1. Supabase einrichten

-- pgvector aktivieren
create extension if not exists vector;

-- Wissensdatenbank-Tabelle
create table embeddings (
  content_id   text primary key,
  content_type text not null,
  title        text not null,
  summary      text,
  content      text,
  tags         text[],
  provider     text,
  metadata     jsonb,
  embedding    vector(1536)
);

-- Ähnlichkeitssuche-Funktion
create function match_embeddings(
  query_embedding vector,
  match_threshold float,
  match_count     int
) returns table (
  content_id   text,
  content_type text,
  title        text,
  summary      text,
  content      text,
  tags         text[],
  provider     text,
  metadata     jsonb,
  similarity   float
) language sql stable as $$
  select
    content_id, content_type, title, summary, content, tags, provider, metadata,
    1 - (embedding <=> query_embedding) as similarity
  from embeddings
  where 1 - (embedding <=> query_embedding) > match_threshold
  order by similarity desc
  limit match_count;
$$;

-- Analytics-Tabelle
create table mcp_usage_logs (
  id                bigserial primary key,
  user_id           uuid references auth.users,
  github_handle     text,
  tool_name         text,
  query             text,
  result_count      int,
  execution_time_ms int,
  session_id        uuid,
  success           boolean,
  error_message     text,
  created_at        timestamptz default now()
);

2. Umgebungsvariablen konfigurieren

cp .env.example .env
# SUPABASE_SERVICE_ROLE_KEY, GOOGLE_API_KEY, AUTH_DOMAIN und SERVER_URL eintragen
# NEXT_PUBLIC_SUPABASE_URL und NEXT_PUBLIC_SUPABASE_ANON_KEY sind bereits gesetzt

3. Lokal starten

# MCP-Server
pnpm dev:server

# Web-App (separates Terminal)
pnpm dev:web

4. Wissensdatenbank befüllen

Erfordert einen eigenen Google API Key und ein eigenes Supabase-Projekt (Service Role Key).

cd scripts
pip install -r requirements.txt
playwright install chromium

# Crawlen, einbetten und in Supabase einfügen — alles in einem Schritt
python crawl.py https://eure-docs-seite.com --depth 3

# Nur neu einbetten, ohne erneut zu crawlen
python embed.py --force

5. In Cursor installieren

Web-App öffnen unter http://localhost:3000/install/mcp und auf Open in Cursor klicken, oder manuell konfigurieren:

{
  "mcpServers": {
    "knowledge-mcp": {
      "url": "http://localhost:3001/mcp"
    }
  }
}

Tests

pnpm test

Läuft Vitest (TypeScript, 20 Tests) und pytest (Python, 18 Tests) in einem Schritt.

Deployment

Der MCP-Server ist eine zustandslose Express-App — läuft überall, wo Docker unterstützt wird:

docker build -t knowledge-mcp ./server
docker run -p 3000:3000 --env-file .env knowledge-mcp

Die Web-App ist eine Standard-Next.js-App — Deployment auf Vercel, Fly oder jedem anderen Node-Host.

Automatischer Sync (GitHub Actions)

SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY und GOOGLE_API_KEY als Repository-Secrets hinterlegen. Der Workflow unter .github/workflows/sync-docs.yml läuft täglich und kann auch manuell mit einer beliebigen URL ausgelöst werden.

Stack

Schicht	Technologie
MCP-Server	Node.js 22, TypeScript, Express, @modelcontextprotocol/sdk
Web-App	Next.js 15 (App Router), React 19, Tailwind CSS 4
Auth	Supabase Auth + GitHub OAuth, PKCE
Vektordatenbank	Supabase pgvector (1536-dim Gemini-Embeddings)
Crawler	Python 3.11, Playwright, BeautifulSoup
CI/CD	GitHub Actions (täglicher Cron + manueller Dispatch)