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.

2. Run scripts/init_fastmcp_service.sh with explicit --name and optional --path, --python, --force, --no-git-init, --initial-commit.
3. For workspace mode, optionally pass --members and --profile-map.
4. Verify quality checks:

• uv run pytest
• uv run ruff check .
• uv run mypy .

5. If bootstrapping from OpenAPI/FastAPI, run scripts/assess_api_for_mcp.py and review mapping report.
6. 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

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.