Communityコーディング＆開発github.com

gaelic-ghost/python-skills

Python開発のためのCodexスキル: uv、FastAPI、FastMCP、pytestワークフロー。

python-skills とは？

このスキルは、Codex（Codex CLIまたはCodex App）を使用してFastMCPサーバースキャフォールドを作成するためのものです。`scripts/init_fastmcp_service.sh`という単一のシェルエントリポイントを提供し、共有の`bootstrap-uv-python-workspace`スクリプトと決定論的なFastMCPオーバーレイロジックを組み合わせます。プロジェクトモード（単一サービス）とワークスペースモード（複数サービス）の両方をサポートし、pydantic-settingsによる型安全な設定、pytest、ruff、mypyによる品質チェックを自動的に行います。また、既存のFastAPIまたはOpenAPI仕様からMCPマッピングレポートを生成する`assess_api_for_mcp.py`も含まれており、FastMCPとFastAPIの統合を容易にします。

対応~Claude Code✓Codex CLI~Cursor
npx skills add gaelic-ghost/python-skills

Installed? Explore more コーディング＆開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

オリジナルを見る→すべてのスキルを見る

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

ドキュメント

Bootstrap Python MCP Service

目的

FastMCPスターターレイアウトを、共有のbootstrap-uv-python-workspaceスキャフォールディングスクリプトと決定論的なMCPオーバーレイロジックをバックエンドとした単一のシェルエントリポイントを使用して作成します。

使用するタイミング

  • 新しいFastMCPサーバースキャフォールドにはこのスキルを使用します。
  • ユーザーがOpenAPIやFastAPIからMCPへのマッピングガイダンスをブートストラップと一緒に希望する場合に使用します。
  • ユーザーがFastAPIサービス（MCPサーバーではない）を希望する場合は、bootstrap-python-serviceを推奨します。

単一パスワークフロー

  1. 必要な入力を収集します:
    • name
    • mode
    • path
    • オプション: python、members、profile_map、force、initial_commit、no_git_init
  2. 標準エントリポイントを実行します: 
    scripts/init_fastmcp_service.sh --name <name> --mode <project|workspace>
  3. スクリプトが共有のbootstrap-uv-python-workspaceスキャフォールディングレイヤーに委譲し、その後FastMCPオーバーレイを適用するのを待ちます。
  4. 組み込みの検証パスを受け入れます:
    • uv run pytest
    • uv run ruff check .
    • uv run mypy .
  5. 生成されたプロジェクトに以下が含まれていることを確認します:
    • 安全なデフォルト値用のコミット済み.env
    • マシンローカルまたはシークレットのオーバーライド用の無視される.env.local
    • pydantic-settingsによる型付き設定
  6. タスクが既存のAPIから始まる場合、オプションでuv run scripts/assess_api_for_mcp.py ...を使用してマッピングレポートを生成します。
  7. 生成されたパスと、スクリプトによって出力された正確な次のステップのコマンドを返します。

コマンド

# プロジェクトモード（デフォルト）
scripts/init_fastmcp_service.sh --name my-mcp-server

# 明示的なオプション付きプロジェクトモード
scripts/init_fastmcp_service.sh --name my-mcp-server --mode project --python 3.13 --path /tmp/my-mcp-server

# デフォルト値を使用したワークスペースモード（core-libパッケージ + api-serviceサービス）
scripts/init_fastmcp_service.sh --name platform --mode workspace

# 明示的なメンバーとプロファイルマッピングを使用したワークスペースモード
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"

# 空でないターゲットディレクトリを許可
scripts/init_fastmcp_service.sh --name my-mcp-server --force

# Git初期化をスキップ
scripts/init_fastmcp_service.sh --name my-mcp-server --no-git-init

# 初期コミットを作成
scripts/init_fastmcp_service.sh --name my-mcp-server --initial-commit

# OpenAPIからMCPマッピングガイダンスを生成
uv run scripts/assess_api_for_mcp.py --openapi ./openapi.yaml --out ./mcp_mapping_report.md

# 既存のFastAPIアプリからMCPマッピングガイダンスを生成
uv run scripts/assess_api_for_mcp.py --fastapi app.main:app --out ./mcp_mapping_report.md

