vulnicheck: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

VulniCheck is a Python-based MCP (Model Context Protocol) HTTP server that provides real-time security vulnerability checking for Python packages. It runs as an HTTP-only service with support for both local file access and client-delegated file operations via the FileProvider architecture. The server queries multiple authoritative vulnerability databases including OSV.dev, NVD (National Vulnerability Database), and GitHub Advisory Database.

Key Commands

Development Setup

# Install development dependencies with uv
uv pip install -e ".[dev]"

# Or traditional pip
pip install -e ".[dev]"

Testing

# Run all tests
make test

# Run unit tests only
make test-unit

# Run integration tests only (requires API credentials)
make test-integration

# Run tests with coverage
make test-coverage

# Run specific test categories
make test-mcp        # MCP-related tests
make test-security   # Security-related tests
make test-clients    # Client tests

# Run a single test file
pytest tests/test_scanner.py -v

Note: Integration tests for GitHub API require GITHUB_TOKEN environment variable to avoid rate limiting. Tests will be skipped if credentials are not available.

Code Quality

# Run all linting and type checking
make lint

# Auto-fix linting issues
make lint-fix

# Format code with ruff
make format

# Type checking only
make type-check

Pre-commit Hooks

The project uses pre-commit hooks to ensure code quality before commits:

# Install pre-commit hooks (one-time setup)
uv run pre-commit install

# Run pre-commit hooks manually on all files
uv run pre-commit run --all-files

# Skip pre-commit hooks temporarily (not recommended)
git commit --no-verify

Pre-commit checks include:

• Standard checks (trailing whitespace, file endings, yaml/json/toml validation)
• make lint - Runs ruff and mypy checks
• make test-unit - Runs unit tests
• Detects private keys and merge conflicts