bootstrap-python-mcp-service

Bootstrap Python MCP Service

Purpose

Create FastMCP starter layouts using one direct shell entrypoint backed by the shared bootstrap-uv-python-workspace scaffolding scripts plus deterministic MCP overlay logic.

When To Use

• Use this skill for new FastMCP server scaffolds.
• Use this skill when the user wants OpenAPI or FastAPI-to-MCP mapping guidance alongside bootstrap.
• Recommend bootstrap-python-service when the user wants a FastAPI service but not an MCP server.

Single-Path Workflow

1. Collect the required inputs:
   • name
   • mode
   • path
   • optional python, members, profile_map, force, initial_commit, no_git_init
2. Run the canonical entrypoint:

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

3. Let the script delegate to the shared bootstrap-uv-python-workspace scaffolding layer, then apply the FastMCP overlay.
4. Accept the built-in validation path:
   • uv run pytest
   • uv run ruff check .
   • uv run mypy .
5. Confirm the generated project includes:
   • a committed .env for safe defaults
   • an ignored .env.local for machine-local or secret overrides
   • typed configuration via pydantic-settings
6. If the task starts from an existing API, optionally generate a mapping report with uv run scripts/assess_api_for_mcp.py ....
7. Return the generated path plus the exact next-step commands emitted by the script.

Commands

# Project mode (default)
scripts/init_fastmcp_service.sh --name my-mcp-server

# Project mode with explicit options
scripts/init_fastmcp_service.sh --name my-mcp-server --mode project --python 3.13 --path /tmp/my-mcp-server

# Workspace mode with defaults (core-lib package + api-service service)
scripts/init_fastmcp_service.sh --name platform --mode workspace

# Workspace mode with explicit members and profile mapping
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"

# Allow non-empty target directory
scripts/init_fastmcp_service.sh --name my-mcp-server --force

# Skip git initialization
scripts/init_fastmcp_service.sh --name my-mcp-server --no-git-init

# Create initial commit
scripts/init_fastmcp_service.sh --name my-mcp-server --initial-commit

# Generate MCP mapping guidance from OpenAPI
uv run scripts/assess_api_for_mcp.py --openapi ./openapi.yaml --out ./mcp_mapping_report.md

# Generate MCP mapping guidance from existing FastAPI app
uv run scripts/assess_api_for_mcp.py --fastapi app.main:app --out ./mcp_mapping_report.md

Inputs

• name: required
• mode: project or workspace; defaults to project
• path: optional target directory; defaults to ./<name>
• python: optional Python version; defaults to 3.13
• members: optional workspace member CSV for workspace mode
• profile_map: optional workspace profile CSV for workspace mode
• force: optional flag allowing non-empty target directories
• initial_commit: optional flag creating an initial commit after a successful scaffold
• no_git_init: optional flag disabling git initialization

Outputs

• status
  • success: scaffold and built-in validation completed
  • blocked: prerequisites or target-directory constraints prevented the run
  • failed: the script started but validation or generation failed
• path_type
  • primary: the canonical shell entrypoint completed
• output
  • resolved project or workspace path
  • emitted run commands
  • emitted validation commands
  • optional mapping-report path

Defaults

• mode: project
• Python version: 3.13
• quality tooling: pytest, ruff, mypy
• config baseline: committed .env, ignored .env.local, and pydantic-settings
• workspace default members: core-lib,api-service
• workspace default profiles: first member package, remaining members service

Base UV/FastAPI Guidance

The shared scaffold basis follows uv FastAPI integration style:

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

This skill then overlays FastMCP dependencies and server files for MCP service members. Generated FastMCP scaffolds should keep safe defaults in .env, local or secret overrides in .env.local, and typed runtime configuration in app/config.py.

API Import Guidance

When starting from OpenAPI or FastAPI, bootstrap first, then map endpoints to MCP primitives:

1. Generate mapping report with scripts/assess_api_for_mcp.py.
2. Classify endpoints into Resources, Tools, and Prompts.
3. Recommend RouteMaps/Transforms only when they improve usability.
4. Keep bootstrap deterministic; defer heavy custom mapping unless requested.

FastMCP Docs Lookup

Use the fastmcp_docs MCP server for up-to-date framework details.

Suggested queries:

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

Guardrails

• Refuse non-empty target directories unless --force is set.
• Require at least one service profile member in workspace mode.
• Require uv and git unless git initialization was explicitly disabled.
• Fail when workspace-only options are used in project mode.
• Fail when --initial-commit is combined with --no-git-init.

Fallbacks and Handoffs

• The preferred path is always scripts/init_fastmcp_service.sh.
• Use bootstrap-python-service when the user wants FastAPI-only output.
• Use bootstrap-uv-python-workspace directly only when FastMCP-specific behavior is not wanted.
• Recommend integrate-fastapi-fastmcp when the user needs to fold this FastMCP output into an existing FastAPI app, mount an MCP server into FastAPI, or promote generated FastAPI-derived MCP output into a curated combined architecture.

Automation Suitability

• Codex App automation: Medium. Useful for recurring FastMCP scaffold checks and mapping-assessment checks.
• Codex CLI automation: High. Strong fit for CI-style scaffold validation.

Codex App Automation Prompt Template

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 Automation Prompt Template

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

<PROMPT_BODY> template:

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.

Customization Placeholders

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

Interactive Customization Workflow

1. Ask for mode, name, path, Python version, and git/force flags.
2. If workspace mode, also ask for members and profile map.
3. Return both:

• A YAML profile for durable reuse.
• The exact scaffold command to run.

4. Use this precedence order:

• CLI flags
• --config profile file
• .codex/profiles/bootstrap-python-mcp-service/customization.yaml
• ~/.config/gaelic-ghost/python-skills/bootstrap-python-mcp-service/customization.yaml
• Script defaults

5. If users want temporary reset behavior:

• --bypassing-all-profiles
• --bypassing-repo-profile
• --deleting-repo-profile

6. If users provide no customization or profile files, keep existing script defaults unchanged.
7. See references/interactive-customization.md for schema and examples.

References

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

Script Inventory

• scripts/init_fastmcp_service.sh
• scripts/assess_api_for_mcp.py
• Delegates to the shared workspace bootstrap scripts shipped by bootstrap-uv-python-workspace.

Assets

• assets/README.md.tmpl