入力

  • name: 必須
  • mode: project または workspace; デフォルトは project
  • path: オプションのターゲットディレクトリ; デフォルトは ./<name>
  • python: オプションのPythonバージョン; デフォルトは 3.13
  • members: ワークスペースモード用のオプションのワークスペースメンバーCSV
  • profile_map: ワークスペースモード用のオプションのワークスペースプロファイルCSV
  • force: 空でないターゲットディレクトリを許可するオプションフラグ
  • initial_commit: スキャフォールディング成功後に初期コミットを作成するオプションフラグ
  • no_git_init: Git初期化を無効にするオプションフラグ

出力

  • status
    • success: スキャフォールドと組み込み検証が完了
    • blocked: 前提条件またはターゲットディレクトリの制約により実行が妨げられた
    • failed: スクリプトは開始されたが、検証または生成に失敗した
  • path_type
    • primary: 標準シェルエントリポイントが完了
  • output
    • 解決されたプロジェクトまたはワークスペースのパス
    • 発行された実行コマンド
    • 発行された検証コマンド
    • オプションのマッピングレポートパス

デフォルト値

  • mode: project
  • Pythonバージョン: 3.13
  • 品質ツール: pytest、ruff、mypy
  • 設定ベースライン: コミット済み.env、無視される.env.local、およびpydantic-settings
  • ワークスペースデフォルトメンバー: core-lib,api-service
  • ワークスペースデフォルトプロファイル: 最初のメンバー package、残りのメンバー service

ベースUV/FastAPIガイダンス

共有スキャフォールドベースは、uv FastAPI統合スタイルに従います:

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

このスキルはその後、MCPサービスのメンバー用にFastMCP依存関係とサーバーファイルをオーバーレイします。 生成されたFastMCPスキャフォールドは、.envに安全なデフォルト値を、.env.localにローカルまたはシークレットのオーバーライドを、そしてapp/config.pyに型付きランタイム設定を保持する必要があります。

APIインポートガイダンス

OpenAPIまたはFastAPIから始める場合、最初にブートストラップし、次にエンドポイントをMCPプリミティブにマッピングします:

  1. scripts/assess_api_for_mcp.pyでマッピングレポートを生成します。
  2. エンドポイントをResources、Tools、Promptsに分類します。
  3. ユーザビリティが向上する場合にのみ、RouteMaps/Transformsを推奨します。
  4. ブートストラップは決定論的に保ち、要求がない限り過度なカスタムマッピングは行いません。

FastMCPドキュメント参照

最新のフレームワーク詳細については、fastmcp_docs MCPサーバーを使用してください。

推奨クエリ:

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

ガードレール

  • --forceが設定されていない限り、空でないターゲットディレクトリを拒否します。
  • ワークスペースモードでは、少なくとも1つのサービスプロファイルメンバーが必要です。
  • Git初期化が明示的に無効にされていない限り、uvとgitが必要です。
  • ワークスペース専用オプションがプロジェクトモードで使用された場合は失敗します。
  • --initial-commitが--no-git-initと組み合わせて使用された場合は失敗します。

フォールバックとハンドオフ

  • 推奨パスは常にscripts/init_fastmcp_service.shです。
  • ユーザーがFastAPIのみの出力を希望する場合は、bootstrap-python-serviceを使用します。
  • FastMCP固有の動作が必要ない場合にのみ、bootstrap-uv-python-workspaceを直接使用します。
  • このFastMCP出力を既存のFastAPIアプリに統合する必要がある場合、FastAPIにMCPサーバーをマウントする場合、または生成されたFastAPI由来のMCP出力を厳選された統合アーキテクチャに昇格させる必要がある場合は、integrate-fastapi-fastmcpを推奨します。

自動化適合性

  • Codex App自動化: 中。定期的なFastMCPスキャフォールドチェックおよびマッピング評価チェックに有用。
  • Codex CLI自動化: 高。CIスタイルのスキャフォールド検証に強く適合。

Codex App自動化プロンプトテンプレート

Use $bootstrap-python-mcp-service.

