📝 AI Sticky Notes - Python MCP Server

Ein leichtgewichtiger, client-agnostischer Model Context Protocol (MCP)-Server, der in Python mit FastMCP erstellt wurde. Dieser Server stellt KI-Assistenten (wie Claude Desktop, Google Antigravity, Cursor und jedem MCP-kompatiblen Client) dauerhafte Notizfunktionen bereit.

🌟 Hauptfunktionen

Dieser Server implementiert die drei Kern-Primitive des Model Context Protocol:

• 🛠️ Tools (Aktionsausführung):

  • add_note(message: str) -> str: Fügt der lokalen Speicherdatei eine neue Haftnotiz hinzu.

  • read_notes() -> str: Liest alle gespeicherten Notizen und gibt sie als eine einzige Zeichenfolge zurück.

• 📦 Ressourcen (Kontextquellen):

  • notes://latest: Stellt die zuletzt gespeicherte Notiz dynamisch über eine benutzerdefinierte URI bereit.

• 💬 Prompts (Wiederverwendbare LLM-Vorlagen):

  • note_summary_prompt(): Erzeugt einen einsatzbereiten Prompt, der die KI anweist, alle aktuellen Haftnotizen zusammenzufassen.

📂 Projektstruktur

.
├── main.py                  # Primary FastMCP server implementation
├── main_final.py            # Clean reference implementation
├── notes.txt                # Persistent note storage (auto-generated)
├── pyproject.toml           # uv / Python package and dependency configuration
├── BITACORA_DE_ERRORES.md   # Troubleshooting log & root-cause analyses (Linux & PATH notes)
├── MCP_PYTHON_SDK.md        # FastMCP quick reference cheatsheet
└── README.md                # Project documentation (this file)

🚀 Erste Schritte

Voraussetzungen

• Python 3.12+

• uv (empfohlen für schnelle Paket- und Umgebungsverwaltung)

1. Installation

Klonen Sie dieses Repository und synchronisieren Sie die Abhängigkeiten:

git clone https://github.com/<your-username>/<your-repo-name>.git
cd <your-repo-name>
uv sync

🧪 Ausführen & Testen

Option A: Interaktiver MCP Inspector (Empfohlen)

Der MCP Inspector bietet eine visuelle Weboberfläche, um Tools zu testen, Ressourcen zu prüfen und Prompts interaktiv auszuführen:

uv run mcp dev main.py

Öffnen Sie die im Terminal angezeigte URL (normalerweise http://localhost:5173 oder ähnlich), um mit Ihrem Server zu interagieren.

Option B: Claude Desktop-Integration

Fügen Sie die Serverdefinition zu Ihrer claude_desktop_config.json hinzu:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ai-sticky-notes": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/your/project",
        "run",
        "main.py"
      ]
    }
  }
}

💡 Tipp für Linux-/GUI-Umgebungen: Wenn Ihre Desktop-Umgebung das interaktive PATH Ihrer Shell nicht erbt (was spawn uv ENOENT verursacht), geben Sie den absoluten Pfad zu Ihrer uv-Binärdatei an (z. B. /home/<user>/.local/bin/uv oder /home/<user>/miniconda3/bin/uv). Einzelheiten finden Sie in BITACORA_DE_ERRORES.md.

Option C: Integration mit gängigen MCP-Clients (Cursor, Antigravity, benutzerdefinierte CLI)

Konfigurieren Sie den Standard-stdio-Transport mit:

• Befehl: uv

• Argumente: ["--directory", "<PROJECT_PATH>", "run", "main.py"]

📖 MCP-API-Referenz

Tools

Ressourcen

Prompts

🛠️ Entwicklung & Fehlerbehebung

Für ein detailliertes Changelog mit Debugging-Schritten, Linux-Plattform-Workarounds und häufigen Einrichtungsproblemen, die während der Entwicklung aufgetreten sind, siehe:

• 📓 BITACORA_DE_ERRORES.md (Protokoll auf Spanisch)

• 📘 MCP_PYTHON_SDK.md (SDK-Spickzettel)

📄 Lizenz & Credits

• Erstellt mit Model Context Protocol und FastMCP.

• Inspiriert vom MCP-Server-Entwicklungstutorial von Tech With Tim.