@heptabase/mcp

Ein Model Context Protocol (MCP)-Dienst für die Interaktion mit Heptabase-Sicherungsdaten. Dieser Dienst ermöglicht KI-Assistenten wie Claude das Suchen, Abrufen, Analysieren und Exportieren von Heptabase-Whiteboards und -Karten.

Merkmale

🔍 Suche nach Whiteboards und Karten
📁 Automatische Verwaltung von Sicherungsdateien
📄 Export in mehrere Formate (Markdown, JSON, Mermaid)
🔗 Kartenbeziehungen analysieren
📊 Whiteboard-Zusammenfassungen erstellen
⚡ Intelligentes Caching für mehr Leistung

Related MCP server: Supabase MCP Server

Schnellstart

Installation und Einrichtung

Klonen und installieren:
git clone <repository-url> cd heptabase-mcp npm install
Konfigurieren Sie mithilfe von Umgebungsvariablen:
cp .env.example .env # Edit .env with your actual paths
Erstellen Sie das Projekt:
npm run build
Lokal testen (optional):
npm start

Verwendung mit Claude Desktop

Konfigurieren Sie Claude Desktop für die Verwendung Ihres lokalen Builds:

Bearbeiten Sie Ihre Claude Desktop-Konfigurationsdatei:

macOS : ~/Library/Application\ Support/Claude/claude_desktop_config.json
Windows : %APPDATA%\Claude\claude_desktop_config.json
Linux : ~/.config/Claude/claude_desktop_config.json

Fügen Sie diese Konfiguration hinzu:

{ "mcpServers": { "heptabase": { "command": "/path/to/node", "args": ["/path/to/your/heptabase-mcp/dist/index.js"], "env": { "HEPTABASE_BACKUP_PATH": "/path/to/your/heptabase/backups", "HEPTABASE_AUTO_EXTRACT": "true", "HEPTABASE_WATCH_DIRECTORY": "true" } } } }

Wichtig:

Ersetzen Sie /path/to/node durch Ihren Node.js-Pfad (finden Sie heraus, mit which node ).
Ersetzen Sie /path/to/your/heptabase-mcp durch Ihren tatsächlichen Projektpfad
Legen Sie HEPTABASE_BACKUP_PATH auf Ihr Heptabase-Sicherungsverzeichnis fest

Ausführliche Einrichtungsanweisungen finden Sie in QUICK_START.md .

Konfiguration

Dieses Projekt verwendet ein datenschutzsicheres Konfigurationssystem:

Beispieldateien (sicher für Git): claude-config-example.json , .env.example
Persönliche Dateien (gitignored): claude-config-*personal*.json , .env

Ausführliche Konfigurationsanweisungen finden Sie in CONFIG.md .

Grundlegende Verwendung

// Configure backup path await mcpClient.callTool({ name: "configureBackupPath", parameters: { path: "/path/to/your/heptabase/backups" } }); // List available backups const backups = await mcpClient.callTool({ name: "listBackups" }); // Search for whiteboards const whiteboards = await mcpClient.callTool({ name: "searchWhiteboards", parameters: { query: "Project Planning" } }); // Get full whiteboard content const whiteboard = await mcpClient.callTool({ name: "getWhiteboard", parameters: { whiteboardId: "your-whiteboard-id", includeCards: true, includeConnections: true } }); // Export to markdown const markdown = await mcpClient.callTool({ name: "exportWhiteboard", parameters: { whiteboardId: "your-whiteboard-id", format: "markdown" } });

Verfügbare Tools

Sicherungsverwaltung

configureBackupPath - Sicherungsverzeichnis festlegen
listBackups – Listet verfügbare Backups auf
loadBackup - Ein bestimmtes Backup laden

Suchvorgänge

searchWhiteboards – Whiteboards nach Namen oder Inhalt durchsuchen
searchCards – Kartensuche auf allen Whiteboards

Datenabruf

getWhiteboard - Vollständige Whiteboard-Daten abrufen
getCard - Karteninhalte in mehreren Formaten abrufen
getCardContent – Karteninhalt als Ressource abrufen (umgeht Größenbeschränkungen)
getCardsByArea – Karten nach Position auf dem Whiteboard finden

Exportfunktionen

exportWhiteboard – Exportieren in die Formate Markdown, JSON, HTML
summarizeWhiteboard – KI-gestützte Zusammenfassungen generieren

Analysetools

analyzeGraph - Kartenbeziehungen und -verbindungen analysieren
compareBackups - Vergleichen Sie verschiedene Backup-Versionen

Debug-Tools

debugInfo - Systemstatus und Diagnose abrufen

Entwicklung

Projektstruktur

heptabase-mcp/ ├── src/ │ ├── index.ts # Main entry point │ ├── server.ts # MCP server implementation │ ├── services/ # Core business logic │ │ ├── BackupManager.ts # Backup file management │ │ └── HeptabaseDataService.ts # Data querying │ ├── tools/ # MCP tool implementations │ ├── types/ # TypeScript definitions │ └── utils/ # Helper functions ├── tests/ # Test suites ├── docs/ # Documentation └── config files # Configuration templates

Testen

# Run all tests npm test # Run tests in watch mode npm run test:watch # Run with coverage npm run test:coverage # Run integration tests npm run test:integration

Gebäude

# Build for production npm run build # Development mode with auto-reload npm run dev # Type checking only npm run type-check

Dokumentation

📚 Vollständige Spezifikation – Detaillierte API und Architektur
🚀 Kurzanleitung – Schnell einsatzbereit
⚙️ Konfigurationshandbuch – Sichere Konfigurationspraktiken
📖 Claude Desktop Setup - Lokales Entwicklungs-Setup

Datenschutz & Sicherheit

Dieses Projekt folgt den Grundsätzen des „Privacy-by-Design“:

✅ Persönliche Pfade werden nie an Git übergeben
✅ Backup-Daten bleiben lokal auf Ihrem Computer
✅ Konfigurationsvorlagen verwenden sichere Platzhalter
✅ Gitignore schützt sensible Dateien

Anforderungen

Node.js 18+
Heptabase mit aktivierten Backup-Exporten
Claude Desktop (für MCP-Integration)

Fehlerbehebung

Häufige Probleme

"Keine Backups gefunden" - Überprüfen Sie, ob Ihr HEPTABASE_BACKUP_PATH auf das richtige Verzeichnis verweist
„Befehl nicht gefunden“ – Stellen Sie sicher, dass Node.js installiert ist und die Pfade korrekt sind
Claude sieht keine Tools - Starten Sie Claude Desktop nach Konfigurationsänderungen vollständig neu
Build-Fehler - Führen Sie npm install und npm run build bevor Sie

Debug-Modus

Verwenden Sie das Tool debugInfo , um den Systemstatus zu überprüfen:

await mcpClient.callTool({ name: "debugInfo" });

Beitragen

Beiträge sind willkommen! Bitte:

Forken Sie das Repository
Erstellen eines Feature-Zweigs
Nehmen Sie Ihre Änderungen vor
Fügen Sie Tests für neue Funktionen hinzu
Stellen Sie sicher, dass alle Tests erfolgreich sind
Senden einer Pull-Anfrage

Architekturdetails finden Sie in SPECIFICATION.md .

Lizenz

MIT-Lizenz – Einzelheiten finden Sie in der Datei LICENSE .

Unterstützung

🐛 Fehlerberichte : GitHub-Probleme
💬 Fragen : GitHub-Diskussionen
📧 Sicherheitsprobleme : Bitte privat melden

Mit ❤️ für die Heptabase-Community erstellt

Heptabase MCP