# ๐ Enhanced MCP Tools
### *A comprehensive Model Context Protocol (MCP) server with 50+ development tools*
[](https://www.python.org/downloads/)
[](https://github.com/jlowin/fastmcp)
[](https://opensource.org/licenses/MIT)
[](https://github.com/yourusername/enhanced-mcp-tools/actions)
[](https://github.com/yourusername/enhanced-mcp-tools)
[](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)
## ๐ 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
|
### ๐ **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
|
### ๐๏ธ **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
|
### ๐ฏ **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**:
๐ Diff/Patch Operations - Advanced file comparison and patching
| 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 | โ
|
๐ Git Integration - Smart version control operations
| 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 | โ
|
๐ Enhanced File Operations - Powerful file management
| Tool | Description | Status |
|------|-------------|--------|
| `file_watch_files` | Real-time file monitoring | โ
|
| `file_bulk_rename` | Pattern-based bulk renaming | โ
|
| `file_file_backup` | Timestamped backups with compression | โ
|
๐ Advanced Search & Analysis - Intelligent code analysis
| 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 | โ
|
๐๏ธ Development Workflow - Streamlined development process
| 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 | โ
|
๐ Network & API Tools - Advanced networking capabilities
| Tool | Description | Status |
|------|-------------|--------|
| `net_http_request` | Advanced HTTP client with streaming | โ
|
| `net_api_mock_server` | Lightweight mock API server | โ
|
๐ฆ Archive & Compression - File archival operations
| 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 | โ
|
๐ฌ Process Tracing - System monitoring and analysis
| Tool | Description | Status |
|------|-------------|--------|
| `trace_trace_process` | System call tracing | โ
|
| `trace_process_monitor` | Real-time process monitoring | โ
|
| `trace_analyze_syscalls` | System call analysis | โ
|
๐ Environment Management - System and environment control
| Tool | Description | Status |
|------|-------------|--------|
| `env_environment_info` | Comprehensive system information | โ
|
| `env_manage_virtual_env` | Virtual environment management | โ
|
| `env_process_tree` | Process hierarchy visualization | โ
|
๐ ๏ธ Utility Tools - Essential development utilities
| Tool | Description | Status |
|------|-------------|--------|
| `util_generate_documentation` | Auto-generate docs from code | โ
|
| `util_project_template` | Project scaffolding | โ
|
| `util_dependency_check` | Dependency analysis and updates | โ
|
โก Sneller Analytics - High-performance vectorized SQL on JSON
| 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
๐ฌ Asciinema Integration - Terminal recording and sharing
| 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
๐ง Intelligent Completion - AI-powered tool recommendations
| 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
### ๐ฏ **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**
Systemd Service
```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
```
Kubernetes Deployment
```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"
```
### ๐ง **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
---
**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)
[](https://github.com/yourusername/enhanced-mcp-tools/stargazers)
[](https://github.com/yourusername/enhanced-mcp-tools/network/members)
[](https://twitter.com/yourhandle)