# 发布指南

本文档说明如何将此 MCP 服务器包发布到 PyPI。

## 前置要求

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

或使用 `uv`：
```bash
uv pip install build twine
```

2. 注册 PyPI 账号：
   - 访问 [PyPI](https://pypi.org/) 注册账号
   - 如果已注册，确保可以登录

3. 配置 PyPI 凭据（可选）：
   - 创建 `~/.pypirc` 文件配置凭据
   - 或使用环境变量

## 发布步骤

### 1. 更新版本号

在 `pyproject.toml` 中更新版本号：

```toml
version = "0.1.1"  # 更新为新版本号
```

遵循 [语义化版本](https://semver.org/)：
- MAJOR.MINOR.PATCH（例如：1.0.0）
- 修复 bug：PATCH 版本号 +1
- 新功能：MINOR 版本号 +1
- 破坏性变更：MAJOR 版本号 +1

### 2. 更新作者信息

在 `pyproject.toml` 中更新作者信息：

```toml
authors = [
    {name = "Your Name", email = "your.email@example.com"},
]
```

### 3. 构建包

构建源代码分发包和 wheel 包：

```bash
python -m build
```

或使用 `uv`：

```bash
uv build
```

这会在 `dist/` 目录下生成：
- `accounting-subject-analysis-mcp-server-0.1.0.tar.gz`（源代码分发包）
- `accounting_subject_analysis_mcp_server-0.1.0-py3-none-any.whl`（wheel 包）

### 4. 检查构建结果（可选）

检查构建的包：

```bash
python -m twine check dist/*
```

或如果 `twine` 在 PATH 中：

```bash
twine check dist/*
```

### 5. 测试安装（推荐）

在发布前，可以先在测试 PyPI 上测试：

```bash
# 上传到测试 PyPI
python -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*

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

### 6. 发布到 PyPI

发布到正式 PyPI：

```bash
python -m twine upload dist/*
```

或如果 `twine` 在 PATH 中：

```bash
twine upload dist/*
```

系统会提示输入 PyPI 用户名和密码（或 API token）。

### 7. 验证发布

发布后，访问以下 URL 验证：
- https://pypi.org/project/accounting-subject-analysis-mcp-server/

### 8. 安装测试

从 PyPI 安装并测试：

```bash
pip install accounting-subject-analysis-mcp-server
accounting-analysis-server
```

或使用 `uv`：

```bash
uv pip install accounting-subject-analysis-mcp-server
uv run accounting-analysis-server
```

## 使用 `uv` 发布（推荐）

如果您使用 `uv`，可以使用更简单的方式：

```bash
# 构建
uv build

# 发布（需要先配置 PyPI token）
uv publish
```

## 配置 PyPI Token（推荐）

为了安全，建议使用 API token 而不是密码：

1. 在 PyPI 账号设置中创建 API token
2. 使用 token 作为密码，用户名使用 `__token__`

或在环境变量中设置：

```bash
export TWINE_USERNAME=__token__
export TWINE_PASSWORD=pypi-xxxxxxxxxxxxx
```

## 常见问题

### 包名已存在

如果包名已存在，需要：
1. 更改 `pyproject.toml` 中的包名
2. 或联系 PyPI 管理员

### 版本号冲突

如果版本号已存在，需要：
1. 更新版本号
2. 重新构建和发布

### 依赖问题

确保所有依赖都在 `pyproject.toml` 的 `dependencies` 中列出。

## 后续更新

发布新版本时：
1. 更新版本号
2. 更新 CHANGELOG（如果维护）
3. 重新构建和发布
