Claude Academy
Wird geladen

Tools mit MCP definieren

Lektion 519 Min.

Das Erstellen eines MCP-Servers wird viel einfacher, wenn du das offizielle MCP Python SDK verwendest. Anstatt komplexe JSON-Schemas für Tools manuell zu schreiben, kannst du sie mit Decorators definieren und das SDK die Schwerarbeit erledigen lassen.

Die Lese- und Aktualisierungs-Tools unseres MCP-Servers, verbunden mit vier Dateien: document.pdf, spreadsheet.xlsx, report.txt und spec.md.

In diesem Beispiel erstellen wir einen MCP-Server, der Dokumentoperationen verwaltet. Der Server verfügt über zwei Haupt-Tools: eines zum Lesen von Dokumentinhalten und ein weiteres zum Aktualisieren dieser Inhalte. Alle Dokumente existieren im Speicher als einfaches Dictionary, bei dem die Schlüssel Dokument-IDs und die Werte die Inhaltsstrings sind.

Vorteile des MCP Python SDK

Das MCP-Projekt bietet offizielle SDKs für die Entwicklung von Servern und Clients in mehreren Programmiersprachen. Die Verwendung des Python SDK bietet mehrere Vorteile:

  • Erstellt MCP-Server mit minimalem Boilerplate-Code
  • Generiert automatisch JSON-Schemas aus Python-Funktionssignaturen
  • Vereinfacht die Tool-Definition durch Decorators
  • Übernimmt Typvalidierung und Fehlerbehandlung

Die Lese- und Aktualisierungs-Tools unseres MCP-Servers, verbunden mit vier Dateien: document.pdf, spreadsheet.xlsx, report.txt und spec.md.

So einfach ist es, ein Tool mit dem SDK zu definieren. Der @mcp.tool-Decorator erstellt in Kombination mit Type Hints und Feldbeschreibungen automatisch das passende Tool-Schema, das Claude verstehen und verwenden kann.

Einrichten des Servers

Dieser Kurs verwendet Version 1 des MCP Python SDK. Der untenstehende Import schlägt bei Version 2 fehl, in der FastMCP umbenannt wurde. Wenn du das Projekt selbst einrichtest, halte dich an eine SDK-Version unter 2:

bash
uv add "mcp[cli]<2"

Mit pip lautet die gleiche Versionsfestlegung pip install "mcp[cli]<2".

Die grundlegende Server-Einrichtung erfordert nur wenige Zeilen:

python
from mcp.server.fastmcp import FastMCP
from pydantic import Field

mcp = FastMCP("DocumentMCP", log_level="ERROR")

docs = {
    "deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
    "report.pdf": "The report details the state of a 20m condenser tower.",
    "financials.docx": "These financials outline the project's budget and expenditures",
    "outlook.pdf": "This document presents the projected future performance of the system",
    "plan.md": "The plan outlines the steps for the project's implementation.",
    "spec.txt": "These specifications define the technical requirements for the equipment"
}

Implementierung des Lese-Tools

Das erste Tool ermöglicht es Claude, Dokumentinhalte durch Angabe einer Dokument-ID zu lesen:

python
@mcp.tool(
    name="read_doc_contents",
    description="Read the contents of a document and return it as a string."
)
def read_document(
    doc_id: str = Field(description="Id of the document to read")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    return docs[doc_id]

Die Tool-Definition umfasst:

  • Einen klaren Namen, der die Aktion beschreibt
  • Eine Beschreibung, die erklärt, was das Tool tut
  • Typisierte Parameter mit Feldbeschreibungen
  • Fehlerbehandlung für ungültige Dokument-IDs

Implementierung des Bearbeitungs-Tools

Das zweite Tool führt einfache Suchen-und-Ersetzen-Operationen am Dokumentinhalt durch:

python
@mcp.tool(
    name="edit_document",
    description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
    doc_id: str = Field(description="Id of the document that will be edited"),
    old_str: str = Field(description="The text to replace. Must match exactly, including whitespace."),
    new_str: str = Field(description="The new text to insert in place of the old text.")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

Dieses Tool nimmt drei Parameter entgegen: die Dokument-ID, den zu suchenden Text und den Ersatztext. Die Implementierung verwendet der Einfachheit halber Pythons integrierte String-Methode replace().

Wichtige Implementierungsdetails

Beachte beim Definieren von Tools mit dem MCP SDK diese wichtigen Punkte:

  • Importiere Field aus pydantic, um Parameterbeschreibungen hinzuzufügen
  • Verwende Type Hints, um Parametertypen anzugeben
  • Füge Fehlerbehandlung für Randfälle hinzu
  • Schreibe klare, aussagekräftige Tool-Namen und -Beschreibungen
  • Das MCP Python SDK wandelt deine Funktionssignatur automatisch in das passende JSON-Schema um

Das MCP Python SDK reduziert die Komplexität der Tool-Erstellung im Vergleich zum manuellen Schreiben von JSON-Schemas drastisch. Was früher Dutzende Zeilen Schema-Definition erforderte, benötigt jetzt nur noch wenige Zeilen dekorierter Python-Funktionen.

Der @mcp.tool-Decorator und seine signaturbasierte Schema-Generierung stammen aus dem MCP Python SDK. Das Claude Agent SDK bietet einen separaten @tool-Decorator zum Definieren benutzerdefinierter Tools, und es erwartet ein explizites input_schema-Argument anstelle von pydantic-Field-Annotationen an der Funktionssignatur. In Python ist dieses Schema ein Dict, das Parameternamen auf Typen abbildet, wie {"latitude": float}, das das Agent SDK für dich in JSON Schema umwandelt, oder ein vollständiges JSON-Schema-Dict, wenn du Enums, Bereiche, optionale Felder oder verschachtelte Objekte benötigst. Wenn du an anderer Stelle Tool-Code liest, prüfe, welches SDK importiert wird, da die beiden Decorators leicht zu verwechseln sind.