gaelic-ghost/python-skills

FastMCP Python 서비스 부트스트랩

목적

공유 bootstrap-uv-python-workspace 스캐폴딩 스크립트와 결정론적 MCP 오버레이 로직을 기반으로 단일 셸 진입점을 사용하여 FastMCP 스타터 레이아웃을 생성합니다.

사용 시기

• 새로운 FastMCP 서버 스캐폴드에 이 스킬을 사용하세요.
• 사용자가 부트스트래핑과 함께 OpenAPI 또는 FastAPI-to-MCP 매핑 가이드를 원할 때 이 스킬을 사용하세요.
• 사용자가 MCP 서버가 아닌 FastAPI 서비스를 원하면 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. 사용성을 향상시키는 경우에만 RouteMap/Transform을 권장합니다.
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가 설정되지 않으면 비어 있지 않은 대상 디렉터리를 거부합니다.
• 워크스페이스 모드에서 최소 하나의 서비스 프로필 멤버를 요구합니다.
• 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 자동화 프롬프트 템플릿

$bootstrap-python-mcp-service를 사용하세요.

범위 경계:
* `<REPO_PATH>` 내에서만 작업하세요.
* `<TARGET_PATH>`에서만 스캐폴드 출력을 생성하거나 검증하세요.
* 스캐폴드 생성, 선택적 매핑 보고서 생성 및 확인으로 작업을 제한하세요.

작업:
1. <MODE:PROJECT|WORKSPACE>가 PROJECT이면 다음을 실행:
   `scripts/init_fastmcp_service.sh --name <MCP_SERVICE_NAME> --mode project --path <TARGET_PATH> --python <PYTHON_VERSION> <FORCE_FLAG> <GIT_INIT_MODE>`
2. <MODE:PROJECT|WORKSPACE>가 WORKSPACE이면 다음을 실행:
   `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. <GENERATE_MAPPING_REPORT:TRUE|FALSE>가 TRUE이면:
   * <MAPPING_INPUT_MODE:NONE|OPENAPI|FASTAPI_IMPORT>가 OPENAPI이면 다음을 실행:
     `uv run scripts/assess_api_for_mcp.py --openapi <MAPPING_INPUT_PATH> --out <TARGET_PATH>/mcp_mapping_report.md`
   * <MAPPING_INPUT_MODE:NONE|OPENAPI|FASTAPI_IMPORT>가 FASTAPI_IMPORT이면 다음을 실행:
     `uv run scripts/assess_api_for_mcp.py --fastapi <MAPPING_INPUT_PATH> --out <TARGET_PATH>/mcp_mapping_report.md`
4. `<TARGET_PATH>`에서 확인 검사 실행:
   * `uv run pytest`
   * `uv run ruff check .`
   * `uv run mypy .`

출력 계약:
1. STATUS: PASS 또는 FAIL
2. COMMANDS: 실행된 정확한 명령
3. RESULTS: 스캐폴드 및 검사에 대한 간결한 결과
4. 보고서가 생성된 경우: 보고서 경로 포함
5. FAIL인 경우: 가능한 근본 원인과 최소한의 수정 제안 제공

Codex CLI 자동화 프롬프트 템플릿

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

<PROMPT_BODY> 템플릿:

$bootstrap-python-mcp-service를 사용하세요.
범위는 `<TARGET_PATH>`에서의 스캐폴드 생성, 선택적 매핑 보고서 생성 및 확인 검사로 제한됩니다.
이 흐름에 필요한 명령만 실행한 다음 STATUS, 정확한 명령 기록, 간결한 결과 및 실패 발생 시 최소한의 수정을 반환하세요.

사용자 정의 플레이스홀더

• <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. mode, name, path, Python 버전 및 git/force 플래그를 물어보세요.
2. 워크스페이스 모드인 경우 members와 profile_map도 물어보세요.
3. 다음을 모두 반환:
   • 지속적인 재사용을 위한 YAML 프로필.
   • 실행할 정확한 스캐폴드 명령.
4. 이 우선 순위 순서를 사용:
   • CLI 플래그
   • --config 프로필 파일
   • .codex/profiles/bootstrap-python-mcp-service/customization.yaml
   • ~/.config/gaelic-ghost/python-skills/bootstrap-python-mcp-service/customization.yaml
   • 스크립트 기본값
5. 사용자가 임시 재설정 동작을 원하는 경우:
   • --bypassing-all-profiles
   • --bypassing-repo-profile
   • --deleting-repo-profile
6. 사용자가 사용자 정의 또는 프로필 파일을 제공하지 않으면 기존 스크립트 기본값을 그대로 유지합니다.
7. 스키마 및 예제는 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