@depsshield/mcp-server

Model Context Protocol (MCP) server for DepsShield - Expose security risk assessment to AI agents.

Overview

This package provides an MCP server that exposes DepsShield's security assessment capabilities to AI coding agents like Claude Desktop, Cline, and Continue. AI agents can use DepsShield to make informed decisions about package safety in real-time.

Features

• Two MCP Tools:
  • assess_package - Assess security risk of a single npm package
  • analyze_dependencies - Analyze all dependencies from package.json
• Real-time Vulnerability Detection: Live data from OSV.dev
• Comprehensive Risk Scoring: 0-200 point scale with LOW/MEDIUM/HIGH/CRITICAL levels
• Parallel Processing: Analyze multiple packages simultaneously for better performance
• Stdio Transport: Communicates via stdin/stdout (no network ports needed)

Installation

For Claude Desktop

1. Build the MCP server:

cd packages/mcp-server
pnpm install
pnpm build

2. Find your Claude Desktop config file:

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json

# Windows
%APPDATA%\Claude\claude_desktop_config.json

# Linux
~/.config/Claude/claude_desktop_config.json

3. Add DepsShield MCP server to your config:

{
  "mcpServers": {
    "depsshield": {
      "command": "node",
      "args": ["/absolute/path/to/depsshield/packages/mcp-server/build/index.js"]
    }
  }
}

Important: Use the absolute path, not a relative path!

4. Restart Claude Desktop

5. Verify the server appears in Claude's available tools

Usage

In Claude Desktop

Once configured, you can ask Claude to use DepsShield:

Example 1: Assess a single package

You: "What's the security risk of using lodash version 4.17.20?"

Claude: *uses assess_package tool*
       "lodash@4.17.20 has a HIGH risk level (score: 156/200).
        It has 3 known vulnerabilities including CVE-2020-8203 (Prototype Pollution).
        I recommend updating to lodash@4.17.21 or later."

Example 2: Analyze project dependencies

You: "Analyze the security of my project dependencies"

Claude: *reads package.json, uses analyze_dependencies tool*
       "I found 3 packages with security concerns:
        - lodash@4.17.20: HIGH risk (3 CVEs)
        - axios@0.21.1: CRITICAL risk (1 critical CVE)
        - express@4.18.2: LOW risk (well-maintained)"

Tool Schemas

assess_package

Assess a single npm package for security risks.

Input:

{
  package: string;           // Required: Package name (e.g., "lodash" or "@scope/package")
  version?: string;          // Optional: Specific version or range (defaults to latest)
  ecosystem?: 'npm';         // Optional: Only npm supported (default: 'npm')
}

Output:

{
  total: number;             // Risk score 0-200
  riskLevel: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
  components: {
    vulnerabilityScore: number;  // 0-100
    maintenanceScore: number;    // 0-50
    popularityScore: number;     // 0-50
  };
  vulnerabilities: Array<{
    id: string;              // CVE ID
    summary: string;
    severity: string;
    publishedAt: string;
    fixedIn?: string[];      // Versions where fixed
  }>;
  recommendation: string;    // Actionable advice
  metadata: {
    package: string;
    version: string;
    ecosystem: string;
    assessedAt: string;
    dataFreshness: {
      vulnerabilities: string;
      metadata: string;
    };
  };
}

analyze_dependencies

Analyze all dependencies from a package.json file.

Input:

{
  dependencies: Record<string, string>;      // Required: Dependencies object
  devDependencies?: Record<string, string>;  // Optional: Dev dependencies
  ecosystem?: 'npm';                         // Optional: Only npm supported
}

Output:

{
  total: number;             // Total number of dependencies
  assessed: number;          // Successfully assessed
  failed: number;            // Failed assessments
  vulnerabilities: {
    total: number;           // Total vulnerabilities found
  };
  riskLevels: {
    critical: number;
    high: number;
    medium: number;
    low: number;
  };
  results: Array<{
    package: string;
    requestedVersion: string;
    assessment?: DepsShieldScore;  // Full assessment result
    error?: string;                 // If assessment failed
  }>;
}

How It Works

MCP Protocol (Model Context Protocol)

MCP is a standardized protocol for AI agents to interact with external tools:

1. Discovery: AI agent asks "What tools are available?"
2. Invocation: AI agent calls a tool with specific arguments
3. Response: Tool returns structured data (JSON)

Communication Flow

┌─────────────────┐
│ Claude Desktop  │
└────────┬────────┘
         │
         │ 1. Spawn child process
         │    node build/index.js
         │
         ▼
