MCP Server

Model Context Protocol Server für Mapfolio - Ermöglicht KI-Assistenten die Interaktion mit Mapfolio-Daten

Übersicht

Der Mapfolio MCP Server ist ein Model Context Protocol (MCP) Server, der KI-Assistenten und anderen MCP-kompatiblen Clients ermöglicht, mit Mapfolios Daten und Operationen zu interagieren. Er bietet programmatischen Zugriff auf Unternehmen, Projekte, Benutzer, LinkedIn-Profile und administrative Funktionen.

Was ist MCP?

Model Context Protocol (MCP) ist ein offenes Protokoll, das KI-Assistenten ermöglicht, sicher auf externe Datenquellen und Tools zuzugreifen. MCP-Server stellen Funktionen über eine standardisierte Schnittstelle bereit, die es KI-Assistenten ermöglicht:

  • Daten abzufragen und abzurufen
  • Operationen durchzuführen
  • Auf Ressourcen zuzugreifen
  • Mit externen Systemen zu integrieren

Funktionen

Der Mapfolio MCP Server bietet umfassende Funktionalität:

Unternehmensdaten

  • Unternehmen mit erweiterten Filtern suchen
  • Unternehmensdetails nach ID abrufen
  • Unternehmen nach Kanton und Anfangsbuchstaben abrufen
  • Zufällige Unternehmen für Stichproben abrufen
  • Zugriff auf Unternehmensbesuchsstatistiken

Projektverwaltung

  • Projekte erstellen und verwalten
  • Benutzerprojekte auflisten und filtern
  • Projektdetails aktualisieren
  • Projekte löschen
  • Unternehmen zu Projekten hinzufügen und entfernen

Benutzerprofile

  • Benutzerprofilinformationen abrufen
  • Profileinstellungen aktualisieren
  • Benutzerprojekte auflisten
  • API-Schlüssel verwalten

LinkedIn-Integration

  • LinkedIn-Profil Daten abrufen
  • LinkedIn-Profile suchen
  • Zugriff auf Verbindungsinformationen
  • Profilversionsverlauf anzeigen
  • LinkedIn-Unternehmensdaten abrufen

Administrative Operationen

  • Alle Benutzer auflisten (nur Admin)
  • Neue Benutzer erstellen (nur Admin)
  • API-Schlüssel verwalten (nur Admin)
  • Zugriff auf Admin-Dashboard-Statistiken

Statistiken

  • Aggregierte Unternehmensstatistiken abrufen
  • Kantonsbezogene Zählungen anzeigen
  • Zugriff auf buchstabenbasierte Zählungen
  • Zwei-Buchstaben-Kombinationsstatistiken abrufen

Installation

Voraussetzungen

  • Node.js >= 20.0.0
  • npm >= 10.0.0
  • Zugriff auf Mapfolio Supabase-Instanz

Einrichtung

  1. Abhängigkeiten installieren:
cd mcp-server
npm install
  1. Umgebungsvariablen konfigurieren:
cp .env.example .env

Bearbeiten Sie .env und konfigurieren Sie:

# Mapfolio API URL (Standard: https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# Transporttyp: 'stdio' (Standard) oder 'http' für Remote-Zugriff
MCP_TRANSPORT=stdio

# HTTP-Port (nur verwendet, wenn MCP_TRANSPORT=http)
MCP_HTTP_PORT=3001

# Optional: Standard-Authentifizierung (kann über MCP-Kontext oder HTTP-Header bereitgestellt werden)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here
  1. Server erstellen:
npm run build

Verwendung

Server starten

Lokale Entwicklung (stdio Transport)

Der MCP-Server verwendet standardmäßig stdio Transport (Standard MCP-Protokoll):

npm start

Für Entwicklung mit Auto-Reload:

npm run dev

HTTP Transport (für Remote-Zugriff)

Um den Server mit HTTP Transport für lokale Tests zu starten:

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

Dies startet einen HTTP-Server auf Port 3001, der JSON-RPC 2.0-Anfragen über HTTP POST akzeptiert.

Vercel Deployment (Remote-Zugriff)

