Communitygithub.com

ASoudy/AGS

Leitfaden zur Erstellung hochwertiger MCP-Server (Model Context Protocol), die LLMs die Interaktion mit externen Diensten durch gut gestaltete Tools ermöglicht. Verwende diesen bei der Entwicklung von MCP-Servern zur Integration externer APIs oder Dienste, sowohl in Python (FastMCP) als auch in Node/TypeScript (MCP SDK).

Was ist AGS?

Diese Skill-Anleitung beschreibt einen vollständigen vierphasigen Prozess zur Entwicklung hochwertiger MCP-Server. Sie beginnt mit einer gründlichen Forschungs- und Planungsphase, in der moderne MCP-Designprinzipien wie API-Abdeckung, Tool-Benennung und Fehlerbehandlung erlernt werden. In der Implementierungsphase werden Aufbau, Infrastruktur und die eigentlichen Tools codiert, wobei Sprachen wie TypeScript (empfohlen) oder Python mit entsprechenden Schemata wie Zod oder Pydantic verwendet werden. Die dritte Phase umfasst Codequalitätsprüfung und Tests mit dem MCP Inspector. Abschließend werden in Phase 4 umfassende Evaluationsszenarien erstellt, um die Effektivität des Servers mit realistischen, komplexen Fragen zu validieren. Diese Anleitung ist besonders nützlich für Entwickler, die mit den SDKs von MCP oder Frameworks wie FastMCP arbeiten und sicherstellen möchten, dass ihre Server für LLM-Agenten gut nutzbar sind.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/ASoudy/AGS/tree/HEAD/claude_skills_libraries/landing-page-mastery/skills/mcp-builder

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Leitfaden zur MCP-Serverentwicklung

Überblick

Erstelle MCP-Server (Model Context Protocol), die LLMs die Interaktion mit externen Diensten durch gut gestaltete Tools ermöglichen. Die Qualität eines MCP-Servers wird daran gemessen, wie gut er LLMs in die Lage versetzt, reale Aufgaben zu erledigen.


Prozess

🚀 Ablauf auf hoher Ebene

Die Erstellung eines hochwertigen MCP-Servers umfasst vier Hauptphasen:

Phase 1: Gründliche Recherche und Planung

1.1 Modernes MCP-Design verstehen

API-Abdeckung vs. Workflow-Tools: Bringe eine umfassende Abdeckung von API-Endpunkten mit spezialisierten Workflow-Tools in Einklang. Workflow-Tools können für bestimmte Aufgaben praktischer sein, während eine umfassende Abdeckung Agenten die Flexibilität gibt, Operationen zu kombinieren. Die Leistung variiert je nach Client – manche Clients profitieren von Codeausführung, die Basistools kombiniert, während andere besser mit übergeordneten Workflows arbeiten. Bei Unsicherheit priorisiere eine umfassende API-Abdeckung.

Tool-Benennung und Auffindbarkeit: Klare, beschreibende Tool-Namen helfen Agenten, die richtigen Tools schnell zu finden. Verwende konsistente Präfixe (z. B. github_create_issue, github_list_repos) und handlungsorientierte Benennung.

Kontextverwaltung: Agenten profitieren von prägnanten Tool-Beschreibungen und der Möglichkeit, Ergebnisse zu filtern/zu paginieren. Gestalte Tools, die fokussierte, relevante Daten zurückgeben. Manche Clients unterstützen Codeausführung, was Agenten helfen kann, Daten effizient zu filtern und zu verarbeiten.

Handlungsorientierte Fehlermeldungen: Fehlermeldungen sollten Agenten mit spezifischen Vorschlägen und nächsten Schritten zur Lösung führen.

1.2 MCP-Protokolldokumentation studieren

Navigiere durch die MCP-Spezifikation:

Beginne mit der Sitemap, um relevante Seiten zu finden: https://modelcontextprotocol.io/sitemap.xml

