mcp_server_factory by haddock-development - MCP Server

GitHub Auth MCP Server mit PostgreSQL Integration

Ein vollständiger MCP (Model Context Protocol) Server mit GitHub OAuth Authentication, Cloudflare Workers Deployment und realer PostgreSQL-Datenbankanbindung über Supabase.

🚀 Was dieses Projekt kann

GitHub OAuth Authentication: Sichere Benutzerauthentifizierung über GitHub
Device Flow Support: Programmatic Authentication ohne Browser-Interaktion
Cloudflare Workers: Serverless Deployment mit globaler Reichweite
PostgreSQL Integration: Echte Datenbankanbindung über Supabase
MCP Tools: Drei Datenbank-Tools mit Berechtigungsmanagement
TypeScript First: Vollständig in TypeScript implementiert

🛠️ Features

Authentication

OAuth Web Flow: Browser-basierte Authentifizierung
Device Flow: Command-line Authentication mit User Code
Session Management: Sichere Session-Verwaltung über KV Storage
Privileged Users: Rollenbasierte Zugriffssteuerung

Database Tools

listTables: Zeigt alle Datenbanktabellen mit Schema-Informationen
queryDatabase: Führt read-only SQL-Abfragen aus
executeDatabase: Führt write-Abfragen aus (nur für privilegierte Benutzer)

Deployment

Cloudflare Workers: Serverless Hosting
Global Edge Network: Weltweite Verfügbarkeit
Automatic Scaling: Skaliert automatisch mit der Nutzung

📋 Voraussetzungen

Benötigte Accounts

GitHub Account: Für OAuth App Erstellung
Cloudflare Account: Für Workers Deployment
Supabase Account: Für PostgreSQL Hosting

Benötigte Tools

# Node.js und npm
node -v  # >= 18.0.0
npm -v   # >= 8.0.0

# Cloudflare Wrangler
npm install -g wrangler

# Git für Versionskontrolle
git --version

🏗️ Setup Schritt für Schritt

Schritt 1: Repository klonen und vorbereiten

# Repository klonen
git clone <repository-url>
cd mcp_server_factory

# Abhängigkeiten installieren
npm install

Schritt 2: GitHub OAuth App erstellen

GitHub Developer Settings öffnen
- Gehe zu: https://github.com/settings/developers
- Klicke auf "New OAuth App"

OAuth App konfigurieren

App name: GitHub Auth MCP Server
Homepage URL: https://github-auth-mcp-server.deinname.workers.dev
Authorization callback URL: https://github-auth-mcp-server.deinname.workers.dev/auth/callback

Client ID und Secret kopieren
- Client ID: Wird sofort angezeigt
- Client Secret: Klicke auf "Generate a new client secret"

Schritt 3: Cloudflare Workers einrichten

Wrangler einloggen
```
wrangler login
```

Workers Subdomain konfigurieren

# In wrangler.toml anpassen
name = "github-auth-mcp-server"
workers_dev = true

KV Namespace erstellen

wrangler kv namespace create "MCP_SESSIONS"
# Die ID in wrangler.toml eintragen

Schritt 4: Supabase PostgreSQL einrichten

Supabase Projekt erstellen
- Gehe zu: https://supabase.com/dashboard
- Klicke auf "New Project"
- Wähle eine Organisation und erstelle das Projekt
Datenbank-Verbindung details kopieren
- Database Name: Standardmäßig "postgres"
- Host: Unter Project Settings → Database
- Password: Wird bei Erstellung generiert
Service Role Key erstellen
- Gehe zu Project Settings → API
- Unter "Project API keys" → "service_role" kopieren

Schritt 5: Environment Variables konfigurieren

Erstelle .dev.vars im Projektverzeichnis:

# GitHub OAuth
GITHUB_CLIENT_ID=deine_github_client_id
GITHUB_CLIENT_SECRET=dein_github_client_secret

# Session Management
COOKIE_ENCRYPTION_KEY=ein_langer_zufälliger_string_mindestens_32_zeichen

