MCP Server Setup¶
GuardianShield implements the Model Context Protocol (MCP) using JSON-RPC 2.0 over stdin/stdout. It exposes 27 tools, 3 resources, and 3 prompts that any MCP-compatible AI client can discover and invoke automatically.
What is MCP?
The Model Context Protocol is an open standard that lets AI assistants discover and call external tools over a simple JSON-RPC transport. GuardianShield uses the stdio transport — the AI editor launches the server process and communicates through stdin/stdout.
Running the Server¶
After installing GuardianShield, the MCP server is available as a standalone entry point:
Run the server directly:
Or invoke it as a Python module:
The server starts, listens for JSON-RPC 2.0 messages on stdin, and writes responses to stdout. No network ports are opened — all communication is local and process-scoped.
No manual launch required
In normal usage you never run the server yourself. Your AI editor launches it automatically based on the configuration shown below.
Editor Integration¶
Configure your AI editor to launch GuardianShield as an MCP server. Choose your editor below.
Register the server with a single command:
Claude Code will start the server automatically on the next session. To verify it was added:
Create or edit .vscode/mcp.json in your workspace root:
{
"servers": {
"guardianshield": {
"type": "stdio",
"command": "guardianshield-mcp"
}
}
}
Reload the window after saving. The Copilot agent will discover all 27 tools automatically.
Create or edit .cursor/mcp.json in your project root:
Restart Cursor after saving. GuardianShield tools will appear in the agent tool list.
Add the server to your Windsurf MCP configuration:
Restart Windsurf to activate the server.
Edit the Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"guardianshield": {
"command": "guardianshield-mcp"
}
}
}
Restart Claude Desktop. The 27 tools, 3 resources, and 3 prompts will be available in the conversation.
Any MCP-compatible client can launch the server by spawning the process and piping stdin/stdout:
Send JSON-RPC 2.0 messages to stdin and read responses from stdout. The server follows the MCP specification — send initialize, then initialized, then call any tool, resource, or prompt.
Tools Reference¶
GuardianShield exposes 27 MCP tools. Each tool accepts a JSON object of parameters and returns a structured result.
scan_code¶
Scan source code for security vulnerabilities, insecure patterns, and embedded secrets.
| Parameter | Type | Required | Description |
|---|---|---|---|
code |
string |
Yes | The source code to scan |
file_path |
string |
No | File path for context (improves language detection) |
language |
string |
No | Programming language (python, javascript, etc.) |
engines |
string[] |
No | Analysis engines to use (default: profile setting). See Engine Management. |
Example call
With cross-line data flow analysis
Returns: List of findings with severity, category, description, line number, and remediation advice.
scan_input¶
Check text for prompt injection attempts, instruction overrides, role hijacking, and jailbreak patterns.
| Parameter | Type | Required | Description |
|---|---|---|---|
text |
string |
Yes | The input text to scan |
Example call
Returns: Injection detection result with risk score, matched patterns, and severity.
scan_output¶
Scan AI-generated output for PII leaks, sensitive content, and content policy violations.
| Parameter | Type | Required | Description |
|---|---|---|---|
text |
string |
Yes | The AI output text to scan |
Example call
Returns: List of PII findings with type, location, severity, and redacted text.
check_secrets¶
Detect API keys, tokens, passwords, and credentials in any text.
| Parameter | Type | Required | Description |
|---|---|---|---|
text |
string |
Yes | The text to scan for secrets |
file_path |
string |
No | File path for context |
Example call
Returns: List of detected secrets with type, location, severity, and redacted value.
get_profile¶
Get the current safety profile configuration and active rules.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | -- | -- | No parameters required |
Returns: Current profile name, enabled scanners, sensitivity levels, and rule configuration.
set_profile¶
Switch the active safety profile. Profiles adjust scanner sensitivity and enabled rules for specific industries and use cases.
| Parameter | Type | Required | Description |
|---|---|---|---|
name |
string |
Yes | Profile to activate: general, education, healthcare, finance, or children |
Returns: Confirmation with the new profile name and its configuration summary.
audit_log¶
Query the audit log of all scans, findings, and security events.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer |
No | Maximum number of entries to return (default: 50) |
scan_type |
string |
No | Filter by scan type (code, input, output, secrets, dependencies, directory_dependencies) |
Returns: List of audit log entries with timestamps, scan types, results, and finding summaries.
get_findings¶
Retrieve security findings from the findings store.
| Parameter | Type | Required | Description |
|---|---|---|---|
limit |
integer |
No | Maximum number of findings to return (default: 50) |
severity |
string |
No | Filter by severity: low, medium, high, critical |
finding_type |
string |
No | Filter by type: vulnerability, secret, pii, injection |
Returns: List of findings with severity, type, description, timestamp, and context.
shield_status¶
Get the health and configuration status of the GuardianShield server.
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | -- | -- | No parameters required |
Returns: Server version, active profile, enabled scanners, uptime, and database status.
scan_file¶
Scan a single source file for vulnerabilities, secrets, and insecure patterns. The language is auto-detected from the file extension.
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string |
Yes | Path to the file to scan |
language |
string |
No | Override auto-detected language (python, javascript, etc.) |
Returns: List of findings with severity, category, description, line number, CWE IDs, and remediation advice.
scan_directory¶
Recursively scan a directory for vulnerabilities across all supported file types. Emits streaming progress notifications during the scan.
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string |
Yes | Path to the directory to scan |
extensions |
string[] |
No | File extensions to include (e.g. [".py", ".js"]). Default: all supported. |
exclude |
string[] |
No | Directory or file patterns to exclude (e.g. ["node_modules", ".venv"]). |
Example call
Returns: List of findings across all scanned files with a summary of totals by severity. Emits guardianshield/scanProgress and guardianshield/finding JSON-RPC notifications during the scan.
test_pattern¶
Test a custom regex pattern against sample code. Useful for developing and debugging new vulnerability detection rules.
| Parameter | Type | Required | Description |
|---|---|---|---|
regex |
string |
Yes | The regex pattern to test |
sample |
string |
Yes | Sample code to test the pattern against |
language |
string |
No | Language context for the test (e.g. "python") |
Example call
Returns: Match results with positions, matched text, and line numbers.
check_dependencies¶
Check project dependencies for known CVEs using a local OSV.dev vulnerability cache. Supports PyPI, npm, Go, and Packagist ecosystems.
| Parameter | Type | Required | Description |
|---|---|---|---|
dependencies |
array |
Yes | List of dependency objects: {name, version, ecosystem} |
Each dependency object:
| Field | Type | Required | Description |
|---|---|---|---|
name |
string |
Yes | Package name (e.g. "requests", "lodash") |
version |
string |
Yes | Package version (e.g. "2.28.0") |
ecosystem |
string |
Yes | Package ecosystem: "PyPI", "npm", "Go", or "Packagist" |
Example call
Returns: List of CVE findings with severity, advisory details, affected version ranges, and remediation advice.
sync_vulnerabilities¶
Sync the local OSV vulnerability database from OSV.dev. The local cache enables offline dependency scanning.
| Parameter | Type | Required | Description |
|---|---|---|---|
ecosystem |
string |
Yes | Ecosystem to sync: "PyPI", "npm", "Go", or "Packagist". |
packages |
string[] |
No | Optional list of package names to sync. |
Returns: Sync status including number of vulnerabilities cached per ecosystem and last sync timestamp.
parse_manifest¶
Parse a dependency manifest file into a structured list of dependencies. Auto-detects the format from the filename.
| Parameter | Type | Required | Description |
|---|---|---|---|
content |
string |
Yes | The contents of the manifest file |
filename |
string |
Yes | Filename for format detection (e.g. "requirements.txt", "package.json", "go.mod") |
Supported manifest formats:
requirements.txt(and variants likerequirements-dev.txt)package.jsonpyproject.tomlpackage-lock.jsonyarn.lockpnpm-lock.yamlPipfile.lockgo.modgo.sumcomposer.jsoncomposer.lock
Example call
Returns: List of parsed dependencies with name, version, and ecosystem, plus a count and detected ecosystem.
scan_dependencies¶
Recursively scan a directory for manifest and lockfiles, parse dependencies, and check them for known vulnerabilities using the OSV.dev database.
| Parameter | Type | Required | Description |
|---|---|---|---|
path |
string |
Yes | Root directory to scan for manifest files |
exclude |
string[] |
No | Glob patterns to skip (e.g. ["vendor/*"]) |
Example call
Returns: List of vulnerability findings across all discovered manifest files, with a summary of manifests found, total dependencies parsed, and findings by severity.
mark_false_positive¶
Mark a security finding as a false positive. The finding will be flagged in future scans, and similar patterns at other locations will be annotated as potential false positives.
| Parameter | Type | Required | Description |
|---|---|---|---|
finding |
object |
Yes | The finding dict as returned by a scan tool |
reason |
string |
No | Explanation of why this is a false positive |
Example call
Returns: Confirmation with the false positive record ID and fingerprint.
list_false_positives¶
List active false positive records with optional filtering by scanner.
| Parameter | Type | Required | Description |
|---|---|---|---|
scanner |
string |
No | Filter by scanner name (e.g. code_scanner, secrets) |
limit |
integer |
No | Maximum records to return (default: 100) |
Returns: List of false positive records with fingerprints, reasons, and timestamps.
unmark_false_positive¶
Remove a false positive record by its fingerprint. The finding will no longer be suppressed in future scans.
| Parameter | Type | Required | Description |
|---|---|---|---|
fingerprint |
string |
Yes | The fingerprint of the false positive to remove |
Returns: Confirmation of whether the record was removed.
list_engines¶
List available analysis engines with their capabilities and enabled status. Three engines are registered:
| Engine | Type | Description |
|---|---|---|
regex |
Line-by-line pattern matching | 108+ compiled regex patterns across 7 languages. Fast, low false-positive rate. Default engine. |
deep |
Cross-line taint tracking | Traces data flow from untrusted sources to dangerous sinks across multiple lines. Uses Python ast for Python and regex for JS/TS. |
semantic |
Structure-aware confidence adjustment | Post-processing engine that adjusts confidence based on code context: test files, dead code, exception handlers, uncalled functions, unused imports. |
| Parameter | Type | Required | Description |
|---|---|---|---|
| (none) | -- | -- | No parameters required |
Returns: List of engines with name, enabled status, and capabilities (analysis type, supported languages, speed, feature flags).
set_engine¶
Set which analysis engines are active for code scanning in the current session. This is session-scoped and does not persist to disk.
| Parameter | Type | Required | Description |
|---|---|---|---|
engines |
string[] |
Yes | List of engine names to enable |
When to use each engine
regexonly (default) — Fast line-by-line scanning. Best for quick feedback during development.regex+deep— Adds cross-line taint tracking. Best for thorough security review of critical code paths.regex+semantic— Adds context-aware confidence adjustment. Reduces false positives in test files and dead code.- All three — Maximum coverage with intelligent confidence adjustment. Combines pattern matching, data flow analysis, and structural context.
Returns: Confirmation with the updated list of enabled engines.
export_sarif¶
Export scan findings as SARIF 2.1.0 JSON for GitHub Code Scanning, VS Code SARIF Viewer, and CI integration.
| Parameter | Type | Required | Description |
|---|---|---|---|
code |
string |
Yes | Source code to scan |
language |
string |
Yes | Programming language |
file_path |
string |
No | File path for SARIF locations |
engines |
string[] |
No | Analysis engines to use |
Example call
Returns: SARIF 2.1.0 JSON string with $schema, version, runs[].tool.driver, runs[].results, and runs[].taxonomies. Compatible with gh code-scanning upload-sarif.
save_baseline¶
Save current scan findings as a baseline file for delta scanning. On subsequent scans, use scan_with_baseline to report only new findings.
| Parameter | Type | Required | Description |
|---|---|---|---|
code |
string |
Yes | Source code to scan |
language |
string |
No | Programming language |
file_path |
string |
No | File path for context |
output_path |
string |
No | Path to save baseline (default: .guardianshield-baseline.json) |
Example call
Returns: Summary with fingerprints count, path, and finding_count.
scan_with_baseline¶
Scan code and compare against a saved baseline — returns only new findings not present in the baseline.
| Parameter | Type | Required | Description |
|---|---|---|---|
code |
string |
Yes | Source code to scan |
language |
string |
No | Programming language |
file_path |
string |
No | File path for context |
baseline_path |
string |
No | Path to baseline file (default: .guardianshield-baseline.json) |
Example call
Returns: new_findings list and summary with new, unchanged, and fixed counts.
check_quality_gate¶
Evaluate scan findings against configurable severity thresholds. Returns a pass/fail/warn verdict with exit codes for CI integration.
| Parameter | Type | Required | Description |
|---|---|---|---|
code |
string |
Yes | Source code to scan |
language |
string |
No | Programming language |
file_path |
string |
No | File path for context |
fail_on |
string |
No | Fail if any finding at this severity or above (default: high) |
warn_on |
string |
No | Warn if findings at this severity (default: medium) |
max_findings |
integer |
No | Optional absolute cap on total findings |
Example call
Returns: passed (bool), exit_code (0=pass, 1=fail), verdict string, summary with counts by severity, and findings list.
scan_files¶
Scan multiple files in one call. Each file is read from disk and scanned individually.
| Parameter | Type | Required | Description |
|---|---|---|---|
files |
array |
Yes | List of file objects: {path, language?} |
engines |
string[] |
No | Analysis engines to use |
Example call
Returns: results array (one per file with file_path and findings), plus summary with files_scanned and total_findings.
scan_diff¶
Parse a unified diff (e.g., git diff output) and scan only the added lines. Findings include correct line numbers and file paths from the diff context.
| Parameter | Type | Required | Description |
|---|---|---|---|
diff |
string |
Yes | Unified diff text |
engines |
string[] |
No | Analysis engines to use |
Example call
Returns: findings list and summary with files_in_diff, lines_added, and findings_count.
Supported Languages¶
GuardianShield's code scanner uses language-specific pattern sets to detect vulnerabilities. Language is auto-detected from file extension via EXTENSION_MAP, or can be specified explicitly with the language parameter.
Currently Supported¶
| Language | File Extensions | Patterns | Coverage |
|---|---|---|---|
| Python | .py, .pyw |
15 patterns | SQL injection, XSS, command injection, path traversal, insecure functions |
| JavaScript / TypeScript | .js, .ts, .jsx, .tsx, .mjs, .cjs |
7 patterns | Dynamic code generation, shell execution, unsafe HTML, template SQL injection, prototype pollution |
| Go | .go |
13 patterns | SQL injection, command injection, path traversal, template injection, insecure TLS |
| Java | .java |
12 patterns | SQL injection, XSS, command injection, deserialization, path traversal, XXE |
| Ruby | .rb, .rake, .gemspec |
16 patterns | SQL injection, XSS, command injection, mass assignment, open redirect |
| PHP | .php |
20 patterns | SQL injection, XSS, command injection, file inclusion, deserialization |
| C# / ASP.NET | .cs |
22 patterns | SQL injection, XSS, command injection, path traversal, deserialization, LDAP injection |
| Cross-language | (all files) | 3 patterns | Unsafe DOM assignment, unsafe DOM output, dynamic code execution |
Total code patterns: 108 (15 Python + 7 JS/TS + 13 Go + 12 Java + 16 Ruby + 20 PHP + 22 C# + 3 cross-language)
All scanners work on any text
The language-specific patterns above apply only to the code scanner (scan_code, scan_file, scan_directory). The other scanners -- secret detection (12 patterns), prompt injection (9 patterns), PII detection (7 patterns), and content moderation (15 patterns) -- work on any text regardless of programming language.
Request Language Support¶
Want GuardianShield to support your language? We welcome contributions and requests for:
- Rust
- Kotlin
- Swift
Resources¶
GuardianShield exposes 3 MCP resources. Resources provide read-only data that AI clients can fetch at any time.
| Resource URI | Description |
|---|---|
guardianshield://profiles |
List all available safety profiles and their configurations |
guardianshield://findings |
Recent security findings across all scan types |
guardianshield://config |
Current server configuration and active settings |
Reading a resource
MCP clients request resources via the resources/read method:
{
"jsonrpc": "2.0",
"id": 3,
"method": "resources/read",
"params": {
"uri": "guardianshield://profiles"
}
}
The server returns the resource content as a JSON object in the contents array.
Prompts¶
GuardianShield provides 3 MCP prompts. Prompts are reusable templates that AI clients can present to users or invoke programmatically.
security-review¶
A comprehensive security review template. When invoked, it guides the AI through a structured assessment of code, secrets, injection risks, and PII exposure.
Invoking the prompt
compliance-check¶
A compliance checking template. Structures the AI's analysis around regulatory frameworks and policy adherence for the active safety profile.
Invoking the prompt
triage-finding¶
A CWE-specific triage template for evaluating whether a security finding is a true or false positive. Provides structured guidance with true positive indicators, false positive indicators, targeted questions, and context to examine.
Supported vulnerability types: SQL injection (CWE-89), XSS (CWE-79), command injection (CWE-78), path traversal (CWE-22), insecure functions, insecure patterns, and hardcoded secrets (CWE-798).
Invoking the prompt
{
"jsonrpc": "2.0",
"id": 6,
"method": "prompts/get",
"params": {
"name": "triage-finding",
"arguments": {
"finding_type": "sql_injection",
"code_snippet": "cursor.execute('SELECT * FROM users WHERE id=' + user_id)",
"file_path": "app/db.py",
"finding_message": "SQL injection via string concatenation"
}
}
}
When to use triage
Use triage-finding after scan_code returns findings you want to validate. The triage prompt teaches the AI to evaluate each finding using domain-specific knowledge — no data leaves your machine.
JSON-RPC Examples¶
GuardianShield speaks JSON-RPC 2.0 over stdin/stdout. Below are raw request/response examples for direct integration.
Initialize Handshake¶
The client sends initialize to negotiate capabilities, then confirms with initialized.
Request:
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": {
"name": "my-client",
"version": "1.0.0"
}
}
}
Response:
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {
"tools": {},
"resources": {},
"prompts": {}
},
"serverInfo": {
"name": "guardianshield",
"version": "1.2.1"
}
}
}
After receiving the response, send the initialized notification:
Tool Call¶
Call any tool via the tools/call method.
Request:
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "scan_code",
"arguments": {
"code": "import subprocess\nsubprocess.call(user_input, shell=True)",
"language": "python"
}
}
}
Response:
{
"jsonrpc": "2.0",
"id": 2,
"result": {
"content": [
{
"type": "text",
"text": "{\"findings\": [{\"severity\": \"high\", \"category\": \"command_injection\", \"description\": \"Unsanitized input passed to subprocess with shell=True\", \"line\": 2, \"remediation\": \"Avoid shell=True with untrusted input. Use a list of arguments instead.\"}], \"summary\": {\"total\": 1, \"high\": 1, \"medium\": 0, \"low\": 0}}"
}
]
}
}
Security Limits¶
GuardianShield enforces transport-level limits to prevent abuse and resource exhaustion.
| Limit | Value | Description |
|---|---|---|
MAX_MESSAGE_SIZE |
2 MB | Maximum size of a single JSON-RPC message |
MAX_BATCH_SIZE |
50 | Maximum number of requests in a JSON-RPC batch |
Why these limits?
These limits protect against denial-of-service scenarios where a malicious or misconfigured client sends oversized payloads or excessive batch requests. Messages exceeding these limits are rejected with a JSON-RPC error response.