# 发布指南

本文档说明如何将 mcp-docx-thesis-server 发布到 PyPI，以便其他人可以通过 pip 安装使用。

## 📋 发布前准备

### 1. 注册 PyPI 账号

1. 访问 https://pypi.org/account/register/ 注册账号
2. 验证邮箱
3. 启用双因素认证（2FA）

### 2. 创建 API Token

1. 登录 PyPI
2. 访问 https://pypi.org/manage/account/token/
3. 点击 "Add API token"
4. 设置 Token 名称（如 `mcp-docx-thesis-server`）
5. 选择 Scope（建议选 "Entire account" 或特定项目）
6. 复制生成的 Token（**注意：Token 只显示一次！**）

### 3. 配置认证信息

**方式一：使用 .pypirc 文件**

创建或编辑 `~/.pypirc`（Linux/Mac）或 `%USERPROFILE%\.pypirc`（Windows）：

```ini
[pypi]
username = __token__
password = pypi-AgEIcHlwaS5vcmcCJD...

[testpypi]
username = __token__
password = pypi-AgEIcHlwaS5vcmcCJD...
```

**方式二：使用环境变量**

```bash
# Linux/Mac
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-AgEIcHlwaS5vcmcCJD...

# Windows PowerShell
$env:TWINE_USERNAME="__token__"
$env:TWINE_PASSWORD="pypi-AgEIcHlwaS5vcmcCJD..."

# Windows CMD
set TWINE_USERNAME=__token__
set TWINE_PASSWORD=pypi-AgEIcHlwaS5vcmcCJD...
```

## 🚀 发布步骤

### 自动发布（推荐）

**Linux/Mac:**
```bash
bash scripts/publish.sh
```

**Windows:**
```powershell
# PowerShell
.\scripts\publish.ps1
```

脚本会：
1. 运行所有测试
2. 检查代码质量
3. 构建 wheel 和 sdist
4. 询问是否上传到 PyPI 或 TestPyPI

### 手动发布

如果你更喜欢手动控制每个步骤：

```bash
# 1. 安装构建工具
pip install build twine

# 2. 清理旧的构建
rm -rf dist/ build/ *.egg-info/

# 3. 运行测试
python -m pytest tests/ -v

# 4. 构建包
python -m build

# 5. 检查构建结果
ls -lh dist/

# 6. 上传到 TestPyPI（首次建议先测试）
python -m twine upload --repository testpypi dist/*

# 7. 测试安装
pip install --index-url https://test.pypi.org/simple/ mcp-docx-thesis-server

# 8. 上传到正式 PyPI
python -m twine upload dist/*
```

## ✅ 发布后验证

### 1. 检查 PyPI 页面

访问 https://pypi.org/project/mcp-docx-thesis-server/ 确认包已发布

### 2. 测试安装

```bash
# 创建干净的虚拟环境测试
python -m venv test_env
source test_env/bin/activate  # Windows: test_env\Scripts\activate

# 安装
pip install mcp-docx-thesis-server

# 验证安装
python -m mcp_docx_thesis_server.server --help
```

### 3. 在 Cherry Studio 中测试

配置 MCP Server：

```json
{
  "mcpServers": {
    "docx-thesis": {
      "command": "python",
      "args": ["-m", "mcp_docx_thesis_server.server"]
    }
  }
}
```

然后尝试生成一篇论文验证功能正常。

## 🔄 版本更新

发布新版本时：

1. 更新 `pyproject.toml` 中的 `version`
2. 更新 `CHANGELOG.md`（如果有）
3. 提交代码到 git
4. 打标签（可选但推荐）：
   ```bash
   git tag v1.1.0
   git push origin v1.1.0
   ```
5. 重新运行发布脚本

## 🐛 常见问题

### 1. 上传失败：403 Forbidden

**原因：** Token 无效或权限不足

**解决：**
- 检查 Token 是否正确复制
- 确认 Token 有上传权限
- 检查包名是否已被占用

### 2. 上传失败：400 Bad Request

**原因：** 版本号已存在或文件格式错误

**解决：**
- 检查 `pyproject.toml` 中的版本号是否已更新
- 确保版本号符合语义化版本规范（如 1.0.0）

### 3. 构建失败

**原因：** 缺少构建依赖

**解决：**
```bash
pip install build hatchling
```

### 4. 测试失败

**原因：** 代码有 bug 或测试环境不完整

**解决：**
```bash
# 安装开发依赖
pip install -e ".[dev]"

# 运行测试查看详情
python -m pytest tests/ -v --tb=long
```

## 📚 相关链接

- PyPI: https://pypi.org/project/mcp-docx-thesis-server/
- TestPyPI: https://test.pypi.org/project/mcp-docx-thesis-server/
- PyPI 帮助: https://packaging.python.org/tutorials/packaging-projects/
- MCP 文档: https://modelcontextprotocol.io/

## 💡 最佳实践

1. **先在 TestPyPI 测试**：首次发布或重大更新前，先在 TestPyPI 测试
2. **保持版本规范**：使用语义化版本（Semantic Versioning）
3. **写清楚文档**：README 要包含安装和使用说明
4. **及时更新**：修复 bug 或添加功能后及时发布新版本
5. **备份 Token**：安全保存 PyPI API Token，丢失后需要重新生成