Der MCP-Server ist automatisch über HTTP verfügbar, wenn er auf Vercel bereitgestellt wird:

  • Endpoint: https://your-app.vercel.app/api/mcp
  • Protokoll: JSON-RPC 2.0 über HTTP POST
  • Authentifizierung: Über X-API-Key Header oder Authorization: Bearer <token> Header

Beispielanfrage:

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mapf_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

MCP Client Konfiguration

Claude Desktop

Lokale Bereitstellung:

{
  "mcpServers": {
    "mapfolio": {
      "command": "node",
      "args": ["/path/to/mapfolio/mcp-server/dist/index.js"],
      "env": {
        "MAPFOLIO_API_URL": "https://mapfolio.app",
        "MAPFOLIO_API_KEY": "mapf_your_api_key_here"
      }
    }
  }
}

Cursor

Konfigurieren Sie über MCP-Einstellungen:

  • Befehl: node
  • Args: ["/path/to/mapfolio/mcp-server/dist/index.js"]
  • Umgebungsvariablen:
    • MAPFOLIO_API_URL: https://mapfolio.app
    • MAPFOLIO_API_KEY: Ihr API-Schlüssel (optional)

Authentifizierung

Der Server unterstützt zwei Authentifizierungsmethoden:

API-Schlüssel-Authentifizierung

API-Schlüssel sind mit mapf_ vorangestellt und können:

  • Über die Umgebungsvariable MAPFOLIO_API_KEY gesetzt werden
  • Pro-Anfrage über den Parameter apiKey in Tool-Aufrufen übergeben werden

JWT-Token-Authentifizierung

Supabase JWT-Token können:

  • Über die Umgebungsvariable MAPFOLIO_JWT_TOKEN gesetzt werden
  • Pro-Anfrage über den Parameter jwtToken in Tool-Aufrufen übergeben werden

Authentifizierungspriorität

  1. HTTP Transport: Header (X-API-Key oder Authorization) haben Vorrang
  2. Pro-Anfrage-Anmeldedaten (apiKey oder jwtToken in Tool-Argumenten)
  3. Umgebungsvariablen (MAPFOLIO_API_KEY oder MAPFOLIO_JWT_TOKEN)

HTTP Transport Authentifizierung

Bei Verwendung des HTTP-Endpunkts (/api/mcp) wird die Authentifizierung über HTTP-Header bereitgestellt:

  • API-Schlüssel: X-API-Key: mapf_your_api_key
  • JWT-Token: Authorization: Bearer your_jwt_token

Verfügbare Tools

Der Server bietet 30+ Tools in 6 Kategorien:

Unternehmens-Tools

  • search_companies - Suche mit Filtern
  • get_company - Unternehmen nach ID abrufen
  • get_companies_by_canton_letter - Nach Kanton und Buchstabe abrufen
  • get_random_companies - Zufällige Stichproben abrufen
  • get_company_visits - Besuchsstatistiken abrufen

Projekt-Tools

  • create_project - Neues Projekt erstellen
  • list_projects - Benutzerprojekte auflisten
  • get_project - Projektdetails abrufen
  • update_project - Projekt aktualisieren
  • delete_project - Projekt löschen
  • add_companies_to_project - Unternehmen hinzufügen
  • remove_companies_from_project - Unternehmen entfernen

Benutzer-Tools

  • get_user_profile - Profil abrufen
  • update_user_profile - Profil aktualisieren
  • get_user_projects - Projekte auflisten
  • get_user_api_keys - API-Schlüssel auflisten

LinkedIn-Tools

  • get_linkedin_profile - Profil abrufen
  • search_linkedin_profiles - Profile suchen
  • get_linkedin_connections - Verbindungen abrufen
  • get_linkedin_profile_versions - Versionsverlauf abrufen
  • get_linkedin_companies - Unternehmensdaten abrufen

Admin-Tools (nur Admin)

  • list_all_users - Alle Benutzer auflisten
  • create_user - Benutzer erstellen
  • get_user_details - Benutzerdetails abrufen
  • list_api_keys - Alle API-Schlüssel auflisten
  • create_api_key - API-Schlüssel erstellen
  • revoke_api_key - API-Schlüssel widerrufen
  • get_admin_stats - Admin-Statistiken abrufen

