DOCUMENTATION

Complete reference for MCPShield

PACKAGES

MCPShield is published as a monorepo with three packages:

CLI REFERENCE

mcp-shield init

Initialize MCPShield in your project.

mcp-shield init [options]

OPTIONS

CREATES

• mcp.lock.json - Empty lockfile
• policy.yaml - Default policy configuration

mcp-shield add

Add an MCP server with verification and security scanning.

mcp-shield add <server-name> [options]

ARGUMENTS

• server-name - Namespace of the server (e.g., io.github.user/repo)

OPTIONS

WORKFLOW

1. Fetch metadata from MCP Registry
2. Verify namespace ownership (GitHub)
3. Download artifacts (npm/PyPI packages)
4. Compute SHA-512 digests
5. Run security scan
6. Display results and prompt for approval
7. Add to mcp.lock.json

mcp-shield verify

Re-verify all servers in the lockfile.

mcp-shield verify [options]

OPTIONS

CHECKS

• Download artifacts from cache or registry
• Recompute digests
• Compare against lockfile
• Report drift if detected

mcp-shield scan

Run comprehensive security scan on all servers.

mcp-shield scan [options]

OPTIONS

SECURITY CHECKS

• Typosquatting - Levenshtein distance against popular packages
• Code Patterns - Detect eval(), exec(), child_process
• Network Calls - Identify suspicious remote connections
• Install Scripts - Flag dangerous lifecycle hooks
• Dependencies - Scan transitive dependencies

LOCKFILE SPECIFICATION

The mcp.lock.json file uses this schema:

{
  "version": "1.0.0",
  "generatedAt": "2026-02-05T15:30:00.000Z",
  "servers": {
    "<namespace>": {
      "namespace": "string",
      "version": "string",
      "verified": boolean,
      "verificationMethod": "github" | "npm" | "pypi" | null,
      "verifiedOwner": "string" | null,
      "fetchedAt": "ISO8601 timestamp",
      "artifacts": [
        {
          "type": "npm" | "pypi" | "docker",
          "url": "string",
          "digest": "sha512-...",
          "size": number
        }
      ]
    }
  }
}

FIELDS

POLICY CONFIGURATION

The policy.yaml file defines security policies:

version: 1.0.0

policies:
  # Maximum acceptable risk score (0-100)
  maxRiskScore: 50

  # Require namespace verification
  requireVerification: true

  # Block packages with these code patterns
  blockPatterns:
    - eval
    - exec
    - child_process
    - crypto.createCipheriv

  # Allowed package registries
  allowedRegistries:
    - registry.npmjs.org
    - pypi.org

  # Trusted publishers (auto-approve)
  trustedPublishers:
    - modelcontextprotocol

  # Forbidden dependencies
  blockedDependencies:
    - malicious-package
    - known-exploit

  # Minimum version requirements
  minVersions:
    npm: "9.0.0"
    node: "18.0.0"

SECURITY SCANNING

RISK SCORING

Each server receives a risk score from 0-100:

DETECTION RULES

TYPOSQUATTING (+30 POINTS)

• Levenshtein distance < 3 from popular package
• Common character swaps (1 vs l, 0 vs O)
• Name similarity to official packages

SUSPICIOUS CODE (+20 POINTS EACH)

• eval() - Dynamic code execution
• exec() - Shell command execution
• child_process - Process spawning
• Obfuscated code (hex strings, base64)

NETWORK CALLS (+15 POINTS)

• HTTP/HTTPS requests to unknown domains
• WebSocket connections
• DNS lookups to suspicious TLDs (.ru, .cn)

INSTALL SCRIPTS (+10 POINTS)

• postinstall, preinstall scripts
• File system modifications
• Download/execute behavior

INTEGRATION EXAMPLES

GITHUB ACTIONS

name: Security Check
on: [push, pull_request]

jobs:
  mcp-shield:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '18'

      - name: Install MCPShield
        run: npm install -g @kellyclaude/mcpshield

      - name: Verify MCP servers
        run: |
          mcp-shield verify --strict
          mcp-shield scan

PRE-COMMIT HOOK

#!/bin/sh
# .git/hooks/pre-commit

echo "Running MCPShield verification..."
mcp-shield verify

if [ $? -ne 0 ]; then
  echo "❌ MCP server verification failed!"
  exit 1
fi

echo "✅ All MCP servers verified"
exit 0

CI/CD INTEGRATION

// package.json
{
  "scripts": {
    "pretest": "mcp-shield verify",
    "security": "mcp-shield scan --json > security-report.json"
  }
}

API DOCUMENTATION

PROGRAMMATIC USAGE

Use MCPShield as a library in your Node.js applications:

import { RegistryClient, Scanner, Lockfile } from '@kellyclaude/mcpshield-core';

// Fetch server metadata
const client = new RegistryClient();
const server = await client.getServerMetadata('io.github.user/repo');

// Run security scan
const scanner = new Scanner();
const result = await scanner.scanServer(server);

console.log(`Risk Score: ${result.riskScore}`);
console.log(`Verdict: ${result.verdict}`);

// Update lockfile
const lockfile = await Lockfile.load('mcp.lock.json');
await lockfile.addServer(server);
await lockfile.save();

CORE CLASSES

RegistryClient

Available in @kellyclaude/mcpshield-core

class RegistryClient {
  async getServerMetadata(namespace: string): Promise<ServerMetadata>
  async fetchArtifacts(server: ServerMetadata): Promise<Artifact[]>
}

Scanner

Available in @kellyclaude/mcpshield-scanner

class Scanner {
  async scanServer(server: ServerMetadata): Promise<ScanResult>
  async scanPackage(packagePath: string): Promise<ScanResult>
}

Lockfile

Available in @kellyclaude/mcpshield-core

class Lockfile {
  static async load(path: string): Promise<Lockfile>
  async addServer(server: LockedServer): Promise<void>
  async removeServer(namespace: string): Promise<void>
  async save(): Promise<void>
}

ARCHITECTURE

MONOREPO STRUCTURE

mcpshield/
├── packages/
│   ├── core/           # Core types and clients
│   │   ├── types.ts
│   │   ├── registry-client.ts
│   │   ├── namespace-verifier.ts
│   │   ├── lockfile.ts
│   │   └── artifact-resolver.ts
│   ├── scanner/        # Security scanning
│   │   ├── scanner.ts
│   │   └── rules/
│   └── cli/            # Command-line interface
│       ├── cli.ts
│       └── commands/
├── test/
│   ├── unit/
│   └── e2e/
└── docs/

DATA FLOW

1. Registry Fetch - RegistryClient fetches server metadata from MCP Registry
2. Namespace Verification - NamespaceVerifier validates GitHub ownership via API
3. Artifact Download - ArtifactResolver downloads npm/PyPI packages
4. Digest Computation - SHA-512 hashes computed for all artifacts
5. Security Scan - Scanner analyzes code for threats
6. Lockfile Update - Verified server added to mcp.lock.json

VERIFICATION METHODS

TECHNOLOGY STACK

• TypeScript - Type-safe development
• Node.js - Runtime (≥18.0.0)
• npm Workspaces - Monorepo management
• Commander.js - CLI framework
• Axios - HTTP client
• yaml - Policy parsing

PUBLISHED PACKAGES

The monorepo publishes three packages to npm:

• @kellyclaude/mcpshield - Main CLI tool
• @kellyclaude/mcpshield-core - Core types and clients
• @kellyclaude/mcpshield-scanner - Security scanning engine