GuardianMCP 🛡️

Your vigilant security companion that automatically guards your projects against vulnerabilities.

GuardianMCP is an MCP (Model Context Protocol) server that scans project dependencies for known security vulnerabilities using the OSV.dev database. Works with Cursor, VS Code, Claude Desktop, and other MCP-compatible IDEs.

Features

🛡️ Automatic vulnerability scanning for npm and Composer dependencies
🚨 Real-time alerts for CRITICAL and HIGH severity issues
🎯 Three scan modes: full, summary, critical-high-only
🔄 Auto-trigger support via IDE rules (on install, commit, build)
🌍 Multi-language keyword detection (English, Latvian, French, Spanish, German, Russian, etc.)
🐳 Docker support for containerized deployment
📊 Detailed reports with remediation guidance and CVE links
⚡ Fast & lightweight using OSV.dev API
🔒 Secure by design - 0 vulnerabilities, minimal dependencies

Security Status

npm audit Node.js Dependencies

✅ Latest security audit: All dependencies scanned, 0 vulnerabilities found ✅ Node.js: Latest LTS (22.x) with security updates ✅ Regular updates: Weekly dependency checks and monthly security reviews

See SECURITY.md for our security policy and audit details.

Quick Start

Choose your preferred method:

Option 1: npm (Recommended for most users)

npm install -g guardian-mcp

Option 2: From Source

git clone https://github.com/Kalvisan/guardian-mcp.git cd guardian-mcp npm install npm run build

Option 3: Docker

docker pull guardian-mcp:latest # or docker-compose up -d

IDE Setup Instructions

Click on your IDE to see setup instructions:

Cursor Setup

Cursor has native MCP support. Follow these steps:

1. Install GuardianMCP

npm install -g guardian-mcp # or use local installation (see Quick Start)

2. Configure Cursor

Open Cursor settings:

macOS/Linux: ~/.cursor/config.json or Cursor Settings > Features > MCP Servers
Windows: %APPDATA%\Cursor\config.json

Add GuardianMCP configuration:

