# Zettelkasten MCP Server

Dieses Repository implementiert einen **Model Context Protocol (MCP) Server**, der als Brücke zwischen **Claude Desktop / Claude Code** und deinem Zettelkasten (basierend auf [tools4zettelkasten](https://github.com/rreben/tools4zettelkasten)) fungiert.

### Warum dieser MCP Server?

Die Bibliothek `tools4zettelkasten` bietet mächtige Python-Werkzeuge zur Verwaltung eines Zettelkastens (Dateinamen-Logik, Strukturen, Links). Dieser MCP Server macht diese Werkzeuge für KI-Assistenten wie Claude zugänglich.

**Der Nutzen:**
*   **Direkter Zugriff:** Claude kann deinen Zettelkasten nicht nur "sehen" (als Dateien), sondern *versteht* die Struktur (Verwandte Zettel, Hierarchien).
*   **Sichere Manipulation:** Statt dass die KI versucht, Dateien 'blind' umzubenennen, nutzt sie die getestete Logik der Bibliothek, um konsistente Dateinamen und IDs zu erzeugen.
*   **Komplexe Analysen:** Claude kann Fragen beantworten wie "Welche Themen hängen damit zusammen?", indem es die Graphen-Analyse der Bibliothek nutzt.

## Architektur

```
┌─────────────────────────────────────────────────────────────┐
│                 Claude Desktop / Claude Code                │
└─────────────────────┬───────────────────────────────────────┘
                      │ stdio (JSON-RPC)
                      ▼
┌─────────────────────────────────────────────────────────────┐
│                 zettelkasten_mcp/server.py                  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │  MCP Protocol Handler (FastMCP)                       │  │
│  └───────────────────────────────────────────────────────┘  │
│                          │                                  │
│  ┌───────────────────────▼───────────────────────────────┐  │
│  │  12 Tools                                             │  │
│  │  • list_input_files    • search_zettel                │  │
│  │  • stage_file          • get_zettel                   │  │
│  │  • preview_staging     • list_zettel                  │  │
│  │  • get_statistics      • get_links                    │  │
│  │  • find_related        • analyze_structure            │  │
│  │  • preview_reorganize  • execute_reorganize           │  │
│  └───────────────────────────────────────────────────────┘  │
│                          │                                  │
│  ┌───────────────────────▼───────────────────────────────┐  │
│  │  tools4zettelkasten (importlib)                       │  │
│  │  • persistency.PersistencyManager                     │  │
│  │  • handle_filenames                                   │  │
│  │  • reorganize                                         │  │
│  │  • analyse                                            │  │
│  └───────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
                          │
                          ▼
        ┌─────────────────────────────────────┐
        │  ~/Dropbox/zettelkasten/            │
        │  ├── mycelium/  (567 Zettel)        │
        │  └── input/     (neue Notizen)      │
        └─────────────────────────────────────┘
```

## Projektstruktur

```
~/Dropbox/zettelkasten_mcp/
├── README.md                    # Diese Datei
├── venv/                        # Python 3.11 Virtual Environment
│   └── bin/python               # Python-Interpreter für MCP
└── zettelkasten_mcp/
    ├── __init__.py
    ├── __main__.py              # Entry point: python -m zettelkasten_mcp
    └── server.py                # MCP Server mit allen Tools
```

## Abhängigkeiten

**Python-Version:** 3.11+ (MCP erfordert >= 3.10)

**Installierte Packages im venv:**
- `mcp[cli]` - MCP Protocol Library
- `flask`, `flask-wtf`, `flask-pagedown` - Flask-Abhängigkeiten von tools4zettelkasten
- `graphviz`, `pyfiglet`, `inquirerpy`, `colorama`, `markdown` - Weitere Abhängigkeiten

**Externe Abhängigkeit (`tools4zettelkasten`):**
- **Repository:** [rreben/tools4zettelkasten](https://github.com/rreben/tools4zettelkasten)
- **Beschreibung:** Python-Tools für das "Folgezettel"-Prinzip, Verwaltung alphanumerischer Sortierungen und Strukturanalyse.
- **Integration:** Dieses Projekt importiert die Bibliothek direkt (via `PYTHONPATH`), um deren Logik für Parsing und Dateisystem-Operationen zu nutzen.

## Konfiguration

### Claude Desktop / Claude Code

Datei: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "zettelkasten": {
      "command": "/Users/rupertrebentisch/Dropbox/zettelkasten_mcp/venv/bin/python",
      "args": ["-m", "zettelkasten_mcp"],
      "env": {
        "PYTHONPATH": "/Users/rupertrebentisch/Library/CloudStorage/Dropbox/tools4zettelkasten",
        "TOOLS4ZETTELKASTEN_PATH": "/Users/rupertrebentisch/Library/CloudStorage/Dropbox/tools4zettelkasten",
        "ZETTELKASTEN": "/Users/rupertrebentisch/Dropbox/zettelkasten/mycelium",
        "ZETTELKASTEN_INPUT": "/Users/rupertrebentisch/Dropbox/zettelkasten/input"
      },
      "cwd": "/Users/rupertrebentisch/Dropbox/zettelkasten_mcp"
    }
  }
}
```

### Umgebungsvariablen

| Variable | Beschreibung | Standard |
|----------|--------------|----------|
| `ZETTELKASTEN` | Pfad zum Hauptordner des Zettelkastens | `~/Dropbox/zettelkasten/mycelium` |
| `ZETTELKASTEN_INPUT` | Pfad zum Input-Ordner für neue Notizen | `~/Dropbox/zettelkasten/input` |
| `TOOLS4ZETTELKASTEN_PATH` | Pfad zum tools4zettelkasten-Repository | `~/Library/CloudStorage/Dropbox/tools4zettelkasten` |
| `PYTHONPATH` | Muss tools4zettelkasten enthalten | (wie TOOLS4ZETTELKASTEN_PATH) |

## Tools-Übersicht

### Input-Management

| Tool | Parameter | Beschreibung |
|------|-----------|--------------|
| `list_input_files` | - | Zeigt alle Dateien im Input-Ordner |
| `preview_staging` | - | Vorschau der geplanten Umbenennungen |
| `stage_file` | `filename` | Benennt eine Datei nach Titel um |

### Zettelkasten-Abfragen

| Tool | Parameter | Beschreibung |
|------|-----------|--------------|
| `get_zettel` | `identifier` (ID oder Filename) | Liest einen einzelnen Zettel |
| `search_zettel` | `query`, `limit=10` | Volltextsuche |
| `list_zettel` | `prefix=""`, `limit=50` | Listet Zettel (optional nach Topic) |
| `get_statistics` | - | Statistiken über den Zettelkasten |

### Struktur & Analyse

| Tool | Parameter | Beschreibung |
|------|-----------|--------------|
| `get_links` | `identifier` | Ein-/ausgehende Links eines Zettels |
| `find_related` | `identifier`, `limit=5` | Verwandte Zettel (Links + Hierarchie) |
| `analyze_structure` | `topic=""` | Strukturanalyse (Tree + Links) |

### Reorganisation

| Tool | Parameter | Beschreibung |
|------|-----------|--------------|
| `preview_reorganize` | - | Zeigt geplante Änderungen |
| `execute_reorganize` | `confirm=False` | Führt Reorganisation durch |

## Technische Hinweise

### Import-Workaround

`tools4zettelkasten` hat in seiner `__init__.py` ein `from .cli import *`, das Click-Commands exportiert und dabei Modulnamen wie `reorganize` überschreibt. Der MCP-Server umgeht dies durch direkten Import via `importlib`:

```python
import importlib
ro = importlib.import_module("tools4zettelkasten.reorganize")
```

### Manuelles Testen

```bash
cd ~/Dropbox/zettelkasten_mcp

# Server-Import testen
PYTHONPATH="$HOME/Library/CloudStorage/Dropbox/tools4zettelkasten" \
ZETTELKASTEN="$HOME/Dropbox/zettelkasten/mycelium" \
ZETTELKASTEN_INPUT="$HOME/Dropbox/zettelkasten/input" \
./venv/bin/python -c "from zettelkasten_mcp.server import mcp; print('OK')"

# Tools testen
PYTHONPATH="$HOME/Library/CloudStorage/Dropbox/tools4zettelkasten" \
ZETTELKASTEN="$HOME/Dropbox/zettelkasten/mycelium" \
ZETTELKASTEN_INPUT="$HOME/Dropbox/zettelkasten/input" \
./venv/bin/python -c "
from zettelkasten_mcp.server import get_statistics
print(get_statistics())
"
```

### MCP-Status in Claude Code prüfen

```bash
claude mcp list
```

Oder im Chat: `/mcp`

## Deployment-Checkliste

1. **Python 3.11+ installiert?** (`python3.11 --version`)
2. **venv erstellt?** (`python3.11 -m venv venv`)
3. **Dependencies installiert?**
   ```bash
   ./venv/bin/pip install "mcp[cli]" flask flask-wtf flask-pagedown \
       graphviz pyfiglet inquirerpy colorama markdown mistune
   ```
4. **claude_desktop_config.json konfiguriert?**
5. **Pfade korrekt?** (Dropbox-Symlinks beachten!)
6. **Claude Desktop/Code neu gestartet?**

## Beispiel-Nutzung

```
Du: "Was liegt im Input-Ordner?"
Claude: [ruft list_input_files auf]

Du: "Zeige mir den Zettel über Kreativität"
Claude: [ruft search_zettel(query="Kreativität") auf]

Du: "Welche Zettel sind mit 01_001 verwandt?"
Claude: [ruft find_related(identifier="01_001") auf]

Du: "Gib mir Statistiken"
Claude: [ruft get_statistics auf]
```

---

*Erstellt am: 27. Januar 2026*