MCP Server 发布最佳实践

原文链接：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折优惠