{ "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } }

Or if installed locally:

{ "mcpServers": { "guardian-mcp": { "command": "node", "args": ["/absolute/path/to/guardian-mcp/dist/index.js"] } } }

3. Enable Auto-Scanning (Optional)

Create .cursor/rules.md in your project:

# Security Rules When working in this project: - Check for CRITICAL/HIGH vulnerabilities on project start - Scan after npm install or composer update - Verify no critical issues before git commits Use check_vulnerabilities tool with scan_mode="critical-high-only".

4. Restart Cursor

Completely restart Cursor to load GuardianMCP.

5. Test It

Open Cursor's AI chat and type:

Check my project for security vulnerabilities

GuardianMCP will automatically scan your dependencies!

VS Code Setup

VS Code can use MCP servers through extensions or configuration.

Method 1: Using Continue.dev Extension

Install Continue.dev extension
Open Continue settings (.continue/config.json)
Add MCP server configuration:

{ "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } }

Method 2: Direct Configuration

Install GuardianMCP: npm install -g guardian-mcp
Add to VS Code settings (.vscode/settings.json):

{ "mcp.servers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } }

3. Enable Auto-Scanning

Create .vscode/rules.md:

Automatically check for vulnerabilities when: - Opening the project - After running npm install/composer update - Before creating commits

4. Restart VS Code

Reload window: Cmd/Ctrl + Shift + P → "Reload Window"

Claude Desktop Setup

Claude Desktop has built-in MCP support.

1. Install GuardianMCP

npm install -g guardian-mcp

2. Configure Claude Desktop

Open configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add GuardianMCP:

{ "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } }

Or for local installation:

{ "mcpServers": { "guardian-mcp": { "command": "node", "args": ["/Users/you/path/to/guardian-mcp/dist/index.js"] } } }

3. Configure Auto-Scanning

Add to ~/.claude/rules.md (global) or project's .claude/rules.md:

# GuardianMCP Rules Automatically scan for vulnerabilities when: 1. User mentions: security, vulnerability, CVE, audit 2. After package installations 3. Before git commits Use scan_mode="critical-high-only" for auto-scans.

4. Restart Claude Desktop

Completely quit and reopen Claude Desktop.

Windsurf Setup

Windsurf supports MCP servers similar to Cursor.

1. Install GuardianMCP

npm install -g guardian-mcp

2. Configure Windsurf

Open Windsurf configuration:

Location: ~/.windsurf/config.json

Add MCP server:

{ "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } }

3. Create Project Rules

Add .windsurf/rules.md to your project:

Auto-scan dependencies for vulnerabilities on: - Project initialization - npm/composer commands - Pre-commit checks

4. Restart Windsurf

Reload the editor to activate GuardianMCP.

Zed Setup

Zed is adding MCP support. Check current status:

1. Install GuardianMCP

npm install -g guardian-mcp

2. Configure Zed

Open Zed settings:

macOS: ~/.config/zed/settings.json
Linux: ~/.config/zed/settings.json

Add configuration:

{ "assistant": { "mcp_servers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } } }

3. Restart Zed

Reload the editor.

Note: MCP support in Zed may be experimental. Check Zed documentation for latest status.

Docker Setup

Run GuardianMCP in a Docker container and connect from any IDE.

Method 1: Using Docker Compose (Recommended)

Clone the repository:

git clone https://github.com/Kalvisan/guardian-mcp.git cd guardian-mcp

Build and run:

docker-compose up -d

Configure your IDE:

In your IDE's MCP configuration, use:

{ "mcpServers": { "guardian-mcp": { "command": "docker", "args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"] } } }

Method 2: Docker Run

Build the image:

docker build -t guardian-mcp:latest .

Run the container:

docker run -d --name guardian-mcp \ -v /path/to/your/projects:/projects:ro \ guardian-mcp:latest

Configure your IDE:

{ "mcpServers": { "guardian-mcp": { "command": "docker", "args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"] } } }

For Cursor with Docker:

Edit ~/.cursor/config.json:

{ "mcpServers": { "guardian-mcp": { "command": "docker", "args": ["exec", "-i", "guardian-mcp", "node", "dist/index.js"] } } }

Volume Mounting

To scan projects outside the container:

docker run -d --name guardian-mcp \ -v /Users/you/projects:/projects:ro \ -v /Users/you/work:/work:ro \ guardian-mcp:latest

Then scan with:

Scan /projects/my-app for vulnerabilities

Docker Health Check

docker ps --filter name=guardian-mcp # Should show "healthy" status

Stopping the Container

docker-compose down # or docker stop guardian-mcp && docker rm guardian-mcp

Generic MCP Setup

For any IDE that supports Model Context Protocol:

1. Install GuardianMCP

npm install -g guardian-mcp

2. Find Your IDE's MCP Configuration

Common locations:

~/.config/[IDE_NAME]/config.json
~/.config/[IDE_NAME]/settings.json
~/.[IDE_NAME]/mcp.json

3. Add GuardianMCP

{ "mcpServers": { "guardian-mcp": { "command": "npx", "args": ["guardian-mcp"] } } }

Or with full path:

{ "mcpServers": { "guardian-mcp": { "command": "node", "args": ["/full/path/to/guardian-mcp/dist/index.js"] } } }

4. Verify Setup

Test by asking your IDE's AI assistant:

Use the check_vulnerabilities tool to scan my project

Usage

Once GuardianMCP is installed in your IDE, you can:

Manual Scanning

Simply ask your AI assistant:

Check my project for security vulnerabilities

Scan package.json for critical issues only

Give me a full security audit

Automatic Scanning

Configure rules in your IDE's rules file (.cursor/rules.md, .claude/rules.md, etc.):

# Security Automation When I mention: security, vulnerability, CVE, audit, or exploit → Run check_vulnerabilities with scan_mode="critical-high-only" After running: npm install, npm update, composer install, composer update → Automatically scan for new vulnerabilities Before creating git commits: → Check for CRITICAL vulnerabilities and warn if found

Tool Parameters

GuardianMCP provides the check_vulnerabilities tool with these parameters:

Parameter	Type	Options	Default	Description
`project_path`	string	any path	current dir	Path to project directory
`file_type`	string	`package.json` , `composer.json` , `both`	`both`	Which files to scan
`scan_mode`	string	`full` , `summary` , `critical-high-only`	`full`	Output detail level

Examples

Full scan:

Check vulnerabilities with scan_mode="full"

Quick summary:

How many vulnerabilities are in my project? (uses scan_mode="summary")

Auto-scan mode (recommended):

Scan for critical vulnerabilities only (scan_mode="critical-high-only")

Scan Modes Explained

🔍 `full` Mode

Best for: Manual security audits, comprehensive reviews

Shows ALL vulnerabilities with complete details:

CRITICAL, HIGH, MODERATE, and LOW severity
Detailed descriptions and remediation steps
Reference links and CVE IDs
Update commands for each package

Example output:

## 🔴 express@4.17.1 **Vulnerability ID:** GHSA-rv95-896h-c2vc **Severity:** CRITICAL ### ⚠️ CRITICAL RISK! **Description:** Express.js accepts requests with malformed URL encoding **IMMEDIATE ACTION REQUIRED:** 1. Update package: npm update express 2. Verify no vulnerable functionality is used ...

📊 `summary` Mode

Best for: Quick health checks, CI/CD dashboards

Shows only vulnerability counts:

Fast overview
No detailed descriptions
Total counts by severity

Example output:

## 📊 Summary - 🔴 Critical: 2 - 🟠 High: 5 - 🟡 Moderate: 12 - 🟢 Low: 3 **Total: 22 vulnerabilities** Run with scan_mode="full" for details.

🎯 `critical-high-only` Mode

Best for: Auto-scans, automated monitoring (RECOMMENDED for rules)

Shows detailed info for CRITICAL/HIGH, counts others:

Reduces noise
Highlights actionable issues
Perfect for automatic scans
Hides moderate/low details

Example output:

## 🔴 lodash@4.17.20 **Severity:** HIGH **Issue:** Prototype pollution vulnerability **Recommendation:** npm update lodash --- ## 📊 Summary - 🔴 Critical: 1 - 🟠 High: 2 _Also found 8 moderate/low issues (hidden)._ _Run with scan_mode="full" to see all._

Severity Levels

Level	Icon	Action	Examples
CRITICAL	🔴	Update IMMEDIATELY	RCE, Auth bypass, Privilege escalation
HIGH	🟠	Update ASAP	SQL injection, XSS, CSRF
MODERATE	🟡	Plan update	DoS, Information disclosure
LOW	🟢	Consider updating	Deprecated packages, Minor issues

Example Rules Files

See examples/ for ready-to-use templates:

claude-rules.md - Comprehensive template with all scenarios
project-rules.md - Project-specific configuration example
global-rules.md - User-wide configuration for all projects

Copy these to:

Cursor: .cursor/rules.md
Claude Desktop: .claude/rules.md
VS Code: .vscode/rules.md (with Continue.dev)

Supported Ecosystems

Ecosystem	File	Status
npm (Node.js)	`package.json`	✅ Supported
Composer (PHP)	`composer.json`	✅ Supported
PyPI (Python)	`requirements.txt`	🔄 Planned
Go Modules	`go.mod`	🔄 Planned
Maven (Java)	`pom.xml`	🔄 Planned
NuGet (.NET)	`*.csproj`	🔄 Planned
RubyGems	`Gemfile`	🔄 Planned
Cargo (Rust)	`Cargo.toml`	🔄 Planned

Troubleshooting

Verify installation:
npx guardian-mcp --version # or which guardian-mcp
Check config file path is absolute:
- ❌ "args": ["dist/index.js"]
- ✅ "args": ["/Users/you/guardian-mcp/dist/index.js"]
Restart IDE completely (don't just reload window)
Check IDE logs:
- Cursor: Open DevTools (Help > Toggle Developer Tools)
- VS Code: Output panel > Extension Host
- Claude Desktop: View > Developer > Toggle Developer Tools
Test manually:
node /path/to/guardian-mcp/dist/index.js # Should not crash

Verify rules file exists:
cat .cursor/rules.md # or cat .claude/rules.md
Check rules mention tool name:
- Must reference check_vulnerabilities
- Use scan_mode="critical-high-only" for auto-scans
Test with keywords:
- Try saying "security" or "vulnerability"
- Should trigger automatic scan
Check IDE supports rules:
- Cursor: ✅ Built-in support
- Claude Desktop: ✅ Built-in support
- VS Code: Depends on extension

Check logs:
docker logs guardian-mcp
Verify build succeeded:
docker build -t guardian-mcp:latest .
Test manually:
docker run -it guardian-mcp:latest
Check health:
docker ps --filter name=guardian-mcp # Status should be "healthy"

Check internet connection
Verify API is accessible:
curl https://api.osv.dev/v1/query
Rate limiting: OSV.dev has rate limits
- Wait a few minutes
- Reduce scan frequency
Firewall: Ensure outbound HTTPS is allowed

Development

Local Development

git clone https://github.com/Kalvisan/guardian-mcp.git cd guardian-mcp npm install npm run watch # Auto-recompile on changes

Testing Changes

npm run build node dist/index.js # Test locally

Adding New Ecosystems

Create checkXXXJson() function in src/index.ts
Follow pattern of checkPackageJson() or checkComposerJson()
Update file_type enum and descriptions
Use appropriate OSV.dev ecosystem name

Contributing

Contributions are welcome! Areas for improvement:

🌍 Additional ecosystem support (Python, Go, Rust, etc.)
🔧 Better version range parsing
⚡ Caching to reduce API calls
📱 IDE-specific optimizations
🧪 Test coverage
📚 Documentation improvements

License

MIT - See LICENSE file

Resources

Security Note

GuardianMCP helps identify known vulnerabilities but is not a substitute for:

✅ Comprehensive security audits
✅ Penetration testing
✅ Secure coding practices
✅ Regular dependency updates
✅ Security training

Always review and test dependency updates before deploying to production.

GuardianMCP 🛡️

Features

Security Status

Quick Start

Option 1: npm (Recommended for most users)

Option 2: From Source

Option 3: Docker

IDE Setup Instructions

Cursor Setup

1. Install GuardianMCP

2. Configure Cursor

3. Enable Auto-Scanning (Optional)

4. Restart Cursor

5. Test It

VS Code Setup

Method 1: Using Continue.dev Extension

Method 2: Direct Configuration

3. Enable Auto-Scanning

4. Restart VS Code

Claude Desktop Setup

1. Install GuardianMCP

2. Configure Claude Desktop

3. Configure Auto-Scanning

4. Restart Claude Desktop

Windsurf Setup

1. Install GuardianMCP

2. Configure Windsurf

3. Create Project Rules

4. Restart Windsurf

Zed Setup

1. Install GuardianMCP

2. Configure Zed

3. Restart Zed

Docker Setup

Method 1: Using Docker Compose (Recommended)

Method 2: Docker Run

For Cursor with Docker:

Volume Mounting

Docker Health Check

Stopping the Container

Generic MCP Setup

1. Install GuardianMCP

2. Find Your IDE's MCP Configuration

3. Add GuardianMCP

4. Verify Setup

Usage

Manual Scanning

Automatic Scanning

Tool Parameters

Examples

Scan Modes Explained

🔍 full Mode

📊 summary Mode

🎯 critical-high-only Mode

Severity Levels

Example Rules Files

Supported Ecosystems

Troubleshooting

Development

Local Development

Testing Changes

Adding New Ecosystems

Contributing

License

Resources

Security Note

Related Resources

New MCP Servers

MCP directory API

🔍 `full` Mode

📊 `summary` Mode

🎯 `critical-high-only` Mode