# 发布部署指南
本指南介绍如何将 Article MCP 项目发布到 PyPI 和 NPM，以便通过魔搭MCP广场进行云托管。
## 📋 前提条件
### PyPI 发布要求
- Python 3.10+
- uv 包管理器
- PyPI 账号和 API Token
- 项目代码已推送到 GitHub
### NPM 发布要求
- Node.js 16+
- npm 账号
- 项目代码已推送到 GitHub
## 🐍 PyPI 发布步骤
### 1. 准备发布环境
```bash
# 确保uv已安装
curl -LsSf https://astral.sh/uv/install.sh | sh
# 同步项目依赖
uv sync
# 测试项目运行
uv run main.py test
```
### 2. 配置 PyPI 认证
```bash
# 创建PyPI API Token (在 https://pypi.org/manage/account/token/ )
# 设置环境变量
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-your-api-token-here
```
### 3. 构建和发布
```bash
# 清理之前的构建
rm -rf dist/ build/ *.egg-info/
# 构建包
uv build
# 检查构建结果
ls dist/
# 发布到PyPI
uv publish
```
### 4. 验证发布
```bash
# 测试安装
uvx article-mcp@latest --help
# 测试运行
uvx article-mcp@latest server --help
```
## 📦 NPM 发布步骤
### 1. 准备NPM环境
```bash
# 登录NPM
npm login
# 验证登录状态
npm whoami
```
### 2. 发布NPM包
```bash
# 发布包（首次发布）
npm publish --access public
# 更新版本后发布
npm version patch # 或 minor, major
npm publish
```
### 3. 验证NPM包
```bash
# 测试npx运行
npx @gqy20/article-mcp-wrapper@latest server --help
```
## 🌐 魔搭MCP广场部署
### 配置选择
根据魔搭平台的自动化检测要求，**只有 `npx` 和 `uvx` 命令能通过检测**。
#### 推荐配置：uvx (PyPI)
```json
{
"mcpServers": {
"article-mcp": {
"command": "uvx",
"args": [
"article-mcp@latest",
"server"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
#### 备选配置：npx (NPM)
```json
{
"mcpServers": {
"article-mcp": {
"command": "npx",
"args": [
"-y",
"@gqy20/article-mcp-wrapper@latest",
"server"
],
"env": {
"PYTHONUNBUFFERED": "1"
}
}
}
}
```
### 部署检测要点
魔搭平台会进行以下检测：
1. ✅ **服务配置解析**：检测配置字段完整性
2. ✅ **配置可用性校验**：只允许 `npx` 和 `uvx` 命令
3. ✅ **部署连接测试**：尝试部署并调用 `list_tools` 方法
### 成功通过检测的要求
- ✅ `command` 字段必须是 `npx` 或 `uvx`
- ✅ JSON 配置无注释
- ✅ `args` 字段无本地路径依赖
- ✅ 包名加上 `@latest` 后缀
- ✅ 环境变量统一在 `env` 字段中
## 🔄 版本管理
### 语义化版本控制
- **主版本 (Major)**：不兼容的API修改
- **次版本 (Minor)**：向后兼容的功能性新增
- **修订版本 (Patch)**：向后兼容的问题修正
### 发布流程
1. **开发测试** → 在本地测试所有功能
2. **版本更新** → 更新 `pyproject.toml` 和 `package.json` 版本号
3. **推送代码** → `git tag v0.2.0 && git push --tags`
4. **发布PyPI** → `uv publish`
5. **发布NPM** → `npm publish`
6. **更新魔搭** → 使用最新配置部署
## ⚠️ 注意事项
### PyPI 发布注意点
- 包名 `article-mcp` 必须在PyPI上可用
- 确保所有依赖都在 `pyproject.toml` 中正确声明
- 项目入口点 `article-mcp = "main:main"` 必须正确
### NPM 发布注意点
- 包名 `@gqy20/article-mcp-wrapper` 使用作用域避免冲突
- `bin/article-mcp.js` 文件必须有执行权限
- Node.js 脚本需要正确处理Python环境
### 魔搭平台注意点
- 不支持本地路径和用户自定义参数
- JSON配置不能包含注释
- 只接受已发布的包，不支持开发版本
## 🛠️ 故障排除
### PyPI 发布失败
```bash
# 检查包名冲突
uv search article-mcp
# 检查构建结果
uv build --verbose
```
### NPM 发布失败
```bash
# 检查包名可用性
npm view @gqy20/article-mcp-wrapper
# 检查文件权限
chmod +x bin/article-mcp.js
```
### 魔搭部署失败
- 确认包已成功发布到对应平台
- 检查配置格式是否符合要求
- 验证命令在本地是否能正常运行
## 📞 支持
如果遇到发布问题，请：
1. 检查本指南的故障排除部分
2. 查看 [PyPI发布文档](https://packaging.python.org/tutorials/packaging-projects/)
3. 查看 [NPM发布文档](https://docs.npmjs.com/packages-and-modules/contributing-packages-to-the-registry)
4. 在 GitHub 项目中提交 Issue
