Project Hub - Technische Details

Aufbau und Datenhaltung von Project Hub: MCP-Server, SQLite-Datenmodell, Ordnerstruktur, Notiz-Dateien und ihre Synchronisation, Anhänge, Export und Import, HTML-Berichte.

Project Hub - Technische Details

English Version

← Zurück zur Übersicht

Aufbau

Baustein	Beschreibung
Skills	Markdown-Anleitungen unter `skills/`, die Claude als Slash-Befehle ausführt
MCP-Server	Python-Prozess `project-hub-mcp` (stdio), gestartet über `bin/run-server` mit dem Python aus `~/.project-hub/venv`
Datenbank	SQLite-Datei, standardmäßig `~/.project-hub/project-hub.db`
Dateien	Markdown-Notizen und Anhänge unter `docs_root`, Wissensdokumente unter `knowledge_root`

Das Plugin definiert keine Hooks. Der Server initialisiert die Datenbank beim Start und ergänzt fehlende Tabellen und Spalten selbst.

Verzeichnisse

~/.project-hub/
├── config.yaml
├── project-hub.db            (plus -wal und -shm im Betrieb)
├── venv/
├── knowledge/<projekttyp>/*.md
├── project-types/<typ>/      eigene Projekttypen
├── reports/                  HTML-Berichte
└── exports/                  JSON-Exporte

{docs_root}/<projekt-slug>/docs/
├── emails/
├── meeting-notes/
├── misc/
└── attachments/

Datenmodell

Tabelle	Inhalt
`projects`	Slug (eindeutig), Name, Typ, Status, Beschreibung, Markt, Produkte, Phase, Go-Live, Budget, Notizen, Docs-Pfad, Zeitstempel
`contacts`	Projekt, Name, Rolle, Typ (`internal` oder `external`), E-Mail, Telefon, Firma, Notizen, `is_shared`
`notes`	Projekt, Titel, Typ, Inhalt, Agenda, Anhänge (JSON-Liste), Dateipfad, Zeitstempel
`project_links`	Verknüpfungen zwischen zwei Projekten
`session`	genau eine Zeile: aktives Projekt und zuletzt genutzter Skill

Der Slug entsteht aus dem Projektnamen (Kleinbuchstaben, Bindestriche). Zwei Namen mit gleichem Slug sind nicht möglich.
Beim Löschen eines Projekts verschwinden seine Kontakte, Notizen und Verknüpfungen mit. Geteilte Kontakte werden vorher einem anderen Projekt zugeordnet.
Verknüpfungen speichert die Datenbank nur als successor oder related. predecessor ist die umgekehrte Sicht auf ein successor.
Die Sitzungszeile ist global. Sie gilt für alle Claude-Sessions, die dieselbe Datenbank benutzen.

Notizen: Datenbank und Datei

Beim Anlegen einer Notiz schreibt der Server den Text in die Datenbank und zusätzlich als Markdown-Datei in den Docs-Ordner des Projekts:

Notiztyp	Zielordner	Datei
`meeting-notes`	`meeting-notes/`	`<datum>-<titel-slug>.md`
`email`	`emails/`	`<datum>-<titel-slug>.md`
`decision`, `note`	`misc/`	`<datum>-<titel-slug>.md`
`action-item`	`misc/`	Eintrag in der gemeinsamen Datei `todo.md` unter "Open"

Die Datenbank ist die führende Quelle:

Änderungen über tool_update_note (und damit edit-note) schreiben nur in die Datenbank. Die Markdown-Datei behält den alten Titel, Inhalt und Unterordner.
Das Löschen einer Notiz entfernt die zugehörige Datei, außer bei action-item, weil todo.md mehrere Aufgaben enthält.
Der Dateiname ergibt sich aus Zielordner, Datum und Titel-Slug, nicht aus dem Notiztyp. Zwei Notizen mit gleichem Titel am selben Tag landen im selben Ordner und überschreiben einander, auch wenn die Typen verschieden sind: eine note und eine decision teilen sich misc/. Der Titel-Slug wird auf 50 Zeichen gekürzt, sodass auch verschiedene, lange Titel mit gleichem Anfang kollidieren können. Die Datenbank hält in allen Fällen beide Notizen. Ein Datum oder ein eindeutiger Zusatz am Anfang des Titels vermeidet das.
Berichte, Suche und Skills lesen aus der Datenbank, nicht aus den Dateien.

Anhänge

Die Kopie liegt unter {docs_root}/<slug>/docs/attachments/. Das Original bleibt unverändert.
Der Anhang steht als JSON-Eintrag mit Name, Pfad und Größe bei der Notiz.
Beim Löschen einer Notiz bleiben ihre Anhangsdateien im Ordner liegen.
tool_add_note mit source_paths sichert die Originale im selben Aufruf, damit referenzierte Dateien nicht verloren gehen.

Export und Import

Der Export (compose export) ist eine JSON-Datei mit Projekt, Kontakten, Notizen und Verknüpfungen (Verknüpfungen über den Slug des anderen Projekts).

Anhangsdateien und Notiz-Markdown-Dateien sind nicht Teil des Exports.
Die Notizzeilen enthalten das Anhangsfeld unverändert, die Einträge verweisen also auf Pfade des Quellrechners.
Beim Import entsteht ein neuer Docs-Ordner. Verknüpfungen stellt der Import nur her, wenn das verknüpfte Projekt in der Zieldatenbank bereits existiert, sonst erscheinen sie unter "nicht wiederhergestellt".
rename hängt dem Slug einen Zeitstempel an. overwrite löscht das vorhandene Projekt vollständig, auch seinen Docs-Ordner mit Notiz-Markdown-Dateien und Anhängen auf der Festplatte, und legt es neu an.

HTML-Berichte

Der Bericht ist eine einzelne HTML-Datei, erzeugt aus einer Jinja2-Vorlage. Die Diagramme lädt die Datei beim Öffnen im Browser von cdn.jsdelivr.net (Chart.js). Ohne Internetverbindung fehlt diese Bibliothek. Die Beschriftungen sind deutsch. Der Abschnitt "Offene Aufgaben" enthält alle Notizen vom Typ action-item, ohne Erledigt-Filter.

Suche

Die Suche ist eine einfache Teilstring-Suche (SQL LIKE) ohne Index und ohne Ranking. Groß- und Kleinschreibung wird nur für ASCII-Buchstaben ignoriert, Umlaute werden exakt verglichen. % und _ im Suchbegriff wirken als Platzhalter. Notizen kommen neueste zuerst, Kontakte nach Name sortiert.