Scope boundaries:
- Work only inside <REPO_PATH>.
- Create or validate scaffold output only in <TARGET_PATH>.
- Restrict work to scaffold generation, optional mapping report generation, and verification.

Task:
1. If <MODE:PROJECT|WORKSPACE> is PROJECT, run:
   `scripts/init_fastmcp_service.sh --name <MCP_SERVICE_NAME> --mode project --path <TARGET_PATH> --python <PYTHON_VERSION> <FORCE_FLAG> <GIT_INIT_MODE>`
2. If <MODE:PROJECT|WORKSPACE> is WORKSPACE, run:
   `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. If <GENERATE_MAPPING_REPORT:TRUE|FALSE> is TRUE:
   - If <MAPPING_INPUT_MODE:NONE|OPENAPI|FASTAPI_IMPORT> is OPENAPI, run:
     `uv run scripts/assess_api_for_mcp.py --openapi <MAPPING_INPUT_PATH> --out <TARGET_PATH>/mcp_mapping_report.md`
   - If <MAPPING_INPUT_MODE:NONE|OPENAPI|FASTAPI_IMPORT> is FASTAPI_IMPORT, run:
     `uv run scripts/assess_api_for_mcp.py --fastapi <MAPPING_INPUT_PATH> --out <TARGET_PATH>/mcp_mapping_report.md`
4. Run verification checks in <TARGET_PATH>:
   - `uv run pytest`
   - `uv run ruff check .`
   - `uv run mypy .`

Output contract:
1. STATUS: PASS or FAIL
2. COMMANDS: exact commands executed
3. RESULTS: concise outcomes for scaffold and checks
4. If report generated: include report path
5. If FAIL: provide likely root cause and minimal remediation

Codex CLI自動化プロンプトテンプレート

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

<PROMPT_BODY> テンプレート:

Use $bootstrap-python-mcp-service.
Scope is limited to scaffold generation in <TARGET_PATH>, optional mapping report generation, and verification checks.
Run only commands needed for this flow, then return STATUS, exact command transcript, concise results, and minimal remediation if failures occur.

カスタマイズプレースホルダー

  • <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>

インタラクティブカスタマイズワークフロー

  1. モード、名前、パス、Pythonバージョン、git/forceフラグを尋ねます。
  2. ワークスペースモードの場合、メンバーとプロファイルマップも尋ねます。
  3. 以下を両方返します:
  • 再利用可能なYAMLプロファイル。
  • 実行する正確なスキャフォールドコマンド。
  1. この優先順位を使用します:
  • CLIフラグ
  • --config プロファイルファイル
  • .codex/profiles/bootstrap-python-mcp-service/customization.yaml
  • ~/.config/gaelic-ghost/python-skills/bootstrap-python-mcp-service/customization.yaml
  • スクリプトのデフォルト値
  1. ユーザーが一時的なリセット動作を希望する場合:
  • --bypassing-all-profiles
  • --bypassing-repo-profile
  • --deleting-repo-profile
  1. ユーザーがカスタマイズやプロファイルファイルを提供しない場合、既存のスクリプトデフォルト値を変更しません。
  2. スキーマと例については、references/interactive-customization.md を参照してください。

参考文献

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

スクリプト一覧

  • scripts/init_fastmcp_service.sh
  • scripts/assess_api_for_mcp.py
  • 共有ワークスペースブートストラップスクリプト（bootstrap-uv-python-workspaceが出荷）に委譲します。

アセット

  • assets/README.md.tmpl

関連スキル

steipete/bluebubbles

Send and manage iMessages via BlueBubbles, including attachments, tapbacks, edits, replies, and groups.

community

steipete/eightctl

Control Eight Sleep pods (status, temperature, alarms, schedules).

community

steipete/blucli

BluOS CLI (blu) for discovery, playback, grouping, and volume.

community

steipete/bear-notes

Create, search, and manage Bear notes via grizzly CLI.

community

steipete/camsnap

Capture frames or clips from RTSP/ONVIF cameras.

community

steipete/gifgrep

Search GIF providers with CLI/TUI, download results, and extract stills/sheets.

community
← More コーディング＆開発 skills