Add standalone CLI (#13)

Author: joshuadavidthomas

CHANGELOG.md

@@ -18,6 +18,14 @@ and this project attempts to adhere to [Semantic Versioning](https://semver.org/
 
 ## [Unreleased]
 
+### Added
+
+- Standalone CLI via `python -m mcp_django_shell`.
+
+### Deprecated
+
+- Soft-deprecation of the management command `manage.py mcp_shell`. It's now just a wrapper around the CLI, so there's no harm in keeping it, but the recommended usage will be the standalone CLI going forward.
+
 ## [0.3.1]
 
 ### Removed

README.md

@@ -47,7 +47,7 @@ cog.outl(f"- Django {', '.join([version for version in DJ_VERSIONS if version !=
     uv sync
     ```
 
-2. Add to your Django project's `INSTALLED_APPS`:
+2. (Optional) Add to your Django project's `INSTALLED_APPS` if you want to use the management command:
 
    ```python
    DEBUG = ...
@@ -56,6 +56,8 @@ cog.outl(f"- Django {', '.join([version for version in DJ_VERSIONS if version !=
        INSTALLED_APPS.append("mcp_django_shell")
    ```
 
+   **Note**: You can now run mcp-django-shell without adding it to `INSTALLED_APPS` by using `python -m mcp_django_shell` directly. [See below](#getting-started) for more info.
+
 > [!WARNING]
 >
 > **Only enable in development!** 
@@ -64,7 +66,35 @@ cog.outl(f"- Django {', '.join([version for version in DJ_VERSIONS if version !=
 
 ## Getting Started
 
-mcp-django-shell provides a Django management command that MCP clients can connect to. Configure your client using one of the examples below.
+Run the MCP server directly from your Django project directory:
+
+```bash
+python -m mcp_django_shell
+
+# With explicit settings module
+python -m mcp_django_shell --settings myproject.settings
+
+# With debug logging
+python -m mcp_django_shell --debug
+```
+
+Or using uv:
+
+```bash
+uv run -m mcp_django_shell
+```
+
+The server automatically detects `DJANGO_SETTINGS_MODULE` from your environment. You can override it with `--settings` or add to your Python path with `--pythonpath`.
+
+There's also a Django management command if you prefer, but that requires adding mcp-django-shell to `INSTALLED_APPS`:
+
+```bash
+python manage.py mcp_shell
+```
+
+### Client Configuration
+
+Configure your MCP client using one of the examples below. The command is the same for all clients, just expressed in annoyingly different JSON soup.
 
 Don't see your client? [Submit a PR](CONTRIBUTING.md) with setup instructions.
 
@@ -75,8 +105,11 @@ Don't see your client? [Submit a PR](CONTRIBUTING.md) with setup instructions.
   "mcpServers": {
     "django_shell": {
       "command": "python",
-      "args": ["manage.py", "mcp_shell"],
-      "cwd": "/path/to/your/django/project"
+      "args": ["-m", "mcp_django_shell"],
+      "cwd": "/path/to/your/django/project",
+      "env": {
+        "DJANGO_SETTINGS_MODULE": "myproject.settings"
+      }
     }
   }
 }
@@ -90,8 +123,11 @@ Don't see your client? [Submit a PR](CONTRIBUTING.md) with setup instructions.
   "mcp": {
     "django_shell": {
       "type": "local",
-      "command": ["python", "manage.py", "mcp_shell"],
-      "enabled": true
+      "command": ["python", "-m", "mcp_django_shell"],
+      "enabled": true,
+      "environment": {
+        "DJANGO_SETTINGS_MODULE": "myproject.settings"
+      }
     }
   }
 }

pyproject.toml

@@ -110,6 +110,8 @@ fail_under = 100
 omit = [
   "src/mcp_django_shell/management/commands/mcp_shell.py",
   "src/mcp_django_shell/migrations/*",
+  "src/mcp_django_shell/__main__.py",
+  "src/mcp_django_shell/_typing.py",
   "tests/*"
 ]
 source = ["src/mcp_django_shell"]

src/mcp_django_shell/__main__.py

@@ -0,0 +1,6 @@
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

src/mcp_django_shell/_typing.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+import sys
+
+if sys.version_info >= (3, 12):
+    from typing import override as typing_override
+else:
+    from typing_extensions import (
+        override as typing_override,  # pyright: ignore[reportUnreachable]
+    )
+
+override = typing_override

src/mcp_django_shell/cli.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import argparse
+import logging
+import os
+import signal
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Run the MCP Django Shell server")
+    parser.add_argument(
+        "--settings",
+        help="Django settings module (overrides DJANGO_SETTINGS_MODULE env var)",
+    )
+    parser.add_argument(
+        "--pythonpath",
+        help="Python path to add for Django project imports",
+    )
+    parser.add_argument(
+        "--debug",
+        action="store_true",
+        help="Enable debug logging",
+    )
+    args = parser.parse_args(argv)
+
+    debug: bool = args.debug
+    settings: str | None = args.settings
+    pythonpath: str | None = args.pythonpath
+
+    if debug:
+        logging.basicConfig(
+            level=logging.DEBUG,
+            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
+        )
+        logger.debug("Debug logging enabled")
+
+    if settings:
+        os.environ["DJANGO_SETTINGS_MODULE"] = settings
+
+    if pythonpath:
+        sys.path.insert(0, pythonpath)
+
+    django_settings = os.environ.get("DJANGO_SETTINGS_MODULE")
+    if not django_settings:
+        logger.error(
+            "DJANGO_SETTINGS_MODULE not set. Use --settings or set environment variable."
+        )
+        return 1
+
+    logger.info("Starting MCP Django Shell server")
+    logger.debug("Django settings module: %s", django_settings)
+
+    def signal_handler(signum: int, _frame: Any):  # pragma: no cover
+        logger.info("Received signal %s, shutting down MCP server", signum)
+        sys.exit(0)
+
+    signal.signal(signal.SIGINT, signal_handler)
+    signal.signal(signal.SIGTERM, signal_handler)
+
+    try:
+        logger.info("MCP server ready and listening")
+
+        from .server import mcp
+
+        mcp.run()
+
+    except Exception as e:
+        logger.error("MCP server crashed: %s", e, exc_info=True)
+        return 1
+
+    finally:
+        logger.info("MCP Django Shell server stopped")
+
+    return 0

src/mcp_django_shell/management/commands/mcp_shell.py

@@ -1,59 +1,31 @@
 from __future__ import annotations
 
-import logging
-import os
-import signal
-import sys
+from argparse import ArgumentParser
 from typing import Any
+from typing import final
 
 from django.core.management.base import BaseCommand
 
-from mcp_django_shell.server import mcp
-
-logger = logging.getLogger(__name__)
+from mcp_django_shell._typing import override
+from mcp_django_shell.cli import main
 
 
+@final
 class Command(BaseCommand):
     help = "Run the MCP Django Shell server"
 
-    def add_arguments(self, parser):
+    @override
+    def add_arguments(self, parser: ArgumentParser) -> None:
         parser.add_argument(
             "--debug",
             action="store_true",
             help="Enable debug logging",
         )
 
-    def handle(self, *args: Any, **options: Any):
+    @override
+    def handle(self, *args: Any, **options: Any) -> str | None:
+        argv: list[str] = []
         if options.get("debug"):
-            logging.basicConfig(
-                level=logging.DEBUG,
-                format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
-            )
-            logger.debug("Debug logging enabled")
-
-        logger.info("Starting MCP Django Shell server")
-        logger.debug(
-            "Django settings module: %s",
-            os.environ.get("DJANGO_SETTINGS_MODULE", "Not set"),
-        )
-
-        def signal_handler(signum, frame):
-            logger.info("Received signal %s, shutting down MCP server", signum)
-
-            sys.exit(0)
-
-        signal.signal(signal.SIGINT, signal_handler)
-        signal.signal(signal.SIGTERM, signal_handler)
-
-        try:
-            logger.info("MCP server ready and listening")
-
-            mcp.run()
-
-        except Exception as e:
-            logger.error("MCP server crashed: %s", e, exc_info=True)
-
-            raise
+            argv.append("--debug")
 
-        finally:
-            logger.info("MCP Django Shell server stopped")
+        return str(main(argv))

tests/test_cli.py

@@ -0,0 +1,64 @@
+from __future__ import annotations
+
+import os
+import sys
+from unittest.mock import Mock
+
+from mcp_django_shell.cli import main
+
+
+def test_cli_no_django_settings(monkeypatch, caplog):
+    monkeypatch.delenv("DJANGO_SETTINGS_MODULE", raising=False)
+
+    result = main([])
+
+    assert result == 1
+    assert "DJANGO_SETTINGS_MODULE not set" in caplog.text
+
+
+def test_cli_with_settings_arg(monkeypatch):
+    mock_mcp = Mock()
+    monkeypatch.setattr("mcp_django_shell.server.mcp", mock_mcp)
+
+    result = main(["--settings", "myapp.settings"])
+
+    assert os.environ["DJANGO_SETTINGS_MODULE"] == "myapp.settings"
+    mock_mcp.run.assert_called_once()
+    assert result == 0
+
+
+def test_cli_server_crash(monkeypatch, caplog):
+    monkeypatch.setenv("DJANGO_SETTINGS_MODULE", "tests.settings")
+
+    mock_mcp = Mock()
+    mock_mcp.run.side_effect = Exception("Server crashed!")
+    monkeypatch.setattr("mcp_django_shell.server.mcp", mock_mcp)
+
+    result = main([])
+
+    assert result == 1
+    assert "MCP server crashed" in caplog.text
+
+
+def test_cli_with_pythonpath(monkeypatch):
+    monkeypatch.setenv("DJANGO_SETTINGS_MODULE", "tests.settings")
+
+    mock_mcp = Mock()
+    monkeypatch.setattr("mcp_django_shell.server.mcp", mock_mcp)
+
+    test_path = "/test/path"
+    result = main(["--pythonpath", test_path])
+
+    assert test_path in sys.path
+    assert result == 0
+
+
+def test_cli_with_debug(monkeypatch):
+    monkeypatch.setenv("DJANGO_SETTINGS_MODULE", "tests.settings")
+
+    mock_mcp = Mock()
+    monkeypatch.setattr("mcp_django_shell.server.mcp", mock_mcp)
+
+    result = main(["--debug"])
+
+    assert result == 0