enhanced-mcp-tools/README.md

<div align="center">

# 🚀 Enhanced MCP Tools

### *A comprehensive Model Context Protocol (MCP) server with 50+ development tools*

[![Python](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![FastMCP](https://img.shields.io/badge/FastMCP-2.8.1+-green.svg)](https://github.com/jlowin/fastmcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build Status](https://github.com/yourusername/enhanced-mcp-tools/workflows/CI/badge.svg)](https://github.com/yourusername/enhanced-mcp-tools/actions)
[![Coverage](https://img.shields.io/badge/coverage-85%25-brightgreen.svg)](https://github.com/yourusername/enhanced-mcp-tools)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)

---

**🔧 Professional Development Tools** • **🤖 AI Assistant Ready** • **⚡ High Performance** • **🛡️ Type Safe**

[Getting Started](#-getting-started) • [MCP Inspector](#-mcp-inspector---interactive-tool-testing) • [Features](#-features) • [Examples](#-usage-examples) • [Contributing](#-contributing)

</div>

## 📖 Table of Contents

- [✨ Features](#-features)
- [🚀 Getting Started](#-getting-started)
- [🔍 MCP Inspector](#-mcp-inspector---interactive-tool-testing)
- [⚙️ Configuration](#️-configuration)
- [🛠️ Available Tools](#️-available-tools)
- [📚 Usage Examples](#-usage-examples)
- [🏗️ Architecture](#️-architecture)
- [🧪 Testing](#-testing)
- [📦 Deployment](#-deployment)
- [🤝 Contributing](#-contributing)
- [📄 License](#-license)

## ✨ Features

<table>
<tr>
<td width="50%">

### 🔄 **Core Operations**
- **Diff/Patch Operations** - Advanced file comparison and patching
- **Git Integration** - Smart git operations with AI suggestions  
- **File Operations** - Enhanced file watching, bulk operations, backups

### 🔍 **Analysis & Search**
- **Semantic Code Search** - AST-based intelligent code analysis
- **Codebase Analytics** - Comprehensive project insights
- **Duplicate Detection** - Find and analyze code duplication

</td>
<td width="50%">

### 🏗️ **Development Workflow**
- **Test Execution** - Multi-framework test runner with coverage
- **Code Quality** - Linting, formatting, and quality checks
- **Documentation** - Auto-generated docs from code

### 🌐 **Network & System**
- **HTTP Client** - Advanced requests with streaming support
- **Process Tracing** - System call monitoring and analysis
- **Environment Management** - Virtual environments and dependencies

### ⚡ **High-Performance Analytics**
- **Sneller Integration** - Vectorized SQL on JSON (TB/s throughput)
- **AVX-512 Optimization** - 1GB/s/core processing speed
- **Schemaless Querying** - Direct JSON analysis without ETL

### 🎬 **Terminal & Collaboration**
- **Asciinema Recording** - Professional terminal session capture
- **Demo Creation** - Embeddable terminal recordings
- **Command Auditing** - Searchable execution history

### 🧠 **AI-Powered Assistance**
- **Intelligent Recommendations** - Context-aware tool suggestions
- **Workflow Generation** - Automated multi-step process creation
- **Performance Optimization** - AI-guided tool selection

</td>
</tr>
</table>

### 🎯 **Why Enhanced MCP Tools?**

| Feature | Traditional Tools | Enhanced MCP Tools |
|---------|------------------|-------------------|
| **Integration** | Manual CLI calls | Native MCP protocol |
| **AI Assistance** | No context sharing | Full context awareness |
| **Error Handling** | Basic exit codes | Rich error reporting with suggestions |
| **Progress Tracking** | Silent execution | Real-time progress updates |
| **Type Safety** | Runtime errors | Compile-time validation |

## 🚀 Getting Started

### 📋 Prerequisites

- **Python 3.10+** (3.11+ recommended)
- **uv** package manager ([install guide](https://github.com/astral-sh/uv))
- **Git** (for git-related tools)

### ⚡ Quick Installation

```bash
# Clone the repository
git clone https://github.com/yourusername/enhanced-mcp-tools.git
cd enhanced-mcp-tools

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .
```

### 🎮 Quick Start

```bash
# Start the MCP server
enhanced-mcp

# Or run with uv
uv run enhanced-mcp

# Development mode with inspector
mcp dev enhanced_mcp/mcp_server.py
```

> 🎯 **Developer Quick Start**: Launch `mcp dev enhanced_mcp/mcp_server.py` and open http://localhost:3000 to interactively test all 50+ tools in your browser!

## 🔍 MCP Inspector - Interactive Tool Testing

The **MCP Inspector** is a powerful web-based interface for testing, debugging, and exploring your MCP tools interactively. It's essential for development and verification.

### 🚀 **Quick Inspector Launch**

```bash
# Launch inspector with the enhanced MCP tools
mcp dev enhanced_mcp/mcp_server.py

# Or use the module path
uv run mcp dev enhanced_mcp.mcp_server:create_server

# For production inspection (if mcp CLI is installed globally)
mcp inspect enhanced-mcp
```

### 🎮 **Using the Inspector Interface**

Once launched, the inspector provides:

#### **📋 Tools Tab** - Interactive Tool Testing
```bash
# The inspector will show all 50+ tools organized by category:
├── 🔄 diff_patch_*       # Diff and patch operations  
├── 🔀 git_*             # Git integration tools
├── ⚡ sneller_*          # High-performance SQL analytics
├── 🎬 asciinema_*        # Terminal recording tools
├── 🧠 completion_*       # AI-powered recommendations
├── 📁 file_ops_*         # Enhanced file operations
├── 🔍 search_analysis_*  # Advanced search and analysis
├── 🏗️ dev_workflow_*     # Development workflow tools
├── 🌐 network_api_*      # Network and API tools
├── 📦 archive_*          # Archive and compression
├── 🔬 process_tracing_*  # Process tracing tools
├── 🌍 env_process_*      # Environment management
└── 🛠️ utility_*          # Utility tools
```

#### **🧪 Interactive Testing Examples**

**1. Test Git Integration:**
```bash
# In the inspector Tools tab, find "git_git_status"
# Set parameters:
repository_path: "."
include_untracked: true

# Click "Execute" to see comprehensive git status
```

**2. Test Sneller Analytics:**
```bash
# Find "sneller_query" tool
# Parameters:
sql_query: "SELECT COUNT(*) as total FROM events"
data_source: "sample_data.json"
output_format: "json"
performance_hints: true

# Execute to see high-performance analytics in action
```

**3. Test Asciinema Recording:**
```bash
# Find "asciinema_record" tool  
# Parameters:
session_name: "test_demo"
max_duration: 60
visibility: "private"
auto_upload: false

# Creates a test recording session
```

**4. Test AI Recommendations:**
```bash
# Find "completion_recommend_tools" tool
# Parameters:
task_description: "I need to analyze my Python codebase for issues"
working_directory: "./src"
performance_priority: "comprehensive"
include_examples: true

# Get intelligent tool recommendations
```

#### **📚 Resources Tab** (if implemented)
- Browse available data resources
- Test resource URIs and templates
- View resource metadata

#### **💬 Prompts Tab** (if implemented)  
- Test prompt templates
- Preview prompt generation with parameters
- Validate prompt arguments

### 🛠️ **Inspector Development Workflow**

```bash
# 1. Start development with inspector
mcp dev enhanced_mcp/mcp_server.py

# 2. Open browser to inspector URL (usually http://localhost:3000)

# 3. Test individual tools interactively:
#    - Navigate to Tools tab
#    - Select a tool from the dropdown
#    - Fill in parameters using the form
#    - Click "Execute" to run the tool
#    - Review JSON results and any error messages

# 4. Debug and iterate:
#    - Check console logs for detailed error messages
#    - Modify tool parameters and re-test
#    - Use inspector logs to debug tool behavior

# 5. Test tool combinations:
#    - Use results from one tool as input to another
#    - Build complex workflows step by step
#    - Validate tool integration points
```

### 🎯 **Inspector Best Practices**

| Practice | Description | Why Important |
|----------|-------------|---------------|
| **Start with Simple Tools** | Test `git_git_status` or `file_ops_file_backup` first | Verify basic functionality |
| **Use Dry Run Mode** | Set `dry_run=true` for destructive operations | Prevent accidental changes |
| **Test Error Conditions** | Try invalid parameters and edge cases | Ensure robust error handling |
| **Check Performance** | Monitor execution time for heavy operations | Optimize slow tools |
| **Validate Output** | Verify JSON structure and content | Ensure consistent responses |

### 🚨 **Common Inspector Issues & Solutions**

| Issue | Solution |
|-------|----------|
| **"Server not found"** | Check that `enhanced-mcp` is in PATH or use `uv run` |
| **"Tools not loading"** | Verify all imports in `mcp_server.py` are working |
| **"Permission denied"** | Run inspector with appropriate file system permissions |
| **"Tool execution timeout"** | Increase timeout or optimize tool performance |
| **"Invalid parameters"** | Check tool documentation for required parameter types |

### 📖 **Inspector URL & Navigation**

```bash
# After running `mcp dev`, open in browser:
http://localhost:3000

# Inspector sections:
├── 🔧 Tools        # Test all MCP tools interactively
├── 📚 Resources    # Browse available resources  
├── 💬 Prompts      # Test prompt templates
├── 📊 Logs         # View execution logs and errors
└── ⚙️ Settings     # Configure inspector options
```

> 💡 **Pro Tip**: Keep the inspector open during development! It's invaluable for rapid testing and debugging of new tools.

## ⚙️ Configuration

### 🍎 Claude Desktop Setup

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "enhanced-tools": {
      "command": "uv",
      "args": ["run", "enhanced-mcp"],
      "cwd": "/full/path/to/enhanced-mcp-tools",
      "env": {
        "UV_PROJECT_ENVIRONMENT": ".venv"
      }
    }
  }
}
```

### 🖥️ Cursor IDE Setup

```json
{
  "mcp": {
    "servers": {
      "enhanced-tools": {
        "command": "enhanced-mcp",
        "cwd": "/path/to/enhanced-mcp-tools"
      }
    }
  }
}
```

### 🐋 Docker Setup

```bash
# Quick start with Docker
docker-compose up -d

# Or build locally
docker build -t enhanced-mcp-tools .
docker run -p 8000:8000 enhanced-mcp-tools
```
## 🛠️ Available Tools

Our comprehensive toolkit is organized into **13 specialized categories** with **50+ tools**:

<details>
<summary><strong>🔄 Diff/Patch Operations</strong> - Advanced file comparison and patching</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `diff_generate_diff` | Create unified diffs between files/directories | ✅ |
| `diff_apply_patch` | Apply patch files with conflict resolution | ✅ |
| `diff_create_patch_file` | Generate reusable patch files | ✅ |

</details>

<details>
<summary><strong>🔀 Git Integration</strong> - Smart version control operations</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `git_git_status` | Comprehensive repository status | ✅ |
| `git_git_diff` | Intelligent diff formatting | ✅ |
| `git_git_commit_prepare` | AI-suggested commit messages | ✅ |
| `git_git_grep` | Advanced git grep with annotations | ✅ |

</details>

<details>
<summary><strong>📁 Enhanced File Operations</strong> - Powerful file management</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `file_watch_files` | Real-time file monitoring | ✅ |
| `file_bulk_rename` | Pattern-based bulk renaming | ✅ |
| `file_file_backup` | Timestamped backups with compression | ✅ |

</details>

<details>
<summary><strong>🔍 Advanced Search & Analysis</strong> - Intelligent code analysis</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `search_search_and_replace_batch` | Multi-file search/replace with preview | ✅ |
| `search_analyze_codebase` | Comprehensive project analytics | ✅ |
| `search_find_duplicates` | Advanced duplicate detection | ✅ |

</details>

<details>
<summary><strong>🏗️ Development Workflow</strong> - Streamlined development process</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `dev_run_tests` | Multi-framework test execution | ✅ |
| `dev_lint_code` | Multi-linter code analysis | ✅ |
| `dev_format_code` | Auto-formatting with standard tools | ✅ |

</details>

<details>
<summary><strong>🌐 Network & API Tools</strong> - Advanced networking capabilities</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `net_http_request` | Advanced HTTP client with streaming | ✅ |
| `net_api_mock_server` | Lightweight mock API server | ✅ |

</details>

<details>
<summary><strong>📦 Archive & Compression</strong> - File archival operations</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `archive_create_archive` | Multi-format archive creation | ✅ |
| `archive_extract_archive` | Smart archive extraction | ✅ |
| `archive_compress_file` | Individual file compression | ✅ |
| `archive_list_archive` | Archive content inspection | ✅ |

</details>

<details>
<summary><strong>🔬 Process Tracing</strong> - System monitoring and analysis</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `trace_trace_process` | System call tracing | ✅ |
| `trace_process_monitor` | Real-time process monitoring | ✅ |
| `trace_analyze_syscalls` | System call analysis | ✅ |

</details>

<details>
<summary><strong>🌍 Environment Management</strong> - System and environment control</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `env_environment_info` | Comprehensive system information | ✅ |
| `env_manage_virtual_env` | Virtual environment management | ✅ |
| `env_process_tree` | Process hierarchy visualization | ✅ |

</details>

<details>
<summary><strong>🛠️ Utility Tools</strong> - Essential development utilities</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `util_generate_documentation` | Auto-generate docs from code | ✅ |
| `util_project_template` | Project scaffolding | ✅ |
| `util_dependency_check` | Dependency analysis and updates | ✅ |

</details>

<details>
<summary><strong>⚡ Sneller Analytics</strong> - High-performance vectorized SQL on JSON</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `sneller_query` | Lightning-fast vectorized SQL queries (TB/s throughput) | ✅ |
| `sneller_optimize` | SQL query optimization for maximum performance | ✅ |
| `sneller_setup` | Configure Sneller for optimal hardware utilization | ✅ |

**🚀 Performance Features:**
- **1GB/s/core** processing with AVX-512 vectorization
- **Schemaless JSON** querying without ETL overhead
- **Hybrid columnar/row** storage with compression
- **S3-native** with bucketized zion format

</details>

<details>
<summary><strong>🎬 Asciinema Integration</strong> - Terminal recording and sharing</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `asciinema_record` | Record terminal sessions with metadata | ✅ |
| `asciinema_search` | Search recordings with advanced filtering | ✅ |
| `asciinema_playback` | Generate playback URLs and embedding code | ✅ |
| `asciinema_auth` | Manage asciinema.org authentication | ✅ |
| `asciinema_upload` | Upload recordings with privacy controls | ✅ |
| `asciinema_config` | Configure recording settings and destinations | ✅ |

**🎥 Recording Features:**
- **Automatic auditing** of command executions
- **Public/private** sharing with asciinema.org integration
- **Embeddable players** with custom themes and controls
- **Searchable database** with rich metadata

</details>

<details>
<summary><strong>🧠 Intelligent Completion</strong> - AI-powered tool recommendations</summary>

| Tool | Description | Status |
|------|-------------|--------|
| `completion_recommend_tools` | Get intelligent tool suggestions for tasks | ✅ |
| `completion_explain_tool` | Detailed explanations with usage examples | ✅ |
| `completion_suggest_workflow` | Generate multi-step workflows automatically | ✅ |

**🤖 AI Features:**
- **Context-aware** recommendations based on project structure
- **Performance-optimized** tool selection for different use cases
- **Workflow generation** with automation scripts
- **Usage pattern learning** for improved suggestions

</details>

### 🎯 **Tool Usage Patterns**

```python
# Example: Lightning-fast SQL analytics with Sneller
await sneller_query(
    sql_query="SELECT user_id, COUNT(*) FROM events WHERE timestamp > '2024-01-01' GROUP BY user_id",
    data_source="s3://my-bucket/events/*.json",
    output_format="json"
)

# Example: AI-powered tool recommendations
await completion_recommend_tools(
    task_description="I need to analyze my codebase for performance issues",
    performance_priority="speed",
    working_directory="./src"
)

# Example: Terminal session recording for demos
await asciinema_record(
    session_name="api_demo",
    auto_upload=True,
    visibility="public",
    title="API Testing Demo"
)

# Example: Comprehensive codebase analysis
await search_analyze_codebase(
    directory="./src",
    include_metrics=["loc", "complexity", "dependencies"]
)

# Example: Smart commit preparation
await git_commit_prepare(
    repository_path=".",
    files=["src/main.py", "tests/test_main.py"],
    suggest_message=True
)

# Example: Batch file operations with backup
await file_bulk_rename(
    directory="./assets",
    pattern=r"IMG_(\d+)",
    replacement=r"photo_\1",
    dry_run=False  # Set to True for preview
)
```
## 📚 Usage Examples

### 🔄 **Git Workflow Automation**

```python
# Automated commit with AI-generated message
result = await git_commit_prepare(
    repository_path="/path/to/repo",
    files=["src/api.py", "tests/test_api.py"],
    suggest_message=True
)
print(f"Suggested commit: {result['suggested_message']}")
```

### 🔍 **Advanced Code Search**

```python
# Semantic search across codebase
matches = await search_code_enhanced(
    query="database connection",
    directory="./src",
    search_type="semantic",
    file_pattern="*.py"
)

for match in matches['results']:
    print(f"Found in {match['file']}: {match['context']}")
```

### ⚡ **High-Performance Analytics with Sneller**

```python
# Lightning-fast JSON analytics (TB/s performance)
result = await sneller_query(
    sql_query="""
    SELECT 
        date_trunc('hour', timestamp) as hour,
        COUNT(*) as events,
        AVG(response_time) as avg_response
    FROM s3://logs/events/*.json 
    WHERE status = 200 
    GROUP BY hour 
    ORDER BY hour DESC
    """,
    data_source="s3://my-data-lake/",
    performance_hints=True,
    cache_results=True
)

# Query optimization for maximum performance
optimization = await sneller_optimize(
    sql_query=original_query,
    optimization_level="aggressive",
    target_use_case="analytics"
)
print(f"Estimated speedup: {optimization['estimated_speedup']}")
```

### 🎬 **Terminal Recording & Sharing**

```python
# Record a demo session
recording = await asciinema_record(
    session_name="deployment_demo",
    command="./deploy.sh production",
    auto_upload=True,
    visibility="public",
    title="Production Deployment Process"
)

# Search and replay recordings
results = await asciinema_search(
    query="deployment",
    date_range={"start": "2024-01-01", "end": "2024-12-31"},
    uploaded_only=True
)

# Generate embeddable player
playback = await asciinema_playback(
    recording_id=recording['recording_id'],
    autoplay=True,
    theme="solarized-dark"
)
```

### 🧠 **AI-Powered Tool Assistance**

```python
# Get intelligent tool recommendations
recommendations = await completion_recommend_tools(
    task_description="I need to optimize my CI/CD pipeline performance",
    working_directory="./",
    performance_priority="speed",
    include_examples=True
)

for rec in recommendations['recommendations']:
    print(f"Tool: {rec['tool_name']} - {rec['primary_reason']}")

# Get detailed tool explanations
explanation = await completion_explain_tool(
    tool_name="sneller_query",
    include_examples=True,
    use_case_focus="real-time analytics"
)

# Generate complete workflows
workflow = await completion_suggest_workflow(
    goal_description="Set up automated testing and deployment",
    automation_level="semi-automated",
    time_budget="2 hours"
)
```

### 📊 **Project Analytics**

```python
# Comprehensive codebase analysis
analysis = await analyze_codebase(
    directory="./",
    include_metrics=["loc", "complexity", "dependencies"]
)

print(f"Lines of Code: {analysis['metrics']['total_loc']}")
print(f"Complexity Score: {analysis['metrics']['avg_complexity']}")
```

### 🧪 **Testing & Quality Assurance**

```python
# Run tests with coverage
test_results = await run_tests(
    test_path="./tests",
    coverage=True,
    framework="auto-detect"
)

# Format code automatically
await format_code(
    file_paths=["src/main.py", "src/utils.py"],
    formatter="black"
)

# Comprehensive linting
lint_results = await lint_code(
    file_paths=["src/"],
    fix=True,
    linters=["ruff", "mypy"]
)
```

## 🏗️ Architecture

### 🧩 **Modular Design**

Enhanced MCP Tools uses FastMCP's MCPMixin pattern for maximum modularity and extensibility:

```
📦 MCPToolServer (Main Server)
├── 🔄 DiffPatchOperations
├── 🔀 GitIntegration  
├── 📁 EnhancedFileOperations
├── 🔍 AdvancedSearchAnalysis
├── 🏗️ DevelopmentWorkflow
├── 🌐 NetworkAPITools
├── 📦 ArchiveCompression
├── 🔬 ProcessTracingTools
├── 🌍 EnvironmentProcessManagement
├── 🛠️ UtilityTools
├── ⚡ SnellerAnalytics (NEW)
├── 🎬 AsciinemaIntegration (NEW)
└── 🧠 IntelligentCompletion (NEW)
```

### 🚀 **Performance Optimizations**

- **Async-First**: All operations are asynchronous for maximum throughput
- **Streaming Support**: Large file operations with progress reporting
- **Memory Efficient**: Smart caching and lazy loading
- **Type Safe**: Full Pydantic validation for all inputs/outputs

### 🛡️ **Security Features**

- **Input Validation**: Comprehensive parameter validation
- **Path Sanitization**: Secure file path handling
- **Resource Limits**: Configurable timeouts and size limits
- **Error Isolation**: Graceful error handling without system exposure

## 🧪 Testing

### 🔬 **Test Suite**

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=enhanced_mcp --cov-report=html

# Run specific test categories
uv run pytest tests/test_git_integration.py -v

# Performance benchmarks
uv run pytest tests/benchmarks/ --benchmark-only
```

### 🎯 **Interactive Testing with MCP Inspector**

The **MCP Inspector** is your primary tool for interactive testing and development:

```bash
# Launch inspector for comprehensive tool testing
mcp dev enhanced_mcp/mcp_server.py

# Then open http://localhost:3000 to:
# ✅ Test all 50+ tools interactively
# ✅ Validate tool parameters and responses  
# ✅ Debug tool execution and error handling
# ✅ Explore tool combinations and workflows
# ✅ Monitor performance and execution times
```

**Recommended Testing Workflow:**
1. **Start with Inspector** - Test new tools interactively
2. **Write Unit Tests** - Cover edge cases and error conditions  
3. **Integration Tests** - Verify tool combinations work together
4. **Performance Tests** - Ensure tools meet speed requirements

### 📊 **Test Coverage**

| Module | Coverage | Status |
|--------|----------|--------|
| Core Server | 95% | ✅ |
| Git Integration | 92% | ✅ |
| File Operations | 88% | ✅ |
| Search & Analysis | 85% | ✅ |
| Network Tools | 90% | ✅ |

### 🎯 **Integration Testing**

```bash
# Test MCP server startup
timeout 5 uv run enhanced-mcp || echo "✅ Server started successfully"

# Interactive testing with MCP inspector (RECOMMENDED)
mcp dev enhanced_mcp/mcp_server.py
# Then open http://localhost:3000 for comprehensive tool testing

# Direct tool execution testing
uv run python -c "
import asyncio
from enhanced_mcp.git.git_integration import GitIntegration
git = GitIntegration()
print(asyncio.run(git.git_status('.', include_untracked=True)))
"

# Test specific tool categories
uv run python -c "
import asyncio
from enhanced_mcp.sneller_analytics import SnellerAnalytics
sneller = SnellerAnalytics()
result = asyncio.run(sneller.sneller_query(
    'SELECT COUNT(*) as total', 
    'test_data.json'
))
print(result)
"
```

**🚀 Quick Integration Test Checklist:**
- [ ] Server starts without errors (`enhanced-mcp`)
- [ ] Inspector loads all tools (`mcp dev ...`)  
- [ ] Git tools work in a repository
- [ ] File operations respect permissions
- [ ] Sneller tools provide performance metrics
- [ ] Asciinema tools handle recording paths
- [ ] AI completion provides relevant suggestions
```
## 📦 Deployment

### 🐋 **Docker Deployment**

```dockerfile
# Production-ready Dockerfile included
FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install uv && uv sync --frozen
EXPOSE 8000

CMD ["uv", "run", "enhanced-mcp"]
```

```bash
# Quick deployment
docker-compose up -d

# Custom build
docker build -t enhanced-mcp-tools .
docker run -p 8000:8000 enhanced-mcp-tools
```

### ⚙️ **Production Setup**

<details>
<summary><strong>Systemd Service</strong></summary>

```ini
# /etc/systemd/system/enhanced-mcp-tools.service
[Unit]
Description=Enhanced MCP Tools Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/enhanced-mcp-tools
ExecStart=/opt/enhanced-mcp-tools/.venv/bin/enhanced-mcp
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
```

```bash
sudo systemctl enable enhanced-mcp-tools
sudo systemctl start enhanced-mcp-tools
```

</details>

<details>
<summary><strong>Kubernetes Deployment</strong></summary>

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: enhanced-mcp-tools
spec:
  replicas: 3
  selector:
    matchLabels:
      app: enhanced-mcp-tools
  template:
    metadata:
      labels:
        app: enhanced-mcp-tools
    spec:
      containers:
      - name: enhanced-mcp-tools
        image: enhanced-mcp-tools:latest
        ports:
        - containerPort: 8000
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"
```

</details>

### 🔧 **Environment Variables**

| Variable | Description | Default |
|----------|-------------|---------|
| `MCP_LOG_LEVEL` | Logging level | `INFO` |
| `MCP_HOST` | Server host | `localhost` |
| `MCP_PORT` | Server port | `8000` |
| `MCP_TIMEOUT` | Operation timeout (seconds) | `300` |

## 🤝 Contributing

We welcome contributions! Here's how to get started:

### 🚀 **Quick Start for Contributors**

```bash
# Fork and clone
git clone https://github.com/yourusername/enhanced-mcp-tools.git
cd enhanced-mcp-tools

# Set up development environment
uv sync --all-extras
uv run pre-commit install

# Create feature branch
git checkout -b feature/amazing-new-tool

# Make your changes and test
uv run pytest
uv run ruff check .
uv run black --check .

# Commit and push
git add .
git commit -m "✨ Add amazing new tool"
git push origin feature/amazing-new-tool
```

### 🛠️ **Adding New Tools**

1. **Create a new mixin class** following the established pattern:

```python
from fastmcp.contrib.mcp_mixin import MCPMixin, mcp_tool
from pydantic import Field
from typing import Dict, Any, Optional

class MyCustomTools(MCPMixin):
    @mcp_tool(
        name="my_awesome_tool",
        description="Does something awesome for developers"
    )
    async def my_awesome_tool(
        self,
        input_param: str = Field(description="Main input parameter"),
        optional_param: int = Field(default=10, description="Optional parameter"),
        ctx: Optional[Context] = None
    ) -> Dict[str, Any]:
        """
        Implementation of your awesome tool.
        
        Returns:
            Dict containing results and metadata
        """
        if ctx:
            await ctx.log_info(f"Processing {input_param}")
            await ctx.report_progress(0.5, "Halfway done...")
        
        # Your implementation here
        result = {"status": "success", "data": input_param}
        
        if ctx:
            await ctx.report_progress(1.0, "Complete!")
        
        return result
```

2. **Register with the server** in `mcp_server.py`:

```python
# Add to MCPToolServer.__init__
self.my_tools = MyCustomTools()

# Add to register_all_tools method  
self.my_tools.register_all(self.mcp, prefix="my")
```

3. **Add comprehensive tests** in `tests/test_my_tools.py`

### 📋 **Development Guidelines**

- **Code Style**: We use `black` and `ruff` for formatting and linting
- **Type Hints**: Full type annotations required
- **Documentation**: Docstrings for all public methods
- **Testing**: Minimum 80% test coverage
- **Async First**: All I/O operations must be async
- **Error Handling**: Graceful error handling with meaningful messages

### 🏆 **Recognition**

Contributors are recognized in our [Contributors Hall of Fame](https://github.com/yourusername/enhanced-mcp-tools/graphs/contributors)!

## 📈 **Roadmap**

### 🎯 **Upcoming Features**

- [ ] **Web UI Dashboard** - Visual interface for tool management
- [ ] **Plugin System** - Third-party tool extensions
- [ ] **AI Code Review** - Automated code quality suggestions  
- [ ] **Performance Profiler** - Built-in performance analysis
- [ ] **Team Collaboration** - Multi-user workspace support

### 🔄 **Recent Updates**

- ✅ **v1.0.0** - Initial release with 50+ tools across 13 categories
- ✅ **Sneller Integration** - High-performance vectorized SQL analytics (TB/s)
- ✅ **Asciinema Support** - Complete terminal recording and sharing solution
- ✅ **Intelligent Completion** - AI-powered tool recommendations and workflow generation
- ✅ **Enhanced Search** - Semantic code search capabilities
- ✅ **Advanced Git Tools** - Smart commit preparation with AI suggestions
- ✅ **Process Tracing** - Cross-platform system call monitoring
- ✅ **Archive Operations** - Multi-format compression and extraction

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

- **[FastMCP](https://github.com/jlowin/fastmcp)** - The foundation that makes this possible
- **[Model Context Protocol](https://modelcontextprotocol.io/)** - The protocol specification
- **Our Contributors** - Amazing developers who make this project better

---

<div align="center">

**Built with ❤️ by the Enhanced MCP Tools team**

[⭐ Star us on GitHub](https://github.com/yourusername/enhanced-mcp-tools) • [🐛 Report Issues](https://github.com/yourusername/enhanced-mcp-tools/issues) • [💬 Join Discussions](https://github.com/yourusername/enhanced-mcp-tools/discussions)

[![GitHub stars](https://img.shields.io/github/stars/yourusername/enhanced-mcp-tools.svg?style=social&label=Star)](https://github.com/yourusername/enhanced-mcp-tools/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/yourusername/enhanced-mcp-tools.svg?style=social&label=Fork)](https://github.com/yourusername/enhanced-mcp-tools/network/members)
[![Follow on Twitter](https://img.shields.io/twitter/follow/yourhandle.svg?style=social&label=Follow)](https://twitter.com/yourhandle)

</div>