codesort-server/README.md

🚀 CodeSort Server v2.0.0 - Simplified, robust MCP server for code analysis. Works with Claude Desktop, Claude CLI, and other AI tools. Zero configuration required.

# CodeSort Server v2.5.0 - Production Ready

🚀 **Simplified, robust MCP server for code analysis** - Works with Claude Desktop, Claude CLI, and other AI tools.

## ⚡ Quick Start (30 seconds)

### 1. Install
```bash
npm install -g codesort-server
```

⚠️ **Performance Note**: Direct command (`codesort`) is **5x faster** than npx. Always use direct command when possible.

### 2. Add to Claude CLI

**Method A: Direct command (Recommended - Fastest)**
Edit `C:\Users\Martin\.claude.json` (Windows) or `~/.claude.json` (macOS/Linux) and add:
```json
{
  "mcpServers": {
    "codesort": {
      "type": "stdio",
      "command": "codesort",
      "args": ["start", "--transport", "stdio"],
      "env": {}
    }
  }
}
```

**Method B: One-command setup**
```bash
claude mcp add --transport stdio codesort codesort start --transport stdio
```

**Method C: npx fallback (if direct command doesn't work)**
```json
{
  "mcpServers": {
    "codesort": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "codesort-server", "start", "--transport", "stdio"],
      "env": {}
    }
  }
}
```

### 3. Verify installation
```bash
claude mcp list
```

You should see: `codesort: codesort start --transport stdio - ✓ Connected`

### 4. Use immediately
```bash
claude --print "What functions exist in this project?"
```

## ✅ That's it! Minimal configuration required.

CodeSort automatically:
- ✅ Analyzes your entire codebase with intelligent issue detection
- ✅ Detects existing functions before creating duplicates
- ✅ Flags potential code quality issues and duplications:
  - 🔴 **HIGH**: Duplicate function names across files
  - 🟡 **MEDIUM**: Files with excessive functions (>20)
  - 🟢 **LOW**: Naming convention inconsistencies
- ✅ Provides context-aware suggestions
- ✅ Works with any MCP-compatible AI tool

## 🛠️ Supported AI Tools

### Claude CLI (Recommended)
```bash
# Add to Claude CLI (direct command - fastest)
claude mcp add --transport stdio codesort codesort start --transport stdio

# Use immediately
claude --print "Create a user authentication function"
```

### Claude Desktop
```json
{
  "mcpServers": {
    "codesort": {
      "command": "codesort",
      "args": ["start", "--transport", "stdio"]
    }
  }
}
```

### Other MCP Tools
Use universal configuration:
```json
{
  "mcpServers": {
    "codesort": {
      "command": "codesort",
      "args": ["start", "--transport", "stdio"]
    }
  }
}
```

## 🔧 Troubleshooting

### "codesort command not found" or MCP server not connecting:

**Option 1: Use npx fallback (Slower but works)**
⚠️ **Note**: npx is 5x slower than direct command but works regardless of PATH configuration:
```json
{
  "mcpServers": {
    "codesort": {
      "command": "npx",
      "args": ["-y", "codesort-server", "start", "--transport", "stdio"]
    }
  }
}
```

**Option 2: Use full path (Windows)**
```json
{
  "mcpServers": {
    "codesort": {
      "command": "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\npm\\codesort.cmd",
      "args": ["start", "--transport", "stdio"]
    }
  }
}
```

**Option 3: Use full path (macOS/Linux)**
```json
{
  "mcpServers": {
    "codesort": {
      "command": "/usr/local/bin/codesort",
      "args": ["start", "--transport", "stdio"]
    }
  }
}
```

**Option 4: Add to PATH (Recommended fix)**
1. Find your npm global bin directory: `npm config get prefix`
2. Add it to your system PATH environment variable
3. Restart your terminal/AI tool

## 🚀 What CodeSort Does

When you ask an AI to create code, CodeSort automatically:

1. **🔍 Scans your codebase** for existing functions
2. **⚠️ Prevents duplicates** by suggesting existing code
3. **📋 Follows your patterns** and coding conventions
4. **🎯 Provides context** based on your actual codebase

### Example

```
You: "Create a user authentication function"

AI: "I found existing authentication in `src/auth/login.ts:15`.
Would you like me to extend the existing functionality or create something different?"
```

## 📋 Available Commands

```bash
# Direct CLI usage
codesort analyze                    # Analyze current project
codesort search "user auth"          # Search functions
codesort docs all                   # Generate docs
codesort info                       # Show server info

# Start MCP server (for AI tools)
codesort start --transport stdio
```

## 🔧 MCP Tools Available

- **`analyze_codebase`** - Complete project analysis with flexible output formats and token management
  - **NEW:** `output_format` - Choose between `minimal`, `summary`, or `comprehensive`
  - **NEW:** `max_files` - Limit number of files analyzed (1-200)
  - **NEW:** `max_issues` - Limit issues reported (1-100)
  - **NEW:** `severity_filter` - Filter issues by severity (`high`, `medium`, `low`)
  - **NEW:** `max_tokens` - Set token limit with automatic truncation (1000-25000)
- **`search_functions`** - Find existing functions and patterns
- **`find_dependencies`** - 🔗 Analyze import/require dependencies and detect circular dependencies
- **`security_scan`** - 🛡️ Scan code for common security vulnerabilities and anti-patterns
- **`documentation_sitemap`** - Generate comprehensive documentation with AI guidance
- **`validate_structure`** - Validate TypeScript type consistency
- **`ripple_effects`** - Analyze impact of changes before implementing
- **`full_audit`** - Run comprehensive audit of all tools

## 📊 MCP Resources Available

- **`project://overview`** - Project summary and info

## 🎯 Production Features

- ✅ **Simplified Architecture** - Removed complex dependencies
- ✅ **Robust Error Handling** - Graceful failure handling
- ✅ **Performance Optimized** - Smart caching and limits
- ✅ **Type Safe** - Full TypeScript strict mode
- ✅ **Zero Configuration** - Works out of the box
- ✅ **Multi-language Support** - TypeScript, JavaScript, Python

## 🏗️ Development

### Prerequisites
- Node.js 18+
- TypeScript 5.0+

### Setup
```bash
git clone https://github.com/codesort/codesort-server.git
cd codesort-server
npm install
npm run build
```

### Scripts
```bash
npm run dev          # Development mode
npm run build        # Build for production
npm run test         # Run tests
npm run lint         # Lint code
```

## 📈 What's New in v2.5.0

### 🎉 Major Token Management Improvements
- **📊 Flexible Output Formats** - `analyze_codebase` now supports `minimal`, `summary`, and `comprehensive` formats
- **🔧 Advanced Filtering** - Filter issues by severity (`high`, `medium`, `low`) and limit issue count
- **⚡ Performance Controls** - Limit files analyzed (1-200) and manage response size
- **🛡️ Token Limits** - Built-in token management with automatic truncation (1000-25000 tokens)
- **🎯 Smart Caching** - Parameter-aware caching for consistent and fast responses

### 🚀 Enhanced MCP Tool Suite
- **📋 Documentation Sitemap** - Generate AI-aware documentation with cross-references
- **✅ Structure Validation** - Validate TypeScript type consistency and prevent drift
- **🌊 Ripple Effects Analysis** - Analyze impact of changes before implementing
- **🔍 Full Audit Mode** - Comprehensive audit of all tools for complete health assessment

### 🔧 Usage Examples for Large Codebases
```typescript
// For large codebases - use minimal format
analyze_codebase({
  output_format: "minimal",
  max_files: 20,
  max_issues: 5,
  severity_filter: "high",
  max_tokens: 5000
})

// For medium codebases - use summary format
analyze_codebase({
  output_format: "summary",
  max_files: 50,
  max_issues: 15,
  severity_filter: "medium"
})
```

### Previous v2.1.1 Features
- **🔗 Dependency Analysis Tool** - `find_dependencies` tool for comprehensive dependency analysis
- **🛡️ Security Scanning** - `security_scan` tool for detecting common security vulnerabilities
- **⚡ Performance Enhancements** - Parallel processing and improved caching

### 🔗 Dependency Analysis Features (`find_dependencies`)
- **Import/Require Detection** - Analyzes ES6 imports, CommonJS requires, and Python imports
- **Circular Dependency Detection** - Identifies circular dependencies in your codebase
- **Dependency Classification** - Categorizes dependencies as internal, external, or built-in
- **Most Connected Files** - Identifies files with the highest number of dependencies
- **External Dependencies Report** - Shows most frequently used external packages

### 🛡️ Security Analysis Features (`security_scan`)
- **Hardcoded Secrets Detection** - Scans for passwords, API keys, tokens in code
- **Insecure Pattern Detection** - Identifies eval(), innerHTML, document.write() usage
- **Input Validation Issues** - Detects unsanitized user input handling
- **Severity Classification** - Issues classified as High, Medium, or Low severity
- **Actionable Recommendations** - Provides specific remediation advice

### ⚡ Performance Enhancements
- **Parallel Processing** - Multiple files analyzed simultaneously for faster results
- **Enhanced Caching** - Improved cache strategies with longer TTL for different analysis types
- **Memory Optimization** - Better memory management for large codebases
- **Incremental Analysis** - Foundation for future incremental analysis features

### Previous v2.0.2-beta Features
- **🐛 Fixed Duplicate Detection Bug** - Resolved critical function parsing issues
- **🔴 Intelligent Issue Detection** - Added comprehensive code analysis issue detection
- **⚡ Enhanced Search Accuracy** - Improved function detection and reduced false positives
- **📊 Rich Analysis Reports** - Detailed codebase analysis with actionable insights

### Previous v2.0.0 Features
- **Simplified Codebase** - Removed complex AST parsing and embeddings
- **Better Performance** - Faster parsing with regex-based approach
- **Robust Error Handling** - Graceful degradation on errors
- **Production Ready** - Extensive testing and validation
- **Zero Dependencies** - Minimal external dependencies
- **Type Safe** - Full TypeScript strict mode compliance

## 🔍 Technical Details

### Supported Languages
- **TypeScript** (.ts, .tsx)
- **JavaScript** (.js, .jsx)
- **Python** (.py)
- **Java** (.java)
- **C/C++** (.c, .cpp, .cc, .cxx)
- **Go** (.go)
- **Rust** (.rs)
- **PHP** (.php)
- **Ruby** (.rb)

### Function Detection
Uses optimized regex patterns for reliable function detection:
- Function declarations
- Arrow functions
- Class definitions
- Interface declarations
- Method definitions
- Import/Export statements

## 🛡️ Error Handling

- Graceful file reading errors
- Invalid syntax handling
- Network timeout protection
- Memory usage limits
- Comprehensive logging

## 📝 License

MIT License - see the [LICENSE](LICENSE) file for details.

## 🆘 Support

- **Issues**: [GitHub Issues](https://github.com/codesort/codesort-server/issues)
- **Documentation**: [Full Documentation](https://github.com/codesort/codesort-server#readme)

---

**CodeSort Server v2.5.0** - *Simplified, Robust, Production-Ready*

*Install once, use everywhere. Simple. Powerful. Ready to go.* 🚀