|
| 1 | +# Getting Started |
| 2 | + |
| 3 | +Codacy Guardrails is a brand new way of enforcing code security and quality standards for AI-generated code, built into the free Codacy IDE Extension for VSCode, Copilot, Cursor, and Windsurf. Guardrails help developers ship safer, cleaner AI code by applying best practices and blocking insecure patterns while the code is being generated. |
| 4 | + |
| 5 | +Besides real-time AI code scanning, Guardrails users can now prompt all their Codacy findings, without ever leaving the AI chat panel inside their IDE. |
| 6 | + |
| 7 | +**New to Codacy Guardrails?** [Check our blog post](https://blog.codacy.com/codacy-guardrails-free-real-time-enforcement-of-security-and-quality-standards) |
| 8 | + |
| 9 | +<iframe width="560" height="315" src="https://www.youtube.com/embed/uVyRWnnJu-0?si=Pnbk65EvpvvJRXX4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe> |
| 10 | + |
| 11 | + |
| 12 | +## Prerequisites |
| 13 | + |
| 14 | +- git |
| 15 | +- node.js - ensure the `npx` command runs without issues |
| 16 | +- curl |
| 17 | + |
| 18 | +### Supported Operating Systems |
| 19 | + |
| 20 | +- macOS |
| 21 | +- Linux |
| 22 | +- Windows (via WSL) |
| 23 | + |
| 24 | +!!! important |
| 25 | + **For Windows users: Windows WSL** (a feature that allows you to run a Linux environment directly on Windows, without the need for a virtual machine or dual-boot setup) is the only way you can use this feature for now, but we're still working to fully support Windows. |
| 26 | + |
| 27 | + |
| 28 | +### Supported IDEs |
| 29 | + |
| 30 | +- Visual Studio Code |
| 31 | +- Cursor |
| 32 | +- Windsurf |
| 33 | + |
| 34 | +!!! note |
| 35 | + Visual Studio Code Insiders is recommended for its faster performance and compatibility with Codacy Guardrails. However, since it's a beta version, you may encounter occasional issues. |
| 36 | + |
| 37 | +### Built-in Scanners |
| 38 | + |
| 39 | +- Trivy |
| 40 | +- Semgrep |
| 41 | +- ESLint |
| 42 | +- Pylint |
| 43 | +- PMD |
| 44 | +- dartanalyzer |
| 45 | +- [Lizard](https://docs.codacy.com/release-notes/cloud/cloud-2025-02-adding-ruff-lizard/#lizard) |
| 46 | + |
| 47 | +## How to install - Quick Guide {: id="how-to-install-quick-guide"} |
| 48 | + |
| 49 | +#### Note for Windows users: |
| 50 | +To take full advantage of Codacy Guardrails on Windows, you might need to setup WSL first, [check the steps here.](#how-to-install-wsl) |
| 51 | + |
| 52 | +### 1. Download the extension |
| 53 | + |
| 54 | +- [Visual Studio Code](https://tinyurl.com/codacy-vscode) |
| 55 | +- [Cursor](http://tinyurl.com/codacy-cursor) |
| 56 | +- [Windsurf](http://tinyurl.com/codacy-windsurf) |
| 57 | + |
| 58 | +This will open the Codacy Extension in your IDE Marketplace. Click **Install** |
| 59 | + |
| 60 | + |
| 61 | + |
| 62 | + |
| 63 | +### 2. Install and activate the Codacy CLI for local analysis |
| 64 | + |
| 65 | +Click on the button **Install Codacy CLI** |
| 66 | + |
| 67 | + |
| 68 | + |
| 69 | +It will create a folder in your local repository called **.codacy** with all needed configuration: |
| 70 | + |
| 71 | +- The configuration from all built-in scanners |
| 72 | +- Codacy CLI script to run analysis locally |
| 73 | + |
| 74 | +!!! note |
| 75 | + If you don't want this folder to be part of your repository in future commits but continue working with it locally, please add **.codacy** to your .gitignore file |
| 76 | + |
| 77 | + |
| 78 | +### 3. Install MCP Server |
| 79 | + |
| 80 | +#### a. Add the Codacy MCP Server |
| 81 | + |
| 82 | +In the Codacy Extension tab, click **Add Codacy MCP Server** |
| 83 | + |
| 84 | + |
| 85 | + |
| 86 | +#### b. Check if the Codacy MCP Server is enabled |
| 87 | + |
| 88 | +On the left side menu of the Codacy extension, please make sure that MCP server is set up and ready. |
| 89 | + |
| 90 | + |
| 91 | + |
| 92 | +### 4. Restart your IDE |
| 93 | + |
| 94 | +## How to install - WSL {: id="how-to-install-wsl"} |
| 95 | + |
| 96 | +### 1. Install or update [WSL.](https://learn.microsoft.com/en-us/windows/wsl/install) |
| 97 | + |
| 98 | +### 2. Install the [WSL extension for VSCode.](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-wsl) |
| 99 | +* Ensure you go through all the installation steps and double check all warnings the extension may show during setup, since your machine may require some extra setup steps. |
| 100 | + |
| 101 | +### 3. Open a WSL Window. |
| 102 | +* You can do this by using the WSL extension keyboard shortcut `Ctrl` + `Alt` + `O` and then selecting the option or going to the command palette and selecting `WSL: Connect to WSL in New Window`. |
| 103 | + |
| 104 | +### 4. Open your project folder in WSL using the command `WSL: Open Folder in WSL...`. |
| 105 | +* Note that the path you need to enter is the WSL path, not the Windows one, so for example if you want to open your project that's in `C:\Users\your_username\project` the equivalent WSL path should be something like `/mnt/c/Users/your_username/project`. |
| 106 | +* To double check your path you can always open WSL directly by pressing `Win` + `R` and then typing WSL and pressing enter. There you can check your file structure. Keep in mind that your user folder in WSL (`/home/your_username` or `~`) isn't your user folder in Windows (for example `/mnt/c/Users/your_username`). |
| 107 | +* As an alternative, you can also open directly WSL, open your project folder and then opening VSCode from there with the command `code .`. |
| 108 | +* If you open a project through Windows explorer, it might open in a new (non-WSL) window. Open it via the command palette instead. |
| 109 | + |
| 110 | +### 5. Install `curl` on your WSL instance if it's not installed already. |
| 111 | +* This will depend on the Linux distribution you are using, but for example in Debian and Ubuntu the command will be something like `sudo apt update && sudo apt install curl`. |
| 112 | +* You can do this directly in WSL or in VSCode by going to `View > Terminal`. |
| 113 | + |
| 114 | +### 6. Now you should be able to install the Codacy extension without issues. Go through the steps [here](#how-to-install-quick-guide). |
| 115 | +* If you already have the extension installed, you will need to enable it for WSL. Check on your `Extensions` tab. |
| 116 | + |
| 117 | +### 7. After everything is set up, you should now be able to interact with Codacy via Copilot. |
| 118 | +* Remember that for you to be able to interact with Codacy MCP server, you must be on the `Agent` mode of the chat, not the default `Ask` mode. |
| 119 | +* If you're still having issues with the MCP server, try to run the command `Preferences: Open User Settings (JSON)`, look for the Codacy MCP server settings and right on top of it you'll should see a `Start` option. Click on it and, if unsuccessful, go to `View > Debug Console` and check for errors. Don't forget to ensure you have `node.js` and `npx` installed and set up. |
| 120 | + |
| 121 | + |
| 122 | +## How to install - Manually |
| 123 | + |
| 124 | +### 1. Install and activate the Codacy CLI for local analysis {: id="install-cli"} |
| 125 | + |
| 126 | +#### Download |
| 127 | + |
| 128 | +##### MacOS (brew) |
| 129 | + |
| 130 | +To install `codacy-cli` using Homebrew: |
| 131 | + |
| 132 | +```bash |
| 133 | +brew install codacy/codacy-cli-v2/codacy-cli-v2 |
| 134 | +``` |
| 135 | + |
| 136 | +##### Linux |
| 137 | + |
| 138 | +For Linux, we rely on the **codacy-cli.sh** script in the root. To download the CLI, run: |
| 139 | + |
| 140 | +```bash |
| 141 | +bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh) |
| 142 | +``` |
| 143 | +You can either put the downloaded script in a specific file or create an alias that will download the script and look for changes: |
| 144 | + |
| 145 | +```bash |
| 146 | +alias codacy-cli="bash <(curl -Ls https://raw.githubusercontent.com/codacy/codacy-cli-v2/main/codacy-cli.sh)" |
| 147 | +``` |
| 148 | + |
| 149 | +#### Installation |
| 150 | + |
| 151 | +Before running the analysis, install the specified tools: |
| 152 | + |
| 153 | +```bash |
| 154 | +codacy-cli install |
| 155 | +``` |
| 156 | + |
| 157 | +### 2. Install MCP Server {: id="install-mcp-server"} |
| 158 | + |
| 159 | +If you want to use MCP Server with a NPM package you should download it from [here](https://www.npmjs.com/package/@codacy/codacy-mcp) |
| 160 | + |
| 161 | +!!! important |
| 162 | + You can find some limitations using this approach because the AI doesn't automatically analyse the code generated unless there's a rule set for it to do so. When using the IDE extension (VS Code, Cursor, or Windsurf), we create those AI rules for the workspace, but if you are installing the MCP manually, you will need to create those rules by yourself. <a href="mailto:support@codacy.com">Let us know if you you plan to use this approach, so we can provide more information</a> |
| 163 | + |
| 164 | +#### Setup |
| 165 | + |
| 166 | +##### Cursor, Windsurf and Claude Desktop |
| 167 | + |
| 168 | +Depending on what IDE you are connecting the MCP Server to, you can use the following methods: |
| 169 | + |
| 170 | +- Cursor: edit the `.cursor/mcp.json` file to add the following |
| 171 | +- Windsurf: edit the `.codeium/windsurf/mcp_config.json` file to add the following |
| 172 | +- Claude Desktop: edit the `claude_desktop_config.json` file to add the following |
| 173 | + |
| 174 | +```json |
| 175 | +{ |
| 176 | + "mcpServers": { |
| 177 | + "codacy": { |
| 178 | + "command": "npx", |
| 179 | + "args": ["-y", "@codacy/codacy-mcp"], |
| 180 | + "env": { |
| 181 | + "CODACY_ACCOUNT_TOKEN": "<YOUR_TOKEN>", |
| 182 | + "CODACY_CLI_VERSION": "<VERSION>" |
| 183 | + } |
| 184 | + } |
| 185 | + } |
| 186 | +} |
| 187 | +``` |
| 188 | + |
| 189 | +##### VS Code with Copilot |
| 190 | + |
| 191 | +For connecting the MCP Server to Copilot in VS Code, add the following to the global config of the IDE: |
| 192 | + |
| 193 | +```json |
| 194 | +{ |
| 195 | + "mcp": { |
| 196 | + "inputs": [], |
| 197 | + "servers": { |
| 198 | + "codacy": { |
| 199 | + "command": "npx", |
| 200 | + "args": ["-y", "@codacy/codacy-mcp"], |
| 201 | + "env": { |
| 202 | + "CODACY_ACCOUNT_TOKEN": "<YOUR_TOKEN>", |
| 203 | + "CODACY_CLI_VERSION": "<VERSION>" |
| 204 | + } |
| 205 | + } |
| 206 | + } |
| 207 | + } |
| 208 | +} |
| 209 | +``` |
| 210 | + |
| 211 | +You can open the user settings.json file in: |
| 212 | + |
| 213 | +`View > Command Palette > Preferences: Open User Settings (JSON)` |
| 214 | + |
| 215 | +Or open the general settings.json file directly, which according to your OS should be located in: |
| 216 | + |
| 217 | +- for macOS: `~/Library/Application Support/Code/User/settings.json` |
| 218 | +- for Windows: `%APPDATA%\Code\User\settings.json` |
| 219 | +- for Linux: `~/.config/Code/User/settings.json` |
| 220 | + |
| 221 | + |
| 222 | + |
| 223 | +Make sure you update the value of `CODACY_ACCOUNT_TOKEN` with your [API token](../codacy-api/api-tokens.md). |
| 224 | + |
| 225 | +a. Above the MCP Server configuration in **Settings.json** file, you can Click in the command **Start** |
| 226 | + |
| 227 | + |
| 228 | + |
| 229 | +b. Make sure you have Agent mode enabled: [vscode://settings/chat.agent.enabled](vscode://settings/chat.agent.enabled) |
| 230 | + |
| 231 | +c. Open the Copilot chat and switch the mode to `Agent`. You can check that the MCP server was enabled correctly by clicking on the `Select tools` icon, which should list all the available Codacy tools. |
| 232 | + |
| 233 | + |
0 commit comments