Skip to main content
Glama
yungsimeon

knowledge-mcp

by yungsimeon
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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  │
                      └────────────────┘

Related MCP server: Context Lens

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)

This server cannot be installed

A
license - permissive license
-
quality - not tested
C
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
–Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yungsimeon/knowledge-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server