> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chkk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Cursor + Chkk

> A walkthrough of using Cursor with Chkk Upgrade Agent to produce environment-aware IaC pull requests

export const cursorDeeplink = "cursor://anysphere.cursor-deeplink/mcp/install?name=Chkk%20Upgrade%20Context%20MCP&config=eyJjb21tYW5kIjoiZG9ja2VyIHJ1biAtaSAtLXJtIC1lIENIS0tfQUNDRVNTX1RPS0VOIHB1YmxpYy5lY3IuYXdzL2Noa2svY2hray1tY3AtdXBncmFkZS1jb250ZXh0OmxhdGVzdCIsImVudiI6eyJDSEtLX0FDQ0VTU19UT0tFTiI6IjxBREQgVE9LRU4%252BIn19";

<Info>
  Agent Responses on this page are illustrative. Exact phrasing from your AI
  model may vary depending on the model, settings, and repository context.
</Info>

<Note>
  For the best experience, it is recommended to use the **claude-4-sonnet** model with the Chkk-Upgrade-Context-MCP Server.
</Note>

This guide shows how to use **Cursor** with the **Chkk-Upgrade-Context-MCP** to generate precise, environment-aware diffs and apply them to your Cloud Native Project IaC (e.g., Helm).

For a deep conceptual overview of how the Upgrade Agent works (powered by the Upgrade Context MCP server), see **[Upgrade Agent](/ai/upgrade-agent)** first.

## Prerequisites