Rufe dann bestimmte Seiten mit dem Suffix .md für das Markdown-Format ab (z. B. https://modelcontextprotocol.io/specification/draft.md).

Wichtige Seiten, die zu prüfen sind:

  • Spezifikationsüberblick und Architektur
  • Transportmechanismen (streamable HTTP, stdio)
  • Tool-, Ressourcen- und Prompt-Definitionen

1.3 Framework-Dokumentation studieren

Empfohlener Stack:

  • Sprache: TypeScript (hochwertige SDK-Unterstützung und gute Kompatibilität in vielen Ausführungsumgebungen wie MCPB. Außerdem sind KI-Modelle gut darin, TypeScript-Code zu generieren, was von der breiten Nutzung, statischen Typisierung und guten Linting-Tools profitiert)
  • Transport: Streamable HTTP für entfernte Server, unter Verwendung von zustandslosem JSON (einfacher zu skalieren und zu warten, im Gegensatz zu zustandsbehafteten Sitzungen und Streaming-Antworten). stdio für lokale Server.

Lade die Framework-Dokumentation:

Für TypeScript (empfohlen):

  • TypeScript SDK: Verwende WebFetch, um https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md zu laden
  • ⚡ TypeScript-Anleitung – TypeScript-Muster und Beispiele

Für Python:

  • Python SDK: Verwende WebFetch, um https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md zu laden
  • 🐍 Python-Anleitung – Python-Muster und Beispiele

1.4 Implementierung planen

Die API verstehen: Überprüfe die API-Dokumentation des Dienstes, um wichtige Endpunkte, Authentifizierungsanforderungen und Datenmodelle zu identifizieren. Verwende bei Bedarf Websuche und WebFetch.

Tool-Auswahl: Priorisiere eine umfassende API-Abdeckung. Liste die zu implementierenden Endpunkte auf, beginnend mit den häufigsten Operationen.


Phase 2: Implementierung

2.1 Projektstruktur einrichten

Siehe sprachspezifische Anleitungen zur Projekteinrichtung:

2.2 Kerninfrastruktur implementieren

Erstelle gemeinsam genutzte Hilfsprogramme:

  • API-Client mit Authentifizierung
  • Fehlerbehandlungs-Helfer
  • Antwortformatierung (JSON/Markdown)
  • Paginierungsunterstützung

2.3 Tools implementieren

Für jedes Tool:

Eingabeschema:

  • Verwende Zod (TypeScript) oder Pydantic (Python)
  • Füge Einschränkungen und klare Beschreibungen hinzu
  • Füge Beispiele in Feldbeschreibungen ein

Ausgabeschema:

  • Definiere outputSchema wo möglich für strukturierte Daten
  • Verwende structuredContent in Tool-Antworten (TypeScript SDK-Funktion)
  • Hilft Clients, Tool-Ausgaben zu verstehen und zu verarbeiten

Tool-Beschreibung:

  • Prägnante Zusammenfassung der Funktionalität
  • Parameterbeschreibungen
  • Schema des Rückgabetyps

Implementierung:

  • Async/await für I/O-Operationen
  • Ordnungsgemäße Fehlerbehandlung mit handlungsorientierten Meldungen
  • Unterstützung von Paginierung, wo zutreffend
  • Rückgabe von Textinhalten und strukturierten Daten bei Verwendung moderner SDKs

Annotationen:

  • readOnlyHint: true/false
  • destructiveHint: true/false
  • idempotentHint: true/false
  • openWorldHint: true/false

Phase 3: Überprüfung und Test

3.1 Codequalität

Überprüfe auf:

  • Keinen doppelten Code (DRY-Prinzip)
  • Einheitliche Fehlerbehandlung
  • Vollständige Typabdeckung
  • Klare Tool-Beschreibungen

3.2 Bauen und Testen

TypeScript:

  • Führe npm run build aus, um die Kompilierung zu überprüfen
  • Teste mit MCP Inspector: npx @modelcontextprotocol/inspector

Python:

  • Überprüfe die Syntax: python -m py_compile your_server.py
  • Teste mit MCP Inspector

Siehe sprachspezifische Anleitungen für detaillierte Testansätze und Qualitätschecklisten.


Phase 4: Evaluierungen erstellen

Nach der Implementierung deines MCP-Servers erstelle umfassende Evaluierungen, um seine Effektivität zu testen.

Lade ✅ Evaluierungsanleitung für vollständige Evaluierungsrichtlinien.

4.1 Evaluierungszweck verstehen

Verwende Evaluierungen, um zu testen, ob LLMs deinen MCP-Server effektiv nutzen können, um realistische, komplexe Fragen zu beantworten.

4.2 10 Evaluierungsfragen erstellen

Um effektive Evaluierungen zu erstellen, folge dem in der Evaluierungsanleitung beschriebenen Prozess:

  1. Tool-Inspektion: Liste verfügbare Tools auf und verstehe ihre Fähigkeiten
  2. Inhaltserkundung: Verwende SCHREIBGESCHÜTZTE Operationen, um verfügbare Daten zu erkunden
  3. Fragenerstellung: Erstelle 10 komplexe, realistische Fragen
  4. Antwortüberprüfung: Löse jede Frage selbst, um Antworten zu verifizieren

4.3 Evaluierungsanforderungen

Stelle sicher, dass jede Frage:

  • Unabhängig: Nicht von anderen Fragen abhängig
  • Schreibgeschützt: Nur nicht-destruktive Operationen erforderlich
  • Komplex: Mehrere Tool-Aufrufe und tiefgehende Erkundung erforderlich
  • Realistisch: Basierend auf realen Anwendungsfällen, die für Menschen relevant sind
  • Überprüfbar: Einzelne, klare Antwort, die durch String-Vergleich verifiziert werden kann
  • Stabil: Antwort ändert sich im Laufe der Zeit nicht

4.4 Ausgabeformat

Erstelle eine XML-Datei mit dieser Struktur:

<evaluation>
  <qa_pair>
    <question>Finde Diskussionen über KI-Modellstarts mit Tier-Codenamen. Ein Modell benötigte eine spezifische Sicherheitskennzeichnung, die das Format ASL-X verwendet. Welche Zahl X wurde für das Modell bestimmt, das nach einer gefleckten Wildkatze benannt ist?</question>
    <answer>3</answer>
  </qa_pair>
<!-- Weitere qa_pairs... -->
</evaluation>

Referenzdateien

📚 Dokumentationsbibliothek

Lade diese Ressourcen bei Bedarf während der Entwicklung:

Kern-MCP-Dokumentation (zuerst laden)

  • MCP-Protokoll: Beginne mit der Sitemap unter https://modelcontextprotocol.io/sitemap.xml, rufe dann bestimmte Seiten mit dem Suffix .md ab
  • 📋 MCP Best Practices – Universelle MCP-Richtlinien einschließlich:
    • Server- und Tool-Benennungskonventionen
    • Richtlinien zum Antwortformat (JSON vs. Markdown)
    • Best Practices für Paginierung
    • Transportauswahl (streamable HTTP vs. stdio)
    • Sicherheits- und Fehlerbehandlungsstandards

SDK-Dokumentation (während Phase 1/2 laden)

  • Python SDK: Abrufen von https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.md
  • TypeScript SDK: Abrufen von https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.md

Sprachspezifische Implementierungsanleitungen (während Phase 2 laden)

  • 🐍 Python-Implementierungsanleitung – Vollständige Python/FastMCP-Anleitung mit:

    • Server-Initialisierungsmustern
    • Pydantic-Modellbeispielen
    • Tool-Registrierung mit @mcp.tool
    • Vollständigen funktionierenden Beispielen
    • Qualitätscheckliste
  • ⚡ TypeScript-Implementierungsanleitung – Vollständige TypeScript-Anleitung mit:

    • Projektstruktur
    • Zod-Schema-Mustern
    • Tool-Registrierung mit server.registerTool
    • Vollständigen funktionierenden Beispielen
    • Qualitätscheckliste

Evaluierungsanleitung (während Phase 4 laden)

  • ✅ Evaluierungsanleitung – Vollständige Anleitung zur Erstellung von Evaluierungen mit:
    • Richtlinien zur Fragenerstellung
    • Strategien zur Antwortüberprüfung
    • XML-Format-Spezifikationen
    • Beispielfragen und -antworten
    • Ausführen einer Evaluierung mit den bereitgestellten Skripten

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

ASoudy/AGS

Advanced JavaScript animation library skill for creating complex, high-performance web animations.

ASoudy/AGS

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis.

ASoudy/AGS

Build content-focused websites with Astro — zero JS by default, islands architecture, multi-framework components, and Markdown/MDX support.

ASoudy/AGS

One sentence - what this skill does and when to invoke it

ASoudy/AGS

Audit and fix animation performance issues including layout thrashing, compositor properties, scroll-linked motion, and blur effects. Use when animations stutter, transitions jank, or reviewing CSS/JS animation performance.

ASoudy/AGS

Internationalization and localization patterns. Detecting hardcoded strings, managing translations, locale files, RTL support.

ASoudy/AGS

Pull a YouTube video transcript into a queryable markdown vault with yt-dlp subtitle discovery, VTT cleanup, metadata frontmatter, and capture-seed stubs.

ASoudy/AGS

Expert in building portfolios that actually land jobs and clients - not just showing work, but creating memorable experiences. Covers developer portfolios, designer portfolios, creative portfolios, and portfolios that convert visitors into opportunities.

ASoudy/AGS

Generates high-converting Next.js/React landing pages with Tailwind CSS. Uses PAS, AIDA, and BAB frameworks for optimized copy/components (Heroes, Features, Pricing). Focuses on Core Web Vitals/SEO.

ASoudy/AGS

AI-powered animation tool for creating motion in logos, UI, icons, and social media assets.

ASoudy/AGS

CRITICAL: Use for Makepad animation system. Triggers on: makepad animation, makepad animator, makepad hover, makepad state, makepad transition, "from: { all: Forward", makepad pressed, makepad 动画, makepad 状态, makepad 过渡, makepad 悬停效果

ASoudy/AGS

Comprehensive patterns for Next.js 14+ App Router architecture, Server Components, and modern full-stack React development.

ASoudy/AGS

Next.js App Router principles. Server Components, data fetching, routing patterns.

ASoudy/AGS

Expert integration of Supabase Auth with Next.js App Router

ASoudy/AGS

React and Next.js 14+ application development with App Router, Server Components, TypeScript, Tailwind CSS, and modern frontend patterns.

ASoudy/AGS

Best practices for Remotion - Video creation in React

ASoudy/AGS

Generate walkthrough videos from Stitch projects using Remotion with smooth transitions, zooming, and text overlays

ASoudy/AGS

Seek and analyze video content using Memories.ai Large Visual Memory Model for persistent video intelligence

ASoudy/AGS

Writes complete, structured landing pages optimized for SEO ranking, AEO citation, and visitor conversion. Activate when the user wants to write or generate a landing page for a product, service, or offer.

ASoudy/AGS

Skill for discovering and researching autonomous AI agents, tools, and ecosystems using the AgentFolio directory.

Verwandte Skills