# Publishing Guide

This guide covers publishing MCP Grid Studio to PyPI (Python package) and the VS Code Marketplace (extension).

---

## PyPI Publication (Python Package)

### Prerequisites

1. **PyPI Account** -- Create at [pypi.org/account/register](https://pypi.org/account/register/)
2. **API Token** -- Generate at [pypi.org/manage/account/token](https://pypi.org/manage/account/token/)
   - Scope: "Entire account" for the first publish, then restrict to the `mcp-grid` project
3. **`build` and `twine`** installed:

```bash
pip install build twine
```

### Step 1: Verify `pyproject.toml`

Ensure the version is correct:

```toml
[project]
name = "mcp-grid"
version = "1.0.0b1"  # PEP 440: 1.0.0-beta-rc → 1.0.0b1
```

### Step 2: Build the Package

```bash
python -m build
```

This creates:
```
dist/
  mcp_grid-1.0.0b1-py3-none-any.whl
  mcp_grid-1.0.0b1.tar.gz
```

### Step 3: Upload to TestPyPI (Recommended First)

```bash
twine upload --repository testpypi dist/*
```

Enter your TestPyPI API token when prompted (or use `~/.pypirc`).

**Test the install:**

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

### Step 4: Upload to PyPI

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

### Step 5: Verify

```bash
pip install mcp-grid
mcp-grid --version
```

### Using `~/.pypirc` for Credentials

Create `~/.pypirc` to avoid entering tokens manually:

```ini
[distutils]
index-servers =
    pypi
    testpypi

[pypi]
username = __token__
password = pypi-AgEIcH...  # Your PyPI API token

[testpypi]
username = __token__
password = pypi-AgEIcH...  # Your TestPyPI API token
```

**Protect this file:**

```bash
chmod 600 ~/.pypirc
```

### CI/CD Automation

The `release.yml` GitHub Actions workflow automates this. Set the following repository secret:

| Secret | Value |
|--------|-------|
| `PYPI_API_TOKEN` | Your PyPI API token (starts with `pypi-`) |

Triggered on tag push (`v*`):

```bash
git tag v1.0.0-beta-rc
git push origin v1.0.0-beta-rc
```

---

## VS Code Extension Publication (VSIX)

### Prerequisites

1. **Azure DevOps Organization** -- Create at [dev.azure.com](https://dev.azure.com/)
2. **Personal Access Token (PAT)** -- Create in Azure DevOps:
   - Go to **User Settings** (top-right) → **Personal access tokens**
   - Click **+ New Token**
   - Name: `vsce-publish`
   - Organization: **All accessible organizations**
   - Scopes: **Marketplace** → **Manage**
   - Copy the token
3. **Publisher** -- Create at [marketplace.visualstudio.com/manage](https://marketplace.visualstudio.com/manage):
   - Click **+ Create publisher**
   - Publisher ID: `IB-QA`
   - Display name: `IB-QA`
4. **`vsce`** installed:

```bash
npm install -g @vscode/vsce
```

### Step 1: Login

```bash
vsce login IB-QA
```

Paste your Azure DevOps PAT when prompted.

### Step 2: Package the Extension

```bash
cd extension
npm install
npm run compile
vsce package
```

This creates `mcp-grid-studio-1.0.0.vsix`.

### Step 3: Publish

```bash
vsce publish
```

Or upload the `.vsix` manually at [marketplace.visualstudio.com/manage](https://marketplace.visualstudio.com/manage).

### Step 4: Verify

Search "MCP Grid" in VS Code Extensions, or visit:
```
https://marketplace.visualstudio.com/items?itemName=IB-QA.mcp-grid-studio
```

### CI/CD Automation

Set the following repository secret:

| Secret | Value |
|--------|-------|
| `VSCE_PAT` | Your Azure DevOps Personal Access Token |

The `release.yml` workflow runs `vsce publish` on tag push.

---

## GitHub Release

### Manual Release

```bash
# Tag the release
git tag -a v1.0.0-beta-rc -m "v1.0.0-beta-rc"
git push origin v1.0.0-beta-rc

# The release.yml workflow will:
# 1. Build the Python package
# 2. Build the VS Code extension
# 3. Upload both to PyPI and VS Code Marketplace
# 4. Create a GitHub Release with artifacts
```

### Release Checklist

- [ ] Version updated in `pyproject.toml` (e.g., `1.0.0b1`)
- [ ] Version updated in `extension/package.json` (e.g., `1.0.0`)
- [ ] Changelog updated
- [ ] All tests passing
- [ ] `PYPI_API_TOKEN` secret set in repository
- [ ] `VSCE_PAT` secret set in repository
- [ ] Tag created and pushed

---

## GitHub Secrets Setup (Required for CI/CD)

You need to configure secrets in **both** repositories for the full pipeline to work.

### Private Repo (`McpServerStudio`) Secrets

Go to: **GitHub > IB-QA/McpServerStudio > Settings > Secrets and variables > Actions > New repository secret**

| Secret | Where to Get It | Purpose |
|--------|----------------|---------|
| `PYPI_API_TOKEN` | [pypi.org/manage/account/token](https://pypi.org/manage/account/token/) -- Create token, scope to `mcp-grid` project after first publish | Publish Python package to PyPI |
| `VSCE_PAT` | [dev.azure.com](https://dev.azure.com/) -- User Settings > Personal access tokens > New Token (Scope: Marketplace > Manage, Org: All accessible) | Publish VS Code extension |
| `DEPLOY_PAT` | [github.com/settings/tokens](https://github.com/settings/tokens) -- Generate new token (classic), scope: `repo` (Full control of private repositories) | Cross-repo dispatch to trigger public repo deployment |
| `PUBLIC_REPO` | Value: `IB-QA/MCPServerGridStudio` | Target repo for marketplace deployment dispatch |

### Public Repo (`MCPServerGridStudio`) Secrets

Go to: **GitHub > IB-QA/MCPServerGridStudio > Settings > Secrets and variables > Actions > New repository secret**

| Secret | Where to Get It | Purpose |
|--------|----------------|---------|
| `PRIVATE_REPO_PAT` | Same GitHub PAT as `DEPLOY_PAT` above (needs `repo` scope on private repo) | Download release artifacts from private repo for GitHub Release |

### Step-by-Step: Create a PyPI API Token

1. Go to [pypi.org](https://pypi.org) and log in (or register)
2. Click your username (top right) > **Account settings**
3. Scroll to **API tokens** > **Add API token**
4. Name: `mcp-grid-github-actions`
5. Scope: **Entire account** (first time) or **Project: mcp-grid** (after first publish)
6. Click **Create token** and copy the value (starts with `pypi-`)
7. Add as `PYPI_API_TOKEN` in McpServerStudio repo secrets

### Step-by-Step: Create an Azure DevOps PAT for VSCE

1. Go to [dev.azure.com](https://dev.azure.com/) and sign in (create an org if needed)
2. Click the **User Settings** gear icon (top right) > **Personal access tokens**
3. Click **+ New Token**
4. Name: `vsce-mcp-grid`
5. Organization: **All accessible organizations**
6. Expiration: 90 days or custom
7. Scopes: Click **Show all scopes** > Under **Marketplace** check **Manage**
8. Click **Create** and copy the token
9. Add as `VSCE_PAT` in McpServerStudio repo secrets

### Step-by-Step: Create a GitHub PAT for Cross-Repo Deployment

1. Go to [github.com/settings/tokens](https://github.com/settings/tokens)
2. Click **Generate new token (classic)**
3. Name: `mcp-grid-deploy`
4. Expiration: 90 days
5. Scopes: Check `repo` (Full control of private repositories)
6. Click **Generate token** and copy
7. Add as `DEPLOY_PAT` in McpServerStudio, and as `PRIVATE_REPO_PAT` in MCPServerGridStudio

### Step-by-Step: Create VS Code Marketplace Publisher

1. Go to [marketplace.visualstudio.com/manage](https://marketplace.visualstudio.com/manage)
2. Sign in with your Microsoft account
3. Click **+ Create publisher**
4. Publisher ID: `IB-QA`
5. Display name: `IBQA`
6. This is a one-time setup; the `vsce publish` command uses this publisher ID

---

## Installation Verification

After publishing, verify all installation methods:

```bash
# PyPI
pip install mcp-grid
mcp-grid --version

# uvx (no install)
uvx mcp-grid --version

# VS Code
code --install-extension IB-QA.mcp-grid-studio

# From GitHub Release
pip install https://github.com/IB-QA/MCPServerGridStudio/releases/download/v1.0.0-beta-rc/mcp_grid-1.0.0b1-py3-none-any.whl
```
