mcp-server-template

Ein produktionsreifer Ausgangspunkt für einen MCP-Server.

Der Schnellstart in der MCP-Dokumentation liefert dir in zehn Zeilen ein funktionierendes Tool. Das ist das, was du in den folgenden drei Wochen hinzufügst, sobald dieses Tool von etwas aufgerufen wird, das du nicht kontrollierst.

@mcp.tool()
def add(a: int, b: int) -> int:
    return a + b          # fine on a laptop

Was dort fehlt, sind keine Funktionen. Es ist das, was passiert, wenn das Tool hängt, eine Exception auslöst, einen Roman zurückgibt oder vierzig Mal gleichzeitig aufgerufen wird – und was das Modell in diesen Fällen sehen darf.

Das Problem, das dieses Template löst

Der Aufrufer eines MCP-Tools ist ein Sprachmodell, und das verändert die Technik.

• Ein Modell kann keinen Stacktrace lesen, aber es gibt freudig einen an deine Benutzer weiter. Ein ausgeleckter Stacktrace ist also sowohl nutzlos als auch eine Offenlegung.

• Ein Modell hat eine eigene Deadline. Ein Tool, das hängt, erzeugt keine langsame Antwort; es erzeugt eine tote Konversation.

• Ein Modell kann ein abgeschnittenes Ergebnis nicht von einem vollständigen unterscheiden. Wenn sein Kontext stillschweigend überläuft, wird kein Fehler ausgelöst – es verschlechtert die Antwort, und du erfährst es von einem Kunden.

• Ein Modell wird wiederholen, wenn du es lässt. „Nicht gefunden" und „Upstream ist down" müssen also unterschiedliche Antworten sein, sonst hämmert es einen Dienst für einen Datensatz, der nie existiert hat.

Jeder dieser Fälle wird nur einmal behandelt, und zwar an einer zentralen Stelle, sodass ein Tool, das am Freitagnachmittag hinzugefügt wird, denselben Schutz erbt wie das, das am ersten Tag sorgfältig geschrieben wurde.

Related MCP server: Graft

Was du bekommst

Schnellstart

git clone https://github.com/muhammadwaqasmbd/mcp-server-template
cd mcp-server-template
make install
make test
make run          # stdio, ready for a desktop MCP client

Stattdessen über das meinene Firefox anbieten:

TRANSPORT=streamable-http PORT=8000 python -m mcp_server_template

Einen Desktop-Client darauf gespeichert

{
  "mcpServers": {
    "template": {
      "command": "python",
      "args": ["-m", "mcp_server_template"],
      "cwd": "/absolute/path/to/mcp-server-template"
    }
  }
}

Ein eigenes Tool hinzufügen

Schreibe die Funktion. Sonst nichts.

# src/mcp_server_template/tools/orders.py
from ..errors import InvalidInput, UpstreamUnavailable

async def cancel_order(order_id: str) -> dict:
    """Cancel an order. Returns the order's new state."""
    if not order_id.strip():
        raise InvalidInput("order_id must not be empty")     # model can fix this
    ...
    raise UpstreamUnavailable("order service timed out")     # model may retry

Registriere es hinter der Die „schütz“:

mcp.tool(name="cancel_order", description="Cancel an order by id.")(
    guard.wrap(orders.cancel_order)
)

Es hat jetzt den Timeout, die Obergrenze, die Fehlergrenze, die Kürzung und es Logging. Du hast davon nichts geschrieben.

Wirf InvalidInput, wenn das Modell es korrigieren kann. Wirf UpstreamUnavailable, wenn ein weiterer Versuch helfen könnte. Gib für schlicht negative Ergebnisse einfach normal zurück – ein fehlender Datensatz ist eine Antwort, kein Fehler.

Stylish

server.py      the ONLY module that imports the MCP SDK
   │
   ├── guard.py          timeout · concurrency · error boundary · truncation · timing
   ├── errors.py         what a model is allowed to see, and secret redaction
   ├── observability.py  JSON logs on stderr, correlation ids
   ├── config.py         validated once at boot, immutable thereafter
   └── tools/            plain functions. No protocol knowledge. No decorators

Der Beunruhigt Diepteilt zeigt in eine Richtung: Tools wissen nichts über das Programm, und die Schutzschicht weiß nichts über Tools. Deshalb laufen die Tests in Millisekunden ohne einen Server, und deshalb betrifft eine SD-Kerne genau eine Datei.

Was dieses Bewusst nicht tut

Die „Ränder“ ehrlich darüber zu sagen ist gerade Funktionen mehr.

• Keine Authentifizierung. Über stdio der System des Betriebssystems ist die Sicherheitsgrenze. Wenn du in HTTP machst, Getreide ein echter Schulschutz davor – die SDK unterstützt das, es hier zu verdrahten in einem Gefahrenmodell implizieren.

• Keine Retry-Logik in den Tools. Die STUFF gibt mit, ob ein Fehler wieder anfällig ist; sagt euch nicht ob, der Aufrufer hat die Kontext und das Budget.

• Keine Beschleunigungsbegrenzung pro Anfrage. Die Obergrenze begrenzt die Gesamtarbeit, nicht die Fairness zwischen Identitäten. Wenn du das brauchst, brauchst du zuerst eine Identität.

• Keine anhaltende, Warteschlange oder Scheduler. Der Tool-Erf ist zu einem „Job Runner“ ohne Schritt wurde und wurde dies, ist ein verteiltes System, das niemanden absichtlich entwaren – eine Wendung.

• Keine Streaming-Ergebnisse. Sinnvoll einge, wenn langlaufende Tools, kannst du es an; die Fehlergrenze macht es schwieriger – die meisten Tools brauchen es nicht.

Testen

make test

Zuversicht, die Suite schlägt fehl: Es gibt keinen Fehler, einangehaltenes Tool wird abgebrochen, eine unerwartete Exception kann die Nachricht nicht warten, Überdimensionierte Ausgabe wird sichtbar gekürzt, die Obergrenze keine unter zehn Aufrufen liegt, und es wird kein nicht blockierender Sync-Tool kann jedoch den Event-Loop nicht wirklich – ale.

Lizenz

MIT – Siehe LICENSE.

Gebaut von Muhammad Waqas, der den größten Teil seiner Zeit im Agentensystemen verbraucht in regulierten Regionen, wo eine sichere falsche Antwort ein meldepflichtiger Unfall ist.