Metadata-Version: 2.4
Name: django-silk-mcp
Version: 0.1.7
Summary: MCP server exposing django-silk profiling data as AI assistant tools
Author: Hernany Costa
Author-email: Hernany Costa <hernany.costa@vinta.com.br>
License-Expression: MIT
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Framework :: Django
Classifier: Framework :: Django :: 4.2
Classifier: Framework :: Django :: 5.2
Requires-Dist: django>=4.2
Requires-Dist: django-silk>=5.0
Requires-Dist: django-mcp-server>=0.5.7
Requires-Python: >=3.11
Description-Content-Type: text/markdown

# django-silk-mcp

[![CI](https://github.com/vintasoftware/django-silk-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/vintasoftware/django-silk-mcp/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/vintasoftware/django-silk-mcp/graph/badge.svg?token=V3HW9B6E9G)](https://codecov.io/gh/vintasoftware/django-silk-mcp)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/django-silk-mcp)](https://pypi.org/project/django-silk-mcp/)
[![PyPI - Django Versions](https://img.shields.io/pypi/djversions/django-silk-mcp)](https://pypi.org/project/django-silk-mcp/)

An [MCP](https://modelcontextprotocol.io/) server that exposes [django-silk](https://github.com/jazzband/django-silk) profiling data as tools for any MCP-compatible AI coding assistant. Enables query-level investigation and optimization directly from your conversation — N+1 detection, EXPLAIN ANALYZE, over-fetch analysis, and Python profiling without leaving your editor.


## Installation

```bash
pip install django-silk-mcp
# or
uv add django-silk-mcp
```

## Configuration

### 1. Add to INSTALLED_APPS

```python
INSTALLED_APPS = [
    ...
    "silk",
    "django_silk_mcp",
]
```

### 2. Configure your MCP client

Expose the MCP server as a URL inside your Django app. Works on both WSGI and ASGI with no extra infrastructure.

Add to your root `urls.py`:

```python

urlpatterns = [
    ...
    path("silk/", include("silk.urls", namespace="silk")),
    path("silk/mcp", include("django_silk_mcp.urls")),
]
```

This serves the MCP endpoint at `/silk/mcp`. The MCP server runs as part of your Django app — no separate process needed, **it shares the same port as your dev server**. Then configure your MCP client:

**Claude Code:**

```bash
claude mcp add silk-mcp --transport http http://localhost:8000/silk/mcp
```

**Cursor:** Go to **Settings → Toos & MCPs → New MCP Server** and add a new server with the following configuration:


```json
{
  "mcpServers": {
    "silk-mcp": {
      "url": "http://localhost:8000/silk/mcp"
    }
  }
}
```

> The same URL works with any MCP-compatible AI tool.

## Security

> **Warning:** The MCP endpoint uses `AllowAny` with no authentication by default, because MCP clients (Claude Code, Cursor, etc.) connect over plain HTTP and do not send credentials. This is intentional for local development but **must not be exposed in production**.
>
> Silk profiling data includes raw SQL query strings, which can contain business data at runtime (user IDs, emails, search terms, etc.). Anyone who can reach the Django host can read this data through the MCP endpoint.


**Recommended:** Only mount in `DEBUG` mode:

   ```python
   # urls.py
   from django.conf import settings

   if settings.DEBUG:
      urlpatterns = [
        path("silk/", include("silk.urls", namespace="silk")),
        path("silk/mcp", include("django_silk_mcp.urls")),
      ]
   ```


## Tools

| Tool | Purpose |
|---|---|
| `get_most_expensive_endpoints` | Rank all endpoints by average DB time |
| `get_request_time_breakdown` | DB% vs Python% — confirm where time is spent |
| `get_duplicate_queries` | Detect N+1 patterns |
| `get_query_sources` | Which code lines triggered each query |
| `get_overfetched_fields` | SQL columns vs serializer fields — `.only()` candidates |
| `explain_slow_queries` | `EXPLAIN (ANALYZE, BUFFERS)` on slow SELECTs |
| `get_request_queries` | All SQL for a specific request |
| `get_slow_queries` | Slowest individual queries across all requests |
| `get_slow_requests` | Slowest HTTP requests |
| `compare_requests` | Before/after comparison with burst deduplication |
| `get_python_profiles` | `@silk_profile` decorated block timings |
| `get_cprofile_hotspots` | cProfile hotspots — no decorators needed |

## Usage

```bash
# Hit an endpoint first so Silk has data
curl http://localhost:8000/api/your-endpoint/

# Then ask your AI assistant
# "What are the slowest endpoints?"
# "Find N+1 queries in /api/your-endpoint/"
# "Run EXPLAIN on the slow queries for /api/your-endpoint/"
```