# Database Connection
DATABASE_URL=postgresql://postgres:dein_passwort@dein_host.supabase.co:5432/deine_datenbank
SUPABASE_SERVICE_KEY=dein_supabase_service_role_key

# Privileged Users (komma-getrennt)
PRIVILEGED_USERS=dein_github_username

# Environment
ENVIRONMENT=development

Schritt 6: Deployment

# TypeScript Type-Checking
npm run type-check

# Lokale Entwicklung
npm run dev

# Deployment zu Cloudflare
npm run deploy

🧪 Testing

Health Check

curl https://github-auth-mcp-server.deinname.workers.dev/health

Device Flow Test

# Device Flow initiieren
npx ts-node demo.ts

# User Code und URL werden angezeigt
# Besuche die URL und gib den Code ein

Full Endpoint Test

# Alle Endpunkte testen
npx ts-node tests/test-endpoints.ts

🔧 Konfiguration

TypeScript Konfiguration (`tsconfig.json`)

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "ESNext",
    "lib": ["ES2022"],
    "strict": false,
    "noImplicitAny": false,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true,
    "resolveJsonModule": true,
    "declaration": true,
    "sourceMap": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist", "tests"]
}

Wrangler Konfiguration (`wrangler.toml`)

name = "github-auth-mcp-server"
main = "src/index.ts"
compatibility_date = "2024-01-01"
workers_dev = true

[[kv_namespaces]]
binding = "MCP_SESSIONS"
id = "dein_kv_namespace_id"

🚨 Wichtige Fallstricke und Lösungen

1. TypeScript statt JavaScript für MCP Server

Problem: Viele MCP Tutorials verwenden JavaScript, aber für professionelle Projekte ist TypeScript besser.

Lösung:

Verwende TypeScript für Typsicherheit und bessere Entwicklung
Konfiguriere tsconfig.json mit noImplicitAny: false für Flexibilität
Verwende tsc --noEmit für Type-Checking ohne JavaScript-Generierung

2. Cloudflare Workers kann nicht auf localhost zugreifen

Problem: Lokale PostgreSQL-Datenbanken sind von Cloudflare Workers nicht erreichbar.

Lösung:

Verwende Cloud-PostgreSQL-Anbieter wie Supabase
Supabase bietet externe Verbindungen und ist Cloudflare-kompatibel

3. GitHub OAuth Callback URLs

Problem: OAuth Callback URLs müssen exakt übereinstimmen.

Lösung:

Verwende die korrekte Format: https://dein-subdomain.workers.dev/auth/callback
Teste die Callback URL nach dem Deployment

4. Environment Variables in Production

Problem: Lokale .dev.vars funktionieren nicht in Production.

Lösung:

Konfiguriere Environment Variables im Cloudflare Dashboard
Oder verwende wrangler secret put für sensible Daten

5. Session Management in Serverless

Problem: Serverless Functions sind stateless, benötigen aber Session-Management.

Lösung:

Verwende Cloudflare KV Storage für Sessions
Implementiere Cookie-basierte Session-Verwaltung

6. SQL Injection Protection

Problem: MCP Tools könnten für SQL Injection missbraucht werden.

Lösung:

Implementiere Keyword-Filter für read-only Abfragen
Beschränke write-Operationen auf privilegierte Benutzer

📚 MCP Client Konfiguration

Claude Desktop

{
  "mcpServers": {
    "github-auth-postgres": {
      "command": "npx",
      "args": ["ts-node", "/pfad/zum/projekt/demo.ts"],
      "env": {
        "GITHUB_CLIENT_ID": "deine_client_id",
        "GITHUB_CLIENT_SECRET": "dein_client_secret"
      }
    }
  }
}

VS Code mit MCP Extension

{
  "mcpServers": {
    "github-auth-postgres": {
      "command": "npx",
      "args": ["ts-node", "/pfad/zum/projekt/demo.ts"]
    }
  }
}

🔍 Troubleshooting

Häufige Fehler

