Feishu MCP Server

# PyPI 发布指南

本文档说明如何将 `yuppie-mcp-feishu` 发布到 PyPI。

## 前置准备

### 1. 安装发布工具

```bash
# 使用 uv（推荐）
uv pip install build twine

# 或使用 pip
pip install build twine
```

### 2. 准备 PyPI 账号

- 注册 PyPI 账号：https://pypi.org/account/register/
- 启用双重认证（2FA）
- 创建 API token：https://pypi.org/manage/account/token/
  - 保存 token，发布时需要使用

## 发布步骤

### 步骤 1: 检查版本号

在 `pyproject.toml` 中确认版本号：
```toml
version = "0.1.0"
```

**重要**: 每次发布都必须更新版本号，PyPI 不允许覆盖已存在的版本。

### 步骤 2: 构建发布包

```bash
# 清理旧的构建文件
rm -rf dist/ build/

# 构建源码包和 wheel
python -m build
```

这将创建：
- `dist/yuppie_mcp_feishu-0.1.0.tar.gz` (源码包)
- `dist/yuppie_mcp_feishu-0.1.0-py3-none-any.whl` (wheel 包)

### 步骤 3: 检查构建结果

```bash
# 查看生成的文件
ls -lh dist/

# 检查包的元数据
twine check dist/*
```

### 步骤 4: 上传到 TestPyPI（推荐先测试）

```bash
# 上传到 TestPyPI
twine upload --repository testpypi dist/*
```

验证安装：
```bash
# 创建虚拟环境测试
python -m venv test_env
source test_env/bin/activate  # Windows: test_env\Scripts\activate
pip install -i https://testpypi.python.org/pypi yuppie-mcp-feishu

# 验证安装
python -c "from tools import register_bitable_app_tools; print('Import success!')"

# 退出测试环境
deactivate
rm -rf test_env
```

### 步骤 5: 上传到 PyPI（正式发布）

```bash
# 使用 API token 上传（推荐）
twine upload dist/*

# 或交互式输入用户名和密码
twine upload dist/*
```

使用 API token 的方式：
- 创建 `~/.pypirc` 文件：
```ini
[pypi]
username = __token__
password = <your-pypi-token>
```

### 步骤 6: 验证发布

```bash
# 安装发布的包
pip install yuppie-mcp-feishu

# 或升级到最新版本
pip install --upgrade yuppie-mcp-feishu
```

访问 PyPI 页面确认：
https://pypi.org/project/yuppie-mcp-feishu/

## 版本发布建议

### 语义化版本号

- `0.1.0` - 初始版本
- `0.1.1` - Bug 修复
- `0.2.0` - 新增功能（向后兼容）
- `1.0.0` - 稳定版本
- `2.0.0` - 破坏性变更

### 发布检查清单

- [ ] 版本号已更新
- [ ] `CHANGELOG.md` 已更新（如果有）
- [ ] `README.md` 是最新的
- [ ] 所有测试通过：`PYTHONPATH=src uv run pytest tests/ -v`
- [ ] 构建成功：`python -m build`
- [ ] 元数据检查通过：`twine check dist/*`
- [ ] 已在 TestPyPI 测试过
- [ ] 标签已创建（可选）：`git tag v0.1.0 && git push origin v0.1.0`

## 常见问题

### Q: 如何回退已发布的版本？
A: PyPI 不允许删除或覆盖已发布的版本。如果发现问题，需要：
1. 发布新的修复版本（如 0.1.1）
2. 在 PyPI 上将旧版本标记为 "yanked"

### Q: 上传失败怎么办？
A: 检查：
- 版本号是否已存在
- 包名是否已被占用
- 网络连接是否正常
- API token 是否有效

### Q: 如何预览包的 PyPI 页面？
A: 使用 TestPyPI 进行测试发布：
```bash
twine upload --repository testpypi dist*
```
然后访问：https://test.pypi.org/project/yuppie-mcp-feishu/

## 相关链接

- PyPI: https://pypi.org/
- TestPyPI: https://test.pypi.org/
- 打包指南: https://packaging.python.org/tutorials/packaging-projects/
- Twine 文档: https://twine.readthedocs.io/