gaelic-ghost/python-skills

Python MCP-Service bootstrappen

Zweck

Erstelle FastMCP-Startlayouts mit einem einzigen direkten Shell-Einstiegspunkt, der von den gemeinsam genutzten bootstrap-uv-python-workspace-Scaffolding-Skripten plus deterministischer MCP-Overlay-Logik unterstützt wird.

Wann verwenden

• Verwende diesen Skill für neue FastMCP-Server-Gerüste.
• Verwende diesen Skill, wenn der Nutzer OpenAPI- oder FastAPI-zu-MCP-Mapping-Anleitung zusammen mit dem Bootstrap wünscht.
• Empfehle bootstrap-python-service, wenn der Nutzer einen FastAPI-Dienst, aber keinen MCP-Server wünscht.

Ein-Pfad-Workflow

1. Sammle die erforderlichen Eingaben:
   • name
   • mode
   • path
   • optional: python, members, profile_map, force, initial_commit, no_git_init
2. Führe den kanonischen Einstiegspunkt aus:

   scripts/init_fastmcp_service.sh --name <name> --mode <project|workspace>
   

3. Lasse das Skript an die gemeinsame bootstrap-uv-python-workspace-Scaffolding-Schicht delegieren und dann das FastMCP-Overlay anwenden.
4. Akzeptiere den integrierten Validierungspfad:
   • uv run pytest
   • uv run ruff check .
   • uv run mypy .
5. Bestätige, dass das generierte Projekt Folgendes enthält:
   • eine committete .env für sichere Standardwerte
   • eine ignorierte .env.local für maschinenlokale oder geheime Überschreibungen
   • typisierte Konfiguration via pydantic-settings
6. Wenn die Aufgabe von einer bestehenden API ausgeht, erstelle optional einen Mapping-Bericht mit uv run scripts/assess_api_for_mcp.py ....
7. Gib den generierten Pfad sowie die genauen, vom Skript ausgegebenen nächsten Befehlsschritte zurück.

Befehle

# Projektmodus (Standard)
scripts/init_fastmcp_service.sh --name my-mcp-server

# Projektmodus mit expliziten Optionen
scripts/init_fastmcp_service.sh --name my-mcp-server --mode project --python 3.13 --path /tmp/my-mcp-server

# Workspace-Modus mit Standardwerten (core-lib Paket + api-service Dienst)
scripts/init_fastmcp_service.sh --name platform --mode workspace

# Workspace-Modus mit expliziten Mitgliedern und Profilzuordnung
scripts/init_fastmcp_service.sh \
  --name platform \
  --mode workspace \
  --members "core-lib,tools-service,ops-service" \
  --profile-map "core-lib=package,tools-service=service,ops-service=service"

# Nicht-leeres Zielverzeichnis zulassen
scripts/init_fastmcp_service.sh --name my-mcp-server --force

# Git-Initialisierung überspringen
scripts/init_fastmcp_service.sh --name my-mcp-server --no-git-init

# Ersten Commit erstellen
scripts/init_fastmcp_service.sh --name my-mcp-server --initial-commit

# MCP-Mapping-Anleitung aus OpenAPI generieren
uv run scripts/assess_api_for_mcp.py --openapi ./openapi.yaml --out ./mcp_mapping_report.md

# MCP-Mapping-Anleitung aus bestehender FastAPI-App generieren
uv run scripts/assess_api_for_mcp.py --fastapi app.main:app --out ./mcp_mapping_report.md

Eingaben

• name: erforderlich
• mode: project oder workspace; Standard ist project
• path: optionales Zielverzeichnis; Standard ist ./<name>
• python: optionale Python-Version; Standard ist 3.13
• members: optionales Komma-getrenntes Workspace-Mitglieder für Workspace-Modus
• profile_map: optionales Komma-getrenntes Workspace-Profil für Workspace-Modus
• force: optionales Flag, das nicht-leere Zielverzeichnisse erlaubt
• initial_commit: optionales Flag, das nach erfolgreichem Scaffolding einen ersten Commit erstellt
• no_git_init: optionales Flag, das die Git-Initialisierung deaktiviert

Ausgaben

• status
  • success: Scaffolding und integrierte Validierung abgeschlossen
  • blocked: Voraussetzungen oder Zielverzeichnis-Beschränkungen verhinderten die Ausführung
  • failed: Das Skript wurde gestartet, aber die Validierung oder Generierung schlug fehl
• path_type
  • primary: Der kanonische Shell-Einstiegspunkt abgeschlossen
