MCP Server 发布最佳实践

原文链接：MCP Server 发布最佳实践

项目结构

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

your-package-name/
├── pyproject.toml          
├── .python-version         
├── 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 
uv publish dist/* 
twine upload dist/* 

创建 ~/.pypirc，内容如下

[distutils]
index-servers =
    pypi

[pypi]
repository = https:
username = __token__
password = ****

pypi.org/manage/acco… 获取 API token

使用

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

{
  "mcpServers": {
    "mcp-server-name": {
      "command": "uvx",
      "args": [
        "mcp-server-name"
      ]
    }
}

常见问题

上传的文件名已经存在

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

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

twine upload --verbose dist

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

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

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

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

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

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