osv-ui-mcp

Instructions

Implementation Reference

• packages/mcp/bin/osv-ui-mcp.js:165-210 (handler)

  The handleScanProject function is the core handler for the scan_project tool. It resolves the directory path, triggers the scanService to perform the actual vulnerability analysis, filters the results based on the provided severity, and formats the output as a Markdown summary.

  async function handleScanProject({ path: dir = '.', severity_filter = 'all', offline = false }) {
    const absDir = resolve(dir);
    if (!existsSync(absDir)) {
      return err(`Directory not found: ${absDir}`);
    }
  
    const result = await scanService(absDir, { noOsv: offline });
    const sevOrder = { critical: 0, high: 1, moderate: 2, low: 3 };
    const filterRank = sevOrder[severity_filter] ?? 4;
  
    const filtered = result.vulns.filter(v => (sevOrder[v.severity] ?? 4) <= filterRank);
  
    // Build a clean, LLM-readable summary
    const lines = [
      `## CVE Scan: ${result.name}`,
      `**Directory:** ${absDir}`,
      `**Ecosystem:** ${result.ecosystem}`,
      `**Packages scanned:** ${result.totalPackages} (${result.directCount} direct)`,
      `**Risk score:** ${result.riskScore}/100`,
      '',
      '### Vulnerability summary',
      `| Severity | Count |`,
      `|----------|-------|`,
      `| 🔴 Critical | ${result.severity.critical} |`,
      `| 🟠 High     | ${result.severity.high} |`,
      `| 🟡 Moderate | ${result.severity.moderate} |`,
      `| 🔵 Low      | ${result.severity.low} |`,
      `| **Total**   | **${result.vulns.length}** |`,
      '',
    ];
  
    if (filtered.length === 0) {
      lines.push(severity_filter === 'all'
        ? '✅ No vulnerabilities found!'
        : `✅ No ${severity_filter}+ vulnerabilities found.`);
    } else {
      lines.push(`### Vulnerabilities (${filtered.length}${severity_filter !== 'all' ? ` filtered to ${severity_filter}+` : ''})`);
      lines.push('');
      for (const v of filtered.slice(0, 30)) {
        const fix = v.fixedIn ? `→ fix: **${v.fixedIn}**` : '→ no fix available';
        const type = v.isDirect ? 'direct' : 'transitive';
        lines.push(`- **[${v.severity.toUpperCase()}]** \`${v.packageName}@${v.packageVersion}\` (${type}) — ${v.title} (${v.cveId || v.id}) ${fix}`);
      }
      if (filtered.length > 30) {
        lines.push(`\n_... and ${filtered.length - 30} more. Use open_dashboard for full list._`);
      }

• packages/mcp/bin/osv-ui-mcp.js:37-64 (registration)

  Registration of the scan_project tool, including its schema definition, input parameters, and description.

  {
    name: 'scan_project',
    description:
      'Scan a project directory for CVE vulnerabilities. ' +
      'Automatically detects npm (package-lock.json), Python (requirements.txt / Pipfile.lock / poetry.lock), ' +
      'Go (go.sum), and Rust (Cargo.lock) manifests. ' +
      'Queries live CVE data from OSV.dev. ' +
      'Returns structured vulnerability report with severity counts, risk score, and fix recommendations. ' +
      'Use this as the first step before open_dashboard or apply_fixes.',
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: 'Absolute or relative path to the project directory. Defaults to current working directory.',
        },
        severity_filter: {
          type: 'string',
          enum: ['all', 'critical', 'high', 'moderate', 'low'],
          description: 'Only return vulnerabilities at this severity or above. Default: all.',
        },
        offline: {
          type: 'boolean',
          description: 'If true, skip OSV.dev query and only parse manifests. Default: false.',
        },
      },
    },
  },