manus-jaegis-mcp-server 1.0.0
JAEGIS AI Web OS MCP Server - Advanced Model Context Protocol server with filesystem, git, project management, and AI integration tools
License: MIT
Requires Python: >=3.8
Keywords: mcp, model-context-protocol, ai, jaegis, filesystem, git, project-management, development-tools, automation, claude, anthropic, augment

# 🤖 JAEGIS MCP Server (Python)

[![PyPI version](https://badge.fury.io/py/jaegis-mcp-server.svg)](https://badge.fury.io/py/jaegis-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue.svg)](https://www.python.org/downloads/)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)

Python wrapper for the JAEGIS AI Web OS MCP Server - Advanced Model Context Protocol server providing comprehensive filesystem, git, project management, and AI integration tools for AI assistants and development workflows.

## 🚀 **Quick Start**

### **Installation**

```bash
# Install from PyPI
pip install jaegis-mcp-server

# Or install with development dependencies
pip install jaegis-mcp-server[dev]
```

### **Prerequisites**

The Python package requires Node.js 18+ to run the underlying MCP server:

```bash
# Check if Node.js is installed
node --version

# If not installed, download from: https://nodejs.org/
# Or install via package manager:

# macOS (Homebrew)
brew install node

# Ubuntu/Debian
sudo apt update && sudo apt install nodejs npm

# Windows (Chocolatey)
choco install nodejs
```

### **Basic Usage**

```bash
# Start the MCP server
jaegis-mcp-server

# Start with debug logging
jaegis-mcp-server --debug

# Check system status
jaegis-mcp-server status

# Install Node.js dependencies (if needed)
jaegis-mcp-server install
```

---

## 🛠️ **Available Tools**

The JAEGIS MCP Server provides 40+ powerful tools across four main categories:

### **📁 Filesystem Tools (10 tools)**
- `read_file` - Read file contents with encoding detection
- `write_file` - Write files with automatic directory creation
- `list_directory` - List directory contents with filtering
- `create_directory` - Create directories recursively
- `delete_file` - Delete files and directories safely
- `move_file` - Move/rename files and directories
- `copy_file` - Copy files and directories
- `get_file_info` - Get detailed file metadata
- `search_files` - Search files by name, content, or pattern
- `watch_directory` - Monitor directory changes in real-time

### **🔧 Git Tools (10 tools)**
- `git_status` - Get repository status and changes
- `git_log` - View commit history with filtering
- `git_diff` - Show differences between commits/files
- `git_add` - Stage files for commit
- `git_commit` - Create commits with validation
- `git_push` - Push changes to remote repositories
- `git_pull` - Pull changes from remote repositories
- `git_branch` - Manage branches (create, delete, switch)
- `git_merge` - Merge branches with conflict detection
- `git_clone` - Clone repositories with progress tracking

### **📋 Project Management Tools (10 tools)**
- `create_project` - Initialize new projects with templates
- `analyze_project` - Analyze project structure and dependencies
- `generate_docs` - Generate project documentation
- `run_tests` - Execute test suites with reporting
- `build_project` - Build projects with multiple targets
- `deploy_project` - Deploy to various platforms
- `manage_dependencies` - Install, update, remove dependencies
- `scaffold_component` - Generate code components
- `validate_config` - Validate configuration files
- `optimize_project` - Optimize project performance

### **🤖 AI Integration Tools (10 tools)**
- `ai_code_review` - Automated code review and suggestions
- `ai_generate_code` - Generate code from natural language
- `ai_explain_code` - Explain complex code sections
- `ai_optimize_code` - Suggest code optimizations
- `ai_generate_tests` - Generate unit tests automatically
- `ai_documentation` - Generate documentation from code
- `ai_refactor` - Suggest refactoring improvements
- `ai_debug_help` - Debug assistance and error analysis
- `ai_translate_code` - Translate between programming languages
- `ai_security_scan` - Security vulnerability analysis

---

## ⚙️ **Configuration**

### **MCP Client Configuration**

#### **Claude Desktop**
Add to your Claude Desktop configuration file (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "jaegis": {
      "command": "python",
      "args": ["-m", "jaegis_mcp_server"],
      "env": {
        "JAEGIS_MCP_DEBUG": "false"
      }
    }
  }
}
```

#### **Augment**
Configure in your Augment settings:

```json
{
  "mcp": {
    "servers": [
      {
        "name": "jaegis",
        "command": "jaegis-mcp-server",
        "args": ["--debug"],
        "cwd": "/path/to/your/project"
      }
    ]
  }
}
```

### **Server Configuration**

Create a configuration file (`mcp-config.json`):

```json
{
  "server": {
    "name": "jaegis-mcp-server",
    "version": "1.0.0",
    "debug": false
  },
  "tools": {
    "filesystem": {
      "enabled": true,
      "maxFileSize": "10MB",
      "allowedExtensions": ["*"],
      "restrictedPaths": ["/etc", "/sys"]
    },
    "git": {
      "enabled": true,
      "autoCommit": false,
      "defaultBranch": "main"
    },
    "project": {
      "enabled": true,
      "templatesPath": "./templates",
      "defaultFramework": "python"
    },
    "ai": {
      "enabled": true,
      "provider": "openai",
      "model": "gpt-4",
      "maxTokens": 4000
    }
  },
  "security": {
    "allowFileOperations": true,
    "allowGitOperations": true,
    "allowNetworkAccess": false,
    "sandboxMode": false
  }
}
```

---

## 🔧 **Command Line Interface**

### **Main Commands**

```bash
# Start the MCP server (default command)
jaegis-mcp-server

# Check system status and dependencies
jaegis-mcp-server status

# Install Node.js dependencies
jaegis-mcp-server install

# Show system information
jaegis-mcp-server info

# Show version
jaegis-mcp-server --version
```

### **Server Options**

```bash
jaegis-mcp-server [OPTIONS]

Options:
  --debug             Enable debug logging
  --config PATH       Configuration file path
  --port NUMBER       Port number (default: auto)
  --host ADDRESS      Host address (default: localhost)
  --stdio             Use stdio transport (default)
  --sse               Use Server-Sent Events transport
  --websocket         Use WebSocket transport

Environment Variables:
  JAEGIS_MCP_PORT     Default port number
  JAEGIS_MCP_HOST     Default host address
  JAEGIS_MCP_DEBUG    Enable debug mode (true/false)
  JAEGIS_MCP_CONFIG   Default configuration file path
```

---

## 📚 **Python API Usage**

### **Programmatic Usage**

```python
from jaegis_mcp_server import MCPServer, MCPClient
import asyncio

async def main():
    # Start the MCP server
    server = MCPServer(debug=True)
    await server.start()
    
    # Connect a client
    client = MCPClient()
    await client.connect()
    
    # Use filesystem tools
    content = await client.call_tool("read_file", {
        "path": "./example.txt"
    })
    
    # Use git tools
    status = await client.call_tool("git_status", {
        "path": "./my-project"
    })
    
    # Use AI tools
    review = await client.call_tool("ai_code_review", {
        "files": ["src/main.py"],
        "focus": ["performance", "security"]
    })
    
    # Cleanup
    await client.disconnect()
    await server.stop()

# Run the example
asyncio.run(main())
```

### **Context Manager Usage**

```python
from jaegis_mcp_server import MCPServer
import asyncio

async def main():
    async with MCPServer(debug=True) as server:
        # Server is automatically started and stopped
        async with server.client() as client:
            # Perform operations
            result = await client.call_tool("list_directory", {
                "path": "./",
                "recursive": True
            })
            print(f"Found {len(result['files'])} files")

asyncio.run(main())
```

---

## 🔍 **Troubleshooting**

### **Common Issues**

#### **Node.js Not Found**
```bash
# Check if Node.js is installed
node --version

# If not found, install Node.js
# Visit: https://nodejs.org/

# Verify installation
jaegis-mcp-server status
```

#### **Permission Errors**
```bash
# On Unix systems, ensure proper permissions
chmod +x $(which jaegis-mcp-server)

# Or install in user directory
pip install --user jaegis-mcp-server
```

#### **Server Won't Start**
```bash
# Check dependencies
jaegis-mcp-server status

# Install Node.js dependencies
jaegis-mcp-server install

# Run with debug logging
jaegis-mcp-server --debug
```

#### **Connection Issues**
```bash
# Test server connectivity
jaegis-mcp-server --debug --stdio

# Check firewall settings
# Ensure configured port is accessible
```

### **Debug Mode**

Enable comprehensive debugging:

```bash
# Command line
jaegis-mcp-server --debug

# Environment variable
export JAEGIS_MCP_DEBUG=true
jaegis-mcp-server

# Python code
from jaegis_mcp_server import MCPServer
server = MCPServer(debug=True)
```

### **System Information**

Get detailed system information for troubleshooting:

```bash
# Text format
jaegis-mcp-server info

# JSON format
jaegis-mcp-server info --format json
```

---

## 🔄 **Cross-Platform Compatibility**

The Python package works seamlessly across platforms:

- **Windows**: Full support with automatic Node.js detection
- **macOS**: Native support with Homebrew integration
- **Linux**: Complete compatibility with all major distributions
- **Docker**: Container-ready with multi-stage builds

### **Docker Usage**

```dockerfile
FROM python:3.11-slim

# Install Node.js
RUN apt-get update && apt-get install -y nodejs npm

# Install JAEGIS MCP Server
RUN pip install jaegis-mcp-server

# Start the server
CMD ["jaegis-mcp-server"]
```

---

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guide](https://github.com/jaegis/jaegis-mcp-server/blob/main/CONTRIBUTING.md) for details.

### **Development Setup**

```bash
# Clone the repository
git clone https://github.com/jaegis/jaegis-mcp-server.git
cd jaegis-mcp-server

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

# Install Node.js dependencies
npm install

# Run tests
pytest

# Run linting
black . && flake8 . && mypy .
```

---

## 📄 **License**

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

---

## 🔗 **Links**

- **GitHub**: [jaegis/jaegis-mcp-server](https://github.com/jaegis/jaegis-mcp-server)
- **PyPI Package**: [jaegis-mcp-server](https://pypi.org/project/jaegis-mcp-server/)
- **NPM Package**: [jaegis-mcp-server](https://www.npmjs.com/package/jaegis-mcp-server)
- **Documentation**: [docs.jaegis.ai](https://docs.jaegis.ai/mcp-server)
- **Issues**: [GitHub Issues](https://github.com/jaegis/jaegis-mcp-server/issues)
- **Support**: support@jaegis.ai

---

## 🙏 **Acknowledgments**

- [Anthropic](https://anthropic.com) for the Model Context Protocol specification
- [OpenAI](https://openai.com) for AI integration capabilities
- The Python and Node.js communities for excellent tooling
- The open-source community for inspiration and contributions

---

**Made with ❤️ by the JAEGIS Team**