• output
  • aufgelöster Projekt- oder Workspace-Pfad
  • ausgegebene Laufbefehle
  • ausgegebene Validierungsbefehle
  • optionaler Mapping-Berichtspfad

Standardwerte

• Modus: project
• Python-Version: 3.13
• Qualitätswerkzeuge: pytest, ruff, mypy
• Konfigurationsbasis: committete .env, ignorierte .env.local und pydantic-settings
• Standard-Workspace-Mitglieder: core-lib,api-service
• Standard-Workspace-Profile: erster Mitglied package, restliche Mitglieder service

Basis-UV/FastAPI-Anleitung

Das gemeinsame Scaffolding folgt dem UV-FastAPI-Integrationsstil:

uv add fastapi --extra standard
uv add pydantic-settings python-dotenv
uv run fastapi dev app/main.py

Dieser Skill legt dann FastMCP-Abhängigkeiten und Serverdateien für MCP-Dienst-Mitglieder darüber. Generierte FastMCP-Gerüste sollten sichere Standardwerte in .env, lokale oder geheime Überschreibungen in .env.local und typisierte Laufzeitkonfiguration in app/config.py behalten.

API-Import-Anleitung

Bei Start von OpenAPI oder FastAPI zuerst bootstrappen, dann Endpunkte auf MCP-Primitive abbilden:

1. Generiere einen Mapping-Bericht mit scripts/assess_api_for_mcp.py.
2. Klassifiziere Endpunkte in Resources, Tools und Prompts.
3. Empfehle RouteMaps/Transforms nur, wenn sie die Benutzerfreundlichkeit verbessern.
4. Halte das Bootstrapping deterministisch; verschiebe aufwändiges benutzerdefiniertes Mapping, es sei denn, es wird angefordert.

FastMCP-Dokumentensuche

Verwende den fastmcp_docs MCP-Server für aktuelle Framework-Details.

Vorgeschlagene Abfragen:

• FastMCP quickstart server example
• FastMCP tools resources prompts best practices
• FastMCP RouteMap Transform
• FastMCP from OpenAPI
• FastMCP from FastAPI

Schutzmaßnahmen

• Verweigere nicht-leere Zielverzeichnisse, es sei denn, --force ist gesetzt.
• Erfordere mindestens ein Dienstprofil-Mitglied im Workspace-Modus.
• Erfordere uv und git, es sei denn, die Git-Initialisierung wurde explizit deaktiviert.
• Schlage fehl, wenn Workspace-spezifische Optionen im Projektmodus verwendet werden.
• Schlage fehl, wenn --initial-commit mit --no-git-init kombiniert wird.

Rückfallebenen und Übergaben

• Der bevorzugte Pfad ist immer scripts/init_fastmcp_service.sh.
• Verwende bootstrap-python-service, wenn der Nutzer nur FastAPI-Ausgabe wünscht.
• Verwende bootstrap-uv-python-workspace nur direkt, wenn das FastMCP-spezifische Verhalten nicht gewünscht wird.
• Empfehle integrate-fastapi-fastmcp, wenn der Nutzer diese FastMCP-Ausgabe in eine bestehende FastAPI-App integrieren, einen MCP-Server in FastAPI einhängen oder generierte FastAPI-abgeleitete MCP-Ausgabe in eine kuratierte kombinierte Architektur überführen muss.

Automatisierungseignung

• Codex App-Automatisierung: Mittel. Nützlich für wiederkehrende FastMCP-Gerüstprüfungen und Mapping-Bewertungsprüfungen.
• Codex CLI-Automatisierung: Hoch. Starke Eignung für CI-artige Gerüstvalidierung.

Codex App-Automatisierungsvorlage

Verwende $bootstrap-python-mcp-service.

Grenzen des Umfangs:
- Arbeite nur innerhalb von <REPO_PATH>.
- Erstelle oder validiere die Gerüstausgabe nur in <TARGET_PATH>.
- Beschränke die Arbeit auf Gerüsterstellung, optionale Berichterstellung und Verifizierung.

Aufgabe:
1. Wenn <MODE:PROJECT|WORKSPACE> PROJECT ist, führe aus:
   `scripts/init_fastmcp_service.sh --name <MCP_SERVICE_NAME> --mode project --path <TARGET_PATH> --python <PYTHON_VERSION> <FORCE_FLAG> <GIT_INIT_MODE>`