1. [Install Docker](https://docs.docker.com/get-docker/): Required to run the Chkk-Upgrade-Context-MCP Server.

2. [Install Cursor](/resources/installation-guides/cursor): Required to begin generating environment-aware pull requests.

## Initialization of Chkk Upgrade Agent

<Steps>
  <Step title="Clone the Sample Chkk IaC repo">
    Run the following command to clone the sample Chkk IaC repo and open it in Cursor:

    ```bash theme={"dark"}
    git clone git@github.com:chkk-io/upgrade-playground.git && \
    cd upgrade-playground && \
    cursor .
    ```
  </Step>

  <Step title="Retrieve your Chkk Access Token">
    1. In the **Chkk Dashboard**, expand **Configure** on the left menu and click **Settings**.
    2. Select the **Tokens** tab. Here you'll see a list of all your active tokens (if any), along with options to create new ones or revoke existing ones.
    3. Click on the **clipboard** icon next to a token to copy it.

           <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/features/chkk-access-token.gif?s=f0f979e1e97c8531d96868a9db175c25" alt="Tokens Tab" width="1920" height="1080" data-path="images/features/chkk-access-token.gif" />
  </Step>

  <Step title="Install in Cursor via deeplink">
    Click the card below to install the Chkk Upgrade Context MCP Server in Cursor.

    <Card title="Add Chkk to Cursor" icon="plus" href={cursorDeeplink} horizontal={true}>
      Click here to add Chkk to your Cursor
    </Card>
  </Step>

  <Step title="Configure your Chkk Access Token">
    Paste your Chkk Access Token in the `CHKK_ACCESS_TOKEN` environment variable
    in the **MCP Tool Settings** opened via the deeplink in the previous step.

    <img src="https://mintcdn.com/chkk/P3h5EG42IrWoBIeY/images/ai/cursor-install-uc-mcp.png?fit=max&auto=format&n=P3h5EG42IrWoBIeY&q=85&s=7d382f57e6de4cbf2975c55811abc15b" alt="Tokens Tab" width="1108" height="532" data-path="images/ai/cursor-install-uc-mcp.png" />
  </Step>

  <Step title="Verify Chkk Upgrade Context MCP Server is installed">
    Verify in **MCP Tool Settings** that Chkk Upgrade Context MCP Server is
    successfully installed and enabled. <img src="https://mintcdn.com/chkk/P3h5EG42IrWoBIeY/images/ai/cursor-uc-mcp-installed.png?fit=max&auto=format&n=P3h5EG42IrWoBIeY&q=85&s=c2e64240eb771281e943b0ac696f3554" alt="Tokens
    Tab" width="1116" height="316" data-path="images/ai/cursor-uc-mcp-installed.png" />
  </Step>

  <Steps title="Retrieve the Upgrade ID">
    1. In the **left-hand column** of the **Chkk Dashboard**, expand **Upgrade Copilot**.

    2. Under **Upgrade Plans** select **Add-on & App Services**.

           <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/navigation/nav-project-upgrade-plans.png?fit=max&auto=format&n=ErQAF5e5P7IkmW9z&q=85&s=5f7a62b414f23a14f92997ef9c855916" alt="Navigate to Project Upgrade Plans" width="3516" height="2166" data-path="images/navigation/nav-project-upgrade-plans.png" />

    3. On the **Middle Right** corner of the page, enable the **Show Example Data** toggle, as shown in the image below.

    4. This will switch the view to only show example data and displays a confirmation banner.

           <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/features/enable-show-example-data-toggle.png?fit=max&auto=format&n=ErQAF5e5P7IkmW9z&q=85&s=014dc909a160122f2b2c08ea0bdc140e" alt="Enable Example Data" width="3510" height="2160" data-path="images/features/enable-show-example-data-toggle.png" />

    5. In the table below, you will see a list of Projects **Example Upgrade Plans**.

    6. Select any Upgrade Plan from the table that has the **AI Context Generated** badge, as shown in the image below.

    <Info>
      The **AI Context Generated** badge indicates that these Upgrade Plans are supported by the **Chkk-Upgrade-Context-MCP Server**.
    </Info>

    <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/features/highlight-example-project-plan-with-ai-context-generated.png?fit=max&auto=format&n=ErQAF5e5P7IkmW9z&q=85&s=70657d45165b34cf2d4146ab9eebdf7c" alt="Example Project Upgrade Plan with AI Context Generated Badge" width="3516" height="2110" data-path="images/features/highlight-example-project-plan-with-ai-context-generated.png" />

    7. At the top of the page, under the name of the Upgrade Plan, you will see the **Upgrade ID**.
    8. Click the **clipboard** icon to copy the Upgrade ID to your clipboard.

           <img src="https://mintcdn.com/chkk/ErQAF5e5P7IkmW9z/images/features/step-copy-project-upgrade-plan-id.png?fit=max&auto=format&n=ErQAF5e5P7IkmW9z&q=85&s=785f980f08904d1dd8cce4e4b6eb4bde" alt="Upgrade ID" width="3516" height="2160" data-path="images/features/step-copy-project-upgrade-plan-id.png" />
  </Steps>

  <Step title="Open a new chat in Cursor">
    * In Cursor (top-left), click **View → Command Palette**.
    * Make sure the chat is opened **from your IaC repo root**.
  </Step>

  <Step title="Load the Chkk Upgrade Agent">
    Paste and send the following Prompt in the Cursor chat:

    <CodeBlock wrap language="text">
      You're in a K8s repo. Fetch "addon-upgrade-agent" from Chkk MCP and upgrade the package listed in the upgrade plan. Start by asking for the upgrade ID.
    </CodeBlock>

    <Info>
      Your opening prompt is flexible, but it **must** explicitly instruct the agent to **fetch "addon-upgrade-agent" from Chkk MCP**.
    </Info>

    **Agent Response:**

    <img src="https://mintcdn.com/chkk/P3h5EG42IrWoBIeY/images/ai/cursor-sample-req-upg-id.png?fit=max&auto=format&n=P3h5EG42IrWoBIeY&q=85&s=426bbfc825917bd6b52286098a0dab48" alt="Tokens Tab" width="950" height="150" data-path="images/ai/cursor-sample-req-upg-id.png" />
  </Step>

  <Step title="Provide the upgrade ID of the Example Upgrade Plan">
    Paste your **upgrade ID** (from your instantiated [Project Upgrade Plan](/resources/glossary#project-upgrade-plan)), for example:

    <CodeBlock copy={false}>
      upgr\_ea53db65-3d8d-4744-b8b7-92e3c7552932
    </CodeBlock>

    **Agent Response:**

    <img src="https://mintcdn.com/chkk/P3h5EG42IrWoBIeY/images/ai/cursor-sample-start-post-upg-id.png?fit=max&auto=format&n=P3h5EG42IrWoBIeY&q=85&s=75087f4c465577eca005d6f86c1b52a9" alt="Tokens Tab" width="950" height="136" data-path="images/ai/cursor-sample-start-post-upg-id.png" />
  </Step>
</Steps>

## Upgrade Agent Workflow

Connect your environment to Chkk and generate an Upgrade Plan. From the Cursor IDE, ask the
Chkk Upgrade MCP to fetch Upgrade Context from that plan for the Cloud Native Project you're about to
change—say cert-manager or External Secrets Operator. The agent retrieves the recommended target
version and rationale, detects your IaC pattern, identifies which files need to be updated,
creates an environment-specific diff, and attaches the notes reviewers want (deprecations, critical fixes, notable features).
Your IDE applies the diff and opens the PR, with optional preflight and postflight checks to keep code and running state aligned.

The entire flow happens in your Cursor editor chat, end-to-end. Below is exactly what you'll see, phase by phase,
using a live example that upgrades **cert-manager** from **v1.14.4 → v1.17.2** with a forked Helm chart.

<Steps>
  <Step title="Kickoff & ID Handshake">
    **What you do:** You connect Chkk-Upgrade-Context-MCP server to Cursor. In Cursor Chat, you invoke the PR creation workflow (e.g., *"Use the Chkk upgrade agent to apply the IaC changes. Start by asking for the upgrade ID."*).

    **What you see:** The agent asks you for the **upgrade\_id**—a single natural key that ties your request to a Chkk **Upgrade Plan** (precomputed for your environment).

    **Why it matters:** The **upgrade\_id** is how the agent fetches the precise context—including resources, subagents and diffs—for *your* cluster constraints, not "generic upstream."
  </Step>

  <Step title="Environment Snapshot & State Setup">
    **What you do**: Provide the upgrade\_id.

    **What you see**: The agent resolves plan metadata immediately (package name and from/to versions) and prepares a safe workspace:

    * Confirms the **package** (e.g., `cert-manager`) and version span (`1.14.4 → 1.17.2`).
    * Creates a project-local scratchpad (e.g., `.chkk/scratchpad/`) which enables workflow tracing and checkpointing.

    **Why it matters**: This isolates automation artifacts from your source tree while keeping a local, inspectable record of every change.
  </Step>

  <Step title="Context Retrieval (MCP Tool Call)">
    **What you do**: Nothing; the agent drives.

    **What you see**: A short progress line—"Now fetching the context". The Context contains:

    * The **authoritative Upgrade Plan** for `cert-manager`.
    * Exact **file artifacts** to add and **unified diff** files to apply.
  </Step>

  <Step title="Plan Load & Sanity Summary">
    **What you do**: Nothing; the agent reads the plan.

    **What you see**: Compact, human-readable instructions from the plan:

    * **Upgrade Details**: `cert-manager v1.14.4 → v1.17.2`
    * **Reasons**: e.g., "1.14.4 is EOL/Unsupported" and "1.14.4 incompatible with Kubernetes 1.32."
    * **Inventory**: **Added: 2 files, Modified: 23 files, Deleted: 0** (your counts will vary by package).

    **Why it matters**: This is the first concrete signal that the plan is **environment-aware**
    (incompatible K8s version, distro nuances, etc.) an**d scoped to what you actually run.**
  </Step>

  <Step title="Target Locator (Chart Finder)">
    **What you do:** Nothing, unless you have multiple candidates.

    **What you see:** The agent identifies your IaC repo pattern and locates the exact **Helm chart root**
    for the package/version you're on (e.g., `.../helm/cert-manager/`) by scanning for **Chart.yaml** where
    `name == cert-manager` and `version == 1.14.4` (exact, case-sensitive).

    **Edge cases you might see:**

    * **Multiple matches:** You'll get a list of absolute paths and a prompt to choose one—no guessing.
    * **No match:** The agent asks for an explicit absolute path (it won't "best-effort" a wrong chart).
  </Step>

  <Step title="Preflight Checks">
    **What you do:** Review pass/fail lines.

    **What you see:** Two precise checks with ✅❌ outcomes:

    * **Chart Name & Version Match** — confirms **Chart.yaml** matches the *current* package & version.
    * **Upgrade Plan Metadata Match** — confirms the plan's **from/to** are consistent with resolved metadata.

    **Why it matters:** Preflight checks safeguard against pointing the patcher at the wrong subtree
    or the wrong plan. Any failure **stops the run** until fixed.
  </Step>

  <Step title="Reviewer Context, Upfront">
    **What you do:** Skim.

    **What you see:** The agent surfaces the "**why**"—the exact notes reviewers care about:

    * **Critical drivers** (e.g., EOL, K8s version compatibility).
    * **Breaking changes** (e.g., structured logging, stricter Helm schema validation, API removals).
    * **Security & bug fixes** (e.g., DoS mitigations, renewal logic).
    * **Notable features** (e.g., Gateway API support, metrics exposure).

    **Why it matters:** Your future PR will **inherit** these callouts so reviewers don't need to hunt docs to understand risk, scope and impact.
  </Step>

  <Step title="Deterministic Apply Pass">
    **What you do:** Watch the live counter; no prompts needed.

    **What you see:** A strict, linear, and **complete** application of the plan:

    * **Full inventory printout:**
      *"Processing 25 total files: 2 added, 23 modified, 0 deleted"*

    * **Adds:** Each source file from the context is copied to the correct relative target (e.g.,\
      `templates/cainjector-service.yaml`, `templates/extras-objects.yaml`) with immediate ✅ **Added** confirmations.

    * **Mods:** Every single `*.diff` is applied **one-by-one** with a visible sequence:\
      *"Processing diff 1 of 23: Chart.yaml … ✅ Modified"*\
      *"Processing diff 2 of 23: README.md … ✅ Modified"*\
      …through to the last template/value file.

    * **Deletions:** If any exist, they're backed up to `.bak`, then removed with ✅ **Deleted** confirmations.
  </Step>

  <Step title="CRD Copy">
    **What you do:** Nothing.

    **What you see:** If the context includes CRDs, the agent copies them into the target CRD directory and prints the exact path used.

    **Why it matters:** Reviewers see CRD changes alongside template and values edits.
  </Step>

  <Step title="Update Custom Resources">
    **What you do:** Nothing.

    **What you see:** If the plan includes Custom Resources, they're edited based on the changes in the CRD schema.

    **Why it matters:** Custom Resources are validated against their CRDs; migrating specs to the new schema
    (handling renamed/deprecated fields and default changes) prevents admission failures,
    reconcile churn, and subtle behavior drift during rollout.
  </Step>

  <Step title="Postflight Checks">
    **What you do:** Review.

    **What you see:** Two final gates:

    * **Chart version updated** — `Chart.yaml version == to_version` (e.g., `v1.17.2`) → ✅❌
    * **All planned changes applied** — match exactly and all items carry ✅ → ✅❌

    **Any failure here stops the flow** and lists the exact mismatches.
  </Step>

  <Step title="Human-Readable Summary (PR-Ready)">
    **What you do:** Read once; this becomes your PR body.

    **What you see:** A concise, celebratory completion message (never "upgraded," always "IaC updated"), plus reviewer-focused details:

    * **Completion:** 🎉 `cert-manager` IaC Successfully Updated — `v1.14.4 → v1.17.2.`
    * **Reasons** (EOL, K8s compatibility) and **most-critical notes** (breaking changes, security fixes).
    * **Applied changes** (counts + important files).
    * **CRD location** (exact path).
    * **Next step:** *"Create a Pull Request to review and apply these IaC changes."*
  </Step>
</Steps>

## Review and commit

<Steps>
  <Step title="Review workspace changes">
    * Open the **Source Control** panel (left sidebar) to inspect the diff.
    * Verify `Chart.yaml`, `values.yaml`, and any template updates.
  </Step>

  <Step title="Commit and open a pull request">
    Use your normal Git flow (Cursor's Git UI or terminal) to commit on a branch and open a PR for review.\
    Chkk's MCP server is read-only; your IDE/agent holds the pen and performs edits locally.
  </Step>
</Steps>