🍌 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?
2. Was du am Ende kannst
3. Voraussetzungen
4. Schritt-für-Schritt-Installation
   • Schritt 1: Python installieren
   • Schritt 2: uv installieren
   • Schritt 3: Projekt öffnen
   • Schritt 4: Abhängigkeiten installieren
5. Den Server starten
6. Den Server mit dem MCP Inspector testen
7. Den Server in VS Code / Copilot einbinden
8. Die Tools im Detail
9. Projektstruktur
10. Häufige Fehler & Lösungen
11. 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:

python --version

• Erscheint z. B. Python 3.14.0 oder höher → super, weiter zu Schritt 2.
• 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 -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Auf macOS oder Linux (im Terminal):

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

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

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:

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:

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:

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:

{
  "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:

@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. 💛