# 发布 image-mcp 到内网 PyPI

## 前提条件

- 内网已部署 PyPI 服务（如 [devpi](https://devpi.net/)、[pypiserver](https://github.com/pypiserver/pypiserver)、[Nexus](https://www.sonatype.com/products/nexus-repository)、[Artifactory](https://jfrog.com/artifactory/) 等）
- 已安装 `uv`（用于构建和发布）
- 拥有内网 PyPI 的上传账号和密码/token

本文以 `http://pypi.internal.com` 为示例地址，请替换为你的实际地址。

---

## 1. 构建包

```bash
cd /home/hyc/mcp_server
uv build
```

构建完成后会在 `dist/` 目录下生成两个文件：

```
dist/
├── image_mcp-0.1.0-py3-none-any.whl
└── image_mcp-0.1.0.tar.gz
```

## 2. 发布到内网 PyPI

### 方式一：命令行直接指定（推荐首次使用）

```bash
uv publish \
  --publish-url http://pypi.internal.com/legacy/ \
  --username your-username \
  --password your-password
```

> 注意：`--publish-url` 是上传接口地址，通常以 `/legacy/` 或 `/simple/` 结尾，具体取决于你的 PyPI 服务：
>
> | 服务 | 上传地址示例 |
> |------|-------------|
> | pypiserver | `http://host:8080/` |
> | devpi | `http://host:3141/user/index/` |
> | Nexus | `http://host:8081/repository/pypi-hosted/` |
> | Artifactory | `http://host:8081/artifactory/api/pypi/pypi-local/` |

### 方式二：通过环境变量（适合 CI/CD）

```bash
export UV_PUBLISH_URL=http://pypi.internal.com/legacy/
export UV_PUBLISH_USERNAME=your-username
export UV_PUBLISH_PASSWORD=your-password

uv publish
```

### 方式三：通过 uv.toml 配置文件（适合长期使用）

在项目根目录或 `~/.config/uv/uv.toml` 创建配置：

```toml
# uv.toml
[[publish]]
url = "http://pypi.internal.com/legacy/"
```

然后发布时只需提供认证信息：

```bash
uv publish --username your-username --password your-password
```

### HTTPS 证书问题

如果内网 PyPI 使用自签名证书，添加 `--allow-insecure-host` 参数：

```bash
uv publish \
  --publish-url https://pypi.internal.com/legacy/ \
  --allow-insecure-host pypi.internal.com \
  --username your-username \
  --password your-password
```

## 3. 配置 uv/uvx 从内网 PyPI 安装

发布后，用户需要配置 `uv` 从内网源安装包。

### 方式一：全局配置（推荐）

编辑 `~/.config/uv/uv.toml`：

```toml
[[index]]
url = "http://pypi.internal.com/simple/"
```

如果是自签名 HTTPS：

```toml
[[index]]
url = "https://pypi.internal.com/simple/"
allow-insecure-host = "pypi.internal.com"
```

配置后直接使用：

```bash
uvx image-mcp
```

### 方式二：通过环境变量

```bash
export UV_INDEX_URL=http://pypi.internal.com/simple/
uvx image-mcp
```

### 方式三：安装时指定

```bash
uvx --index-url http://pypi.internal.com/simple/ image-mcp
```

## 4. 配置 MCP Client 使用

### Claude Code

```bash
claude mcp add -s user image-mcp \
  --env LLM_BASE_URL=http://your-vl-server/v1 \
  --env LLM_API_KEY=your-key \
  --env LLM_MODEL=Qwen3.5-27B \
  --env OCR_API_URL=http://your-ocr-server:8080/layout-parsing \
  -- uvx image-mcp
```

> 前提：用户机器上 `uv` 已配置内网 PyPI 源（见第 3 步）。

### 其他 MCP Client

在 MCP 配置文件中添加：

```json
{
  "mcpServers": {
    "image-mcp": {
      "command": "uvx",
      "args": ["image-mcp"],
      "env": {
        "LLM_BASE_URL": "http://your-vl-server/v1",
        "LLM_API_KEY": "your-key",
        "LLM_MODEL": "Qwen3.5-27B",
        "OCR_API_URL": "http://your-ocr-server:8080/layout-parsing"
      }
    }
  }
}
```

## 5. 版本更新发布

1. 修改 `pyproject.toml` 中的 `version`
2. 重新构建：`uv build`
3. 发布：`uv publish --publish-url http://pypi.internal.com/legacy/ -u user -p pass`

## 常见问题

**Q: `uv publish` 报 409 Conflict？**
A: 该版本已存在。修改 `pyproject.toml` 中的版本号后重新构建。

**Q: `uvx image-mcp` 找不到包？**
A: 检查 uv 的 index 配置是否指向内网 PyPI。运行 `uv pip config list` 确认或设置 `UV_INDEX_URL` 环境变量。

**Q: 上传时认证失败？**
A: 确认 username/password 正确。部分 PyPI 服务（如 Nexus）需要单独开启 PyPI hosted 仓库的上传权限。
