# PyPI 发布指南

## 准备工作

### 1. 创建 PyPI 账号

1. 访问 https://pypi.org/account/register/
2. 完成账号注册
3. 验证邮箱

### 2. 安装发布工具

```bash
pip install twine  # 推荐在虚拟环境中执行
```

### 3. 准备 PyPI 凭证

Twine 6 取消了 `twine login`，推荐使用 **PyPI API Token**：

1. 打开 https://pypi.org/manage/account/token/
2. 点击 "Add API token"，选择要发布的项目或整个账户
3. 复制生成的 token（只会显示一次）

提供凭证的方式：

- **环境变量（推荐）**

  ```bash
  export TWINE_USERNAME="__token__"
  export TWINE_PASSWORD="pypi-AgEIcHlwaS5vcmcCJDJjODRkODQ4LTU2NGEtNGRlOS1hMzM4LTZlYjg1MDU0YzBkZgACFVsxLFsiZnV0dXJtaW5kLW1jcCJdXQACLFsyLFsiNGEyOGIwZjMtZGJiMy00ZmY3LTg2M2ItZjE0OTNhYzQ0NGM2Il1dAAAGIJ7hiw_JP3a5nF-RUvfGf_ZVjWwQpTmyq8K2Oo6eFBjv"
  ```

- **运行脚本时手动输入**：脚本会提示输入用户名（默认为 `__token__`）和 API Token

### 4. 配置项目信息

编辑 `pyproject.toml`，确认以下信息：

- ✅ 项目名称: `futurmind-mcp`
- ✅ 版本号: `0.1.0`
- ✅ 作者信息
- ✅ 许可证 (MIT)
- ✅ 项目链接 (如果需要)

## 发布流程

### 方式 1: 使用发布脚本（推荐）

```bash
chmod +x publish_to_pypi.sh
./publish_to_pypi.sh
```

脚本会自动完成：
1. 激活/创建虚拟环境
2. 安装 twine
3. 询问 PyPI 用户名和密码（若未设置环境变量）
4. 清理旧的构建文件
5. 构建包
6. 上传到 PyPI

### 方式 2: 手动发布

```bash
# 1. 清理旧的构建文件
rm -rf dist/ build/ *.egg-info/

# 2. 构建包
uv build

# 3. 检查构建文件
python -m twine check dist/*

# 4. 上传到 PyPI
python -m twine upload dist/*
```

### 测试发布（发布到 Test PyPI）

在正式发布前，建议先测试到 Test PyPI：

```bash
# 上传到 Test PyPI
python -m twine upload --repository testpypi dist/*

# 测试安装
pip install --index-url https://test.pypi.org/simple/ futurmind-mcp
```

## 验证发布

发布成功后，等待几分钟让 PyPI 处理，然后：

1. 访问 https://pypi.org/project/futurmind-mcp/
2. 确认项目信息正确显示

## 安装使用

发布成功后，用户可以这样安装：

```bash
pip install futurmind-mcp
```

然后在 Cursor 中配置：

```json
{
  "mcpServers": {
    "futurmind": {
      "command": "python",
      "args": ["-m", "futurmind_mcp"],
      "env": {
        "FUTURMIND_API_KEY": "your-api-key"
      }
    }
  }
}
```

## 更新版本

当需要发布新版本时：

1. 在 `pyproject.toml` 中更新版本号
2. 在 `src/futurmind_mcp/__init__.py` 中更新版本号
3. 重新运行发布流程

```bash
# 例如更新到 0.2.0
# 1. 编辑 pyproject.toml: version = "0.2.0"
# 2. 编辑 src/futurmind_mcp/__init__.py: __version__ = "0.2.0"
# 3. 重新发布
./publish_to_pypi.sh
```

## 常见问题

### Q: 上传时提示 "此版本已存在"
A: 需要更新版本号后再发布

### Q: 如何删除已发布的版本？
A: PyPI 不允许删除已发布的版本，只能发布新版本

### Q: 如何发布预发布版本（如 0.1.0a1）？
A: 修改版本号为 `0.1.0a1`，PyPI 会自动识别为预发布版本

### Q: 如何提供账号密码？
A: 建议使用 PyPI API Token，用户名为 `__token__`，密码填入完整的 token；可提前设置环境变量或按脚本提示输入

## 安全检查

发布前检查清单：

- [ ] 没有包含 `.env` 文件
- [ ] 没有硬编码的 API 密钥
- [ ] 没有包含 `__pycache__` 或 `.pyc` 文件
- [ ] 包含完整的 `README.md`
- [ ] 版本号正确
- [ ] 依赖项正确

查看将被包含的文件：
```bash
python -m build
# 然后查看 dist/ 目录中的 tar.gz 文件内容
```


