Get the FREE Ultimate OpenClaw Setup Guide →

bootstrap-python-mcp-service

npx machina-cli add skill gaelic-ghost/python-skills/bootstrap-python-mcp-service --openclaw
Files (1)
SKILL.md
7.8 KB

Bootstrap Python MCP Service

Create production-oriented FastMCP starter layouts using shared uv project/workspace scaffolding plus deterministic MCP overlays.

Workflow

  1. Choose mode:
  • Project: scaffold one MCP service.
  • Workspace: scaffold uv workspace, then convert service members to FastMCP.
  1. Run scripts/init_fastmcp_service.sh with explicit --name and optional --path, --python, --force, --no-git-init, --initial-commit.
  2. For workspace mode, optionally pass --members and --profile-map.
  3. Verify quality checks:
  • uv run pytest
  • uv run ruff check .
  • uv run mypy .
  1. If bootstrapping from OpenAPI/FastAPI, run scripts/assess_api_for_mcp.py and review mapping report.
  2. Return exact next commands.

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
python3 scripts/assess_api_for_mcp.py --openapi ./openapi.yaml --out ./mcp_mapping_report.md

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

Base UV/FastAPI Guidance

The shared scaffold basis follows uv FastAPI integration style:

uv add fastapi --extra standard
uv run fastapi dev app/main.py

This skill then overlays FastMCP dependencies and server files for MCP service members.

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 --no-git-init is set and no initial commit is requested).
  • Fail when workspace-only options are used in project mode.
  • Fail when --initial-commit is used with --no-git-init.

Defaults

  • Mode: project
  • Python version: 3.13
  • Quality tooling: pytest, ruff, mypy
  • Workspace defaults:
  • Members: core-lib,api-service
  • Profiles: first member package, remaining members service

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:
     `python3 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:
     `python3 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.
  1. 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
  1. If users want temporary reset behavior:
  • --bypassing-all-profiles
  • --bypassing-repo-profile
  • --deleting-repo-profile
  1. If users provide no customization or profile files, keep existing script defaults unchanged.
  2. See references/interactive-customization.md for schema and examples.

Resources

scripts/

  • init_fastmcp_service.sh: thin orchestrator that delegates to uv workspace bootstrap then overlays FastMCP files/dependencies.
  • assess_api_for_mcp.py: endpoint-to-MCP mapping analyzer.

references/

  • mcp-mapping-guidelines.md: practical heuristics for MCP primitives, route maps, transforms, and workspace mapping boundaries.
  • fastmcp-docs-lookup.md: curated fastmcp_docs search patterns.

assets/

  • README.md.tmpl: README template for MCP project output.

Source

git clone https://github.com/gaelic-ghost/python-skills/blob/main/bootstrap-python-mcp-service/SKILL.mdView on GitHub

Overview

Bootstrap production-oriented MCP server layouts on macOS by combining shared uv project/workspace scaffolds with deterministic MCP overlays. It supports creating a project or a workspace, layering YAML profiles to customize defaults, and initializing pytest/ruff/mypy tooling along with README, git, and validation checks. When starting from OpenAPI/FastAPI, it provides mapping guidance to MCP primitives.

How This Skill Works

Choose mode (project or workspace), then run scripts/init_fastmcp_service.sh with the required --name and optional flags. For workspace mode, supply --members and --profile-map; after generation, run uv-based quality checks (pytest, ruff, mypy). If starting from OpenAPI/FastAPI, generate a mapping report with scripts/assess_api_for_mcp.py and review it before finalizing.

When to Use It

  • Starting a new MCP server from scratch on macOS (project mode).
  • Scaffolding a single uv MCP project with deterministic defaults.
  • Scaffolding a uv workspace with package/service members and then converting to FastMCP.
  • Customizing scaffold defaults via layered YAML profiles.
  • Bootstrapping from OpenAPI/FastAPI to map endpoints to MCP primitives.

Quick Start

  1. Step 1: Run scripts/init_fastmcp_service.sh --name my-mcp-server
  2. Step 2: If workspace, add --mode workspace --members "core-lib,api-service" --profile-map "core-lib=package,api-service=service"
  3. Step 3: Run quality checks: uv run pytest; uv run ruff check .; uv run mypy .

Best Practices

  • Prefer project mode for a single service; use workspace mode for multi-member setups.
  • After scaffolding, run: uv run pytest, uv run ruff check ., and uv run mypy .
  • Use --force to override non-empty target directories; use --no-git-init if you want to skip git.
  • If starting from API, run assess_api_for_mcp.py to generate a mapping report before heavy customization.
  • Keep bootstrap deterministic and apply heavy custom mappings only when requested.

Example Use Cases

  • Bootstrapping a new my-mcp-server in macOS with Python 3.13 and uv/FastMCP defaults.
  • Creating a workspace platform with core-lib and api-service as default members.
  • Generating an OpenAPI-driven MCP mapping report from openapi.yaml.
  • Initializing a first commit during bootstrap with git enabled.
  • Applying YAML-profile overrides to customize defaults for a multi-service scaffold.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