AI导哈

Python MCP服务器模板

基于FastMCP和Docker/Devcontainer的Python MCP服务器开发模板，提供MCP服务器功能示例、类型提示、静态分析、测试环境和开发环境设置。

  • by akitana-airtanker
  • Python
  • 本地部署
  • 5 星标
  • 更新于
在 GitHub 查看 akitana-airtanker/mcp-python-streamable-e2e-test-template

使用说明

Python MCP服务器模板（FastMCP+Docker/Devcontainer）

这是一个模板项目，用于使用以下工具高效开发基于Python的模型上下文协议（MCP）服务器 FastMCP 以及Docker（开发容器）。 它提供了MCP服务器基本功能的示例（例如 add 工具和a greeting 资源），利用类型提示，包括 Ruff 用于静态分析和格式化，测试环境，并支持即用型开发环境设置。

此存储库是 可流式处理的端到端（E2E）测试模板 用于用Python编写的MCP，并附带 Docker/Devcontainer设置 开箱即用。

详细的解释性文章已经发表！

目录

特性

  • MCP Python SDK：建立在官方的基础上 模型上下文协议Python SDK.
  • 基于FastMCP：用途 FastMCP （SDK的一部分），一个轻量级、快速的Python MCP服务器库。
  • Docker和Devcontainer：使用Docker提供容器化，使用VS Code Dev Containers提供一致的开发环境。
    • 容器以非root用户身份运行(appuser)以增强安全性。
  • 软件包管理 uv：雇员 uv，一个快速的Python包安装程序和解析器。
  • 静态分析和格式化：用 Ruff 已预先配置。
  • 测试环境：使用示例异步测试 pytest 和 pytest-asyncio 具有执行环境。
  • 类型提示：在整个项目中积极使用类型提示来提高代码的健壮性和可读性。
  • 可配置日志记录：日志输出可以通过以下方式控制 LOG_LEVEL 环境变量（例如。， DEBUG, INFO, WARNING).

先决条件

  • Python（3.10或更高版本，请参阅 pyproject.tomlDockerfile使用3.13-slim）
  • uv （Python包管理工具）
  • Docker（用于容器执行）
  • （可选）VS代码和开发容器扩展（用于开发容器）

设置（本地环境）

  1. 使用此模板创建新存储库或克隆存储库。 使用GitHub上的“使用此模板”按钮或按如下方式克隆：

    git clone https://github.com/akitana-airtanker/mcp-python-streamable-e2e-test-template.git <your-project-name>
cd <your-project-name>

    替换 <your-project-name> 您的项目名称。

  2. 创建虚拟环境并安装依赖项。 在项目的根目录中运行以下命令：

    uv venv
uv pip install -e ".[test,dev]" # Install test and dev dependencies as well

    这在中创建了一个虚拟环境 .venv 目录并安装必要的软件包（包括用于测试和开发的软件包） pyproject.toml.

在本地使用Ruff（Linter/Formatter）

此模板使用 Ruff。要在本地使用它：

# Install Ruff (should already be installed with dev dependencies, but can be installed individually)
# uv pip install ruff
# Check code
ruff check .
# Format code
ruff format .

建议设置预提交挂钩以自动化此操作：

pre-commit install

运行服务器（本地环境）

  1. 激活虚拟环境（如果尚未激活）。

    source .venv/bin/activate

  2. 启动服务器。

    mcp-server-demo

    服务器将在以下时间启动 http://0.0.0.0:8000 并监听MCP请求。 您可以通过设置 LOG_LEVEL 环境变量（例如。， LOG_LEVEL=DEBUG mcp-server-demo).

运行客户端（本地环境）

  1. 确保服务器正在运行。
  2. 打开另一个终端并激活虚拟环境。
    cd <your-project-name> # Navigate to the project root directory
source .venv/bin/activate
  3. 运行客户端。
    mcp-client-demo
    客户端将连接到服务器，调用 add 工具，并打印结果(Result of add(10, 5): 15)到控制台。 您可以使用以下命令控制客户端的输出详细程度 --quiet 或 --verbose 旗帜：
    mcp-client-demo --quiet   # Suppresses print statements, logs WARNING and above
mcp-client-demo --verbose # Enables DEBUG logging and print statements
    这 LOG_LEVEL 环境变量也可用于设置日志记录级别，如果指定了CLI标志，则以CLI标志为准。

