MCP-Server-Boilerplate

Eine minimale, gut dokumentierte MCP-Server-Implementierung (Model Context Protocol), die als wiederverwendbare Basis für die Erstellung benutzerdefinierter MCP-Server dient.

Was ist MCP?

Das Model Context Protocol (MCP) ist ein standardisiertes Protokoll, das es KI-Assistenten ermöglicht, mit externen Servern zu interagieren. MCP-Server können Folgendes bereitstellen:

• Tools: Funktionen, die die KI aufrufen kann, um Aktionen auszuführen

• Ressourcen: Statische oder dynamische Daten, die die KI lesen kann

• Prompts: Wiederverwendbare Prompt-Vorlagen für konsistente KI-Interaktionen

Related MCP server: MCP Mingdao

Funktionen

Dieses Boilerplate bietet:

• Minimale Struktur: Eine saubere Basis, die leicht erweitert werden kann

• Umfangreiche Dokumentation: Inline-Kommentare und separate Dokumentationsdateien

• Architekturdiagramme: Mermaid-Diagramme, die die Interaktionen der Komponenten zeigen

• Skalierungsleitfaden: Best Practices für das Wachstum Ihres Servers

• Typ-Hinweise: Vollständige Typ-Annotationen für bessere IDE-Unterstützung

• Async/await: Nicht-blockierende E/A für gleichzeitige Operationen

Wiederverwendbare Prompt-Vorlagen

Prompts sind wiederverwendbare Vorlagen, mit denen Sie strukturierte Prompts mit Platzhaltern definieren können. Sie ermöglichen:

• Konsistenz: Standardisierte Prompt-Formate über verschiedene KI-Interaktionen hinweg

• Parametrisierung: Dynamisches Einfügen von Inhalten durch Argumente

• Wiederverwendbarkeit: Einmal definieren, mehrfach mit verschiedenen Eingaben verwenden

• Typsicherheit: Definierte Argument-Schemata mit Validierung

Eine Prompt-Vorlage besteht aus:

• Name: Eindeutiger Bezeichner für den Prompt

• Beschreibung: Was der Prompt bewirkt

• Argumente: Optionale Parameter, die bei der Verwendung des Prompts ausgefüllt werden können

Beispiel-Anwendungsfälle:

• Code-Review-Vorlagen mit konfigurierbaren Schweregraden

• Dokumentationserstellung mit anpassbarem Tonfall

• Analyse-Prompts mit variablen Fokusbereichen

• Berichterstellung mit verschiedenen Ausgabeformaten

Projektstruktur

windsurf-project-3/
├── mcp_server.py          # Main server implementation with extensive comments
├── pyproject.toml         # Project configuration for uv
├── ARCHITECTURE.md        # Architecture documentation with Mermaid diagrams
├── SCALING_GUIDE.md       # Scaling patterns and best practices
├── README.md              # This file
├── tools/                 # Placeholder for tool modules (create as needed)
├── resources/             # Placeholder for resource modules (create as needed)
├── prompts/               # Placeholder for prompt modules (create as needed)
└── utils/                 # Placeholder for utility modules (create as needed)

Installation

Dieses Projekt verwendet uv für schnelles Python-Paketmanagement.

1. Installieren Sie Python 3.10 oder höher

2. Installieren Sie uv (falls noch nicht geschehen):

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

3. Installieren Sie die Abhängigkeiten:

uv sync

Schnellstart

1. Fügen Sie Ihr erstes Tool hinzu

Bearbeiten Sie mcp_server.py und fügen Sie ein Tool in der Funktion list_tools() hinzu:

@app.list_tools()
async def list_tools() -> list[Tool]:
    return [
        Tool(
            name="echo",
            description="Echo back the input text",
            inputSchema={
                "type": "object",
                "properties": {
                    "text": {"type": "string", "description": "Text to echo"}
                },
                "required": ["text"]
            }
        )
    ]

2. Implementieren Sie den Tool-Handler

Fügen Sie die Tool-Logik in der Funktion call_tool() hinzu:

@app.call_tool()
async def call_tool(name: str, arguments: Any) -> str:
    if name == "echo":
        text = arguments.get("text", "")
        return f"Echo: {text}"
    raise ValueError(f"Unknown tool: {name}")

3. Fügen Sie einen Prompt hinzu (optional)

Fügen Sie einen Prompt in der Funktion list_prompts() hinzu:

@app.list_prompts()
async def list_prompts() -> list[Prompt]:
    return [
        Prompt(
            name="example_prompt",
            description="An example prompt template",
            arguments=[
                PromptArgument(
                    name="topic",
                    description="The topic to write about",
                    required=True
                )
            ]
        )
    ]

Implementieren Sie dann den Handler in get_prompt():

@app.get_prompt()
async def get_prompt(name: str, arguments: dict[str, str] | None) -> str:
    if name == "example_prompt":
        topic = arguments.get("topic") if arguments else None
        if not topic:
            raise ValueError("Argument 'topic' is required")
        return f"Write a detailed explanation about {topic}."
    raise ValueError(f"Unknown prompt: {name}")

