# Публикация пакета: установка через uvx и npx

## Установка через uvx (рекомендуется для Python)

**uvx** — способ запуска Python-приложений из PyPI без глобальной установки (аналог npx для Python).

### Шаги для публикации

1. **Аккаунт на PyPI**
   - Зарегистрируйтесь на [pypi.org](https://pypi.org/account/register/).
   - Для тестовой публикации: [test.pypi.org](https://test.pypi.org/account/register/).

2. **Токен API PyPI**
   - **Основной PyPI:** [pypi.org](https://pypi.org) → Account settings → API tokens → Add API token.
   - **TestPyPI (для тестов):** [test.pypi.org](https://test.pypi.org/manage/account/token/) → Add API token.
   - Используйте **API Token**, а не логин/пароль: username = `__token__`, password = значение токена. Старая аутентификация по паролю отключена.

3. **Сборка и публикация**
   Из каталога, где лежит `pyproject.toml` (например, `mcp-atlassian-bcs`):

   **Публикация на основной PyPI:**
   ```bash
   uv build
   uv publish
   ```
   При первом запуске будет запрошен токен PyPI или укажите: `UV_PUBLISH_TOKEN=pypi-... uv publish`.

   **Публикация на TestPyPI** (если токен с [test.pypi.org](https://test.pypi.org)):
   ```bash
   # Если в dist/ остались старые артефакты (с версией вида …+abc1234), удалите их:
   # Windows (PowerShell): Remove-Item dist\*.whl, dist\*.tar.gz -ErrorAction SilentlyContinue
   # Сборка: при настроенном индексе testpypi в pyproject.toml используйте unsafe-best-match,
   # иначе uv может не найти hatchling/packaging (они есть на PyPI, но не на TestPyPI):
   uv build --index-strategy unsafe-best-match
   uv publish --index testpypi --token pypi-ВАШ_ТОКЕН_ИЗ_TEST_PYPI
   ```
   Либо задайте токен переменной окружения: `set UV_PUBLISH_TOKEN=pypi-...` (Windows) / `export UV_PUBLISH_TOKEN=pypi-...` (Linux/macOS), затем `uv publish --index testpypi`.

4. **Использование после публикации**
   Пользователи смогут запускать без установки пакета:

   ```bash
   uvx bcs-mcp-atlassian
   ```

   Или установить в изолированное окружение и вызывать команду:

   ```bash
   uv tool install bcs-mcp-atlassian
   bcs-mcp-atlassian
   ```

---

## Конфигурация MCP (Cursor)

В `~/.cursor/mcp.json` (или в настройках Cursor) добавьте сервер и подставьте свои URL и токены в `env`. **Рабочие варианты:**

### 1. Локальный код (рекомендуется, всегда работает)

Клонируйте репозиторий и укажите полный путь к батнику (Windows) или скрипту:

```json
"bcs-mcp-atlassian": {
  "command": "C:\\путь\\к\\mcp-atlassian-bcs\\run-bcs-mcp-atlassian.bat",
  "args": [],
  "env": {
    "JIRA_URL": "https://jira.example.com",
    "JIRA_PERSONAL_TOKEN": "...",
    "CONFLUENCE_URL": "https://confluence.example.com",
    "CONFLUENCE_PERSONAL_TOKEN": "...",
    "CONTENT_MASK_SERVICE_URL": "https://...",
    "MCP_LOG_FILE": "C:\\путь\\к\\mcp-atlassian-bcs\\mcp-atlassian.log"
  }
}
```

На Linux/macOS используйте скрипт-обёртку, который делает `cd` в каталог проекта и запускает `uv run bcs-mcp-atlassian`.

### 2. Установка через pip (пакет с TestPyPI)

Один раз установите (PyPI — для зависимостей, TestPyPI — для самого пакета):

```bash
pip install --extra-index-url https://test.pypi.org/simple/ bcs-mcp-atlassian
```

В конфиге MCP укажите установленную команду (должна быть в PATH у процесса Cursor):

```json
"bcs-mcp-atlassian": {
  "command": "bcs-mcp-atlassian",
  "args": [],
  "env": { ... }
}
```

Если Cursor не находит команду, подставьте полный путь к скрипту (после установки: `where bcs-mcp-atlassian` на Windows, `which bcs-mcp-atlassian` на Linux/macOS).

### 3. Пакет с основного PyPI (после публикации на pypi.org)

После публикации на pypi.org можно использовать `uvx` без доп. индексов:

```json
"bcs-mcp-atlassian": {
  "command": "uvx",
  "args": ["bcs-mcp-atlassian"],
  "env": { ... }
}
```

**Примечание:** с TestPyPI `uvx` и `uv tool run` дают конфликты разрешения зависимостей (старые/поддельные пакеты на TestPyPI), поэтому для TestPyPI используйте вариант 1 или 2.

---

## Установка через npx (опционально)

**npx** работает с npm-пакетами. Ваш проект — Python, поэтому «напрямую» в npx его не опубликовать. Варианты:

### Вариант A: Только uvx

Официально распространять пакет как Python-инструмент и в документации указывать только `uvx bcs-mcp-atlassian`. Для Python-аудитории этого достаточно.

### Вариант B: npm-обёртка для npx

Создать отдельный репозиторий/пакет на npm с именем, например, `bcs-mcp-atlassian` или `bcs-mcp-atlassian-cli`, который при запуске через npx:

- проверяет наличие Python и `uv`/`pip`;
- при необходимости устанавливает пакет `bcs-mcp-atlassian` из PyPI (например, через `uv tool install bcs-mcp-atlassian` или `pipx install bcs-mcp-atlassian`);
- запускает `bcs-mcp-atlassian`.

Такой пакет будет маленьким (один `package.json` + скрипт на Node.js или shell). Публикация: обычная публикация в npm (`npm publish`).

---

## Чек-лист перед публикацией на PyPI

- [ ] Версия задаётся через `uv-dynamic-versioning` (из git) или задана в `pyproject.toml`. В конфиге указано `metadata = false`, чтобы версия не содержала локальный идентификатор (`+commit`), иначе PyPI/TestPyPI вернут 400.
- [ ] В `pyproject.toml`: `name`, `description`, `readme`, зависимости, `[project.scripts]` с точкой входа `bcs-mcp-atlassian = "mcp_atlassian:main"`.
- [ ] В корне есть `README.md`.
- [ ] Репозиторий в git (для динамической версии нужен хотя бы один тег, например `v0.1.0`).
- [ ] Проверка сборки: `uv build` выполняется без ошибок, в `dist/` появляются wheel и sdist.

После выполнения этих шагов публикация через `uv publish` и установка через `uvx bcs-mcp-atlassian` будут работать.
