npm package: @mamounalzyoud/django-mcp-server
Description: AI-powered MCP server for autonomous Django development with GitHub Copilot - code analysis, generation, security scanning, and best practices
Author: Mamoun Alzyoud
Latest version: 2.0.0

# Django SaaS MCP Server

An MCP (Model Context Protocol) server that provides autonomous assistance for Django SaaS development. This server runs continuously in the background, monitoring your Django project and providing proactive help through VS Code Copilot without requiring manual intervention.

## Features

- **🔍 Continuous Monitoring**: Automatically watches Django project files for changes
- **🤖 Autonomous Assistance**: Provides suggestions and detects issues without user action
- **🛠️ Django-Specific Tools**: Exposes specialized tools for Django development
- **📊 Project Analysis**: Analyzes Django project structure and identifies apps
- **⚠️ Issue Detection**: Detects common Django patterns, anti-patterns, and security issues
- **🔄 Real-time Updates**: Monitors models, views, settings, templates, and more

## What It Monitors

The server automatically monitors:
- Python files (`**/*.py`)
- Django core files (`settings.py`, `models.py`, `views.py`, `urls.py`, `manage.py`)
- Templates (`**/templates/**/*.html`)
- Requirements files (`requirements*.txt`)

And ignores:
- Virtual environments (`venv/`, `env/`)
- Python cache (`__pycache__/`, `*.pyc`)
- Node modules (`node_modules/`)
- Build directories

## Available Tools

### 1. `set_django_project_path`
Set the path to your Django project for monitoring.

**Input:**
```json
{
  "path": "/absolute/path/to/django/project"
}
```

**Output:**
```json
{
  "success": true,
  "message": "Now monitoring Django project at: /path/to/project",
  "monitoringActive": true
}
```

### 2. `analyze_django_project`
Analyze the Django project structure and detect potential issues.

**Output:**
```json
{
  "projectPath": "/path/to/project",
  "hasDjango": true,
  "apps": ["blog", "users", "api"],
  "hasSettings": true,
  "hasManagePy": true,
  "issues": [],
  "fileCount": 45
}
```

### 3. `check_django_file`
Check a specific Django file for common issues and get suggestions.

**Input:**
```json
{
  "filePath": "myapp/models.py"
}
```

**Output:**
```json
{
  "filePath": "/absolute/path/to/file",
  "exists": true,
  "issues": ["Missing Django models import"],
  "suggestions": ["Add: from django.db import models"]
}
```

### 4. `list_monitored_files`
List all files currently being monitored.

**Input:**
```json
{
  "pattern": "models.py"  // Optional filter
}
```

**Output:**
```json
{
  "totalFiles": 3,
  "files": [
    {
      "path": "/full/path/to/file",
      "relativePath": "blog/models.py",
      "size": 1024,
      "lastModified": "2025-10-26T12:00:00.000Z"
    }
  ]
}
```

## Installation & Setup

### Prerequisites
- Node.js 18+ installed
- VS Code with GitHub Copilot
- A Django project

### Setup Steps

1. **Install Dependencies** (already done during workspace creation)
   ```bash
   npm install
   ```

2. **Build the Server** (already done)
   ```bash
   npm run build
   ```

3. **Configure in VS Code**
   The server is already configured in `.vscode/mcp.json`. VS Code Copilot will automatically connect to it when you open this workspace.

4. **Verify Connection**
   - Open VS Code
   - Open the Command Palette (`Ctrl+Shift+P` or `Cmd+Shift+P`)
   - Type "MCP" to see MCP-related commands
   - The `django-saas-assistant` server should be listed

## Usage

### With VS Code Copilot

Once configured, the MCP server runs automatically in the background. You can interact with it through Copilot:

1. **Set Your Django Project Path**
   In Copilot chat, ask:
   ```
   @workspace Use the django-saas-assistant to monitor my Django project at /path/to/my/project
   ```

2. **Analyze Your Project**
   ```
   @workspace Analyze my Django project structure
   ```

3. **Check for Issues**
   ```
   @workspace Check my Django models file for issues
   ```

4. **List Monitored Files**
   ```
   @workspace Show me all monitored Django files
   ```

### Autonomous Monitoring

The server runs continuously and logs activity to stderr (visible in the MCP output channel):
- File additions
- File modifications
- File deletions
- Detected issues

## Development

### Project Structure
```
.
├── src/
│   └── index.ts          # Main server implementation
├── build/                # Compiled JavaScript (generated)
├── .vscode/
│   └── mcp.json         # MCP server configuration
├── .github/
│   └── copilot-instructions.md
├── package.json
├── tsconfig.json
└── README.md
```

### Building
```bash
npm run build
```

### Watch Mode (for development)
```bash
npm run watch
```

### Running Locally
```bash
npm run dev
```

## Issue Detection

The server automatically detects:

### Models (`models.py`)
- Missing Django models import
- Incorrect model class definitions
- Missing migrations directories

### Views (`views.py`)
- Missing Django imports

### Settings (`settings.py`)
- `DEBUG = True` with empty `ALLOWED_HOSTS` (security risk)
- Hardcoded `SECRET_KEY` (security risk)

### Project Structure
- Settings file without `manage.py`
- Django project without apps

## How It Works

1. **File Watching**: Uses `chokidar` to monitor Django files in real-time
2. **Pattern Detection**: Analyzes file content for Django-specific patterns
3. **MCP Protocol**: Exposes tools via the Model Context Protocol
4. **Stdio Transport**: Communicates with VS Code through standard input/output
5. **Copilot Integration**: Works seamlessly with GitHub Copilot for autonomous assistance

## Debugging

To view server logs:
1. Open VS Code Output panel (`View` → `Output`)
2. Select "MCP: django-saas-assistant" from the dropdown
3. Watch real-time logs as the server monitors your project

## Configuration

### Changing the Project Path
Edit `.vscode/mcp.json` to point to a different location:
```json
{
  "servers": {
    "django-saas-assistant": {
      "type": "stdio",
      "command": "node",
      "args": [
        "/your/custom/path/build/index.js"
      ]
    }
  }
}
```

## Troubleshooting

### Server Not Starting
- Ensure Node.js is installed: `node --version`
- Check build output: `npm run build`
- Verify the path in `.vscode/mcp.json`

### No Files Being Monitored
- Use the `set_django_project_path` tool to set the correct path
- Check that the path contains Django files
- Review the MCP output logs

### Tools Not Appearing in Copilot
- Restart VS Code
- Check MCP server status in the Output panel
- Verify `.vscode/mcp.json` configuration

## Contributing

This is an autonomous assistant for Django SaaS development. To extend it:

1. Add new tools in `src/index.ts` using `server.registerTool()`
2. Implement new file watchers for additional patterns
3. Add more issue detection logic
4. Build and test: `npm run build`

## License

MIT

## Support

For issues or questions:
- Check the MCP server logs in VS Code Output
- Review this README
- Check the MCP specification: https://modelcontextprotocol.io/

---

**Note**: This server is designed to run continuously in the background. It automatically starts when you open VS Code with this workspace and provides autonomous assistance through Copilot without requiring manual commands.