{
"markdown": "# django-chainsaw-mcp\n\n\n\n\n\n\n\n\n\n\n\n\n\n**An MCP server and CLI that analyses a Django project rather than describing\nit.** Not *what is in here* — *what will hurt*: what a delete takes with it,\nwhich migration breaks the pods still running, which query returns another\ntenant's row, what a `save()` sets off three hops away.\n\nThere is **no model in the loop**. Every answer comes from the AST and Django's\nown app registry, so the same input gives the same output, and nothing leaves\nthe machine. It is an MCP server so an assistant can ask it questions, and a CLI\nso CI can gate on the answers.\n\n22 checks: 19 need the app registry (16 Django, three of those DRF as well), one\nneeds only Python, one reads FastAPI, one reads SQLAlchemy.\n**[Why this exists →](docs/why.md)**\n\n## Install\n\n**It has to run in an interpreter that can import your project.** Everything\nhere reads the app registry, which means `django.setup()`, your settings and\nyour apps:\n\n```bash\n/path/to/project/.venv/bin/python -m pip install django-chainsaw-mcp\n```\n\nA plain `uvx django-chainsaw-mcp` starts and then fails every check, because\n`uvx` gives it an isolated environment with no trace of your project. To avoid\ninstalling, hand `uv` the dependencies instead:\n\n```bash\nuvx --with-requirements requirements.txt --from django-chainsaw-mcp django-chainsaw check\n```\n\nTwo environment variables point it at the project:\n\n| Variable | Example |\n| --- | --- |\n| `DJANGO_CHAINSAW_PROJECT_PATH` | `/srv/app` — the directory settings are importable **from** |\n| `DJANGO_CHAINSAW_SETTINGS_MODULE` | `myproject.settings` |\n\n`django-chainsaw project-info` proves the setup before anything else, and says\nwhich half is missing. **[Five minutes end to end →](docs/quickstart.md)**\n\nmcp-name: io.github.syrian963/django-chainsaw-mcp\n\n## One command\n\n```bash\ndjango-chainsaw check --tenant-root myapp.Organisation\n```\n\n```\n44 finding(s): 1 critical, 14 high, 29 medium\n\nCRITICAL\n--------\n [deploy-safety] RemoveField drops 'legacy_code' while code still uses it\n shop/0002_remove_product_legacy_code\n During a rolling deploy the old pods keep running against the new\n schema and will fail.\n fix: Ship a release that stops using it, deploy that everywhere,\n then ship this migration.\n```\n\nEvery analysis, merged, worst first, one exit code.\n\n## On a pull request\n\nThis is the part that decides whether a tool like this survives. Point `tenancy`\nat a five year old project and it returns two hundred candidates; nobody reads\ntwo hundred candidates, somebody adds `continue-on-error`, and it runs forever\nwith nobody looking.\n\n```bash\ndjango-chainsaw tenancy --since main # only what this branch changed\ndjango-chainsaw tenancy --baseline # everything old, ratcheted\ndjango-chainsaw check --sarif out.json # annotate the diff, on the line\n```\n\n`--since` compares at the **merge base**, so a branch that is behind main is not\nblamed for other people's work. `--baseline` keeps existing findings in the\nreport and stops them blocking; anything new fails the build, and fixing an old\none is reported so the number only ever goes down. Findings are fingerprinted on\nfile plus identity, never the line, so adding an import does not resurrect\ntwenty findings nobody touched.\n\n`--sarif` writes the format GitHub and GitLab annotate a pull request with, so\nfindings land **on the line** instead of in a log nobody opens.\n\n**[baseline.md](docs/baseline.md)** · **[cli.md](docs/cli.md)**\n\n## As an MCP server\n\n```bash\nclaude mcp add django-chainsaw --scope local \\\n --env DJANGO_CHAINSAW_PROJECT_PATH=/srv/app \\\n --env DJANGO_CHAINSAW_SETTINGS_MODULE=myproject.settings \\\n -- /srv/app/.venv/bin/python -m django_chainsaw_mcp.server\n```\n\nAsk it `project_info` first: the smallest call that proves both the transport\nand the Django boot. Five prompts carry the ordering the tools do not —\n`before_deploy`, `why_is_this_slow`, `what_breaks_if_i_delete`, `triage`,\n`review_this_branch`.\n\n**[Claude Desktop, Cursor, VS Code, Windsurf, Zed, Docker →](docs/clients.md)**\n\n## Or as one HTML file\n\n```bash\ndjango-chainsaw report --out findings.html --title myproject\n```\n\n\n\nGrouped by **endpoint** is the view that matters: which pages carry this, and\nthrough what call path. No server, no network, no build step — the CSS, the\nscript and the data are all in the file, so it works from a CI artifact or an\nemail attachment. **[report.md](docs/report.md)**\n\n## The checks\n\n\nDjango projects — these read the app registry, so they need DJANGO_CHAINSAW_SETTINGS_MODULE as well as the project path
\n\n| Tool | Answers |\n| --- | --- |\n| `project_info` | Does the target project load at all? Run this first when something is broken. |\n| `list_models` | Every model with fields, relation kind, direction and `on_delete`. |\n| `delete_impact` | Delete one row: what cascades, what blocks, what gets nulled. Transitive. |\n| `find_n_plus_one` | Relation traversals in a template that each cost a query, and the fix. |\n| `scan_templates` | The same across a directory, resolving context from views. |\n| `migration_risk` | Migrations rated: blocks writes, rewrites the table, breaks running code. |\n| `deploy_safety` | **Is this destructive migration safe to ship yet?** |\n| `find_unscoped_queries` | **Which queries read data the caller may not own?** The IDOR shape. |\n| `what_happens_on` | **What does this save actually trigger?** Follows the signal chain. |\n| `missing_indexes` | Fields the code filters or sorts on that carry no index. |\n| `datetime_audit` | Naive datetimes and field defaults that break when the clock moves. |\n| `serializer_exposure` | What DRF serializers expose, including what the next migration will add. |\n| `serializer_nplusone` | N+1 in DRF serializers, which is where it lives in an API project. |\n| `explain_model` | **Everything about one model, plus the risks only visible combined.** |\n| `endpoint_cost` | How many queries one request costs, before anybody sends one. |\n| `api_contract` / `api_contract_check` | What this branch changes about the API, and who it breaks. |\n| `escaping_side_effects` | Mail and tasks fired inside a transaction that can still roll back. |\n| `bypassed_effects` | Bulk writes that skip everything the `save()` chain promised. |\n| `race_conditions` | Counters read into Python, changed, and saved. Also unsafe upserts. |\n| `money_precision` | **Where a decimal amount stops being exact.** |\n| `celery_arguments` | **What the worker actually receives**, and whether it can even be called. |\n| `queries_in_loops` | Queries written inside a loop, split by which of three fixes applies. |\n| `defeated_prefetches` | Prefetches paid for and then re-queried by the accessor that reads them. |\n| `request_impact` | Every finding grouped by the entry points that reach it, so the question becomes which endpoint to fix. |\n| `choice_typos` | Literals a field's `choices` will never match: valid SQL, zero rows, no exception. |\n| `multiplied_aggregates` | Counts and sums multiplied by a join across two multi-valued relations. |\n| `dangling_references` | URL names, templates, signal senders and Celery tasks nothing will resolve. |\n| `open_endpoints` | Sensitive fields on endpoints anybody can call. |\n| `unused_eager_loading` | Joins and prefetches nothing in the response reads. |\n| `check` | Run everything that applies, one severity-sorted list, one exit code. |\n| `suggest_fixes` | **Findings turned into code, grouped by how safe each one is to apply.** |\n\n \n\n\nAny Python project — no Django, no settings module
\n\n| Tool | Answers |\n| --- | --- |\n| `project_profile` | What is this built on? Counted from the project's own imports. |\n| `blocking_in_async` | **Which synchronous call stops the event loop for every request?** |\n| `fastapi_exposure` | Endpoints that serialise more than they declare. |\n| `sqlalchemy_nplusone` | Relationships loaded one row at a time, including during serialisation. |\n| `amplification` | **Which endpoint can a stranger use to exhaust the database?** |\n\nPlus the resource `django://models`. `check` profiles the project first and runs\nwhat applies, and says **\"does not apply, and here is why\"** for the rest —\nsilence would read exactly like a clean result. Nothing about the FastAPI\nsupport imports the project, so those checks run on a checkout with no\ndependencies installed at all.\n\n \n\n36 of the 37 tools declare `readOnlyHint`, so a client can stop asking\npermission for each call; the exception is `api_contract_check` with\n`update=True`, which writes the snapshot and says so.\n**[Every tool, argument and output shape →](docs/tools.md)**\n\n## What it will not tell you\n\nNothing here executes the target project or reads its data, which buys safety\nand speed and costs certainty. Every tool states its own blind spots in its own\noutput:\n\n- `delete_impact` does not run signals or custom `delete()` overrides.\n- `find_n_plus_one` reports **candidates**; it reads the template and the model\n graph, not the queryset in the view.\n- `migration_risk` does not know row counts, PostgreSQL version, or deploy\n strategy.\n- `deploy_safety` cannot see `getattr(obj, name)`, runtime SQL, or another\n repository. `CLEAR` means nothing was found **here**.\n\n**A confident wrong answer is worse than an incomplete one.** In this kind of\ntooling the failure mode is not a crash, it is a plausible sentence that sends\nsomeone in the wrong direction. **[limitations.md](docs/limitations.md)**\n\n## What it does to your code\n\n**It imports the target project.** `django.setup()` imports your settings and\nevery app in `INSTALLED_APPS`, and the checks additionally import the modules\nthat declare serializers, views and URLs — so anything those do at import time\nhappens. **Do not point this at code you would not run.**\n\n**It does not run your application**: no view, no task, no management command.\n**One check reads the database, read-only** — `MigrationLoader` reads\n`django_migrations`, and nothing is written.\n**It writes files only when you ask**: `fix --write` applies the mechanical\nclass of fix only, and a baseline, a contract snapshot or `--sarif` write where\nyou tell them to. **Nothing leaves the machine** — no network calls, no\ntelemetry, no uploads.\n\n**[SECURITY.md](SECURITY.md)**\n\n## Documentation\n\n**[docs/](docs/README.md) is the index.**\n\n| | |\n| --- | --- |\n| [`why.md`](docs/why.md) | why this exists, three checks worth reading about, and the bar a new one clears |\n| [`quickstart.md`](docs/quickstart.md) | five minutes from clone to first finding |\n| [`usage.md`](docs/usage.md) | installing against a real project, Docker, troubleshooting |\n| [`clients.md`](docs/clients.md) | Claude Code, Cursor, VS Code, Windsurf, Zed |\n| [`cli.md`](docs/cli.md) | commands, exit codes, CI |\n| [`tools.md`](docs/tools.md) | every tool, argument and output shape |\n| [`tested-against.md`](docs/tested-against.md) | eighteen public projects, what they found in this tool, and the checks that never fired |\n| [`limitations.md`](docs/limitations.md) | what the analysis cannot see |\n| [`baseline.md`](docs/baseline.md) | ratcheting, so this survives a legacy codebase |\n| [`fixes.md`](docs/fixes.md) | suggestions as real code, and which can be applied |\n| [`architecture.md`](docs/architecture.md) | how it is put together, and why the bootstrap drives the design |\n| [`performance.md`](docs/performance.md) | where the time goes on a large project |\n\n## Contributing\n\n| | |\n| --- | --- |\n| [`CONTRIBUTING.md`](CONTRIBUTING.md) | workflow, house style, how to run the suites |\n| [`CHANGELOG.md`](CHANGELOG.md) | every release, and the reasoning behind the changes |\n| [`SECURITY.md`](SECURITY.md) | what this does to the code you point it at |\n| [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md) | be straight with people and be kind about it |\n\nA proposal for a new check answers four questions, which the\n[issue template](.github/ISSUE_TEMPLATE/new_check.yml) asks directly: what the\ndefect looks like as code, how it fails in production, what already finds it,\nand what it must stay silent on. Two finished features were deleted from this\nrepository after measurement showed they could not tell a real finding from a\ncorrect one.\n\nMIT. One process stays bound to the first project it loads, because\n`django.setup()` cannot be undone — run a second instance for a second project.\n",
"bytes": 13581,
"sha": "e112092f2773467bcea41200c7ac4ef90bb16a9d480c91d1f296d4b39e52d77a",
"repo_slug": "syrian963/django-chainsaw-mcp",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_syrian963_django_chainsaw_mcp_9e430ad2/readme"
}