2. Wenn <MODE:PROJECT|WORKSPACE> WORKSPACE ist, führe aus:
   `scripts/init_fastmcp_service.sh --name <MCP_SERVICE_NAME> --mode workspace --path <TARGET_PATH> --python <PYTHON_VERSION> --members "<MEMBERS_CSV>" --profile-map "<PROFILE_MAP>" <FORCE_FLAG> <GIT_INIT_MODE>`
3. Wenn <GENERATE_MAPPING_REPORT:TRUE|FALSE> TRUE ist:
   - Wenn <MAPPING_INPUT_MODE:NONE|OPENAPI|FASTAPI_IMPORT> OPENAPI ist, führe aus:
     `uv run scripts/assess_api_for_mcp.py --openapi <MAPPING_INPUT_PATH> --out <TARGET_PATH>/mcp_mapping_report.md`
   - Wenn <MAPPING_INPUT_MODE:NONE|OPENAPI|FASTAPI_IMPORT> FASTAPI_IMPORT ist, führe aus:
     `uv run scripts/assess_api_for_mcp.py --fastapi <MAPPING_INPUT_PATH> --out <TARGET_PATH>/mcp_mapping_report.md`
4. Führe Verifizierungsprüfungen in <TARGET_PATH> durch:
   - `uv run pytest`
   - `uv run ruff check .`
   - `uv run mypy .`

Ausgabe-Vertrag:
1. STATUS: PASS oder FAIL
2. COMMANDS: ausgeführte Befehle
3. RESULTS: prägnante Ergebnisse für Gerüst und Prüfungen
4. Wenn Bericht generiert wurde: Pfad zum Bericht angeben
5. Bei FAIL: wahrscheinliche Ursache und minimale Abhilfe nennen

Codex CLI-Automatisierungsvorlage

codex exec --full-auto --sandbox workspace-write --cd "<REPO_PATH>" "<PROMPT_BODY>"

<PROMPT_BODY>-Vorlage:

Verwende $bootstrap-python-mcp-service.
Der Umfang ist beschränkt auf die Gerüsterstellung in <TARGET_PATH>, optionale Berichterstellung und Verifizierungsprüfungen.
Führe nur die für diesen Ablauf erforderlichen Befehle aus und gib dann STATUS, genaues Befehlsprotokoll, prägnante Ergebnisse und minimale Abhilfe bei Fehlern zurück.

Platzhalter für Anpassung

• <REPO_PATH>
• <MCP_SERVICE_NAME>
• <MODE:PROJECT|WORKSPACE>
• <TARGET_PATH>
• <PYTHON_VERSION>
• <MEMBERS_CSV>
• <PROFILE_MAP>
• <FORCE_FLAG>
• <GIT_INIT_MODE>
• <MAPPING_INPUT_MODE:NONE|OPENAPI|FASTAPI_IMPORT>
• <MAPPING_INPUT_PATH>
• <GENERATE_MAPPING_REPORT:TRUE|FALSE>

Interaktiver Anpassungsworkflow

1. Frage nach Modus, Name, Pfad, Python-Version und Git/Force-Flags.
2. Wenn Workspace-Modus, frage auch nach Mitgliedern und Profilzuordnung.
3. Gib beides zurück:
   • Ein YAML-Profil zur dauerhaften Wiederverwendung.
   • Den genauen Gerüstbefehl zur Ausführung.
4. Verwende diese Rangfolge:
   • CLI-Flags
   • --config Profildatei
   • .codex/profiles/bootstrap-python-mcp-service/customization.yaml
   • ~/.config/gaelic-ghost/python-skills/bootstrap-python-mcp-service/customization.yaml
   • Skript-Standardwerte
5. Wenn Nutzer temporäres Reset-Verhalten wünschen:
   • --bypassing-all-profiles
   • --bypassing-repo-profile
   • --deleting-repo-profile
6. Wenn Nutzer keine Anpassung oder Profildateien bereitstellen, behalte die bestehenden Skript-Standardwerte unverändert bei.
7. Siehe references/interactive-customization.md für Schema und Beispiele.

Referenzen

• references/mcp-mapping-guidelines.md
• references/fastmcp-docs-lookup.md
• references/customization.md
• references/interactive-customization.md

Skriptinventar

• scripts/init_fastmcp_service.sh
• scripts/assess_api_for_mcp.py
• Delegiert an die gemeinsamen Workspace-Bootstrap-Skripte, die von bootstrap-uv-python-workspace bereitgestellt werden.

Assets

• assets/README.md.tmpl