django-admin-mcp: Instructions file for Codex

AGENTS.md - AI Agent Instructions for django-admin-mcp

This document provides context and guidelines for AI agents (GitHub Copilot, etc.) working on this codebase.

Project Overview

django-admin-mcp is a Django package that exposes Django admin models to MCP (Model Context Protocol) clients via HTTP. It enables AI assistants to interact with Django admin interfaces through standardized tools, providing CRUD operations, admin actions, model history, and more.

Key Features

• Zero dependencies beyond Django and Pydantic
• Token-based HTTP authentication with configurable expiry
• Respects Django admin permissions (view/add/change/delete)
• Full CRUD, bulk operations, admin actions, model introspection
• Related object traversal and change history access

Architecture

MCP Client (IDE, Agent, etc.)
    ↓ HTTP + Bearer Token
MCPHTTPView (django_admin_mcp/views.py)
    ↓ JSON-RPC
Tools Registry (django_admin_mcp/tools/registry.py)
    ↓
Handlers (django_admin_mcp/handlers/)
    ↓
Django Admin + ModelAdmin
    ↓
Database

Directory Structure

django-admin-mcp/
├── django_admin_mcp/           # Main package
│   ├── __init__.py             # Public exports (MCPAdminMixin)
│   ├── mixin.py                # Core MCPAdminMixin class
│   ├── models.py               # MCPToken model (authentication)
│   ├── views.py                # HTTP view (MCPHTTPView)
│   ├── admin.py                # Django admin registration
│   ├── apps.py                 # Django app config
│   ├── urls.py                 # URL routing
│   ├── handlers/               # Operation handlers
│   │   ├── base.py             # Base utilities, permissions
│   │   ├── crud.py             # Create, Read, Update, Delete
│   │   ├── actions.py          # Admin actions
│   │   ├── relations.py        # Foreign key relations
│   │   └── meta.py             # Model introspection
│   ├── protocol/               # MCP protocol implementation
│   │   ├── types.py            # Pydantic type definitions
│   │   ├── jsonrpc.py          # JSON-RPC implementation
│   │   └── errors.py           # Error definitions
│   ├── tools/                  # Tool registry and management
│   │   ├── registry.py         # Tool registration and routing
│   │   └── __init__.py         # Tool exports
│   └── migrations/             # Database migrations
├── example/                    # Example Django application
├── tests/                      # Test suite (pytest)
├── docs/                       # Documentation (OpenAPI specs)
└── plans/                      # Future improvement plans