使用Devcontainer进行开发（推荐）

使用VS代码开发容器可以轻松设置具有所有必要工具和配置的一致开发环境。

  1. 先决条件:

  2. 打开开发容器:

    • 在VS Code中打开此项目文件夹。
    • VS Code将检测 .devcontainer/devcontainer.json 文件，并在右下角显示“在容器中重新打开”的通知。单击此通知。
    • 或者，打开命令面板（Ctrl+Shift+P或Cmd+Shift+P），键入“开发容器：在容器中重新打开”，然后执行它。

  3. 在集装箱内工作:

    • 一旦容器构建并启动，VS Code将自动连接到容器内的项目。
    • 打开码头将打开集装箱内的码头。
    • mcp-server-demo 和 mcp-client-demo 可以直接在这个集装箱码头运行。
      # Start the server (in the container terminal)
mcp-server-demo

# Run the client (in another container terminal)
mcp-client-demo
    • 依赖关系（包括 test 和 dev extrases）通过Dockerfile安装 postCreateCommand 在……里面 devcontainer.json，因此当容器启动时，所有必要的包都可用。还安装了预提交挂钩。
    • 装订和格式化 Ruff 由于VS代码设置，将自动执行。
    • 容器以非root用户身份运行(appuser).
    • 端口8000会自动转发，因此您可以访问 http://localhost:8000/mcp （适用于MCP检查器）从主机的浏览器中。

使用Docker运行

  1. 构建Docker镜像。 在项目的根目录中运行以下命令：

    docker build -t mcp-server .

  2. 运行Docker容器。

    docker run -p 8000:8000 -e LOG_LEVEL=DEBUG mcp-server

    这将启动容器内的MCP服务器，并将其映射到主机上的端口8000。您可以通过传递环境变量来控制服务器在容器中的日志级别，例如 -e LOG_LEVEL=DEBUG。容器以非root用户身份运行(appuser).

运行测试（pytest）

此存储库包括位于 tests/ 目录（例如。， tests/test_client.py). 测试启动FastMCP服务器 专用端口8001 （配置于 tests/conftest.py)并验证工具调用是否正确。

机制

  • 这 tests/conftest.py 夹具通行证 MCP_SERVER_PORT=8001 作为启动服务器进程时子进程的环境变量。
  • 在……里面 src/mcp_python_streamable_e2e_test_template/server.py，the Config 课堂阅读 MCP_SERVER_PORT 和 FASTMCP_PORT.如果 MCP_SERVER_PORT 设置和 FASTMCP_PORT 不是， FASTMCP_PORT （由FastMCP使用）默认值为 MCP_SERVER_PORT.
    # src/mcp_python_streamable_e2e_test_template/server.py
# ...
from .config import Config
cfg = Config()
if cfg.mcp_server_port and not cfg.fastmcp_port:
    os.environ.setdefault("FASTMCP_PORT", cfg.mcp_server_port)
# ...
    这确保了 正常启动(mcp-server-demo)默认为端口8000 （或价值 FASTMCP_PORT / MCP_SERVER_PORT 如果设置），同时 pytest执行使用端口8001 对于服务器。

执行

# Assuming the virtual environment is activated
pytest

如果测试通过，您将看到类似于以下内容的输出：

collected 1 item

test_client.py .                                                       [100%]

============================= 1 passed in X.XXs =============================

与MCP检查员联系

当服务器在本地或Docker中运行时，您可以使用MCP Inspector连接到它以验证其行为。

  1. 启动MCP检查器。 在新终端中运行以下命令：

    npx --yes @modelcontextprotocol/inspector

  2. 连接到MCP检查器。 在浏览器中打开MCP检查器后，使用以下设置进行连接：

    • 传输类型: Streamable HTTP
    • 统一资源定位符: http://localhost:8000/mcp

特点

  • add 工具：将两个数字相加。
    • 输入示例： {"a": 10, "b": 5}
    • 输出示例： 15 （作为文本内容）
  • greeting 资源：返回指定姓名的问候语。
    • 示例URI： greeting://World
    • 输出示例： "Hello, World!"

许可证

该项目根据MIT许可证获得许可。请参阅 许可证 文件以获取详细信息。

相关 MCP