Statistik-Tools

  • get_company_stats - Aggregierte Statistiken abrufen
  • get_canton_counts - Kantonszählungen abrufen
  • get_letter_counts - Buchstabenzählungen abrufen
  • get_two_letter_counts - Zwei-Buchstaben-Zählungen abrufen

Ressourcen

Der Server bietet ressourcenbasierten Zugriff:

  • mapfolio://company/{id} - Unternehmensdaten
  • mapfolio://project/{id} - Projektdaten
  • mapfolio://user/{id} - Benutzerprofil
  • mapfolio://linkedin-profile/{id} - LinkedIn-Profil

Ressourcen können Authentifizierung über Abfrageparameter enthalten:

  • mapfolio://company/{id}?apiKey=mapf_...
  • mapfolio://company/{id}?jwtToken=...

Beispielverwendung

Unternehmen suchen

{
  "tool": "search_companies",
  "arguments": {
    "query": "technology",
    "cantons": ["ZH", "BE"],
    "page": 1,
    "limit": 20
  }
}

Projekt erstellen

{
  "tool": "create_project",
  "arguments": {
    "name": "Tech Companies Zurich",
    "searchType": "company",
    "searchQuery": "technology",
    "isPublic": false
  }
}

Unternehmensdetails abrufen

{
  "tool": "get_company",
  "arguments": {
    "companyId": "company-uuid-here"
  }
}

Fehlerbehandlung

Alle Tools geben Fehler in einem konsistenten Format zurück:

{
  "error": "Fehlermeldung"
}

Häufige Fehlerszenarien:

  • 401 Unauthorized: Ungültige oder fehlende Authentifizierung
  • 403 Forbidden: Unzureichende Berechtigungen
  • 404 Not Found: Ressource nicht gefunden
  • 500 Internal Server Error: Server-seitiger Fehler

API-Only Architektur

Der MCP-Server verwendet HTTP-Anfragen an mapfolio.app anstelle von direktem Datenbankzugriff. Das bedeutet:

  • ✅ Keine Supabase-Anmeldedaten erforderlich - Funktioniert nur mit API-URL und API-Schlüssel
  • ✅ Einfaches Vercel Deployment - Als Serverless-Funktion bereitstellen
  • ✅ Sicher - Alle Anfragen gehen über Mapfolios API mit Authentifizierung
  • ✅ Skalierbar - Nutzt Mapfolios API-Rate-Limiting und Caching

Derzeit über API verfügbar

  • ✅ Unternehmenssuche und -abruf
  • ✅ Unternehmensstatistiken (Kantonszählungen, Buchstabenzählungen)
  • ✅ Zufällige Unternehmen
  • ✅ Unternehmensbesuche

Kommt bald (erfordert API-Endpunkte)

  • ⏳ Projektverwaltung (erstellen, auflisten, aktualisieren, löschen)
  • ⏳ Benutzerprofilverwaltung
  • ⏳ LinkedIn-Profilzugriff
  • ⏳ Admin-Operationen

Diese Funktionen geben hilfreiche Fehlermeldungen zurück, bis die API-Endpunkte erstellt sind.

Sicherheitsüberlegungen

  1. API-Schlüssel: Sicher speichern, niemals in Versionskontrolle committen
  2. JWT-Token: Token laufen ab, Refresh angemessen handhaben
  3. API-Rate-Limiting: Respektiert Mapfolios API-Rate-Limits
  4. Nur HTTPS: Immer HTTPS für API-Anfragen verwenden
  5. Admin-Operationen: Erfordern explizite Admin-Authentifizierung (wenn Endpunkte verfügbar sind)

Entwicklung

Typprüfung

npm run type-check

Erstellen

npm run build

Entwicklungsmodus

npm run dev

Dokumentation

Für vollständige Dokumentation siehe MCP Server README.

Support

Bei Problemen oder Fragen:

Lizenz

MIT