"Authentication required"
- Stelle sicher, dass du eine gültige Session hast
- Führe den Device Flow aus und autorisiere die App
"Database connection failed"
- Überprüfe die Supabase Connection Details
- Stelle sicher, dass die Datenbank externe Verbindungen erlaubt
"TypeScript compilation errors"
- Führe npm run type-check aus
- Überprüfe die TypeScript-Konfiguration
"Deployment failed"
- Überprüfe die Wrangler-Konfiguration
- Stelle sicher, dass alle Secrets konfiguriert sind

Debugging

# Lokale Entwicklung mit Debugging
npm run dev

# Logs in Cloudflare Dashboard ansehen
wrangler tail

# TypeScript-Debugging
npx ts-node --inspect demo.ts

🏗️ Projektstruktur

├── src/
│   ├── index.ts                    # Haupt-MCP Server
│   └── device-flow-auth.ts         # Device Flow Implementation
├── tests/
│   ├── test-endpoints.ts          # Endpunkt-Tests
│   ├── test-device-flow-endpoint.ts # Device Flow Tests
│   ├── test-browser-session-tools.ts # Browser Session Tests
│   ├── test-database-tools.ts      # Datenbank-Tool Tests
│   └── test-supabase-postgresql.ts # Supabase Integration Tests
├── demo.ts                        # Demo und Beispiele
├── .dev.vars                      # Environment Variables (dev)
├── wrangler.toml                  # Cloudflare Konfiguration
├── tsconfig.json                  # TypeScript Konfiguration
├── package.json                   # Dependencies und Scripts
└── README.md                      # Diese Datei

🚀 Deployment zu anderen Environments

Staging

wrangler deploy --env staging

Production

wrangler deploy --env production

🤝 Contributing

Fork das Repository
Erstelle einen Feature Branch (git checkout -b feature/amazing-feature)
Commit deine Changes (git commit -m 'Add amazing feature')
Push zum Branch (git push origin feature/amazing-feature)
Öffne ein Pull Request

📄 License

Dieses Projekt ist MIT lizenziert - siehe die Datei für Details.

🙏 Danksagungen

Model Context Protocol (MCP) für das Protocol
Cloudflare Workers für das Serverless Platform
Supabase für die PostgreSQL Integration
GitHub OAuth für die Authentication

📞 Support

Bei Fragen oder Problemen:

Überprüfe die Troubleshooting Sektion
Suche in existing Issues
Erstelle ein neues Issue mit详细的 Beschreibung

Hinweis: Dieses Projekt wurde als Referenzimplementierung für MCP Server mit GitHub Auth und PostgreSQL Integration entwickelt. Es kann als Grundlage für eigene MCP Server-Projekte dienen.

haddock-development/mcp_server_factory

GitHub Auth MCP Server mit PostgreSQL Integration

🚀 Was dieses Projekt kann

🛠️ Features

Authentication

Database Tools

Deployment

📋 Voraussetzungen

Benötigte Accounts

Benötigte Tools

🏗️ Setup Schritt für Schritt

Schritt 1: Repository klonen und vorbereiten

Schritt 2: GitHub OAuth App erstellen

Schritt 3: Cloudflare Workers einrichten

Schritt 4: Supabase PostgreSQL einrichten

Schritt 5: Environment Variables konfigurieren

Schritt 6: Deployment

🧪 Testing

Health Check

Device Flow Test

Full Endpoint Test

🔧 Konfiguration

TypeScript Konfiguration (tsconfig.json)

Wrangler Konfiguration (wrangler.toml)

🚨 Wichtige Fallstricke und Lösungen

1. TypeScript statt JavaScript für MCP Server

2. Cloudflare Workers kann nicht auf localhost zugreifen

3. GitHub OAuth Callback URLs

4. Environment Variables in Production

5. Session Management in Serverless

6. SQL Injection Protection

📚 MCP Client Konfiguration

Claude Desktop

VS Code mit MCP Extension

🔍 Troubleshooting

Häufige Fehler

Debugging

🏗️ Projektstruktur

🚀 Deployment zu anderen Environments

Staging

Production

🤝 Contributing

📄 License

🙏 Danksagungen

📞 Support

TypeScript Konfiguration (`tsconfig.json`)

Wrangler Konfiguration (`wrangler.toml`)