# 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](https://modelcontextprotocol.io)-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

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

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

```bash
# 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).

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

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

## Tests

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

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