如何用 uv 搭建 Python MCP Server 的本地开发环境（uv sync、pytest、pyright、ruff）

如何用 uv 搭建 Python MCP Server 的本地开发环境（uv sync、pytest、pyright、ruff）

【免费下载链接】serversModel Context Protocol Servers项目地址: https://gitcode.com/GitHub_Trending/se/servers

本仓库（servers）是 Model Context Protocol 的参考实现集合，其中 3 个 Python 服务器位于src/fetch、src/git、src/time，对应发布包mcp-server-fetch、mcp-server-git、mcp-server-time。如果你要在本地运行、测试或二次开发这些 Python MCP Server，需要按仓库约定使用 uv（而非 pip）管理依赖，并跑通 pytest、pyright、ruff 三条检查。仓库的 Python 版本要求为>= 3.10，每个服务器目录下还有一个.python-version文件用于固定 Python 版本（CI 中actions/setup-python就读取该文件），构建系统为 hatchling。

以下以src/fetch为例给出完整操作路径，src/git与src/time步骤完全相同。

准备条件

• 已安装 uv。仓库的 CI 通过astral-sh/setup-uv@v7安装 uv，本地可直接安装后使用（仓库 README 指向官方 uv 安装说明）。
• Python 版本满足>= 3.10（各pyproject.toml中的requires-python均为>=3.10）。
• 在仓库根目录打开终端，进入目标服务器目录。

三个 Python 服务器的开发依赖都在各自的pyproject.toml中声明，但声明位置不同，后续添加依赖时要注意：

• src/fetch/pyproject.toml 与 src/time/pyproject.toml 使用[tool.uv]段的dev-dependencies（fetch 为pyright>=1.1.389、ruff>=0.7.3、pytest>=8.0.0、pytest-asyncio>=0.21.0；time 额外含freezegun，且pytest>=8.3.3、ruff>=0.8.1）；
• src/git/pyproject.toml 使用[dependency-groups]段的dev（pyright>=1.1.407、ruff>=0.7.3、pytest>=8.0.0）。

同步依赖：uv sync

进入服务器目录后执行：

cd src/fetch uv sync --frozen --all-extras --dev

这是 CLAUDE.md 中给出的标准命令，参数含义按仓库约定理解：

• --all-extras：安装全部 extras（当前各服务器的pyproject.toml未定义 extras，此处为仓库统一写法）；
• --dev：一并安装开发依赖（pyright、ruff、pytest 等），后续所有检查命令依赖这一步；
• --frozen：以现有锁文件为准，不更新锁文件。

CI 中两条流水线用的参数略有差异，可以对照 .github/workflows/python.yml：testjob 使用uv sync --frozen --all-extras --dev，buildjob 使用uv sync --locked --all-extras --dev（--locked在锁文件过期时会直接报错）。两个参数都表示"不重新生成锁文件"，本地日常开发用--frozen即可。

执行成功后会在该目录生成虚拟环境并写入锁文件解析出的依赖。若提示锁文件不一致，说明pyproject.toml与uv.lock不同步，需要先按仓库流程更新锁文件再提交，而不是绕过锁文件运行。

运行测试：pytest

fetch、git 有tests/目录，time 有test/目录（CI 中通过检测tests或test目录、或pyproject.toml中是否出现pytest来决定是否执行测试），因此三个服务器都可以运行：

uv run pytest

测试路径由各自pyproject.toml的[tool.pytest.ini_options]指定：fetch 和 git 均为testpaths = ["tests"]。fetch 的 pytest 配置额外含asyncio_mode = "auto"并依赖pytest-asyncio，因为其工具实现为 async/await 模式——这是仓库 CLAUDE.md 中明确列出的 Python 代码风格要求之一。测试通过（pytest 无失败用例）即表示该服务器当前代码可用。

类型检查与 Lint：pyright、ruff

仓库对 Python 代码强制类型标注，CI 的buildjob 会执行 pyright 和打包构建，本地应跑同样的检查：

# 类型检查（CI 中为 uv run --frozen pyright，此处为 CLAUDE.md 给出的本地写法） uv run pyright # Lint 检查 uv run ruff check .

pyright 无类型错误、ruff 无告警，即与 CI 的检查项对齐。

可选验证：构建与运行服务器本体

确认开发环境完整后，可以用 CIbuildjob 的打包命令验证 hatchling 构建链：

uv build

产物输出到该服务器目录的dist/（CI 将dist/作为 artifact 上传）。

若还要实际启动服务器验证，fetch 的 README 给出了 MCP inspector 的调试命令：

cd path/to/servers/src/fetch npx @modelcontextprotocol/inspector uv run mcp-server-fetch

其中path/to/servers是文档中的占位路径，替换为你本地仓库目录。各服务器的入口脚本名见pyproject.toml的[project.scripts]段，例如mcp-server-fetch = "mcp_server_fetch:main"，因此uv run mcp-server-fetch也可以直接以 stdio 方式启动服务器。

添加自己的开发依赖

在二次开发中需要新增开发依赖（如新的测试工具）时，先看你所在服务器的pyproject.toml用的是哪种声明方式：fetch 和 time 写在[tool.uv]的dev-dependencies，git 写在[dependency-groups]的dev。按既有方式追加后重新执行uv sync --frozen --all-extras --dev（若锁文件因此需要更新，需同步提交更新后的uv.lock，否则 CI 的--locked步骤会失败），再依次跑uv run pytest、uv run pyright、uv run ruff check .三条检查。

以上四步（sync、pytest、pyright、ruff）正是 CLAUDE.md "Python servers" 小节与 CI 工作流定义的完整检查路径；全部通过即表示本地开发环境与仓库 CI 对齐。

【免费下载链接】serversModel Context Protocol Servers项目地址: https://gitcode.com/GitHub_Trending/se/servers