drf-mcp-docs
API documentation via MCP for AI coding agents
---
**drf-mcp-docs** exposes your Django REST Framework API **documentation** through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) so AI coding agents can read, understand, and help you write correct frontend integration code.
> **How is this different from other Django+MCP packages?**
>
> Packages like `django-mcp-server` and `django-rest-framework-mcp` expose DRF **actions** as MCP tools — the AI agent calls your endpoints directly. **drf-mcp-docs** is fundamentally different: it exposes API **documentation** so AI agents can help developers **write frontend code** (React, Vue, Angular, etc.).
>
> Think of it as: *drf-spectacular generates docs for humans in a browser* → *drf-mcp-docs generates docs for AI agents via MCP*.
## Features
- **MCP Resources** — Browse your API structure: overview, endpoints, schemas, auth methods
- **MCP Tools** — Search endpoints, get detailed docs, generate request/response examples
- **Code Generation** — Generate integration code with real types and docs (JS/TS: fetch, axios, ky — Python: requests, httpx — cURL)
- **Multi-adapter** — Works with drf-spectacular, drf-yasg, or DRF's built-in schema generation
- **Zero risk** — Read-only documentation exposure, no data mutation possible
- **Two transports** — stdio for local AI tools, streamable-http for remote/network access
## Quick Start
### 1. Install
```bash
pip install drf-mcp-docs
```
With a specific schema generator:
```bash
pip install drf-mcp-docs[spectacular] # recommended
pip install drf-mcp-docs[yasg]
```
### 2. Configure
Add to your Django settings:
```python
INSTALLED_APPS = [
# ...
'rest_framework',
'drf_mcp_docs',
]
```
That's it for basic usage. drf-mcp-docs auto-detects your schema generator.
### 3. Run
**stdio transport** (for local AI tools like Claude Code, Cursor, etc.):
```bash
python manage.py runmcpserver --transport stdio
```
**Streamable HTTP transport** (for network access):
```bash
python manage.py runmcpserver --transport streamable-http --host 0.0.0.0 --port 8100
```
**Check configuration** (validate settings, adapter, and schema):
```bash
python manage.py checkmcpconfig
```
### 4. Connect your AI tool
**Claude Code** (`~/.claude.json`):
```json
{
"mcpServers": {
"my-api-docs": {
"command": "python",
"args": ["manage.py", "runmcpserver", "--transport", "stdio"],
"cwd": "/path/to/your/django/project"
}
}
}
```
**Cursor** (`.cursor/mcp.json`):
```json
{
"mcpServers": {
"my-api-docs": {
"command": "python",
"args": ["manage.py", "runmcpserver", "--transport", "stdio"],
"cwd": "/path/to/your/django/project"
}
}
}
```
## What AI Agents Can Do
Once connected, your AI coding agent can:
```
You: "Show me all the product endpoints"
Agent: [reads api://endpoints resource, filters by tag]
You: "Generate a React hook to create a new product"
Agent: [calls get_endpoint_detail for POST /api/products/]
[calls get_request_example for the request body]
[calls generate_code_snippet with typescript + fetch]
→ Generates a complete, typed React hook with correct fields
```
### Available Resources
| Resource URI | Description |
|---|---|
| `api://overview` | API title, version, base URL, auth summary, tags, endpoint count |
| `api://endpoints` | All endpoints: path, method, summary, tags (compact listing) |
| `api://endpoints/{method}/{path}` | Full detail for one endpoint |
| `api://schemas` | All schema/model definitions (names + field summaries) |
| `api://schemas/{name}` | Full schema with properties, types, constraints |
| `api://auth` | Authentication guide with all auth methods |
### Available Tools
| Tool | Parameters | Description |
|---|---|---|
| `search_endpoints` | `query`, `method?`, `tag?` | Search endpoints by keyword |
| `get_endpoint_detail` | `path`, `method` | Full endpoint documentation |
| `get_request_example` | `path`, `method` | Example request body and parameters |
| `get_response_example` | `path`, `method`, `status_code?` | Example response |
| `generate_code_snippet` | `path`, `method`, `language?`, `client?` | Integration code (JS/TS, Python, cURL) with pagination support |
| `list_schemas` | — | All data model names and descriptions |
| `get_schema_detail` | `name` | Full schema with all fields and types |
## Configuration
All settings are optional. Add a `DRF_MCP_DOCS` dict to your Django settings:
```python
DRF_MCP_DOCS = {
# Server
'SERVER_NAME': 'my-api', # MCP server name (default: 'drf-mcp-docs')
'SERVER_INSTRUCTIONS': 'Custom prompt...', # Instructions shown to AI agents
# Schema
'SCHEMA_ADAPTER': None, # Auto-detect, or full dotted path
'SCHEMA_PATH_PREFIX': '/api/', # Only include endpoints under this prefix
'EXCLUDE_PATHS': ['/api/internal/'], # Paths to exclude
'CACHE_SCHEMA': not DEBUG, # Cache in production, refresh in dev
'CACHE_TTL': None, # Schema cache TTL in seconds (None = no expiry)
# Transport
'TRANSPORT': 'streamable-http', # Default transport: 'streamable-http' or 'stdio'
'MCP_ENDPOINT': '/mcp/', # URL path for HTTP transport
# Code generation
'DEFAULT_CODE_LANGUAGE': 'javascript', # 'javascript', 'typescript', or 'python'
'DEFAULT_HTTP_CLIENT': 'fetch', # 'fetch', 'axios', 'ky', 'requests', or 'httpx'
}
```
### Schema Adapter Selection
drf-mcp-docs auto-detects your schema generator in this priority order:
1. **drf-spectacular** (recommended) — most complete OpenAPI 3.x output
2. **drf-yasg** — Swagger 2.0 auto-converted to OpenAPI 3.0
3. **DRF built-in** — basic fallback with limited schema detail
To force a specific adapter:
```python
DRF_MCP_DOCS = {
'SCHEMA_ADAPTER': 'drf_mcp_docs.adapters.spectacular.SpectacularAdapter',
}
```
## ASGI Integration
For projects using ASGI, mount the MCP endpoint alongside your Django app:
```python
# asgi.py
from django.core.asgi import get_asgi_application
from drf_mcp_docs.urls import mount_mcp
django_app = get_asgi_application()
application = mount_mcp(django_app) # Mounts at /mcp/ by default
```
With custom path:
```python
application = mount_mcp(django_app, path="/api-docs-mcp/")
```
## Development
```bash
git clone https://github.com/Abdulkhalek-1/drf-mcp-docs.git
cd drf-mcp-docs
pip install -e ".[dev]"
pytest
```
## How It Works
```
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐ ┌───────────┐
│ AI Agent │────>│ MCP Server │────>│ Schema Processor │────>│ Adapter │
│ (Claude, │<────│ (FastMCP) │<────│ (OpenAPI dict │<────│ (spectac- │
│ Cursor...) │ │ │ │ → structured) │ │ ular, │
└─────────────┘ └──────────────┘ └─────────────────┘ │ yasg, │
Resources + Tools Dataclasses + Search │ DRF) │
└───────────┘
```
1. **Adapter** pulls the OpenAPI schema from your chosen generator
2. **Processor** transforms the raw dict into structured, AI-friendly dataclasses
3. **MCP Server** exposes resources (browsable docs) and tools (search, examples, code gen)
4. **AI Agent** connects via stdio or HTTP, reads your API docs, helps write frontend code
## License
MIT License. See [LICENSE](LICENSE) for details.