bootstrap-python-mcp-service

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Bootstrap Python MCP Service

快速搭建Python MCP服务

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

通过通用的uv项目/工作区脚手架搭配确定性MCP配置层，创建面向生产环境的FastMCP启动模板。

Workflow

工作流

Choose mode:

Project: scaffold one MCP service.
Workspace: scaffold uv workspace, then convert service members to FastMCP.

Run

scripts/init_fastmcp_service.sh

with explicit

--name

and optional

--path

--python

--force

--no-git-init

--initial-commit

For workspace mode, optionally pass
```
--members
```
and
```
--profile-map
```
.
Verify quality checks:

```
uv run pytest
```
```
uv run ruff check .
```
```
uv run mypy .
```

If bootstrapping from OpenAPI/FastAPI, run
```
scripts/assess_api_for_mcp.py
```
and review mapping report.
Return exact next commands.

选择模式：

项目模式：搭建单个MCP服务。
工作区模式：搭建uv工作区，再将服务成员转换为FastMCP服务。

运行

scripts/init_fastmcp_service.sh

，需指定

--name

参数，可选参数包括

--path

、

--python

、

--force

、

--no-git-init

、

--initial-commit

。

若使用工作区模式，可选择性传入
```
--members
```
和
```
--profile-map
```
参数。
验证质量检查：

```
uv run pytest
```
```
uv run ruff check .
```
```
uv run mypy .
```

若基于OpenAPI/FastAPI搭建，运行
```
scripts/assess_api_for_mcp.py
```
并查看映射报告。
返回后续需执行的准确命令。

Commands

命令

bash

undefined

bash

undefined

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)

带默认配置的工作区模式（core-lib包 + api-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

跳过git初始化

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

从OpenAPI生成MCP映射指导

python3 scripts/assess_api_for_mcp.py --openapi ./openapi.yaml --out ./mcp_mapping_report.md

Generate MCP mapping guidance from existing FastAPI app

从现有FastAPI应用生成MCP映射指导

python3 scripts/assess_api_for_mcp.py --fastapi app.main:app --out ./mcp_mapping_report.md

undefined

python3 scripts/assess_api_for_mcp.py --fastapi app.main:app --out ./mcp_mapping_report.md

undefined

Base UV/FastAPI Guidance

UV/FastAPI基础指导

The shared scaffold basis follows uv FastAPI integration style:

bash

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.

通用脚手架基础遵循uv FastAPI集成规范：

bash

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

本工具会在此基础上为MCP服务成员叠加FastMCP依赖和服务器文件。

API Import Guidance

API导入指导

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

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

当基于OpenAPI或FastAPI搭建时，先完成初始化，再将端点映射到MCP原语：

通过
```
scripts/assess_api_for_mcp.py
```
生成映射报告。
将端点分类为
```
Resources
```
、
```
Tools
```
和
```
Prompts
```
。
仅当RouteMaps/Transforms能提升可用性时才推荐使用。
保持初始化过程确定性，除非用户要求，否则不进行重度自定义映射。

FastMCP Docs Lookup

FastMCP文档查询

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

使用

fastmcp_docs

MCP服务器获取最新的框架细节。

推荐查询关键词：

```
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
```
.

除非设置
```
--force
```
，否则拒绝非空目标目录。
工作区模式下至少需要一个服务配置成员。
要求环境存在
```
uv
```
和
```
git
```
（除非设置了
```
--no-git-init
```
且未要求初始提交）。
项目模式下使用仅工作区支持的选项时会失败。
同时使用
```
--initial-commit
```
和
```
--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
```

模式：
```
project
```
Python版本：
```
3.13
```
质量工具：
```
pytest
```
、
```
ruff
```
、
```
mypy
```
工作区默认配置：
成员：
```
core-lib,api-service
```
配置：首个成员为
```
package
```
，其余成员为
```
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自动化：中等。适用于高频FastMCP脚手架检查和映射评估检查。
Codex CLI自动化：高。非常适合CI模式的脚手架校验。

Codex App Automation Prompt Template

Codex App自动化提示词模板

markdown

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

markdown

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 CLI自动化提示词模板

bash

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

<PROMPT_BODY>

template:

markdown

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.

bash

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

<PROMPT_BODY>

模板：

markdown

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

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

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.

```
init_fastmcp_service.sh
```
: 轻量级编排脚本，先调用uv工作区初始化，再叠加FastMCP文件和依赖。
```
assess_api_for_mcp.py
```
: 端点到MCP映射的分析工具。

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.

```
mcp-mapping-guidelines.md
```
: MCP原语、路由映射、转换规则和工作区映射边界的实用启发式规则。
```
fastmcp-docs-lookup.md
```
: 精选的
```
fastmcp_docs
```
搜索模式。

assets/

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

```
README.md.tmpl
```
: MCP项目输出的README模板。