django-mcp-sql 0.1.0a1__py3-none-any.whl

django_mcp_sql-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,278 @@
+Metadata-Version: 2.4
+Name: django-mcp-sql
+Version: 0.1.0a1
+Summary: Read-only PostgreSQL surface for an LLM agent over the MCP protocol, with defense-in-depth at parser, executor, DB-role, and transport layers.
+Author: Ivan Kharlamov, Claude (Anthropic)
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/thepapermen/django-mcp-sql
+Project-URL: Repository, https://github.com/thepapermen/django-mcp-sql
+Project-URL: Issues, https://github.com/thepapermen/django-mcp-sql/issues
+Project-URL: Changelog, https://github.com/thepapermen/django-mcp-sql/blob/main/CHANGELOG.md
+Keywords: django,mcp,postgresql,llm-agent,oauth,read-only-sql
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 5.2
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: django<6.0,>=5.2
+Requires-Dist: djangorestframework<4,>=3.15.2
+Requires-Dist: django-oauth-toolkit<4,>=3.2
+Requires-Dist: sqlglot<31,>=30.7
+Requires-Dist: mcp<2,>=1.27
+Requires-Dist: a2wsgi<2,>=1.10
+Requires-Dist: pydantic<3,>=2.11
+Provides-Extra: allauth
+Requires-Dist: django-allauth[mfa]<66,>=65.14; extra == "allauth"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-django>=4.8; extra == "test"
+Requires-Dist: psycopg[binary]>=3.2; extra == "test"
+Dynamic: license-file
+
+# django-mcp-sql
+
+[![PyPI](https://img.shields.io/pypi/v/django-mcp-sql)](https://pypi.org/project/django-mcp-sql/)
+[![CI](https://github.com/thepapermen/django-mcp-sql/actions/workflows/ci.yml/badge.svg)](https://github.com/thepapermen/django-mcp-sql/actions/workflows/ci.yml)
+
+A tightly scoped, read-only PostgreSQL surface for an LLM agent (e.g.
+Claude Code) over the [Model Context Protocol](https://modelcontextprotocol.io/).
+Defense-in-depth at four layers: parser (sqlglot AST validators), executor
+(PG NOLOGIN role + GUCs), DB-role (`mcp_readonly_role` SELECT grants), and
+transport (DRF + django-oauth-toolkit OAuth 2.1 with PKCE + RFC 7591/8414/9728
+discovery).
+
+> **Status**: pre-release alpha (`0.1.0a1`). The package is used in
+> production as part of a larger Django project; expect the public API and
+> settings shape to move between alpha releases.
+
+## What you get
+
+Three MCP tools mounted at `/mcp/sql/`:
+
+| Tool | Purpose |
+|---|---|
+| `list_tables()` | Returns the whitelisted db_tables for the surface (sorted). |
+| `describe_table(name)` | Returns column types / null / pk for a whitelisted table. |
+| `run_query(sql, limit=None)` | Validates + executes a single SELECT. Returns `{columns, rows, row_count, truncated, duration_ms, hint, rejection_reason, error, data_handling}`. `rows` (and `error`, when set) come back wrapped in a per-response random-UUID `<untrusted-data-…>` fence so DB content carrying a prompt-injection payload can't be read as agent instructions; `data_handling` explains the boundary. |
+
+Every call writes one append-only `MCPQueryLog` audit row. Every auth
+rejection writes one `MCPAuthRejectionLog` row (six resolved-user gates;
+anonymous / bad-token probing goes through Django-cache counters with a
+silent per-IP block, not the audit table — use a shared cache backend
+(Redis, Memcached) in production: with a per-process backend like LocMem
+the counters, and therefore the block, are per-worker).
+
+**Observability** — per-user query-volume tripwires (one `ERROR` per
+`(user, decision, window)` crossing of `VOLUME_ALERT_THRESHOLDS`; alerts,
+never blocks), an `ERROR` when a user is added to the MCP permission group,
+and read-only Django admin browsers for both audit tables plus a per-user
+usage-summary view (allowed / rejected / auth-rejection counts per rolling
+window). The package emits `logger.error` only — wire a Sentry
+`LoggingIntegration(event_level=logging.ERROR)` to receive these as events;
+the package itself never imports `sentry_sdk`.
+
+## Postgres-only by design
+
+The package depends on Postgres features that don't port: `SET LOCAL ROLE`
+into a NOLOGIN role, `statement_timeout` / `lock_timeout` /
+`idle_in_transaction_session_timeout` / `default_transaction_read_only`
+GUCs, PG-only error codes (`57014`, `42501`), `CREATE OR REPLACE VIEW`
+semantics, sqlglot's `dialect='postgres'`. There is no design path to
+MySQL / SQLite without a parallel implementation — hence `django-mcp-sql`
+not `django-mcp-mysql` etc.
+
+## Installation
+
+```sh
+pip install django-mcp-sql
+# Optional extras
+pip install "django-mcp-sql[allauth]"   # wire MFA gate to allauth.mfa.utils.is_mfa_enabled
+```
+
+Then in your Django settings:
+
+```python
+INSTALLED_APPS = [
+    # ... your apps ...
+    "rest_framework",
+    "oauth2_provider",
+    "mcp_sql",
+]
+
+DATABASES = {
+    "default": { ... },
+    # Required: dedicated read-only alias. The executor asserts
+    # connection.alias == MCP_SQL["DB_ALIAS"] before issuing any SELECT.
+    "mcp_readonly": {
+        # ... pointed at the same database as default but as a non-superuser ...
+        "OPTIONS": {"application_name": "mcp-readonly"},
+        "ATOMIC_REQUESTS": False,
+        "CONN_MAX_AGE": 0,
+    },
+}
+
+DATABASE_ROUTERS = ["mcp_sql.db_router.McpSqlRouter"]
+
+MCP_SQL = {
+    "ALLOWED_MODELS": [
+        "auth.Permission",  # your real whitelist goes here
+    ],
+    "BAN_SELECT_STAR": True,
+    "LIMITS": {"DEFAULT_LIMIT": 10, "HARD_LIMIT": 100, "BYTES_LIMIT": 256 * 1024},
+    # Per-user volume tripwires: {decision: {window_seconds: threshold}}.
+    # Crossing emits one Sentry ERROR per (user, decision, window) bucket;
+    # it alerts, it never blocks.
+    "VOLUME_ALERT_THRESHOLDS": {
+        "allowed": {3600: 50, 86400: 150},
+        "rejected": {3600: 50, 86400: 150},
+    },
+    "BAD_TOKEN_IP_THRESHOLD": 100,
+    "BAD_TOKEN_IP_WINDOW_SECONDS": 21600,
+    # Optional overrides — see `mcp_sql/conf.py` DEFAULTS for the full list:
+    # "RESOURCE_NAME": "My App",
+    # "MFA_CHECKER": "allauth.mfa.utils.is_mfa_enabled",
+    # "SESSION_MODEL": "your_app.Session",  # opt-in runtime session-existence gate;
+                                            # must be a session model with a `user` FK
+                                            # (stock `django.contrib.sessions.Session`
+                                            # does NOT qualify — its absence of a `user`
+                                            # column is why the default is `None`)
+}
+
+OAUTH2_PROVIDER = {
+    "OAUTH2_VALIDATOR_CLASS": "mcp_sql.oauth.MCPOAuth2Validator",
+    "SCOPES": {"mcp:sql": "Read-only SQL surface for MCP agents"},
+    "DEFAULT_SCOPES": ["mcp:sql"],
+    "ACCESS_TOKEN_EXPIRE_SECONDS": 6 * 3600,
+    "REFRESH_TOKEN_EXPIRE_SECONDS": 0,
+    "AUTHORIZATION_CODE_EXPIRE_SECONDS": 60,
+    "PKCE_REQUIRED": True,
+    "ALLOWED_REDIRECT_URI_SCHEMES": ["http"],   # RFC 8252 loopback
+}
+```
+
+Wire the URLs in your project's `urls.py`:
+
+```python
+urlpatterns = [
+    # ... your routes ...
+    path("", include("mcp_sql.urls")),
+]
+```
+
+Then run the DBA setup once per environment (creates the
+`mcp_readonly_role` Postgres role + role-level guard GUCs):
+
+```sh
+psql -U <superuser> -d <database> \
+    -v app_role=<your_app_role> \
+    -f $(python -c "import mcp_sql, os; print(os.path.join(os.path.dirname(mcp_sql.__file__), 'sql/role_setup.sql'))")
+```
+
+Then apply migrations and the SELECT grants:
+
+```sh
+python manage.py migrate
+python manage.py mcp_sql_grants --apply
+```
+
+## Documentation
+
+The architecture / design doc and the full operational runbooks ship inside
+the package (importable consumers find them under `mcp_sql/docs/`):
+
+- `docs/architecture.md` — design, file map, settings shape, OAuth surface,
+  curated-view pattern, the complete "Watch out" list.
+- `docs/role-setup.md` — DBA setup, grants reconciliation, sanity checks.
+- `docs/oauth.md` — OAuth issuance gate, MCP client registration, incident response.
+
+## Compatibility
+
+- **Python**: 3.11+
+- **Django**: 5.2+ (LTS line; 6.0 untested).
+- **Postgres**: 14+ recommended (uses `pg_has_role`, `information_schema.role_table_grants`, `SET LOCAL ROLE`, `CREATE OR REPLACE VIEW` — all of which work on earlier versions, but the test matrix runs on 14+).
+
+The package has been exercised against a 2000+ test suite in a real
+Django CRM. Its own standalone suite (`make test`, settings in
+`tests/settings.py`) runs in CI across Python 3.11–3.13 against
+PostgreSQL 14 (`.github/workflows/ci.yml`).
+
+## Postgres role setup
+
+Once per environment, a DBA with PG superuser rights applies
+`sql/role_setup.sql` to create the `mcp_readonly_role` role + the
+role-level guard GUCs (`statement_timeout`, `lock_timeout`,
+`idle_in_transaction_session_timeout`, `default_transaction_read_only`)
+and grant the role membership to the consuming app's PG user. The script
+is idempotent and is parameterised by a `-v app_role=<role>` psql
+variable so a single SQL file works across deployments whose app role
+differs.
+
+```sh
+psql -h <pg_host> -U <pg_superuser> -d <database> \
+    -v app_role=<app_pg_role> \
+    -f sql/role_setup.sql
+
+# Verify:
+psql -h <pg_host> -U <pg_superuser> -d <database> -c "\du mcp_readonly_role"
+# Expected: row present, "Cannot login".
+```
+
+After the role exists, apply the package's migrations and reconcile the
+table-level SELECT grants:
+
+```sh
+python manage.py migrate
+python manage.py mcp_sql_grants --apply
+```
+
+See `docs/role-setup.md` for the full DBA-facing runbook (drift
+detection, CI gates, troubleshooting).
+
+## Local example
+
+A standalone, stock-Django consumer of the package lives in the
+[`example/`](https://github.com/thepapermen/django-mcp-sql/tree/main/example)
+directory of the repository (not shipped in the wheel). It demonstrates the
+package against a vanilla Django setup — `auth.User`, stock sessions, no
+allauth — including a two-profile (multi-tier) configuration with a
+row-and-column-limited curated view. Its own README carries the full
+end-to-end runbook: bootstrap, OAuth dance, and registering the server with
+`claude mcp add`.
+
+## Development
+
+Run the package's own test suite (needs `uv` and a reachable PostgreSQL —
+see `tests/settings.py` for the `MCP_SQL_TEST_PG_*` connection env vars.
+Bootstrap `mcp_readonly_role` via `sql/role_setup.sql` first — several
+tests enter it with `SET LOCAL ROLE` — and connect as a superuser so the
+role-isolation tests run instead of skipping):
+
+```sh
+make test
+```
+
+Build the distribution and verify the wheel installs cleanly into a fresh
+venv (Django-independent imports + package-data presence):
+
+```sh
+make build              # produces ./dist/django_mcp_sql-<version>-py3-none-any.whl + .tar.gz
+make test-install       # ephemeral build + venv install + import & package-data smoke
+```
+
+All targets require `uv` on PATH (install once: `curl -LsSf https://astral.sh/uv/install.sh | sh`).
+Release/extraction mechanics live in `RELEASING.md`; contribution
+expectations in `CONTRIBUTING.md`.
+
+## License
+
+MIT.

django_mcp_sql-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,57 @@
+django_mcp_sql-0.1.0a1.dist-info/licenses/LICENSE,sha256=J9wxXiLlVvjXpiSKCRoBT3IvcQp3WwK0R0HK4U50ZI0,1071
+mcp_sql/__init__.py,sha256=3vrbyJfW4C0ufPH0MF8CthVo0a97OjEoob40ZpRTH-0,118
+mcp_sql/admin.py,sha256=iJtW1ORLJNZRGyX794QMvWm-fu_8iLn7GQK7fsEq8F0,8871
+mcp_sql/apps.py,sha256=Z2y5ABH5KoFXS-zrERZX60K5SZ6vSqfxK2sCdRqQV0U,1674
+mcp_sql/auth.py,sha256=wb8DVPQbD9lhlG-fFSEElZcdqgl3CaufIwubsC-g_tg,19752
+mcp_sql/conf.py,sha256=Nw6XTmiu9CdCaBY3RW1MDGSO0oAZ-PHCeS7kCQv6VcQ,15793
+mcp_sql/consts.py,sha256=nff2OPifscDhJF8UWj_hka5T6Wk9ro3ZXVTrJplkrnw,2423
+mcp_sql/db_router.py,sha256=nd6iuSng7gijYv7KYQelqKnKXvD6XVVdnKFr7NRcqBU,1796
+mcp_sql/decorators.py,sha256=fVexC_ty5pbpYdeKAea2fMX2QJ2U6ZGbMK6cdp9hkss,3121
+mcp_sql/executor.py,sha256=rVZLSSQUna8ZcdklwTxV7urySJEg6xHnooFM2vKHKBE,20912
+mcp_sql/fencing.py,sha256=xQmmOPiWrV9ClAeFSNU4sQr5EiaWhC2enr0UOY8_ZfM,3352
+mcp_sql/grants.py,sha256=3HRAV3xEZLrtTL1MNn8730zyiiZZ3K1iCYHynKR8PwY,13687
+mcp_sql/models.py,sha256=dWNdMmHzFNnMteF82ToUhaEXV0p1zCjJBwTa-IoyMes,8830
+mcp_sql/oauth.py,sha256=haeiXPApsOsU4wcRvU58L_sEXerP5dC0C6sGfr3AzfI,2656
+mcp_sql/observability.py,sha256=Rwru3HQ919NnesPCpd_zITcxYXfeSj6w6q7lMbNZmZs,4038
+mcp_sql/parser.py,sha256=LoSirb6HV7sHVYXHWpO6vpRXPIEmHsLBzSsk4IgWDkQ,30753
+mcp_sql/schemas.py,sha256=v9XmBqrv9jgcWEdKgfGHjzgQ6azkstFkq0Tdjf-RgxQ,7556
+mcp_sql/session.py,sha256=cgkQdsnxv1a_qcCF81FFT4iprTTYvfu7bxXgRH33D14,4606
+mcp_sql/signals.py,sha256=Bq4KbAbgA4jMVtIbUGkrkl3lYJrBjp1E2595Vv9RBlE,13426
+mcp_sql/throttle.py,sha256=ykwCumoUcJ7w8hbQAQdqVnNsnNMRQCqPXf3cWgCgkIo,4559
+mcp_sql/urls.py,sha256=tAr4HFDqxFWcoMlfBAYQwm9wdHqP7o7KtLd9eOmtaR0,3347
+mcp_sql/validation.py,sha256=qOd1jRv6sTb0rLpehENb3xZ0v8bZXDcd6fdXynV8S08,11337
+mcp_sql/docs/architecture.md,sha256=R7L1PozXw8YuhcJIFr5yQJ_diQNESh2Fi_tyQ4qQ7pg,67734
+mcp_sql/docs/oauth.md,sha256=Z5PtI2lte6pb9nOl173Kxls2GSIRPJEune4arq6lLyI,27049
+mcp_sql/docs/role-setup.md,sha256=TDypv2TBJYF-TtIuZ9bXrkKOu5GqGI-tsnXqYn19Zh8,17700
+mcp_sql/management/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_sql/management/commands/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_sql/management/commands/mcp_sql_grants.py,sha256=fBQkLp2OpZ3x9z7GHmxYMED-83CsWWXqDNJ8HLeL-Z0,3141
+mcp_sql/management/commands/mcp_sql_lint.py,sha256=7KHcskEU32uvqbmJ7l2QPBKxss2N2_1riU80Hbhf9zA,3257
+mcp_sql/management/commands/mcp_sql_role_setup.py,sha256=sc_QExVKOGpezxryLTpVpOIM1K0hN5qVq7oXC8_FeA4,4612
+mcp_sql/management/commands/mcp_sql_smoke.py,sha256=JF56kT2hpP1PEneyTfG8CrYR6vP6wZHWlS3AceejVvc,12405
+mcp_sql/migrations/0001_initial.py,sha256=UvYtd1LMfPokp_6WSD0DeKy4GwtKx-C7uobXmumoa8M,2307
+mcp_sql/migrations/0002_revoke_audit_grants.py,sha256=jeWE0F5pqJLdxtzNDKSMIDW9TpxCrcNG5zXqJoqwdwc,485
+mcp_sql/migrations/0003_alter_mcpquerylog_result_sample.py,sha256=qYuXrf0hRe5h9u_UBSoAuSxzsD2a-gvY-YmazgJifPo,411
+mcp_sql/migrations/0004_create_mcp_sql_users_group.py,sha256=ZTKmY587EO-SMOF6s89IpGvHha1VDYnD1QfaKiz8izs,1286
+mcp_sql/migrations/0005_create_mcp_sql_application.py,sha256=kp1LK6ohZcoikjUX171eFfig5vfkC_NIhS5PICINyCY,3361
+mcp_sql/migrations/0006_remove_mcpquerylog_result_sample.py,sha256=gUB-2jiG0SAMymixen4cVlQIX_4BR849hH-UQrYoJYw,349
+mcp_sql/migrations/0007_mcpauthrejectionlog.py,sha256=Ixyf7l0CSIk3w3LiQd-KdMuZYpS4DNUZSnuEXiBG-ww,1977
+mcp_sql/migrations/0008_revoke_mcpauthrejectionlog_grants.py,sha256=blQYJcd283daIlOyU7GENc6fyDHgi3EJUTwxF8hoDPA,1708
+mcp_sql/migrations/0009_alter_mcpauthrejectionlog_reason.py,sha256=FKL4wbM8PqZQEZYIMSUtdaeRUlzdQZfncpi_NhRlWdI,836
+mcp_sql/migrations/0010_mcpquerylog_tool.py,sha256=JExavu-q59DyDorp6JL_ifmTqsCkKqTGcZMfKAui5vk,423
+mcp_sql/migrations/0011_alter_mcpquerylog_options_mcpquerylog_profile_and_more.py,sha256=7xYsNQf-rd-oFjkHO7Dgdv5gnPaqCasBeSAI-ldvFP4,1271
+mcp_sql/migrations/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_sql/sql/10_mcp_role.sh,sha256=jdL6hzZkky9JU-1uLSHtaS_T26PFTAmNT09bmi00spA,1936
+mcp_sql/sql/role_setup.sql,sha256=MeWtc1Z4lATpbSUDt6fqnOJVAQCrcplsuYdOjj6h9A4,3566
+mcp_sql/templates/admin/mcp_sql/mcpquerylog_change_list.html,sha256=VnZBpqOx204ipH_NIKbiNUdbXGEKcjiR4-BU80E07QI,229
+mcp_sql/templates/admin/mcp_sql/usage_summary.html,sha256=K3xWBelNfwcFoOY186AL7xXcshYkjkITnSpsqiZSbKg,1637
+mcp_sql/templates/mcp_sql/authorize.html,sha256=FNVMRhjt8UUaQt3rJZkfZEJnCgtNFNQhj1IHQwVwazM,1572
+mcp_sql/views/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+mcp_sql/views/discovery.py,sha256=xg0DtF9YJ1CYZts1HRs-WMDMe7q504GGnCQEyJ0aHqU,4814
+mcp_sql/views/mcp_endpoint.py,sha256=OPLF5svBZZUaCF8uAQrDN-YrbcIOtflRljbcTTfeSuQ,23893
+mcp_sql/views/oauth_authorize.py,sha256=eegFLe5bSFm86BxQm6S3lnCEHtFGZdoVm6QoFHFOjyc,3982
+mcp_sql/views/registration.py,sha256=G6lQH4pqSLSDtv2qBY-d8zEFZilFosyKOSLWhgetBuU,9506
+django_mcp_sql-0.1.0a1.dist-info/METADATA,sha256=0b8mespTjHicBg4bcdHQtsPj3RbadaS_2ggCCZR-OOY,11274
+django_mcp_sql-0.1.0a1.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+django_mcp_sql-0.1.0a1.dist-info/top_level.txt,sha256=vgGs1OTAVjBuHkT8ANto9EOtce_kwc3fvcu4TWtEF18,8
+django_mcp_sql-0.1.0a1.dist-info/RECORD,,

django_mcp_sql-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

django_mcp_sql-0.1.0a1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ivan Kharlamov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

django_mcp_sql-0.1.0a1.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcp_sql

mcp_sql/__init__.py

@@ -0,0 +1,6 @@
+"""django-mcp-sql.
+
+Read-only PostgreSQL surface for an LLM agent over the MCP protocol.
+"""
+
+__version__ = "0.1.0a1"

mcp_sql/admin.py

@@ -0,0 +1,240 @@
+"""Unregister django-oauth-toolkit ModelAdmin classes.
+
+DOT auto-registers ModelAdmin for `Application`, `AccessToken`, `Grant`,
+`RefreshToken`, and `IDToken` when `oauth2_provider` is in
+`INSTALLED_APPS`. Those admins are write-enabled to superusers, which
+would bypass two design invariants of the MCP SQL surface:
+
+1. The single-Application contract. A superuser could create a new
+   Application, attach a redirect URI under their control, and mint
+   tokens with `mcp:sql` scope. `MCPOAuth2Authentication` rejects tokens
+   not bound to an `mcp-sql` Application, but keeping a parallel write
+   path open invites confusion and a future regression.
+2. The locked-down redirect URI. Migration 0005 sets the canonical
+   `mcp-sql` Application's `redirect_uris` to the single loopback entry
+   `http://127.0.0.1` (RFC 8252 §7.3). Editing it via the admin would
+   reroute the OAuth flow to an attacker-controlled URI in a single edit.
+
+Unregistering does not remove the underlying tables (DOT still uses them
+at runtime). It only removes the operator-facing admin surface. Token
+lifecycle operations (revoke a user's tokens, audit usage) are documented
+in `docs/oauth.md` and use the Django shell.
+
+This module also registers READ-ONLY admins for the two audit tables
+(`MCPQueryLog`, `MCPAuthRejectionLog`) plus a per-user usage-summary view
+(allowed/rejected query counts + auth-rejection counts per rolling window) —
+the instrument for tuning `MCP_SQL["VOLUME_ALERT_THRESHOLDS"]`.
+"""
+
+import contextlib
+from datetime import timedelta
+
+from django.contrib import admin
+from django.contrib.admin.sites import NotRegistered
+from django.contrib.auth import get_user_model
+from django.core.exceptions import PermissionDenied
+from django.db.models import Count
+from django.template.response import TemplateResponse
+from django.urls import path
+from django.utils import timezone
+from oauth2_provider.models import AccessToken
+from oauth2_provider.models import Application
+from oauth2_provider.models import Grant
+from oauth2_provider.models import IDToken
+from oauth2_provider.models import RefreshToken
+
+from mcp_sql.conf import mcp_sql_settings
+from mcp_sql.models import MCPAuthRejectionLog
+from mcp_sql.models import MCPQueryLog
+
+for model_cls in (Application, AccessToken, Grant, RefreshToken, IDToken):
+    with contextlib.suppress(NotRegistered):
+        admin.site.unregister(model_cls)
+
+
+# Rolling windows for the usage summary: label → seconds.
+_USAGE_WINDOWS = (("1h", 3600), ("24h", 86400), ("7d", 604800))
+
+# Search / ordering / summary labels traverse the consumer user model's
+# USERNAME_FIELD — the same model-agnostic contract as `get_username()`.
+_USER_LOOKUP = f"user__{get_user_model().USERNAME_FIELD}"
+
+
+class _ProfileListFilter(admin.SimpleListFilter):
+    """Filter by configured tier names from `MCP_SQL["PROFILES"]`.
+
+    NOT the stock `AllValuesFieldListFilter` a bare `"profile"` entry would
+    give: `profile` is an unindexed, choice-less CharField, so the stock
+    filter runs `SELECT DISTINCT profile` over the unbounded append-only
+    audit table on every changelist render. Configured tiers are also the
+    more correct lookup set — operators filter by live tiers, not by
+    whatever historical strings accumulated.
+    """
+
+    title = "profile"
+    parameter_name = "profile"
+
+    def lookups(self, request, model_admin):
+        return [(name, name) for name in sorted(mcp_sql_settings.profiles())]
+
+    def queryset(self, request, queryset):
+        if self.value():
+            return queryset.filter(profile=self.value())
+        return queryset
+
+
+class _ReadOnlyModelAdmin(admin.ModelAdmin):
+    """View-only admin: browse rows, never add/change/delete.
+
+    The audit tables are append-only — the executor, signal receivers, and
+    auth class are the only writers — so the admin must not open a write
+    path. A LOCAL mixin (not some consumer-provided read-only mixin) keeps
+    the package free of project imports.
+    """
+
+    def has_add_permission(self, request):
+        return False
+
+    def has_change_permission(self, request, obj=None):
+        return False
+
+    def has_delete_permission(self, request, obj=None):
+        return False
+
+
+@admin.register(MCPQueryLog)
+class MCPQueryLogAdmin(_ReadOnlyModelAdmin):
+    """Read-only browser for query audit rows + the per-user usage summary.
+
+    Search / ordering / the `user_email` display all key on the consumer
+    user model's `USERNAME_FIELD` (via `_USER_LOOKUP` / `get_username()`),
+    so the admin works against any user model.
+    """
+
+    date_hierarchy = "started_at"
+    list_display = (
+        "id",
+        "started_at",
+        "user_email",
+        "profile",
+        "decision",
+        "tool",
+        "rejection_reason",
+        "row_count",
+        "truncated",
+        "duration_ms",
+        "client_ip",
+    )
+    list_filter = ("decision", "tool", "truncated", _ProfileListFilter)
+    search_fields = (_USER_LOOKUP, "rejection_reason", "client_ip")
+    list_select_related = ("user",)
+    change_list_template = "admin/mcp_sql/mcpquerylog_change_list.html"
+
+    @admin.display(description="user", ordering=_USER_LOOKUP)
+    def user_email(self, obj):
+        return obj.user.get_username()
+
+    def get_urls(self):
+        return [
+            path(
+                "usage-summary/",
+                self.admin_site.admin_view(self.usage_summary_view),
+                name="mcp_sql_usage_summary",
+            ),
+            *super().get_urls(),
+        ]
+
+    def usage_summary_view(self, request):
+        # `admin_view` enforces staff login but NOT the model view
+        # permission — re-add it so only operators allowed to read the audit
+        # log see the per-user volume breakdown.
+        if not self.has_view_permission(request):
+            raise PermissionDenied
+        return TemplateResponse(
+            request,
+            "admin/mcp_sql/usage_summary.html",
+            {
+                **self.admin_site.each_context(request),
+                "title": "MCP usage summary",
+                "opts": self.model._meta,
+                "window_labels": [label for label, _ in _USAGE_WINDOWS],
+                "col_count": len(_USAGE_WINDOWS) * 3 + 1,
+                "rows": _usage_rows(),
+            },
+        )
+
+
+@admin.register(MCPAuthRejectionLog)
+class MCPAuthRejectionLogAdmin(_ReadOnlyModelAdmin):
+    """Read-only browser for resolved-user access-ending events."""
+
+    date_hierarchy = "started_at"
+    list_display = (
+        "id",
+        "started_at",
+        "user_email",
+        "reason",
+        "application_name",
+        "client_ip",
+    )
+    list_filter = ("reason",)
+    search_fields = (_USER_LOOKUP, "application_name", "client_ip")
+    list_select_related = ("user",)
+
+    @admin.display(description="user", ordering=_USER_LOOKUP)
+    def user_email(self, obj):
+        return obj.user.get_username()
+
+
+def _usage_rows():
+    """Per-user counts of allowed/rejected queries + auth-rejections per window.
+
+    Six grouped queries (3 windows x {query log, auth-rejection log}), each
+    backed by the models' `(decision|reason, started_at)` / `(user,
+    started_at)` indexes. Each row is pre-shaped into a `cells` list aligned
+    to `_USAGE_WINDOWS` because Django templates cannot index a dict by a
+    computed key. Row labels traverse the consumer user model's
+    `USERNAME_FIELD` so the summary stays model-agnostic (mirrors
+    `get_username()` without a per-row instance fetch).
+    """
+    now = timezone.now()
+    table: dict = {}
+
+    def _row(user_id, user_label):
+        return table.setdefault(
+            user_id,
+            {
+                "label": user_label,
+                "cells": {
+                    label: {"allowed": 0, "rejected": 0, "auth": 0}
+                    for label, _ in _USAGE_WINDOWS
+                },
+            },
+        )
+
+    for label, seconds in _USAGE_WINDOWS:
+        since = now - timedelta(seconds=seconds)
+        for r in (
+            MCPQueryLog.objects.filter(started_at__gte=since)
+            .values("user_id", _USER_LOOKUP, "decision")
+            .annotate(n=Count("id"))
+        ):
+            cell = _row(r["user_id"], r[_USER_LOOKUP])["cells"][label]
+            if r["decision"] in cell:  # "allowed" / "rejected"
+                cell[r["decision"]] += r["n"]
+        for r in (
+            MCPAuthRejectionLog.objects.filter(started_at__gte=since)
+            .values("user_id", _USER_LOOKUP)
+            .annotate(n=Count("id"))
+        ):
+            _row(r["user_id"], r[_USER_LOOKUP])["cells"][label]["auth"] += r["n"]
+
+    rows = [
+        {
+            "label": row["label"],
+            "cells": [row["cells"][label] for label, _ in _USAGE_WINDOWS],
+        }
+        for row in table.values()
+    ]
+    rows.sort(key=lambda r: r["label"] or "")  # label is nullable on exotic user models
+    return rows

mcp_sql/apps.py

@@ -0,0 +1,45 @@
+from django.apps import AppConfig
+
+
+class McpSqlConfig(AppConfig):
+    name = "mcp_sql"
+    verbose_name = "MCP SQL"
+    default_auto_field = "django.db.models.BigAutoField"
+
+    def ready(self):
+        self.validate_settings()
+        self.warn_if_mfa_unconfigured()
+        # Importing the module wires its @receiver-decorated handlers.
+        from mcp_sql import signals  # noqa: F401
+
+    @staticmethod
+    def validate_settings():
+        from django.conf import settings
+
+        from mcp_sql.validation import validate_mcp_sql_settings
+
+        validate_mcp_sql_settings(settings.MCP_SQL)
+
+    @staticmethod
+    def warn_if_mfa_unconfigured():
+        """Loudly flag the fail-closed default MFA checker at startup.
+
+        The in-package default (`deny_unconfigured_mfa`) denies every
+        MFA-gated decision, so a consumer who never set
+        `MCP_SQL["MFA_CHECKER"]` would find the whole MCP surface
+        inaccessible. That's the safe failure (fail-closed), but a silent
+        one is mystifying — emit one WARNING per process so the cause is
+        obvious in logs.
+        """
+        import logging
+
+        from mcp_sql.conf import deny_unconfigured_mfa
+        from mcp_sql.conf import mcp_sql_settings
+
+        if mcp_sql_settings.MFA_CHECKER is deny_unconfigured_mfa:
+            logging.getLogger("mcp_sql").warning(
+                "MCP SQL is using the fail-closed default MFA checker "
+                "(deny_unconfigured_mfa): every MFA-gated decision will be "
+                "DENIED until MCP_SQL['MFA_CHECKER'] is set to a real check "
+                "(django-allauth projects use 'allauth.mfa.utils.is_mfa_enabled')."
+            )