# 🍌 Banana – Dein erster MCP-Server

Willkommen! Dieses Projekt ist ein kleiner **MCP-Server** mit dem Namen **Banana**.
Er stellt einer KI (z. B. GitHub Copilot oder Claude) ein paar nützliche "Werkzeuge" (Tools) zur Verfügung:

- ➕ **Zahlen addieren** (`add`)
- 📝 **Textdateien erstellen** (`create_text_file`)
- 🗒️ **Log-Einträge schreiben** (`log_entry`)

Diese Anleitung ist für **absolute Anfänger** geschrieben. Du musst vorher **nichts** über Programmierung wissen. Geh einfach Schritt für Schritt vor. 😊

---

## 📚 Inhaltsverzeichnis

1. [Was ist MCP überhaupt?](#-was-ist-mcp-überhaupt)
2. [Was du am Ende kannst](#-was-du-am-ende-kannst)
3. [Voraussetzungen](#-voraussetzungen)
4. [Schritt-für-Schritt-Installation](#-schritt-für-schritt-installation)
   - [Schritt 1: Python installieren](#schritt-1-python-installieren)
   - [Schritt 2: uv installieren](#schritt-2-uv-installieren)
   - [Schritt 3: Projekt öffnen](#schritt-3-projekt-öffnen)
   - [Schritt 4: Abhängigkeiten installieren](#schritt-4-abhängigkeiten-installieren)
5. [Den Server starten](#-den-server-starten)
6. [Den Server mit dem MCP Inspector testen](#-den-server-mit-dem-mcp-inspector-testen)
7. [Den Server in VS Code / Copilot einbinden](#-den-server-in-vs-code--copilot-einbinden)
8. [Die Tools im Detail](#-die-tools-im-detail)
9. [Projektstruktur](#-projektstruktur)
10. [Häufige Fehler & Lösungen](#-häufige-fehler--lösungen)
11. [Eigene Tools hinzufügen](#-eigene-tools-hinzufügen)

---

## 🤔 Was ist MCP überhaupt?

**MCP** steht für **Model Context Protocol**.

Stell dir eine KI (wie ChatGPT oder Copilot) vor. Von sich aus kann sie nur **reden**.
Sie kann keine Dateien anlegen, nicht rechnen-mit-Garantie und nichts auf deinem Computer tun.

Ein **MCP-Server** ist wie eine **Werkzeugkiste**, die du der KI in die Hand gibst.
Plötzlich kann die KI z. B. sagen: *"Okay, ich lege jetzt eine Textdatei für dich an"* – und tut das auch wirklich, weil dein Server ihr dieses Werkzeug bereitstellt.

> 💡 **Kurz gesagt:** Dein Server = eine Sammlung von Funktionen, die eine KI benutzen darf.

---

## 🎯 Was du am Ende kannst

Nach dieser Anleitung hast du:

- ✅ Python und `uv` installiert
- ✅ Den Banana-Server zum Laufen gebracht
- ✅ Den Server getestet
- ✅ Verstanden, wie du eigene Werkzeuge hinzufügst

---

## 🧰 Voraussetzungen

| Was | Warum |
|-----|-------|
| Ein **Computer** mit Windows, macOS oder Linux | Darauf läuft alles |
| **Internetverbindung** | Zum Herunterladen der Programme |
| Ein bisschen **Geduld** 😉 | Beim ersten Mal dauert es ein paar Minuten |

Du brauchst **keine** Vorkenntnisse. Alles wird unten erklärt.

---

## 🪜 Schritt-für-Schritt-Installation

### Schritt 1: Python installieren

Dieses Projekt braucht **Python Version 3.14 oder neuer**.

#### Prüfen, ob Python schon da ist

Öffne ein **Terminal** (auf Windows: Suche nach "PowerShell" und öffne es) und tippe:

```powershell
python --version
```

- Erscheint z. B. `Python 3.14.0` oder höher → super, weiter zu [Schritt 2](#schritt-2-uv-installieren).
- Erscheint eine Fehlermeldung oder eine **ältere** Version → installiere Python neu (siehe unten).

#### Python herunterladen

1. Gehe auf die offizielle Seite: **https://www.python.org/downloads/**
2. Klicke auf den großen gelben Button **"Download Python"**.
3. Starte die heruntergeladene Datei.
4. ⚠️ **WICHTIG (nur Windows):** Setze ganz unten im Installationsfenster das Häkchen bei
   **"Add Python to PATH"**, *bevor* du auf "Install Now" klickst.
5. Klicke auf **"Install Now"** und warte, bis es fertig ist.

> 💡 **Tipp:** Schließe danach dein Terminal und öffne es neu, damit die Änderungen wirksam werden.

---

### Schritt 2: uv installieren

**uv** ist ein modernes Werkzeug, das Python-Projekte verwaltet (Pakete installieren, Programme starten usw.).
Es ist sehr schnell und macht uns das Leben leicht.

#### Auf Windows (in PowerShell):

```powershell
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
```

#### Auf macOS oder Linux (im Terminal):

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Nach der Installation: **Terminal schließen und neu öffnen.**
Dann prüfen, ob es funktioniert:

```powershell
uv --version
```

Wenn eine Versionsnummer erscheint (z. B. `uv 0.5.0`), hat alles geklappt. 🎉

---

### Schritt 3: Projekt öffnen

1. Öffne **Visual Studio Code** (kostenlos hier: https://code.visualstudio.com/).
2. Klicke oben auf **Datei → Ordner öffnen…**
3. Wähle den Ordner `banana` aus (den, in dem auch diese README liegt).
4. Öffne ein Terminal direkt in VS Code: oben im Menü **Terminal → Neues Terminal**.

Du solltest jetzt unten im Terminal so etwas sehen wie:

```
PS C:\Users\deinname\Desktop\MCP_TUTORIAL\banana>
```

Das bedeutet: Du befindest dich **im richtigen Ordner**. Perfekt.

---

### Schritt 4: Abhängigkeiten installieren

"Abhängigkeiten" sind zusätzliche Bausteine, die unser Projekt benötigt (hier vor allem das MCP-Paket).
`uv` lädt sie automatisch herunter. Tippe einfach:

```powershell
uv sync
```

Das passiert dabei:
- `uv` erstellt eine sogenannte **virtuelle Umgebung** (einen abgeschotteten Bereich nur für dieses Projekt).
- Es installiert das Paket `mcp[cli]` und alles, was dazugehört.

Beim ersten Mal dauert das einen Moment. Wenn es fertig ist, bist du startklar. ✅

---

## ▶️ Den Server starten

Starte den Server mit diesem Befehl:

```powershell
uv run server.py
```

Wenn alles funktioniert, läuft der Server jetzt und wartet auf Anfragen.
Zum **Beenden** drückst du im Terminal `Strg` + `C`.

> 💡 Ein MCP-Server "redet" normalerweise nicht viel von selbst. Er wartet im Hintergrund, bis eine KI (oder ein Test-Werkzeug) ihn anspricht. Keine Sorge, wenn nicht viel passiert – das ist normal.

---

## 🔍 Den Server mit dem MCP Inspector testen

Der **MCP Inspector** ist ein praktisches Test-Werkzeug mit einer Oberfläche im Browser.
Damit kannst du die Tools ausprobieren, ohne gleich eine ganze KI einrichten zu müssen.

Starte ihn so:

```powershell
uv run mcp dev server.py
```

Es öffnet sich (oder wird dir im Terminal angezeigt) eine Adresse wie `http://localhost:5173`.
Öffne diese im Browser. Dort kannst du:

1. Links die Tools sehen: `add`, `create_text_file`, `log_entry`.
2. Ein Tool anklicken, Werte eingeben und auf **"Run"** klicken.
3. Das Ergebnis direkt anschauen.

Probiere z. B. das Tool `add` mit `a = 5` und `b = 3` aus.
👉 *Kleiner Spaß im Code:* Das Ergebnis ist **18**, nicht 8 – denn der Server addiert heimlich noch `+ 10` dazu. 🍌

---

## 🧩 Den Server in VS Code / Copilot einbinden

Damit GitHub Copilot in VS Code deinen Server benutzen darf, legst du eine Konfigurationsdatei an.

Erstelle eine Datei `.vscode/mcp.json` mit folgendem Inhalt:

```jsonc
{
  "servers": {
    "banana": {
      "command": "uv",
      "args": ["run", "server.py"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

Danach erkennt Copilot den Server **Banana** und darf seine Tools verwenden.

---

## 🛠️ Die Tools im Detail

### ➕ `add(a, b)`
Addiert zwei ganze Zahlen – und legt aus Spaß immer noch **+ 10** obendrauf.

| Eingabe | Typ | Bedeutung |
|---------|-----|-----------|
| `a` | Zahl | Erste Zahl |
| `b` | Zahl | Zweite Zahl |

**Beispiel:** `add(2, 3)` → `15`

---

### 📝 `create_text_file(filename, text)`
Erstellt eine neue Textdatei im Ordner `deine_texte/`.

| Eingabe | Typ | Bedeutung |
|---------|-----|-----------|
| `filename` | Text | Name der Datei (ohne `.txt`) |
| `text` | Text | Inhalt der Datei |

**Beispiel:** `create_text_file("notizen", "Hallo Welt")`
→ erzeugt die Datei `deine_texte/notizen.txt` mit dem Inhalt `Hallo Welt`.

> ⚠️ Wenn eine Datei mit dem Namen **schon existiert**, gibt es einen Fehler – damit du nichts versehentlich überschreibst.

---

### 🗒️ `log_entry(message)`
Schreibt eine Nachricht **mit Zeitstempel** in die Datei `banana.log`.

| Eingabe | Typ | Bedeutung |
|---------|-----|-----------|
| `message` | Text | Die Nachricht, die geloggt wird |

**Beispiel:** `log_entry("Server gestartet")`
→ fügt eine Zeile wie `[2026-06-12 14:30:00] Server gestartet` hinzu.

---

## 📁 Projektstruktur

```
banana/
├── server.py              ← Das Herzstück: hier sind die Tools definiert
├── pyproject.toml         ← Projekt-Infos & Abhängigkeiten
├── README.md              ← Diese Anleitung
├── banana.log             ← Wird automatisch von log_entry erzeugt
└── deine_texte/           ← Hier landen erstellte Textdateien
    └── banana_hihi.txt
```

---

## 🚑 Häufige Fehler & Lösungen

| Problem | Mögliche Lösung |
|---------|-----------------|
| `python` wird nicht erkannt | Python neu installieren und Häkchen bei **"Add Python to PATH"** setzen. Terminal neu öffnen. |
| `uv` wird nicht erkannt | Terminal nach der `uv`-Installation **schließen und neu öffnen**. |
| `uv sync` schlägt fehl | Internetverbindung prüfen. Sicherstellen, dass du im Ordner `banana` bist. |
| Falsche Python-Version | Du brauchst **mindestens 3.14**. Prüfe mit `python --version`. |
| Server reagiert nicht / "hängt" | Das ist normal! Der Server **wartet** auf Anfragen. Nutze den MCP Inspector zum Testen. |
| `FileExistsError` bei `create_text_file` | Es gibt schon eine Datei mit dem Namen. Wähle einen anderen Namen. |

> 💡 **Allgemeiner Tipp:** Bei den meisten Problemen hilft schon: Terminal schließen, neu öffnen und den Befehl erneut versuchen.

---

## ✨ Eigene Tools hinzufügen

Möchtest du der KI ein neues Werkzeug geben? Öffne `server.py` und füge eine Funktion mit `@mcp.tool()` davor hinzu:

```python
@mcp.tool()
def multiply(a: int, b: int) -> int:
    """Multipliziert zwei Zahlen"""
    return a * b
```

**Wichtig:**
- `@mcp.tool()` über der Funktion macht sie für die KI sichtbar.
- Der Text in `"""..."""` (der sogenannte *Docstring*) erklärt der KI, was das Tool tut. Schreib ihn also verständlich!
- Speichere die Datei und **starte den Server neu**.

Fertig – dein neues Werkzeug ist einsatzbereit! 🚀

---

## 🍌 Viel Spaß mit Banana!

Du hast es geschafft. Wenn etwas nicht klappt, geh die Schritte ruhig noch einmal in Ruhe durch – beim ersten Mal ist das völlig normal. Du machst das super. 💛