# Getting Started with Django MCP

This guide will walk you through setting up Django MCP in your Django REST Framework project.

## Installation

```bash
uv add drf-mcp
```

Or with pip:
```bash
pip install drf-mcp
```

## Quick Start

### 1. Create an MCP Server Script

Create a file called `mcp_server.py` in your Django project root:

```python
#!/usr/bin/env python
"""
Django MCP Server for exposing DRF API as MCP tools
"""

import os
import django

# Setup Django
os.environ.setdefault("DJANGO_SETTINGS_MODULE", "myproject.settings")
django.setup()

from drf_mcp import DRFMCP

# Initialize MCP server
mcp = DRFMCP(
    name="MyEnterpriseAPI",
    version="1.0.0",
    description="Enterprise API exposed via Model Context Protocol"
)

# Option 1: Auto-discover all DRF views in URLconf
mcp.autodiscover()

# Option 2: Register specific ViewSets
# from myapp.views import CustomerViewSet
# mcp.register_viewset(CustomerViewSet, namespace="crm")

if __name__ == "__main__":
    # Run with stdio transport (default for Claude Desktop)
    mcp.run()
```

### 2. Run the Server

```bash
python mcp_server.py
```

The server will start listening for MCP requests via stdio.

### 3. Connect to Claude Desktop (or other MCP clients)

Edit `~/.claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "django-api": {
      "command": "python",
      "args": ["/path/to/mcp_server.py"]
    }
  }
}
```

Then restart Claude Desktop. Your DRF API endpoints are now available as tools!

## Key Concepts

### ViewSet Tools

For each DRF ViewSet, Django MCP automatically creates separate tools for each action:

```python
from rest_framework import viewsets
from drf_mcp import DRFMCP

class CustomerViewSet(viewsets.ModelViewSet):
    queryset = Customer.objects.all()
    serializer_class = CustomerSerializer
    # list, retrieve, create, update, destroy actions automatically exposed

mcp = DRFMCP("MyAPI")
mcp.register_viewset(CustomerViewSet, namespace="crm")
```

This generates tools:
- `crm_get_list_customers` - List all customers (GET)
- `crm_post_create_customer` - Create a customer (POST)
- `crm_get_retrieve_customer` - Get a customer detail (GET with ID)
- `crm_put_update_customer` - Update a customer (PUT)
- `crm_patch_partial_update_customer` - Partial update (PATCH)
- `crm_delete_destroy_customer` - Delete a customer (DELETE)

### Custom Actions

ViewSet `@action` decorators are automatically discovered:

```python
from rest_framework.decorators import action

class CustomerViewSet(viewsets.ModelViewSet):
    serializer_class = CustomerSerializer
    
    @action(detail=False, methods=['post'])
    def bulk_export(self, request):
        # Custom action
        pass

# Generated tool: crm_post_bulk_export
```

### Schema Generation

DRF Serializers are automatically converted to JSON schemas for MCP:

```python
class CustomerSerializer(serializers.ModelSerializer):
    class Meta:
        model = Customer
        fields = ['id', 'name', 'email', 'created_at']
        read_only_fields = ['id', 'created_at']

# Automatically converts to MCP-compatible JSON schema
# with proper required/optional/readonly field handling
```

## Inspector CLI

Test your exposed tools without running a full MCP server:

```bash
python manage.py mcp_inspector
```

Options:
- `--namespace PREFIX` - Filter tools by namespace
- `--output {json,table,text}` - Output format
- `--endpoint PATH` - Filter by endpoint path
- `--list-only` - Only list tools, don't enter interactive mode

Example:
```bash
python manage.py mcp_inspector --namespace crm --output json
```

## Permission Integration

Django MCP respects your DRF permission classes:

```python
from rest_framework.permissions import IsAuthenticated, IsAdminUser

class CustomerViewSet(viewsets.ModelViewSet):
    serializer_class = CustomerSerializer
    permission_classes = [IsAuthenticated, IsAdminUser]
    # Tools generated from this ViewSet enforce these permissions
```

MCP agents must authenticate before accessing restricted tools.

## Next Steps

- [Architecture Guide](./architecture.md) - Learn how Django MCP works internally
- [Security Guide](./security.md) - Secure your MCP server
- [Examples](../examples/) - Real-world examples