3. Starten Sie den Server

uv run python mcp_server.py

4. Konfigurieren Sie Ihren MCP-Client

Fügen Sie dies zur Konfiguration Ihres MCP-Clients hinzu:

{
  "mcpServers": {
    "your-server-name": {
      "command": "uv",
      "args": ["run", "python", "/path/to/mcp_server.py"]
    }
  }
}

Dokumentation

• ARCHITECTURE.md: Detaillierte Architektur-Dokumentation mit Mermaid-Diagrammen, die Folgendes zeigen:

  • Python-Module und ihre Zwecke

  • Komponenten-Interaktionen

  • Anforderungsabläufe (Tool-Aufruf, Ressourcenlesen)

  • Verwendete Entwurfsmuster

• SCALING_GUIDE.md: Best Practices für die Skalierung Ihres Servers:

  • Modularisierungsmuster

  • Strategien zur Zustandsverwaltung

  • Fehlerbehandlungsmuster

  • Protokollierung und Überwachung

  • Konfigurationsmanagement

  • Teststrategien

  • Leistungsoptimierung

  • Sicherheitsüberlegungen

Codestruktur

Die Hauptserverdatei (mcp_server.py) ist in Abschnitte unterteilt:

1. Server-Initialisierung: Erstellen der MCP-Server-Instanz

2. Tool-Registrierung: Definieren verfügbarer Tools

3. Tool-Handler: Implementieren der Tool-Ausführungslogik

4. Ressourcen-Registrierung: Definieren verfügbarer Ressourcen

5. Ressourcen-Handler: Implementieren der Ressourcen-Leselogik

6. Einstiegspunkt: Starten des Servers mit stdio-Kommunikation

Jeder Abschnitt enthält umfangreiche Inline-Kommentare, die den Zweck und die Verwendung jeder Komponente erläutern.

Erweiterungspunkte

Tools hinzufügen

1. Definieren Sie das Tool in list_tools() mit seinem Schema

2. Implementieren Sie den Handler in call_tool()

3. Verschieben Sie bei größeren Projekten den Code in ein separates Modul im Verzeichnis tools/

Prompts hinzufügen

1. Definieren Sie den Prompt in list_prompts() mit seinen Argumenten

2. Implementieren Sie den Handler in get_prompt()

3. Verschieben Sie bei größeren Projekten den Code in ein separates Modul im Verzeichnis prompts/

Ressourcen hinzufügen

1. Definieren Sie die Ressource in list_resources() mit ihren Metadaten

2. Implementieren Sie den Handler in read_resource()

3. Verschieben Sie bei größeren Projekten den Code in ein separates Modul im Verzeichnis resources/

Dienstprogramme hinzufügen

Extrahieren Sie gemeinsam genutzten Code in das Verzeichnis utils/:

• Validierungsfunktionen

• Protokollierungs-Helfer

• Konfigurationsmanagement

• Dienstprogramme zur Fehlerbehandlung

Verwendung als Basis

Dieses Boilerplate ist darauf ausgelegt, kopiert und für neue Projekte modifiziert zu werden:

1. Kopieren Sie das gesamte Projektverzeichnis

2. Benennen Sie das Projekt in pyproject.toml um

3. Aktualisieren Sie den Servernamen in mcp_server.py

4. Fügen Sie Ihre Tools, Ressourcen und Prompts hinzu

5. Passen Sie die Dokumentation nach Bedarf an

Verwendete Python-Module

• mcp.server.Server: Haupt-MCP-Serverklasse

• mcp.types.Tool: Tool-Typdefinition

• mcp.types.Resource: Ressourcen-Typdefinition

• mcp.types.Prompt: Prompt-Typdefinition

• mcp.types.PromptArgument: Prompt-Argument-Typdefinition

• mcp.server.stdio: Stdio-Kommunikationsstreams

• asyncio: Async/await für gleichzeitige Operationen

• typing: Typ-Hinweise für Code-Klarheit

Siehe ARCHITECTURE.md für detaillierte Erklärungen zu jedem Modul.

Entwicklung

Tests ausführen

# Run with pytest (add tests first)
uv run pytest

Codestil

Dieses Projekt verwendet Python-Typ-Hinweise und folgt den PEP 8-Konventionen. Erwägen Sie die Verwendung von:

• ruff für Linting

• mypy für Typüberprüfung

Abhängigkeiten hinzufügen

uv add <package-name>

Fehlerbehebung

• Importfehler: Führen Sie uv sync aus, um Abhängigkeiten zu installieren

• Server antwortet nicht: Überprüfen Sie die MCP-Client-Konfiguration

• Typfehler: Stellen Sie sicher, dass Python 3.10+ installiert ist

• uv-Befehl nicht gefunden: Installieren Sie uv von https://github.com/astral-sh/uv

Ressourcen

• MCP-Spezifikation

• MCP Python SDK

• uv-Dokumentation

Lizenz

Dieses Boilerplate wird für Bildungs- und Entwicklungszwecke bereitgestellt. Sie können es gerne für Ihre Projekte verwenden und modifizieren.