Metadata-Version: 2.4
Name: django-silk-mcp
Version: 0.1.5
Summary: MCP server exposing django-silk profiling data as AI assistant tools
Author: Hernany Costa
Author-email: Hernany Costa <hernanytec777@gmail.com>
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
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.

## 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/"
```
