MCP Server 发布最佳实践

项目结构

以下是一个标准的 Python 包代码结构示例，结合 uv 的项目管理方式

your-package-name/

├── pyproject.toml          # 项目元数据（必填）

├── .python-version         # 指定 Python 版本（可选）

├── src/                    # 包代码目录（推荐布局）

│   └── your_package/

│       ├── __init__.py     # 初始化模块

│       └── core.py         # 核心功能代码

├── tests/                  # 测试目录（可选）

│   ├── __init__.py

│   └── test_core.py

├── README.md               # 项目说明

├── LICENSE                 # 开源协议

└── examples/               # 使用示例（可选）

    └── demo.py

pyproject.toml

[build-system]

requires = ["setuptools>=61.0"]

build-backend = "setuptools.build_meta"

[project]

name = "your-package-name"

version = "0.1.0"

authors = [

  {name = "Your Name", email = "you@example.com"},

]

description = "A brief description of your package"

readme = "README.md"

requires-python = ">=3.8"

classifiers = [

  "Programming Language :: Python :: 3",

  "License :: OSI Approved :: MIT License",

]

[project.urls]

Homepage = "https://github.com/yourusername/your-package"

# 依赖声明

[project.dependencies]

requests = "^2.31.0"  # 示例依赖

# 开发依赖（可选）

[project.optional-dependencies]

dev = [

  "pytest>=7.0",

  "ruff>=0.5.4",

]

模块代码（src/your_package/core.py）

"""核心功能模块"""

def greet(name: str) -> str:

    """返回问候语"""

    return f"Hello, {name}!"

构建和发布

在项目根目录下执行

uv build # 构建，完成后会生成目录 dist，下面放着压缩包

uv publish dist/* # 需要输入密码

twine upload dist/* # 或者使用这个命令，配置 ～/.pypirc后不需要手动输入密码

创建 ~/.pypirc，内容如下

[distutils]

index-servers =

    pypi

[pypi]

repository = https://upload.pypi.org/legacy/

username = __token__

password = ****

https://pypi.org/manage/account 获取 API token

使用

上传到 pypi 上后，就可以在 MCP Client 上使用了

{

  "mcpServers": {

    "mcp-server-name": {

      "command": "uvx",

      "args": [

        "mcp-server-name"

      ]

    }

}

常见问题

发布后清理缓存

uv cache clean

强制升级/重新下载

uv pip install --upgrade 包名

上传的文件名已经存在

Error: This filename has already been used, use a different version.

使用 --verbose 选项来获取更详细的错误信息

twine upload --verbose dist/*

如果当前目录下不存在该文件，但是还是提示文件名已经被使用。PyPI 服务器可能存在缓存，导致它仍然认为该文件名已被使用。有时候服务器的缓存需要一些时间来更新，你可以等待几个小时之后再尝试上传。

引用同级目录包，提示包不存在

如果引用同目录的包时，需要在前面加上 "."

因为在 Python 3 中，为了避免隐式相对导入带来的一些问题，它默认使用绝对导入。如果你想要进行相对导入，就需要显式地使用 . 或 .. 来指明相对路径。这里的 . 代表当前包，.. 代表上一级包。

避免命名冲突：使用显式相对导入可以避免命名冲突。假如你的项目中有一个模块名和 Python 标准库或者第三方库中的模块名相同，使用绝对导入可能会导入到错误的模块。而使用显式相对导入可以确保你导入的是当前包内的模块。

需要注意，显式相对导入只能在包内部使用。也就是说，只有当你的代码位于一个包中（即包含 __init__.py 文件的目录）时，才能够使用相对导入。如果你尝试在脚本文件（非包内模块）中使用相对导入，就会引发 ImportError

最后给如果需要购买服务器的，可以使用这里的优惠码，可以享受8折优惠