feat: Add doctest infrastructure and fix existing doctests (#395)

* feat: Add doctest infrastructure and fix existing doctests

- Fix Alembic env.py context execution to prevent import errors
- Fix wrapper.py environment validation to prevent module-level exit
- Fix JSON-RPC validation doctests with proper exception paths
- Add proper header to create_slug.py

Part of #249 - Phase 1: Infrastructure setup

* Updated everything to use python3 binary instead of python for consistency

Signed-off-by: Mihai Criveti <[email protected]>

---------

Signed-off-by: Mihai Criveti <[email protected]>
Co-authored-by: Mihai Criveti <[email protected]>

Author: manavgup

.github/tools/normalize_special_characters.py

@@ -27,16 +27,16 @@
 Usage examples::
 
     # See which files would change and view a coloured unified diff
-    python normalize_characters.py "**/*.py" --dry-run --diff
+    python3 normalize_characters.py "**/*.py" --dry-run --diff
 
     # Clean the entire project tree, keeping *.bak* backups of changed files
-    python normalize_characters.py . --backup-ext .bak
+    python3 normalize_characters.py . --backup-ext .bak
 
     # Normalise Markdown docs verbosely; ignore the vendor directory
-    python normalize_characters.py "docs/**/*.md" -v -i "vendor/**/*"
+    python3 normalize_characters.py "docs/**/*.md" -v -i "vendor/**/*"
 
     # Process only Python files in src/ directory
-    python normalize_characters.py "src/**/*.py" --verbose
+    python3 normalize_characters.py "src/**/*.py" --verbose
 
 Exit codes:
 

.github/workflows/lint.yml

@@ -116,7 +116,7 @@ jobs:
       # -----------------------------------------------------------
       - name: 📦  Install project (editable mode)
         run: |
-          python -m pip install --upgrade pip
+          python3 -m pip install --upgrade pip
           pip install -e .[dev]
 
       # -----------------------------------------------------------

.github/workflows/pytest.yml

@@ -62,7 +62,7 @@ jobs:
       # -----------------------------------------------------------
       - name: 📦 Install dependencies (editable + dev extra)
         run: |
-          python -m pip install --upgrade pip
+          python3 -m pip install --upgrade pip
           # install the project itself in *editable* mode so tests import the same codebase
           # and pull in every dev / test extra declared in pyproject.toml
           pip install -e .[dev]
@@ -82,6 +82,30 @@ jobs:
             --cov-branch \
             --cov-fail-under=40
 
+      # -----------------------------------------------------------
+      # 4️⃣  Run doctests
+      # -----------------------------------------------------------
+      - name: 🧪  Run doctests
+        run: |
+          pytest --doctest-modules mcpgateway/ --tb=short
+
+      # -----------------------------------------------------------
+      # 5️⃣  Doctest coverage check
+      # -----------------------------------------------------------
+      - name: 📊  Doctest coverage validation
+        run: |
+          python3 -c "
+          import subprocess, sys
+          result = subprocess.run(['python', '-m', 'pytest', '--doctest-modules', 'mcpgateway/', '--tb=no', '-q'], capture_output=True)
+          if result.returncode == 0:
+              print('✅ All doctests passing')
+          else:
+              print('❌ Doctest failures detected')
+              print(result.stdout.decode())
+              print(result.stderr.decode())
+              sys.exit(1)
+          "
+
     # -----------------------------------------------------------
     # 4️⃣  Upload coverage artifacts (XML + HTML)
     #       --- keep disabled unless you need them ---
@@ -130,7 +154,7 @@ jobs:
 #         echo "| File | Stmts | Miss | Branch | BrMiss | Cover |" >> "$GITHUB_STEP_SUMMARY"
 #         echo "|------|------:|-----:|-------:|-------:|------:|" >> "$GITHUB_STEP_SUMMARY"
 #         coverage json -q -o cov.json
-#         python - <<'PY'
+#         python3 - <<'PY'
 # import json, pathlib, sys, os
 # data = json.load(open("cov.json"))
 # root = pathlib.Path().resolve()

.pre-commit-config.yaml

@@ -510,3 +510,17 @@ repos:
   #         - mdformat-gfm
   #         - mdformat-tables
   #         - mdformat-black
+
+  # -----------------------------------------------------------------------------
+  # 🧪 DOCTEST VALIDATION
+  # -----------------------------------------------------------------------------
+  - repo: local
+    hooks:
+      - id: doctest
+        name: 🧪 Doctest - Validate Documentation Examples
+        description: Runs doctest on all Python modules to ensure documentation examples work.
+        entry: python3 -m pytest --doctest-modules mcpgateway/ --tb=short
+        language: system
+        pass_filenames: false
+        always_run: true
+        types: [python]

CHANGELOG.md

@@ -67,7 +67,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
   * Expose local stdio MCP servers over SSE endpoints with session management
   * Bridge remote SSE endpoints to local stdio for seamless integration
   * Built-in keepalive mechanisms and unique session identifiers
-  * Full CLI support: `python -m mcpgateway.translate --stdio "uvx mcp-server-git" --port 9000`
+  * Full CLI support: `python3 -m mcpgateway.translate --stdio "uvx mcp-server-git" --port 9000`
 
 * **Tool Annotations & Metadata** - comprehensive tool annotation system:
   * New `annotations` JSON column in tools table for storing rich metadata

DEVELOPING.md

@@ -12,8 +12,8 @@ export MCP_AUTH_TOKEN="<your_bearer_token>"
 | Mode                                                        | Command                                                                      | Notes                                                                         |
 | ----------------------------------------------------------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
 | **SSE (direct)**                                            | `npx @modelcontextprotocol/inspector`                                        | Connects straight to the Gateway's SSE endpoint.                              |
-| **Stdio wrapper** <br/>*(for clients that can't speak SSE)* | `npx @modelcontextprotocol/inspector python -m mcpgateway.wrapper`           | Spins up the wrapper **in-process** and points Inspector to its stdio stream. |
-| **Stdio wrapper via uv / uvx**                            | `npx @modelcontextprotocol/inspector uvx python -m mcpgateway.wrapper` | Uses the lightning-fast `uv` virtual-env if installed.                        |
+| **Stdio wrapper** <br/>*(for clients that can't speak SSE)* | `npx @modelcontextprotocol/inspector python3 -m mcpgateway.wrapper`           | Spins up the wrapper **in-process** and points Inspector to its stdio stream. |
+| **Stdio wrapper via uv / uvx**                            | `npx @modelcontextprotocol/inspector uvx python3 -m mcpgateway.wrapper` | Uses the lightning-fast `uv` virtual-env if installed.                        |
 
 🔍 MCP Inspector boots at **[http://localhost:5173](http://localhost:5173)** - open it in a browser and add:
 

Makefile

@@ -3,7 +3,7 @@
 #   (An enterprise-ready Model Context Protocol Gateway)
 # ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 #
-# Author: Mihai Criveti
+# Authors: Mihai Criveti, Manav Gupta
 # Description: Build & automation helpers for the MCP Gateway project
 # Usage: run `make` or `make help` to view available targets
 #
@@ -182,8 +182,12 @@ clean:
 # help: htmlcov              - (re)build just the HTML coverage report into docs
 # help: test-curl            - Smoke-test API endpoints with curl script
 # help: pytest-examples      - Run README / examples through pytest-examples
+# help: doctest              - Run doctest on all modules with summary report
+# help: doctest-verbose      - Run doctest with detailed output (-v flag)
+# help: doctest-coverage     - Generate coverage report for doctest examples
+# help: doctest-check        - Check doctest coverage percentage (fail if < 100%)
 
-.PHONY: smoketest test coverage pytest-examples test-curl htmlcov
+.PHONY: smoketest test coverage pytest-examples test-curl htmlcov doctest doctest-verbose doctest-coverage doctest-check
 
 ## --- Automated checks --------------------------------------------------------
 smoketest:
@@ -239,6 +243,43 @@ pytest-examples:
 test-curl:
 	./test_endpoints.sh
 
+## --- Doctest targets ---------------------------------------------------------
+doctest:
+	@echo "🧪 Running doctest on all modules..."
+	@test -d "$(VENV_DIR)" || $(MAKE) venv
+	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
+		python3 -m pytest --doctest-modules mcpgateway/ --tb=short"
+
+doctest-verbose:
+	@echo "🧪 Running doctest with verbose output..."
+	@test -d "$(VENV_DIR)" || $(MAKE) venv
+	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
+		python3 -m pytest --doctest-modules mcpgateway/ -v --tb=short"
+
+doctest-coverage:
+	@echo "📊 Generating doctest coverage report..."
+	@test -d "$(VENV_DIR)" || $(MAKE) venv
+	@mkdir -p $(TEST_DOCS_DIR)
+	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
+		python3 -m pytest --doctest-modules mcpgateway/ \
+		--cov=mcpgateway --cov-report=term --cov-report=html:htmlcov-doctest \
+		--cov-report=xml:coverage-doctest.xml"
+	@echo "✅ Doctest coverage report generated in htmlcov-doctest/"
+
+doctest-check:
+	@echo "🔍 Checking doctest coverage..."
+	@test -d "$(VENV_DIR)" || $(MAKE) venv
+	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
+		python3 -c \"import subprocess, sys; \
+		result = subprocess.run(['python', '-m', 'pytest', '--doctest-modules', 'mcpgateway/', '--tb=no', '-q'], capture_output=True); \
+		if result.returncode == 0: \
+			print('✅ All doctests passing'); \
+		else: \
+			print('❌ Doctest failures detected'); \
+			print(result.stdout.decode()); \
+			print(result.stderr.decode()); \
+			sys.exit(1)\""
+
 # =============================================================================
 # 📊 METRICS
 # =============================================================================
@@ -304,8 +345,8 @@ images:
 	@mkdir -p $(DOCS_DIR)/docs/design/images
 	@code2flow mcpgateway/ --output $(DOCS_DIR)/docs/design/images/code2flow.dot || true
 	@dot -Tsvg -Gbgcolor=transparent -Gfontname="Arial" -Nfontname="Arial" -Nfontsize=14 -Nfontcolor=black -Nfillcolor=white -Nshape=box -Nstyle="filled,rounded" -Ecolor=gray -Efontname="Arial" -Efontsize=14 -Efontcolor=black $(DOCS_DIR)/docs/design/images/code2flow.dot -o $(DOCS_DIR)/docs/design/images/code2flow.svg || true
-	@/bin/bash -c "source $(VENV_DIR)/bin/activate && python -m pip install snakefood3"
-	@/bin/bash -c "source $(VENV_DIR)/bin/activate && python -m snakefood3 . mcpgateway > snakefood.dot"
+	@/bin/bash -c "source $(VENV_DIR)/bin/activate && python3 -m pip install snakefood3"
+	@/bin/bash -c "source $(VENV_DIR)/bin/activate && python3 -m snakefood3 . mcpgateway > snakefood.dot"
 	@dot -Tpng -Gbgcolor=transparent -Gfontname="Arial" -Nfontname="Arial" -Nfontsize=12 -Nfontcolor=black -Nfillcolor=white -Nshape=box -Nstyle="filled,rounded" -Ecolor=gray -Efontname="Arial" -Efontsize=10 -Efontcolor=black snakefood.dot -o $(DOCS_DIR)/docs/design/images/snakefood.png || true
 	@pyreverse --colorized mcpgateway || true
 	@dot -Tsvg -Gbgcolor=transparent -Gfontname="Arial" -Nfontname="Arial" -Nfontsize=14 -Nfontcolor=black -Nfillcolor=white -Nshape=box -Nstyle="filled,rounded" -Ecolor=gray -Efontname="Arial" -Efontsize=14 -Efontcolor=black packages.dot -o $(DOCS_DIR)/docs/design/images/packages.svg || true
@@ -403,7 +444,13 @@ pycodestyle:                        ## 📝  Simple PEP-8 checker
 	@$(VENV_DIR)/bin/pycodestyle mcpgateway --max-line-length=200
 
 pre-commit:                         ## 🪄  Run pre-commit hooks
-	@$(VENV_DIR)/bin/pre-commit run --all-files --show-diff-on-failure
+	@echo "🪄  Running pre-commit hooks..."
+	@test -d "$(VENV_DIR)" || $(MAKE) venv install install-dev
+	@if [ ! -f "$(VENV_DIR)/bin/pre-commit" ]; then \
+		echo "📦  Installing pre-commit..."; \
+		/bin/bash -c "source $(VENV_DIR)/bin/activate && python3 -m pip install --quiet pre-commit"; \
+	fi
+	@/bin/bash -c "source $(VENV_DIR)/bin/activate && pre-commit run --all-files --show-diff-on-failure"
 
 ruff:                               ## ⚡  Ruff lint + format
 	@$(VENV_DIR)/bin/ruff check mcpgateway && $(VENV_DIR)/bin/ruff format mcpgateway tests
@@ -460,7 +507,7 @@ spellcheck-sort: .spellcheck-en.txt ## 🔤  Sort spell-list
 
 tox:                                ## 🧪  Multi-Python tox matrix (uv)
 	@echo "🧪  Running tox with uv ..."
-	python -m tox -p auto $(TOXARGS)
+	python3 -m tox -p auto $(TOXARGS)
 
 sbom:								## 🛡️  Generate SBOM & security report
 	@echo "🛡️   Generating SBOM & security report..."
@@ -470,7 +517,7 @@ sbom:								## 🛡️  Generate SBOM & security report
 	@/bin/bash -c "source $(VENV_DIR)/bin/activate && python3 -m uv pip install cyclonedx-bom sbom2doc"
 	@echo "🔍  Generating SBOM from environment..."
 	@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
-		python -m cyclonedx_py environment \
+		python3 -m cyclonedx_py environment \
 			--output-format XML \
 			--output-file $(PROJECT_NAME).sbom.xml \
 			--no-validate \
@@ -843,7 +890,7 @@ pip-audit:
 deps-update:
 	@echo "⬆️  Updating project dependencies via update-deps.py..."
 	@test -f update-deps.py || { echo "❌ update-deps.py not found in root directory."; exit 1; }
-	@/bin/bash -c "source $(VENV_DIR)/bin/activate && python update-deps.py"
+	@/bin/bash -c "source $(VENV_DIR)/bin/activate && python3 update-deps.py"
 	@echo "✅ Dependencies updated in pyproject.toml and docs/requirements.txt"
 
 containerfile-update:
@@ -2090,7 +2137,7 @@ devpi-unconfigure-pip:
 # 📦  Version helper (defaults to the version in pyproject.toml)
 #      override on the CLI:  make VER=0.2.1 devpi-delete
 # ─────────────────────────────────────────────────────────────────────────────
-VER ?= $(shell python -c "import tomllib, pathlib; \
+VER ?= $(shell python3 -c "import tomllib, pathlib; \
 print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['project']['version'])" \
 2>/dev/null || echo 0.0.0)
 

README.md

@@ -238,7 +238,7 @@ curl -s -H "Authorization: Bearer $MCPGATEWAY_BEARER_TOKEN" \
 ```powershell
 # 1️⃣  Isolated env + install from PyPI
 mkdir mcpgateway ; cd mcpgateway
-python -m venv .venv ; .\.venv\Scripts\Activate.ps1
+python3 -m venv .venv ; .\.venv\Scripts\Activate.ps1
 pip install --upgrade pip
 pip install mcp-contextforge-gateway
 
@@ -255,7 +255,7 @@ mcpgateway.exe --host 0.0.0.0 --port 4444
 # Start-Process -FilePath "mcpgateway.exe" -ArgumentList "--host 0.0.0.0 --port 4444"
 
 # 4️⃣  Bearer token and smoke-test
-$Env:MCPGATEWAY_BEARER_TOKEN = python -m mcpgateway.utils.create_jwt_token `
+$Env:MCPGATEWAY_BEARER_TOKEN = python3 -m mcpgateway.utils.create_jwt_token `
     --username admin --exp 10080 --secret my-test-key
 
 curl -s -H "Authorization: Bearer $Env:MCPGATEWAY_BEARER_TOKEN" `
@@ -389,7 +389,7 @@ docker logs -f mcpgateway
 
 # Generating an API key
 docker run --rm -it ghcr.io/ibm/mcp-context-forge:0.3.1 \
-  python -m mcpgateway.utils.create_jwt_token --username admin --exp 0 --secret my-test-key
+  python3 -m mcpgateway.utils.create_jwt_token --username admin --exp 0 --secret my-test-key
 ```
 
 Browse to **[http://localhost:4444/admin](http://localhost:4444/admin)** (user `admin` / pass `changeme`).

charts/README.md

@@ -325,7 +325,7 @@ migration:
     tag: latest                    # Should match mcpContextForge.image.tag
 
   command:
-    waitForDb: "python /app/mcpgateway/utils/db_isready.py --max-tries 30 --interval 2 --timeout 5"
+    waitForDb: "python3 /app/mcpgateway/utils/db_isready.py --max-tries 30 --interval 2 --timeout 5"
     migrate: "alembic upgrade head || echo '⚠️ Migration check failed'"
 ---
 

charts/mcp-stack/README.md

@@ -177,7 +177,7 @@ Kubernetes: `>=1.21.0`
 | migration.activeDeadlineSeconds | int | `600` |  |
 | migration.backoffLimit | int | `3` |  |
 | migration.command.migrate | string | `"alembic upgrade head || echo '⚠️ Migration check failed'"` |  |
-| migration.command.waitForDb | string | `"python /app/mcpgateway/utils/db_isready.py --max-tries 30 --interval 2 --timeout 5"` |  |
+| migration.command.waitForDb | string | `"python3 /app/mcpgateway/utils/db_isready.py --max-tries 30 --interval 2 --timeout 5"` |  |
 | migration.enabled | bool | `true` |  |
 | migration.image.pullPolicy | string | `"Always"` |  |
 | migration.image.repository | string | `"ghcr.io/ibm/mcp-context-forge"` |  |