knip-mcp-server/README.md

MCP server for knip.dev integration to help AI agents identify and clean up unused code

# @genar/knip-mcp-server

A Model Control Protocol (MCP) server that integrates with [knip.dev](https://knip.dev) to help AI agents identify and clean up unused files, imports, exports, and dependencies in JavaScript/TypeScript projects.

## Overview

This MCP server provides AI agents with powerful code cleanup capabilities through knip.dev integration. It's designed to work seamlessly with Cursor AI and other MCP-compatible tools to maintain clean, efficient codebases.

## Features

- **Code Analysis**: Run comprehensive knip analysis to find unused code
- **Unused File Detection**: Identify files that are no longer referenced
- **Import/Export Cleanup**: Find and remove unused imports and exports
- **Dependency Management**: Detect unused npm dependencies and devDependencies
- **Safe Operations**: Built-in safety checks and backup mechanisms
- **Workspace Support**: Full support for monorepo and workspace setups
- **Dry Run Mode**: Preview changes before applying them

## Installation

```bash
npm install -g @genar/knip-mcp-server
```

Or in your project:

```bash
npm install @genar/knip-mcp-server
```

## Usage

### As an MCP Server

Run the server directly:

```bash
knip-mcp-server
```

Or use npx:

```bash
npx @genar/knip-mcp-server
```

### Configuration

Configure via environment variables:

```bash
export KNIP_PROJECT_ROOT="/path/to/your/project"
export KNIP_CONFIG_PATH="/path/to/knip.json"
export KNIP_BACKUP_DIR="/path/to/backups"
export KNIP_LOG_LEVEL="info"
export KNIP_SAFE_MODE="true"
```

### Integration with Cursor AI

#### Option 1: MCP Server Configuration

1. In Cursor AI settings, navigate to MCP configuration
2. Add a new MCP server:
   - Name: "Knip Code Cleanup"
   - Command: `npx @genar/knip-mcp-server`
3. Save and restart Cursor AI

#### Option 2: Cursor Rules Configuration

You can also integrate this MCP server through Cursor's rules system by creating a `.cursor/rules` directory in your project root and adding the following configuration:

1. Create the rules directory structure:
```bash
mkdir -p .cursor/rules
```

2. Create a knip rule file (`.cursor/rules/knip-mcp.md`):

```markdown
# Knip Code Cleanup Rules

You have access to the Knip MCP server for code cleanup tasks. Use these tools proactively to maintain clean code:

## Available Tools

- `knip_scan` - Run comprehensive code analysis
- `knip_get_unused_files` - Find unused files
- `knip_get_unused_exports` - Find unused exports
- `knip_get_unused_imports` - Find unused imports  
- `knip_get_unused_dependencies` - Find unused dependencies
- `knip_remove_unused_files` - Safely remove unused files
- `knip_remove_unused_imports` - Clean up unused imports
- `knip_fix_issues` - Auto-fix common issues
- `knip_get_config` - View knip configuration
- `knip_validate_config` - Validate knip config

## Usage Guidelines

1. **After implementing features**: Always run `knip_scan` to identify cleanup opportunities
2. **Before commits**: Use `knip_fix_issues` with `dryRun: true` to preview cleanup
3. **Regular maintenance**: Run `knip_get_unused_dependencies` to audit packages
4. **Safety first**: Always use dry-run mode first, create backups for destructive operations

## Workflow Integration

When asked to implement features:
1. Complete the implementation
2. Run `knip_scan` to analyze unused code
3. Use `knip_remove_unused_imports` to clean imports
4. Check `knip_get_unused_files` for orphaned files
5. Apply fixes with appropriate safety measures

## Safety Measures

- All destructive operations default to dry-run mode
- Backups are created automatically before modifications
- File limits prevent accidental bulk deletions
- Safe mode protects critical files (package.json, etc.)

Remember: Always review suggestions before applying changes to ensure they don't break functionality.
```

3. Create a main rules file (`.cursor/rules/main.md`) that includes knip rules:

```markdown
# Project Development Rules

Include code cleanup and maintenance guidelines.

@knip-mcp.md

## Code Quality Standards

- Use the Knip MCP server for regular code cleanup
- Maintain clean imports and remove unused dependencies
- Follow the knip workflow after feature implementation
```

4. Optional: Add to your `.gitignore` if you want to keep rules private:
```bash
echo ".cursor/" >> .gitignore
```

#### Option 3: Per-Project MCP Configuration

Create a local MCP configuration file in your project root (`.mcp-config.json`):

```json
{
  "servers": {
    "knip": {
      "command": "npx",
      "args": ["@genar/knip-mcp-server"],
      "env": {
        "KNIP_PROJECT_ROOT": ".",
        "KNIP_LOG_LEVEL": "info",
        "KNIP_SAFE_MODE": "true"
      }
    }
  }
}
```

Then reference this configuration in Cursor's MCP settings.

## Available Tools

### `knip_scan`
Run comprehensive knip analysis on your project.

**Parameters:**
- `projectPath` (optional): Project path to analyze
- `workspace` (optional): Specific workspace for monorepos
- `includePaths` (optional): Array of paths to include
- `excludePaths` (optional): Array of paths to exclude
- `dryRun` (default: true): Run without making changes

### `knip_get_unused_files`
Get a list of unused files in the project.

**Parameters:**
- `workspace` (optional): Specific workspace to analyze

### `knip_get_unused_exports`
Get unused exports organized by file.

**Parameters:**
- `workspace` (optional): Specific workspace to analyze
- `filePath` (optional): Get exports for specific file only

### `knip_get_unused_imports`
Get unused imports organized by file.

**Parameters:**
- `workspace` (optional): Specific workspace to analyze
- `filePath` (optional): Get imports for specific file only

### `knip_get_unused_dependencies`
Get unused npm dependencies and devDependencies.

**Parameters:**
- `workspace` (optional): Specific workspace to analyze
- `type` (optional): 'dependencies', 'devDependencies', or 'all'

### `knip_remove_unused_files`
Safely remove unused files with backup options.

**Parameters:**
- `files` (optional): Specific files to remove, or all if empty
- `dryRun` (default: true): Preview mode
- `createBackup` (default: true): Create backups before removal
- `backupDir` (optional): Custom backup directory
- `maxFiles` (default: 50): Safety limit

### `knip_remove_unused_imports`
Remove unused imports from a specific file.

**Parameters:**
- `filePath` (required): File to clean up
- `imports` (optional): Specific imports to remove
- `dryRun` (default: true): Preview mode
- `createBackup` (default: true): Create backup before changes

### `knip_fix_issues`
Automatically fix common knip issues.

**Parameters:**
- `issueTypes` (default: ['imports']): Types of issues to fix
- `dryRun` (default: true): Preview mode
- `createBackup` (default: true): Create backups
- `maxFiles` (default: 25): Safety limit

### `knip_get_config`
Get the current knip configuration.

**Parameters:**
- `projectPath` (optional): Project path
- `configPath` (optional): Specific config file path

### `knip_validate_config`
Validate knip configuration for correctness.

**Parameters:**
- `projectPath` (optional): Project path
- `configPath` (optional): Specific config file path
- `config` (optional): Configuration object to validate

## Example AI Agent Workflows

### 1. Code Cleanup After Feature Implementation

```
AI Agent: I just implemented a new authentication feature. Let me clean up any unused code.

1. Run knip_scan to get overview of unused code
2. Use knip_get_unused_imports to find unused imports
3. Apply knip_remove_unused_imports to clean up imports
4. Check knip_get_unused_files for any orphaned files
5. Safely remove files using knip_remove_unused_files
```

### 2. Dependency Audit

```
AI Agent: Let me audit our dependencies for unused packages.

1. Run knip_get_unused_dependencies
2. Review the list of unused dependencies
3. Generate recommendation report for package.json cleanup
```

### 3. Project Health Check

```
AI Agent: Let me analyze the overall health of this codebase.

1. Run knip_scan for comprehensive analysis
2. Use knip_validate_config to check configuration
3. Generate health report with recommendations
```

## Safety Features

- **Dry Run Mode**: All destructive operations default to dry-run mode
- **Backup Creation**: Automatic backups before file modifications
- **Safe Mode**: Prevents removal of critical files (package.json, etc.)
- **File Limits**: Configurable limits on batch operations
- **Error Handling**: Comprehensive error reporting and recovery

## Configuration

The server supports knip configuration files:
- `knip.json`
- `knip.jsonc`
- `.knip.json`
- `.knip.jsonc`
- `knip.config.js`
- `knip.config.ts`

## Development

```bash
# Clone the repository
git clone https://github.com/genar/galleries.git
cd galleries/packages/knip-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

- GitHub Issues: [Report bugs or request features](https://github.com/genar/galleries/issues)
- Documentation: [Full documentation](https://github.com/genar/galleries/tree/main/packages/knip-mcp-server)

## Related Projects

- [knip.dev](https://knip.dev) - The underlying code analysis tool
- [MCP SDK](https://github.com/modelcontextprotocol/typescript-sdk) - Model Context Protocol implementation
- [Cursor AI](https://cursor.ai) - AI-powered code editor with MCP support