GuardianMCP

Instructions

Implementation Reference

• src/index.ts:443-470 (handler)

  Handler for the check_vulnerabilities tool call. Extracts parameters (project_path, file_type, scan_mode), invokes appropriate scanning functions for package.json and/or composer.json, and returns formatted markdown results.
  if (request.params.name === "check_vulnerabilities") { const projectPath = (request.params.arguments?.project_path as string) || process.cwd(); const fileType = (request.params.arguments?.file_type as string) || "both"; const scanMode = (request.params.arguments?.scan_mode as ScanMode) || "full"; let result = ""; if (fileType === "package.json" || fileType === "both") { result += await checkPackageJson(projectPath, scanMode); result += "\n\n"; } if (fileType === "composer.json" || fileType === "both") { result += await checkComposerJson(projectPath, scanMode); } return { content: [ { type: "text", text: result, }, ], }; }
• src/index.ts:414-435 (schema)

  JSON schema defining the input parameters for the check_vulnerabilities tool: project_path (string), file_type (enum), scan_mode (enum).
  inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to project directory (default: current directory)", }, file_type: { type: "string", enum: ["package.json", "composer.json", "both"], description: "Which file(s) to check (default: both)", }, scan_mode: { type: "string", enum: ["full", "summary", "critical-high-only"], description: "Output detail level: 'full' shows all vulnerabilities with details, " + "'summary' shows only counts, 'critical-high-only' shows detailed info for CRITICAL/HIGH only (default: full)", }, }, },
• src/index.ts:407-436 (registration)

  Tool registration in the ListTools response, including name, description, and reference to inputSchema.
  { name: "check_vulnerabilities", description: "Scans project dependencies (package.json, composer.json) for known security vulnerabilities using the OSV.dev database. " + "Supports multiple scan modes: 'full' for detailed reports, 'summary' for quick overview, 'critical-high-only' for auto-scans showing only actionable issues. " + "Use this tool when: user asks about security/vulnerabilities, after package installations (npm install, composer update), " + "before commits/builds, or when starting work in a new project with dependency files.", inputSchema: { type: "object", properties: { project_path: { type: "string", description: "Path to project directory (default: current directory)", }, file_type: { type: "string", enum: ["package.json", "composer.json", "both"], description: "Which file(s) to check (default: both)", }, scan_mode: { type: "string", enum: ["full", "summary", "critical-high-only"], description: "Output detail level: 'full' shows all vulnerabilities with details, " + "'summary' shows only counts, 'critical-high-only' shows detailed info for CRITICAL/HIGH only (default: full)", }, }, }, },
• src/index.ts:178-283 (helper)

  Helper function that scans package.json for dependencies, queries OSV API for vulnerabilities, counts by severity, and generates markdown report based on scan mode.
  async function checkPackageJson( projectPath: string, mode: ScanMode ): Promise<string> { try { const packageJsonPath = path.join(projectPath, "package.json"); const content = await fs.readFile(packageJsonPath, "utf-8"); const packageJson = JSON.parse(content); const allDeps = { ...packageJson.dependencies, ...packageJson.devDependencies, }; let results = "# Security Scan Results (package.json)\n\n"; let criticalCount = 0; let highCount = 0; let moderateCount = 0; let lowCount = 0; const allVulnerabilities: Array<{ packageName: string; version: string; vulnerabilities: Vulnerability[]; }> = []; for (const [packageName, versionRange] of Object.entries(allDeps)) { // Extract version from range (simplified - remove ^~>=< symbols) const version = (versionRange as string).replace(/[\^~>=<]/g, ""); const vulnerabilities = await checkVulnerability( packageName, version, "npm" ); if (vulnerabilities.length > 0) { allVulnerabilities.push({ packageName, version, vulnerabilities }); for (const vuln of vulnerabilities) { const severity = vuln.severity.toUpperCase(); if (severity.includes("CRITICAL")) criticalCount++; else if (severity.includes("HIGH")) highCount++; else if (severity.includes("MODERATE")) moderateCount++; else lowCount++; } } } // Summary mode: just show counts if (mode === "summary") { const total = criticalCount + highCount + moderateCount + lowCount; if (total === 0) { results += "\n✅ **No known security vulnerabilities found!**\n"; } else { results += `## 📊 Summary\n`; results += `- 🔴 Critical: ${criticalCount}\n`; results += `- 🟠 High: ${highCount}\n`; results += `- 🟡 Moderate: ${moderateCount}\n`; results += `- 🟢 Low: ${lowCount}\n`; results += `\n**Total vulnerabilities found: ${total}**\n\n`; results += `Run with scan_mode="full" for detailed information.\n`; } return results; } // Full or critical-high-only mode: show details for (const { packageName, version, vulnerabilities } of allVulnerabilities) { results += formatVulnerabilities( vulnerabilities, packageName, version, mode ); } // Summary section const total = criticalCount + highCount + moderateCount + lowCount; if (total === 0) { results += "\n✅ **No known security vulnerabilities found!**\n"; } else { results += `\n## 📊 Summary\n`; if (mode === "critical-high-only") { results += `- 🔴 Critical: ${criticalCount}\n`; results += `- 🟠 High: ${highCount}\n`; if (moderateCount + lowCount > 0) { results += `\n_Also found ${moderateCount + lowCount} moderate/low severity issues (hidden in this mode)._\n`; results += `_Run with scan_mode="full" to see all vulnerabilities._\n`; } } else { results += `- 🔴 Critical: ${criticalCount}\n`; results += `- 🟠 High: ${highCount}\n`; results += `- 🟡 Moderate: ${moderateCount}\n`; results += `- 🟢 Low: ${lowCount}\n`; results += `\n**Total vulnerabilities found: ${total}**\n`; } } return results; } catch (error) { if ((error as NodeJS.ErrnoException).code === "ENOENT") { return "❌ package.json file not found in this directory."; } throw error; } }
• src/index.ts:55-116 (helper)

  Core helper that queries the OSV.dev API for vulnerabilities in a specific package/version/ecosystem and maps results to standardized Vulnerability interface.
  async function checkVulnerability( packageName: string, version: string, ecosystem: string ): Promise<Vulnerability[]> { try { const response = await fetch("https://api.osv.dev/v1/query", { method: "POST", headers: { "Content-Type": "application/json", }, body: JSON.stringify({ package: { name: packageName, ecosystem: ecosystem, }, version: version, }), }); if (!response.ok) { throw new Error(`OSV API error: ${response.statusText}`); } const data = (await response.json()) as OSVResponse; if (!data.vulns || data.vulns.length === 0) { return []; } return data.vulns.map((vuln) => { let severity = "UNKNOWN"; // Try to get severity from different sources if (vuln.database_specific?.severity) { severity = vuln.database_specific.severity; } else if (vuln.severity && vuln.severity.length > 0) { // CVSS score parsing const cvss = vuln.severity.find((s) => s.type === "CVSS_V3"); if (cvss) { const score = parseFloat(cvss.score.split("/")[0] || "0"); if (score >= 9.0) severity = "CRITICAL"; else if (score >= 7.0) severity = "HIGH"; else if (score >= 4.0) severity = "MODERATE"; else severity = "LOW"; } } return { id: vuln.id, summary: vuln.summary || "No description available", severity: severity, references: vuln.references || [], package_name: packageName, affected_versions: [version], }; }); } catch (error) { console.error(`Error checking ${packageName}:`, error); return []; } }