┌─────────────────┐
│  MCP Server     │ ◄──── stdin/stdout (JSON-RPC)
│  (DepsShield)   │
└────────┬────────┘
         │
         │ 2. List available tools
         │    → assess_package
         │    → analyze_dependencies
         │
         │ 3. Call tool
         │    { tool: "assess_package", args: {...} }
         │
         ▼
┌─────────────────┐
│ PackageAssessor │ ◄──── Fetch data from OSV + npm
│ (@depsshield/   │
│      core)      │
└────────┬────────┘
         │
         │ 4. Return results
         │    { total: 156, riskLevel: "HIGH", ... }
         │
         ▼
┌─────────────────┐
│ Claude Desktop  │ ◄──── Parse and present to user
└─────────────────┘

Why stdin/stdout?

• Simpler than HTTP: No port management or network configuration
• Secure: No exposed network endpoints
• Lightweight: Just pipe JSON messages back and forth
• Standard: Works across all platforms (macOS, Windows, Linux)

Performance

Parallel Processing

The analyze_dependencies tool assesses all packages in parallel using Promise.all():

Sequential (slow):

for (const pkg of packages) {
  await assess(pkg);  // Wait for each one
}
// Total time: 5s (if each takes 1s)

Parallel (fast):

await Promise.all(
  packages.map(pkg => assess(pkg))
);
// Total time: ~1s (all run simultaneously!)

Real Performance (from tests):

• Assessing 3 packages in parallel: 412ms
• Sequential would take: ~1200ms+
• Speedup: ~3x faster

Response Times

• Single package (cache miss): ~2-3 seconds
• Single package (cache hit): ~50ms
• 10 packages (parallel): ~3-5 seconds
• 10 packages (sequential): ~20-30 seconds

Development

Running Tests

pnpm test

Building

pnpm build

Development Mode

pnpm dev

Troubleshooting

Server not showing in Claude Desktop

1. Check config file path: Make sure you edited the correct claude_desktop_config.json
2. Use absolute paths: Relative paths won't work
3. Restart Claude Desktop: Fully quit and relaunch
4. Check logs:
   • macOS: ~/Library/Logs/Claude/mcp.log
   • Windows: %APPDATA%\Claude\logs\mcp.log

Server crashing

1. Build first: Make sure you ran pnpm build
2. Check dependencies: Run pnpm install in both root and mcp-server
3. Check core package: Make sure @depsshield/core is built
4. View errors: Check Claude logs or run manually:

   node build/index.js
   # Then type: {"jsonrpc":"2.0","id":1,"method":"initialize"}

Slow performance

1. Check internet: OSV and npm APIs require network access
2. Cache warming: First assessment is slow, subsequent are fast
3. Parallel processing: Make sure you're using analyze_dependencies for multiple packages

Architecture

File Structure

packages/mcp-server/
├── src/
│   ├── index.ts           # Main MCP server implementation
│   └── index.test.ts      # Unit tests
├── build/                 # Compiled JavaScript (generated)
│   ├── index.js
│   ├── index.d.ts
│   └── *.map
├── package.json
├── tsconfig.json
└── README.md              # This file

Dependencies

• @modelcontextprotocol/sdk - MCP protocol implementation
• @depsshield/core - Risk assessment engine
• vitest - Testing framework (dev)

API Reference

See @depsshield/core for the underlying assessment API.

Examples

Example 1: Basic Usage

# Start the server (normally done by Claude Desktop)
node build/index.js

# Send a request (stdin)
{"jsonrpc":"2.0","id":1,"method":"tools/list"}

# Response (stdout)
{"jsonrpc":"2.0","id":1,"result":{"tools":[...]}}

Example 2: Assess Package

# Request
{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "assess_package",
    "arguments": {
      "package": "lodash",
      "version": "4.17.20"
    }
  }
}

# Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "content": [{
      "type": "text",
      "text": "{\"total\":156,\"riskLevel\":\"HIGH\",...}"
    }]
  }
}

Future Enhancements (M4+)

• Support for PyPI, Maven, and other ecosystems
• Webhook notifications when package risk changes
• Cached results for faster responses
• Batch processing optimizations
• Alternative transports (HTTP, WebSocket)

Contributing

This is currently a solo project. Contributions will be accepted after M3 validation.

License

MIT

Part of DepsShield - AI-native security intelligence platform Last Updated: November 2025 Status: M1 Week 2 - MCP Server Implementation Complete