# CodeGuard MCP Server
Security rules for AI code generation via Model Context Protocol.
> **Built upon [Project CodeGuard](https://github.com/project-codeguard/rules):** This MCP server integrates the comprehensive security instruction rules from Project CodeGuard, solving scaling and central governance challenges by delivering them via Model Context Protocol instead of per-repository file duplication.
## What is this?
GitHub Copilot can use `.github/instructions/` files for security rules, but this sucks for orgs:
- 22+ files duplicated in every repo
- No central control
- Pain to update
This MCP server centralizes all security rules in one place.
## Quick Start
### 1. Install Package
```bash
npm install -g @isagasi/codeguard-mcp-server
```
### 2. Configure VS Code
**Windows:**
```powershell
# Get the global npm modules path
$npmPath = npm root -g
$serverPath = Join-Path $npmPath "@isagasi\codeguard-mcp-server\dist\index.js"
# Create configuration using node with args for reliable stdio
$config = @"
{
"servers": {
"codeguard": {
"type": "stdio",
"command": "node",
"args": ["$($serverPath -replace '\\', '\\\\')"],
"autoStart": true
}
}
}
"@
[System.IO.File]::WriteAllText("$env:APPDATA\Code\User\mcp.json", $config, (New-Object System.Text.UTF8Encoding $false))
Write-Host "✓ mcp.json created at: $env:APPDATA\Code\User\mcp.json"
```
**macOS/Linux:**
```bash
# Get the global npm modules path
NPM_PATH=$(npm root -g)
SERVER_PATH="$NPM_PATH/@isagasi/codeguard-mcp-server/dist/index.js"
# Create configuration using node with args for reliable stdio
cat > ~/Library/Application\ Support/Code/User/mcp.json << EOF
{
"servers": {
"codeguard": {
"type": "stdio",
"command": "node",
"args": ["$SERVER_PATH"],
"autoStart": true
}
}
}
EOF
echo "✓ mcp.json created"
```
### 3. Install Auto-Starter
```bash
code --install-extension alankyshum.vscode-mcp-autostarter
```
### 4. Reload VS Code
Press `Ctrl+Shift+P` → "Developer: Reload Window"
### 5. Verify Setup
`Ctrl+Shift+P` → "MCP: List Servers" → Should show `codeguard` running ✅
Done! Server is now active and will auto-start with VS Code.
### 6. Sanity Test (Recommended)
Verify the MCP server is actually being invoked by Copilot:
**Test 1: Password Hashing**
```
@workspace Generate a Python function to hash a password
```
**Expected:** Copilot should generate code using `bcrypt` or `Argon2` (not MD5 or SHA1)
**Test 2: Database Query**
```
@workspace Create a PostgreSQL query function in Node.js
```
**Expected:** Code should use parameterized queries, not string concatenation
**Test 3: API Key Storage**
```
@workspace Show how to store an API key in a Python app
```
**Expected:** Should suggest environment variables (`os.getenv`), not hardcoded strings
If Copilot generates **insecure code** (MD5 passwords, SQL injection, hardcoded keys), the MCP server may not be loaded. Retry steps 4-5.
## How it Works
The server provides 23 default security instruction files + 3 custom org rules:
- Crypto rules (no MD5, use Argon2/bcrypt)
- Auth/authz best practices
- Input validation, SQL injection prevention
- API security, logging, container hardening
- Custom rules can override defaults
Copilot Chat can query these via MCP tools when generating code.
## Custom Rules
Add org-specific rules in `rules/custom/`:
```markdown
---
applyTo: '**/*.ts'
description: Company API Standards
---
# API Standards
All REST endpoints must:
- Use company error format
- Log to ELK stack
- Rate limit: 100 req/min
```
Custom rules get +25 priority and override defaults.
## Maintenance
**Update to latest version:**
```bash
npm update -g @isagasi/codeguard-mcp-server
# Then reload VS Code
```
**Publishing new versions** (Maintainers):
1. Update version: `npm version patch` (1.0.8 → 1.0.9)
2. Push tags: `git push --follow-tags`
3. [Create GitHub release](https://github.com/isagasi/codeguard-mcp-server/releases/new)
4. Workflow auto-publishes to npm ✅
## Troubleshooting
**Server not running:**
- Check: `Ctrl+Shift+P` → "MCP: List Servers"
- Should see `codeguard` with status "running"
- If not listed, verify mcp.json path and reload VS Code
**Error: `spawn ENOENT` or `spawn EINVAL`:**
- This means the command path is incorrect or the binary wrapper isn't compatible
- Use the `node` with `args` configuration shown in Step 2 (not `codeguard-mcp` command)
- The MCP protocol requires clean stdio - using `node` directly ensures compatibility
**View server logs:**
- Open VS Code: View → Output
- Select "MCP Auto-Starter" from dropdown
- Check for startup errors or protocol violations
**Reinstall package:**
```bash
npm uninstall -g @isagasi/codeguard-mcp-server
npm install -g @isagasi/codeguard-mcp-server
# Reload VS Code
```
## Acknowledgments
This project integrates the security instruction rules from **[Project CodeGuard](https://github.com/project-codeguard/rules)**, a comprehensive collection of security best practices for AI-assisted code generation.
The MCP server architecture solves the scaling and central governance challenges inherent in per-repository instruction files, enabling organizations to maintain a single source of truth for security standards across all projects.
## License
MIT
