feat: add graceful shutdown handling

[kocaemre]

Summary

• Add ENABLE_GRACEFUL_SHUTDOWN and SHUTDOWN_TIMEOUT_SECONDS settings.
• Add a GracefulShutdownManager that runs registered cleanup callbacks with timeout protection.
• Register SIGINT/SIGTERM handlers when the feature flag is enabled.
• Treat already-closed resource errors as DEBUG-level shutdown noise.
• Document the new configuration in .env.example and README.md.

Why

Production deployments need bounded cleanup during SIGINT/SIGTERM so resource shutdown can be coordinated without noisy already-closed-resource logs.

Closes #44.

Test plan

• Added regression/unit tests and confirmed RED collection failure before implementation (ModuleNotFoundError: No module named 'template_mcp_server.utils.graceful_shutdown').
• uv run --python 3.12 python -m pytest tests/test_graceful_shutdown.py -q — 6 passed
• uv run --python 3.12 python -m pytest tests/test_main.py tests/test_settings.py tests/test_graceful_shutdown.py -q — 44 passed, 1 existing warning
• uv run --python 3.12 python -m pytest tests -q — 311 passed, 1 skipped, 1 existing warning
• uv run --python 3.12 ruff check template_mcp_server tests/test_graceful_shutdown.py tests/test_main.py tests/test_settings.py — passed
• uv run --python 3.12 python -m py_compile template_mcp_server/utils/graceful_shutdown.py template_mcp_server/src/main.py template_mcp_server/src/settings.py tests/test_graceful_shutdown.py
• README/.env feature flag assertion script
• git diff --check

[Copilot]

Pull request overview

Adds an opt-in (default enabled) “graceful shutdown” feature that is intended to coordinate bounded cleanup on SIGINT/SIGTERM, backed by new settings and documentation updates.

Changes:

• Introduces GracefulShutdownManager plus register_graceful_shutdown() for signal-driven shutdown coordination with timeout protection.
• Adds ENABLE_GRACEFUL_SHUTDOWN and SHUTDOWN_TIMEOUT_SECONDS to settings and documents them in .env.example and README.md.
• Adds unit tests covering manager behavior, timeout enforcement, and signal handler registration.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/test_graceful_shutdown.py	Adds unit tests for the shutdown manager and signal registration behavior.
template_mcp_server/utils/graceful_shutdown.py	Implements the shutdown manager and signal handler registration helper.
template_mcp_server/src/settings.py	Adds new env-backed settings for enabling graceful shutdown and configuring timeout.
template_mcp_server/src/main.py	Instantiates/registers the shutdown manager during server startup.
README.md	Documents the new configuration flags in the environment variable table.
.env.example	Adds example values for the new shutdown configuration flags.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.