npm package: @notprolands/dev-tools-mcp
Description: MCP (Model Context Protocol) server with tree, linter, and jq tools
Author: notprolands
Latest version: 1.1.0

# Dev-Tools MCP Server

Modern MCP (Model Context Protocol) server providing essential development tools for AI-assisted coding in TypeScript/JavaScript projects.

## 🚀 Features

### 🌳 **Tree Tool** - Enhanced Directory Visualization
- **Hierarchical tree view** with git status integration
- **Superior to `ls`** for AI agents - shows structure, git status, and metadata in one call
- **Git integration**: Shows modified files (M), staged changes (A), untracked files (??)
- **Workspace-aware**: Automatically detects project root in pnpm/bun workspaces
- **Flexible filtering**: Hidden files, gitignored files, detailed information

### 🔧 **Linter Tool** - Code Quality & Formatting
- **All-in-one**: Formatting, linting, and import sorting in a single command
- **Multi-package manager support**: Works seamlessly with both pnpm and bun workspaces
- **Fast Rust-based**: Powered by Biome for superior performance vs Prettier + ESLint
- **Smart fixes**: Safe and unsafe code improvements with granular control
- **CI-ready**: Supports staged files, changed files, and verbose diagnostics

### 📊 **JQ Tool** - JSON Data Processing
- **Powerful queries**: Filter, map, sort, group, and transform JSON data
- **Flexible output**: Compact mode, raw strings, or pretty-formatted JSON
- **Complex operations**: Supports nested queries and advanced jq expressions
- **Type-safe**: Handles various JSON structures (objects, arrays, primitives)

## 📦 Installation

### Global Installation
```bash
npm install -g @notprolands/dev-tools-mcp
```

### Project-specific Installation
```bash
# pnpm workspaces
pnpm add -wD @notprolands/dev-tools-mcp

# npm projects  
npm install --save-dev @notprolands/dev-tools-mcp
```

## 🔧 Usage

### With Claude Code
```bash
# Using global install
claude mcp add dev-tools -- npx @notprolands/dev-tools-mcp

# Using workspace install (recommended for teams)
claude mcp add dev-tools -- pnpm exec @notprolands/dev-tools-mcp
```

### With Other MCP Clients

**For pnpm workspaces** (`.mcp.json`):
```json
{
  "mcpServers": {
    "dev-tools": {
      "type": "stdio",
      "command": "pnpm",
      "args": ["exec", "@notprolands/dev-tools-mcp"]
    }
  }
}
```

**For bun workspaces** (`.mcp.json`):
```json
{
  "mcpServers": {
    "dev-tools": {
      "type": "stdio", 
      "command": "bun",
      "args": ["x", "@notprolands/dev-tools-mcp"]
    }
  }
}
```

**For global installs** (`.mcp.json`):
```json
{
  "mcpServers": {
    "dev-tools": {
      "type": "stdio",
      "command": "npx",
      "args": ["@notprolands/dev-tools-mcp"]
    }
  }
}
```

## 🛠️ Tool Reference

### Tree Tool
```javascript
// Basic directory listing with git status
{
  "name": "tree",
  "arguments": {
    "git": true,
    "path": "src/"
  }
}

// Comprehensive analysis with all options
{
  "name": "tree", 
  "arguments": {
    "git": true,
    "long": true,
    "all": true,
    "gitIgnore": true
  }
}
```

### Linter Tool
```javascript
// Format and fix specific files
{
  "name": "linter",
  "arguments": {
    "paths": ["src/", "packages/"],
    "write": true,
    "verbose": true
  }
}

// Check staged files before commit
{
  "name": "linter",
  "arguments": {
    "staged": true,
    "write": false
  }
}

// Apply unsafe fixes (use with caution)
{
  "name": "linter",
  "arguments": {
    "write": true,
    "unsafe": true
  }
}
```

### JQ Tool  
```javascript
// Extract specific fields
{
  "name": "jq",
  "arguments": {
    "data": {"users": [{"name": "Alice", "age": 30}]},
    "query": ".users[].name"
  }
}

// Complex filtering and transformation
{
  "name": "jq",
  "arguments": {
    "data": apiResponse,
    "query": ".items[] | select(.active == true) | {name, id}",
    "options": {"compact": true}
  }
}
```

## 📋 Requirements

### Core Requirements
- **Node.js 18+**
- **Package Manager**: pnpm, bun, or npm

### Optional Dependencies (auto-detected)
- **`eza`**: Required for tree tool functionality
- **`jq`**: Required for JSON processing tool
- **`biome`**: Automatically installed via package manager for linter tool

### Installation Commands
```bash
# Install eza (cross-platform)
cargo install eza
# or: brew install eza (macOS)
# or: apt install eza (Ubuntu 22.04+)

# Install jq
brew install jq        # macOS
apt install jq         # Ubuntu/Debian  
choco install jq       # Windows
```

## 🔍 Advanced Features

### Multi-Package Manager Support
The server automatically detects your workspace type:
- **pnpm workspaces**: Detected by `pnpm-workspace.yaml`
- **bun workspaces**: Detected by `package.json` + `bun.lockb`
- **Fallback**: Uses available package manager

### AI Agent Optimizations
- **Single-call efficiency**: Tree tool combines `ls` + `git status` + metadata
- **Smart defaults**: Linter applies safe fixes by default
- **Rich context**: All tools provide comprehensive output for better AI understanding
- **Error handling**: Graceful fallbacks with helpful error messages

### Security Features
- **Path validation**: Prevents directory traversal attacks
- **Input sanitization**: All parameters are validated and sanitized
- **Safe execution**: Commands run within workspace boundaries

## 🏗️ Architecture

- **Modular Design**: Easy to extend with new tools
- **Type Safety**: Full TypeScript with Zod validation
- **MCP Compliant**: Follows MCP 2025-06-18 protocol specifications
- **Cross-Platform**: Works on Windows, macOS, and Linux

## 📝 License

MIT - see [LICENSE](LICENSE) file for details

## 🤝 Contributing

Contributions welcome! This server is part of a larger dev-tools monorepo. See the main repository for contribution guidelines.

## 🔗 Related Packages

- **[@notprolands/ast-grep-mcp](https://www.npmjs.com/package/@notprolands/ast-grep-mcp)**: AST-based code search and transformation
- **[MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)**: Official MCP SDK for TypeScript