stackdoctor 0.1.0__tar.gz → 0.1.2__tar.gz

{stackdoctor-0.1.0 → stackdoctor-0.1.2}/.github/workflows/release.yml

@@ -1,7 +1,7 @@
 name: release
 
 # Publishes to PyPI with trusted publishing (OIDC), no API token.
-# Triggered by pushing a version tag that matches pyproject.toml, e.g. `git tag v0.1.0 && git push origin v0.1.0`.
+# Triggered by pushing a version tag that matches pyproject.toml: git tag "v$(uv version --short)" && git push origin --tags
 
 on:
   push:

{stackdoctor-0.1.0 → stackdoctor-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: stackdoctor
-Version: 0.1.0
+Version: 0.1.2
 Summary: Read-only MCP server that diagnoses a Python backend stack (Postgres, Celery, Redis, logs) with cross-system correlation.
 Project-URL: Homepage, https://github.com/lepri89/stackdoctor
 Project-URL: Issues, https://github.com/lepri89/stackdoctor/issues
@@ -20,6 +20,7 @@ Description-Content-Type: text/markdown
 
 [![tests](https://github.com/lepri89/stackdoctor/actions/workflows/tests.yml/badge.svg)](https://github.com/lepri89/stackdoctor/actions/workflows/tests.yml)
 [![demo](https://github.com/lepri89/stackdoctor/actions/workflows/demo.yml/badge.svg)](https://github.com/lepri89/stackdoctor/actions/workflows/demo.yml)
+[![PyPI](https://img.shields.io/pypi/v/stackdoctor)](https://pypi.org/project/stackdoctor/)
 ![python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 
@@ -60,20 +61,23 @@ curl -LsSf https://astral.sh/uv/install.sh | sh                          # macOS
 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"                # Windows
 ```
 
-Then one command runs the server, with no other install step:
+Then either run it straight from [PyPI](https://pypi.org/project/stackdoctor/) or install it once:
 
 ```sh
-uvx stackdoctor
+uvx stackdoctor                  # runs the latest release, nothing to install
+uv tool install stackdoctor      # or install it; the command is then `stackdoctor`
 ```
 
-Until the package is on PyPI, run it from a checkout with `uvx --from /path/to/stackdoctor stackdoctor`,
-or from git with `uvx --from git+https://github.com/lepri89/stackdoctor stackdoctor`.
+You don't normally run it by hand: your MCP client starts it (see [Configure](#configure)).
+To check that it works, run `uvx stackdoctor --help`, which prints usage and the configuration
+variables. To upgrade, use `uvx stackdoctor@latest` or `uv tool upgrade stackdoctor`.
 
 > **macOS 12 (Monterey):** `uvx stackdoctor` fails with `realpath: command not found`, because uv's
 > launcher script needs `realpath`, which only ships with macOS 13+. Use
 > `uvx --from stackdoctor python -m stackdoctor` instead. In client configs that means
-> `"args": ["--from", "stackdoctor", "python", "-m", "stackdoctor"]`. Alternatively, run
-> `uv tool install stackdoctor` once and use `stackdoctor` as the command.
+> `"args": ["--from", "stackdoctor", "python", "-m", "stackdoctor"]`. Alternatively, use
+> `uv tool install stackdoctor` and set the command to the full path of the installed tool,
+> `/Users/<username>/.local/bin/stackdoctor`. Its launcher doesn't need `realpath`.
 
 ## Configure
 
@@ -317,7 +321,9 @@ in WSL2 and run the `.ps1` scripts from PowerShell.
 ## Development
 
 ```sh
+git clone https://github.com/lepri89/stackdoctor && cd stackdoctor
 uv sync
+uv run stackdoctor --help                       # run from the checkout
 uv run pytest                                   # unit tests (safety layer, diagnose, logs)
 STACKDOCTOR_TEST_DATABASE_URL=postgresql://shop:shop@localhost:55432/shop \
 STACKDOCTOR_TEST_REDIS_URL=redis://localhost:56379/0 \
@@ -333,7 +339,7 @@ Releases go to PyPI from GitHub Actions with
    `lepri89`, repository `stackdoctor`, workflow `release.yml` and environment `pypi`. In GitHub, create
    an environment named `pypi` (Settings → Environments); adding yourself as a required reviewer is a good idea.
 2. Bump `version` in `pyproject.toml`, commit, then tag and push:
-   `git tag v0.1.0 && git push origin v0.1.0`.
+   `git tag "v$(uv version --short)" && git push origin "v$(uv version --short)"`.
    The workflow checks that the tag matches the version, runs the tests, builds, and publishes.
 
 ## License

{stackdoctor-0.1.0 → stackdoctor-0.1.2}/README.md

@@ -2,6 +2,7 @@
 
 [![tests](https://github.com/lepri89/stackdoctor/actions/workflows/tests.yml/badge.svg)](https://github.com/lepri89/stackdoctor/actions/workflows/tests.yml)
 [![demo](https://github.com/lepri89/stackdoctor/actions/workflows/demo.yml/badge.svg)](https://github.com/lepri89/stackdoctor/actions/workflows/demo.yml)
+[![PyPI](https://img.shields.io/pypi/v/stackdoctor)](https://pypi.org/project/stackdoctor/)
 ![python](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13-blue)
 ![license](https://img.shields.io/badge/license-MIT-green)
 
@@ -42,20 +43,23 @@ curl -LsSf https://astral.sh/uv/install.sh | sh                          # macOS
 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"                # Windows
 ```
 
-Then one command runs the server, with no other install step:
+Then either run it straight from [PyPI](https://pypi.org/project/stackdoctor/) or install it once:
 
 ```sh
-uvx stackdoctor
+uvx stackdoctor                  # runs the latest release, nothing to install
+uv tool install stackdoctor      # or install it; the command is then `stackdoctor`
 ```
 
-Until the package is on PyPI, run it from a checkout with `uvx --from /path/to/stackdoctor stackdoctor`,
-or from git with `uvx --from git+https://github.com/lepri89/stackdoctor stackdoctor`.
+You don't normally run it by hand: your MCP client starts it (see [Configure](#configure)).
+To check that it works, run `uvx stackdoctor --help`, which prints usage and the configuration
+variables. To upgrade, use `uvx stackdoctor@latest` or `uv tool upgrade stackdoctor`.
 
 > **macOS 12 (Monterey):** `uvx stackdoctor` fails with `realpath: command not found`, because uv's
 > launcher script needs `realpath`, which only ships with macOS 13+. Use
 > `uvx --from stackdoctor python -m stackdoctor` instead. In client configs that means
-> `"args": ["--from", "stackdoctor", "python", "-m", "stackdoctor"]`. Alternatively, run
-> `uv tool install stackdoctor` once and use `stackdoctor` as the command.
+> `"args": ["--from", "stackdoctor", "python", "-m", "stackdoctor"]`. Alternatively, use
+> `uv tool install stackdoctor` and set the command to the full path of the installed tool,
+> `/Users/<username>/.local/bin/stackdoctor`. Its launcher doesn't need `realpath`.
 
 ## Configure
 
@@ -299,7 +303,9 @@ in WSL2 and run the `.ps1` scripts from PowerShell.
 ## Development
 
 ```sh
+git clone https://github.com/lepri89/stackdoctor && cd stackdoctor
 uv sync
+uv run stackdoctor --help                       # run from the checkout
 uv run pytest                                   # unit tests (safety layer, diagnose, logs)
 STACKDOCTOR_TEST_DATABASE_URL=postgresql://shop:shop@localhost:55432/shop \
 STACKDOCTOR_TEST_REDIS_URL=redis://localhost:56379/0 \
@@ -315,7 +321,7 @@ Releases go to PyPI from GitHub Actions with
    `lepri89`, repository `stackdoctor`, workflow `release.yml` and environment `pypi`. In GitHub, create
    an environment named `pypi` (Settings → Environments); adding yourself as a required reviewer is a good idea.
 2. Bump `version` in `pyproject.toml`, commit, then tag and push:
-   `git tag v0.1.0 && git push origin v0.1.0`.
+   `git tag "v$(uv version --short)" && git push origin "v$(uv version --short)"`.
    The workflow checks that the tag matches the version, runs the tests, builds, and publishes.
 
 ## License

{stackdoctor-0.1.0 → stackdoctor-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackdoctor"
-version = "0.1.0"
+version = "0.1.2"
 description = "Read-only MCP server that diagnoses a Python backend stack (Postgres, Celery, Redis, logs) with cross-system correlation."
 readme = "README.md"
 license = { text = "MIT" }

stackdoctor-0.1.2/stackdoctor/__init__.py

@@ -0,0 +1,9 @@
+"""stackdoctor: read-only MCP server that diagnoses a Python backend stack."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    # pyproject.toml is the single source of truth; this reads the installed package's metadata.
+    __version__ = version("stackdoctor")
+except PackageNotFoundError:  # running from a source tree that isn't installed
+    __version__ = "0.0.0+unknown"

{stackdoctor-0.1.0 → stackdoctor-0.1.2}/stackdoctor/server.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import argparse
 import functools
 import inspect
 import logging
@@ -10,6 +11,7 @@ import sys
 from mcp.server.mcpserver import MCPServer
 from mcp.types import ToolAnnotations
 
+from . import __version__
 from . import diagnose as diag
 from .checks import celery, logs, postgres, redis
 from .config import get_config
@@ -154,7 +156,34 @@ def search_logs(pattern: str, since_minutes: int = 30, source: str | None = None
     return logs.search_logs(pattern, since_minutes, source)
 
 
-def main() -> None:
+USAGE_EPILOG = """\
+MCP clients (Claude Desktop, Claude Code, Cursor, VS Code) start this server themselves.
+Running it by hand starts an MCP server on stdin/stdout that waits for a client.
+
+configuration (environment variables or a .env file; unset sources are skipped):
+  DATABASE_URL           Postgres, e.g. postgresql://stackdoctor_ro:...@localhost:5432/app
+  REDIS_URL              Redis, e.g. redis://localhost:6379/0
+  CELERY_BROKER_URL      Celery broker (Redis; RabbitMQ is experimental)
+  CELERY_RESULT_BACKEND  Redis result backend, for failed tasks
+  CELERY_APP             optional import path of your Celery app, e.g. myproject.celery:app
+  LOG_SOURCES            comma-separated log files and/or docker:<container>
+  STACKDOCTOR_ENV_FILE   path to a .env file (default: .env in the working directory)
+
+docs: https://github.com/lepri89/stackdoctor
+"""
+
+
+def main(argv: list[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="stackdoctor",
+        description="Read-only MCP server that diagnoses a Python backend stack "
+                    "(Postgres, Celery, Redis, logs).",
+        epilog=USAGE_EPILOG,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"stackdoctor {__version__}")
+    parser.parse_args(argv)  # --help / --version print and exit here
+
     logging.basicConfig(level=logging.WARNING, stream=sys.stderr)  # stdout is the MCP channel
     get_config()
     mcp.run("stdio")

stackdoctor-0.1.2/tests/test_cli.py

@@ -0,0 +1,47 @@
+import pytest
+
+from stackdoctor import server
+
+
+@pytest.mark.parametrize("flag,expected", [("--help", "usage: stackdoctor"), ("--version", "stackdoctor ")])
+def test_flags_print_and_exit_without_starting_server(flag, expected, capsys, monkeypatch):
+    monkeypatch.setattr(server.mcp, "run", lambda *a, **k: pytest.fail("server must not start"))
+    with pytest.raises(SystemExit) as exit_info:
+        server.main([flag])
+    assert exit_info.value.code == 0
+    assert expected in capsys.readouterr().out
+
+
+def test_unknown_flag_is_an_error(monkeypatch):
+    monkeypatch.setattr(server.mcp, "run", lambda *a, **k: pytest.fail("server must not start"))
+    with pytest.raises(SystemExit) as exit_info:
+        server.main(["--nope"])
+    assert exit_info.value.code == 2
+
+
+def test_version_matches_pyproject(capsys):
+    """pyproject.toml is the single source of truth for the version."""
+    import tomllib
+    from pathlib import Path
+
+    pyproject = tomllib.loads((Path(__file__).parents[1] / "pyproject.toml").read_text())
+    with pytest.raises(SystemExit):
+        server.main(["--version"])
+    assert capsys.readouterr().out.strip() == f"stackdoctor {pyproject['project']['version']}"
+
+
+def test_version_fallback_when_not_installed(monkeypatch):
+    import importlib
+    import importlib.metadata
+
+    import stackdoctor
+
+    def missing(name):
+        raise importlib.metadata.PackageNotFoundError(name)
+
+    monkeypatch.setattr(importlib.metadata, "version", missing)
+    try:
+        assert importlib.reload(stackdoctor).__version__ == "0.0.0+unknown"
+    finally:
+        monkeypatch.undo()
+        importlib.reload(stackdoctor)

{stackdoctor-0.1.0 → stackdoctor-0.1.2}/uv.lock

@@ -1003,7 +1003,7 @@ wheels = [
 
 [[package]]
 name = "stackdoctor"
-version = "0.1.0"
+version = "0.1.2"
 source = { editable = "." }
 dependencies = [
     { name = "celery" },