@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