Workshop MCP

Dieses Projekt wurde während des Workshops der Veranstaltung The Developers Life Weekend in Umuarama - PR (online) entwickelt.

Über den Workshop

Repository mit Schritt-für-Schritt-Anleitung, Quellcode und Übungen zum Bauen Ihres ersten Servers, der auf dem Model Context Protocol (MCP) basiert.

Während des Workshops wurden vorgestellt:

• Die Client-Server-Architektur des MCP-Protokolls;

• Die Erstellung und Bereitstellung von Tools (tools) für LLMs;

• Die Verwaltung von Ressourcen (resources) und dynamischen Prompts;

• Die Verbindung des Servers zu echten KI-Clients.

Das Hauptprojekt wurde mit Python und FastMCP erstellt. Es stellt Tools und Ressourcen zur Abfrage der Wettervorhersage bereit und demonstriert eine Operation, die vor dem Senden von Einladungen eine Bestätigung verlangt.

Related MCP server: Weather MCP Server

Voraussetzungen

• Python 3.14 oder höher;

• uv installiert;

• Eine Anwendung, die in Auth0 konfiguriert ist;

• Internetzugang, um https://wttr.in abzufragen;

• Ein kompatibler MCP-Client, wie OpenCode oder MCP Inspector.

Das Projekt verwendet uv.lock, um die Versionen der Abhängigkeiten reproduzierbar zu halten.

Installation

Klonen Sie das Repository und wechseln Sie in den Projektordner:

git clone https://github.com/marcelomarkus/tdlw-workshop-mcp.git
cd tdlw-workshop-mcp

Synchronisieren Sie die Abhängigkeiten. Der Befehl erstellt oder aktualisiert die virtuelle Umgebung .venv automatisch:

uv sync

Überprüfen Sie die ausgewählte Python-Version:

python --version
uv python find

Auth0-Konfiguration

Der Hauptserver verwendet Auth0Provider und benötigt diese Umgebungsvariablen:

Erstellen Sie die lokale Konfigurationsdatei aus der Vorlage:

cp .env_example .env

Füllen Sie die .env mit echten Werten aus:

AUTH_DOMAIN=https://seu-dominio.auth0.com
CLIENT_ID=seu-client-id
CLIENT_SECRET=seu-client-secret
AUDIENCE=https://sua-api

Die Datei .env wird von Python nicht automatisch geladen. Exportieren Sie die Variablen, bevor Sie den Server starten:

set -a
source .env
set +a

Oder definieren Sie sie direkt im selben Aufruf:

AUTH_DOMAIN="https://seu-dominio.auth0.com" \
CLIENT_ID="seu-client-id" \
CLIENT_SECRET="seu-client-secret" \
AUDIENCE="https://sua-api" \
uv run main.py

Teilen Sie niemals das CLIENT_SECRET und nehmen Sie es nicht in Commits auf.

Server ausführen

Mit den geladenen Variablen starten Sie den Hauptserver:

uv run main.py

Der MCP-Endpunkt ist verfügbar unter:

http://127.0.0.1:8000/mcp

Halten Sie den Prozess am Laufen, während der MCP-Client verbunden ist. Zum Beenden drücken Sie Ctrl+C.

MCP Inspector ausführen

Der MCP Inspector bietet eine Weboberfläche zum Testen von Tools, Ressourcen und Prompts.

Starten Sie in einem ersten Terminal den Server:

set -a
source .env
set +a
uv run main.py

Führen Sie in einem anderen Terminal den Inspector aus:

npx @modelcontextprotocol/inspector

Öffnen Sie http://localhost:6274 im Browser und konfigurieren Sie:

Klicken Sie auf Connect und testen Sie die verfügbaren Tools und Ressourcen. Die Auth0-Variablen müssen in der Umgebung des Serverprozesses vorhanden sein.

Verbinden über OpenCode

Die Datei opencode.json verweist bereits auf den lokalen Endpunkt:

{
  "mcp": {
    "Workshop": {
      "type": "remote",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Öffnen Sie OpenCode in diesem Projekt, während der Server läuft.

Verfügbare Funktionen

Tools

• Tempo(cidade): fragt das aktuelle Wetter einer Stadt ab;

• Temperatura(cidade): fragt die aktuelle Temperatur einer Stadt ab;

• Enviar_Convites(quantidade): fordert eine Bestätigung an und simuliert das Senden, wobei der Fortschritt jedes Elements gemeldet wird.

Die Wetterabfragen verwenden wttr.in/<cidade>?format=%t.

Ressourcen

• workshop://oque-o-mcp-nao-e: Einführungstext über MCP;

• previsao://{cidade}: Vorhersage für eine in der URI angegebene Stadt.

Prompt

• exemplo_prompt(pergunta): leitet die Auswahl zwischen den Wetter-Tools an.

Projektstruktur

.
├── main.py          # Servidor MCP principal
├── mcp_com_api.py   # Servidor MCP gerado a partir da API Petstore
├── exercises/       # Exercícios progressivos do workshop
│   ├── 01-mcp-server/
│   ├── 02-resources/
│   ├── 03-tools/
│   ├── 04-prompts/
│   ├── 05-Context/
│   ├── 06-auth/
│   └── 07-mcp-api/
├── slide/            # Material de apoio
│   └── TDLW-Umuarama.pdf
├── opencode.json    # Configuração do OpenCode
├── pyproject.toml   # Metadados e dependências
├── uv.lock          # Versões resolvidas
└── .env_example     # Modelo das variáveis do Auth0

Entwicklung

Sie können das Projekt über den Debug-Modus von VS Code oder über uv ausführen:

uv run main.py

Um die Syntax der Module zu überprüfen:

python -m compileall main.py mcp_com_api.py exercises

Fehlerbehebung

ModuleNotFoundError

Führen Sie uv sync aus und starten Sie das Programm mit uv run main.py, um das globale Python zu vermeiden, wenn die Abhängigkeiten nur in .venv installiert sind.

Authentifizierungsfehler

Überprüfen Sie, ob die vier Auth0-Variablen in derselben Umgebung wie der Server exportiert wurden und ob die Domäne das erwartete Protokoll enthält.

Fehler bei der Wetterabfrage

Testen Sie die Konnektivität mit:

curl "https://wttr.in/Sao%20Paulo?format=%t"

Port 8000 belegt

Geben Sie den Port frei oder passen Sie den Port im Server und in der opencode.json an, wobei Sie auf beiden Seiten dieselbe Adresse beibehalten.

Dokumentation und Referenzen

• Offizielle uv-Dokumentation

• Offizielle HTTPX-Dokumentation

• Offizielle FastMCP-Dokumentation

• Offizielles Repository des MCP SDK für Python

• Offizielle MCP-Dokumentation

• Spezifikation des MCP-Protokolls