ci: support MCP v1 maintenance releases

.github/workflows/bump-package.yml

@@ -11,6 +11,37 @@ on:
         required: true
         type: string
         description: "Directory of the package (e.g., packages/oauth)"
+      target_branch:
+        required: false
+        type: string
+        default: main
+        description: "Branch that receives the bump PR"
+      increment:
+        required: false
+        type: string
+        default: auto
+        description: "Optional forced increment: major, minor, or patch"
+  workflow_dispatch:
+    inputs:
+      package_name:
+        required: true
+        type: string
+      package_dir:
+        required: true
+        type: string
+      target_branch:
+        required: false
+        type: string
+        default: main
+      increment:
+        required: false
+        type: choice
+        default: auto
+        options:
+          - auto
+          - major
+          - minor
+          - patch
 
 jobs:
   bump:
@@ -48,4 +79,8 @@ jobs:
         env:
           GH_TOKEN: ${{ steps.generate-token.outputs.token }}
         run: |
-          uv run python scripts/bump_package.py "${{ inputs.package_name }}" "${{ inputs.package_dir }}"
+          ARGS=(--target-branch "${{ inputs.target_branch }}")
+          if [[ "${{ inputs.increment }}" != "auto" && -n "${{ inputs.increment }}" ]]; then
+            ARGS+=(--increment "${{ inputs.increment }}")
+          fi
+          uv run python scripts/bump_package.py "${{ inputs.package_name }}" "${{ inputs.package_dir }}" "${ARGS[@]}"

.github/workflows/main.yml

@@ -4,9 +4,10 @@ on:
   push:
     branches:
       - main
+      - release/mcp-v1
 
 concurrency:
-  group: main
+  group: release-${{ github.ref_name }}
   cancel-in-progress: false
 
 jobs:
@@ -42,6 +43,9 @@ jobs:
         id: changes
         run: |
           PACKAGES=$(just detect-changes)
+          if [[ "${{ github.ref_name }}" == "release/mcp-v1" ]]; then
+            PACKAGES=$(jq -c '[.[] | select(.package_name == "keycardai-mcp")]' <<< "$PACKAGES")
+          fi
           echo "changed-packages=$PACKAGES" >> $GITHUB_OUTPUT
 
   bump-packages:
@@ -58,4 +62,5 @@ jobs:
     with:
       package_name: ${{ matrix.package.package_name }}
       package_dir: ${{ matrix.package.package_dir }}
-    secrets: inherit
+      target_branch: ${{ github.ref_name }}
+    secrets: inherit

.github/workflows/pr.yml

@@ -4,6 +4,7 @@ on:
   pull_request:
     branches:
       - main
+      - release/mcp-v1
 
 permissions:
   contents: read

MCP_RELEASES.md

@@ -0,0 +1,53 @@
+# MCP release lines
+
+`keycardai-mcp` tracks the upstream `mcp` package's major version, so its major
+version tells you which protocol SDK generation it pairs with:
+
+| keycardai-mcp | pairs with | released from |
+|---|---|---|
+| `1.x` | `mcp >= 1.28, < 2.0` | `release/mcp-v1` |
+| `2.x` | `mcp >= 2.0, < 3.0` | `main` |
+
+PyPI has no dist-tags, so nothing here changes how versions are published; the
+dependency ranges above are what steer resolvers to the right line. Users stay
+on 1.x with `keycardai-mcp<2`, which is also what dependents that still pin
+`mcp<2.0` (fastmcp 3.x, and the agent frameworks) resolve to naturally.
+
+## Branches
+
+- `main` is the 2.x line. Normal development happens here.
+- `release/mcp-v1` publishes fixes for the 1.x line. It receives
+  security/critical fixes only, no features. To land a fix there,
+  cherry-pick it into a PR targeting `release/mcp-v1`; the merge-to-branch
+  workflow auto-bumps and publishes exactly as `main` does. Only
+  `keycardai-mcp` bumps from this branch — the other packages release from
+  `main` regardless of line. (This differs from typescript-sdk, where the
+  aggregate `@keycardai/sdk` also releases from the maintenance branch; the
+  Python root `keycardai` package does not depend on `keycardai-mcp`.)
+
+## Forced increments
+
+Use the **Bump Package Version** workflow (workflow_dispatch) when a forced
+increment is required — deliberate majors, or establishing a new release line.
+`auto` derives the increment from conventional commits as usual.
+
+| input | maintenance release | major cut |
+|---|---|---|
+| `package_name` | `keycardai-mcp` | `keycardai-mcp` |
+| `package_dir` | `packages/mcp` | `packages/mcp` |
+| `target_branch` | `release/mcp-v1` | `main` |
+| `increment` | `auto` | `major` |
+
+## Establishing the lines (one-time sequence)
+
+1. Release `keycardai-mcp@1.0.0` from `main` (forced `major`) while `main`
+   still carries the `mcp<2.0` constraint.
+2. Create `release/mcp-v1` at the 1.0.0 release commit.
+3. Merge the MCP 2.0 cutover into `main`; its `feat!` commit makes cz cut
+   `2.0.0` automatically.
+4. Update `packages/fastmcp`'s `keycardai-mcp` constraint to `>=1,<2` in the
+   same window (it pairs with fastmcp 3.x / `mcp<2.0` until the fastmcp 4.x
+   bump).
+
+Do not create the maintenance branch before 1.0.0 exists; the branch must
+contain the 1.0.0 tag's commit so cz derives 1.x patches from it.