-
Notifications
You must be signed in to change notification settings - Fork 631
Expand file tree
/
Copy pathMakefile
More file actions
8829 lines (7932 loc) · 416 KB
/
Makefile
File metadata and controls
8829 lines (7932 loc) · 416 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🐍 ContextForge AI Gateway - Makefile
# (AI Gateway, registry, and proxy for MCP, A2A, and REST/gRPC APIs)
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# Authors: Mihai Criveti, Manav Gupta
# Description: Build & automation helpers for ContextForge project
# Usage: run `make` or `make help` to view available targets
#
# help: 🐍 ContextForge AI Gateway (AI Gateway, registry, and proxy for MCP, A2A, and REST/gRPC APIs)
#
# ──────────────────────────────────────────────────────────────────────────
SHELL := /bin/bash
.SHELLFLAGS := -eu -o pipefail -c
# Read values from .env.make
-include .env.make
# Rust build configuration (set to 1 to enable Rust builds, 0 to disable)
# Default is disabled to avoid requiring Rust toolchain for standard builds
ENABLE_RUST_BUILD ?= 0
ENABLE_RUST_MCP_RMCP_BUILD ?=
RUST_MCP_BUILD ?= 0
RUST_MCP_MODE ?= off
RUST_MCP_LOG ?= warn
# Project variables
PROJECT_NAME = mcpgateway
DOCS_DIR = docs
HANDSDOWN_PARAMS = -o $(DOCS_DIR)/ -n $(PROJECT_NAME) --name "ContextForge" --cleanup
TEST_DOCS_DIR ?= $(DOCS_DIR)/docs/test
MCP_2025_TEST_DIR ?= tests/compliance/mcp_2025_11_25
MCP_2025_ARTIFACTS_DIR ?= artifacts/mcp-2025-11-25
MCP_2025_MARKER ?= mcp20251125
MCP_2025_PYTEST_ARGS ?=
MCP_2025_BASE_URL ?=
MCP_2025_RPC_PATH ?= /mcp/
MCP_2025_BEARER_TOKEN ?=
# Virtual-environment variables
VENV_DIR ?= $(CURDIR)/.venv
# -----------------------------------------------------------------------------
# Project-wide clean-up targets
# -----------------------------------------------------------------------------
COVERAGE_DIR ?= $(DOCS_DIR)/docs/coverage
LICENSES_MD ?= $(DOCS_DIR)/docs/test/licenses.md
METRICS_MD ?= $(DOCS_DIR)/docs/metrics/loc.md
DIRS_TO_CLEAN := __pycache__ .pytest_cache .tox .ruff_cache .pyre .mypy_cache .pytype \
dist build site .eggs *.egg-info .cache htmlcov certs \
$(VENV_DIR) $(VENV_DIR).sbom $(COVERAGE_DIR) htmlcov-doctest htmlcov_ai_normalizer \
node_modules .mutmut-cache html
FILES_TO_CLEAN := .coverage .coverage.* coverage.xml mcp.prof mcp.pstats mcp.db-* \
$(PROJECT_NAME).sbom.json \
snakefood.dot packages.dot classes.dot \
$(DOCS_DIR)/pstats.png \
$(DOCS_DIR)/docs/test/sbom.md \
$(LICENSE_CHECK_REPORT) \
$(DOCS_DIR)/docs/test/{unittest,full,index,test}.md \
$(DOCS_DIR)/docs/images/coverage.svg $(LICENSES_MD) $(METRICS_MD) \
*.db *.sqlite *.sqlite3 mcp.db-journal *.py,cover \
.depsorter_cache.json .depupdate.* \
devskim-results.sarif \
*.tar.gz *.tar.bz2 *.tar.xz *.zip *.deb \
*.log mcpgateway.sbom.xml
# Extra cleanup targets that are easiest to remove by explicit path/pattern.
EXTRA_DIRS_TO_CLEAN := reports test-results tests/playwright/reports \
tests/playwright/screenshots tests/playwright/videos \
tests/jmeter/results tests/async/profiles tests/async/reports \
tests/migration/reports tests/migration/logs .jmeter
EXTRA_FILES_TO_CLEAN := docs/docs/security/report.md \
playwright-report-*.html test-results-*.xml \
logs/db-queries.jsonl \
snyk-code-results.json snyk-container-results.json \
snyk-iac-compose-results.json snyk-iac-docker-results.json \
snyk-helm-results.json aibom.json sbom-cyclonedx.json sbom-spdx.json
COVERAGE_DIR ?= $(DOCS_DIR)/docs/coverage
LICENSES_MD ?= $(DOCS_DIR)/docs/test/licenses.md
LICENSE_CHECK_REPORT ?= $(DOCS_DIR)/docs/test/license-check-report.json
LICENSE_CHECK_POLICY ?= license-policy.toml
LICENSE_CHECK_INCLUDE_DEV_GROUPS ?= false
LICENSE_CHECK_SUMMARY_ONLY ?= false
METRICS_MD ?= $(DOCS_DIR)/docs/metrics/loc.md
# -----------------------------------------------------------------------------
# Container resource configuration
# -----------------------------------------------------------------------------
CONTAINER_MEMORY = 2048m
CONTAINER_CPUS = 2
# -----------------------------------------------------------------------------
# OS Specific
# -----------------------------------------------------------------------------
# The -r flag for xargs is GNU-specific and will fail on macOS
XARGS_FLAGS := $(shell [ "$$(uname)" = "Darwin" ] && echo "" || echo "-r")
# -----------------------------------------------------------------------------
# Allow override of the image to be used in various docker compose
# up and down actions
# -----------------------------------------------------------------------------
ifndef IMAGE_LOCAL
# Base image name (without any prefix)
IMAGE_BASE := mcpgateway/mcpgateway
IMAGE_TAG := latest
# Handle runtime-specific image naming
ifeq ($(CONTAINER_RUNTIME),podman)
# Podman adds localhost/ prefix for local builds
IMAGE_LOCAL := localhost/$(IMAGE_BASE):$(IMAGE_TAG)
IMAGE_LOCAL_DEV := localhost/$(IMAGE_BASE)-dev:$(IMAGE_TAG)
IMAGE_PUSH := $(IMAGE_BASE):$(IMAGE_TAG)
else
# Docker doesn't add prefix
IMAGE_LOCAL := $(IMAGE_BASE):$(IMAGE_TAG)
IMAGE_LOCAL_DEV := $(IMAGE_BASE)-dev:$(IMAGE_TAG)
IMAGE_PUSH := $(IMAGE_BASE):$(IMAGE_TAG)
endif
endif
# =============================================================================
# 📖 DYNAMIC HELP
# =============================================================================
.PHONY: help
help:
@grep "^# help\:" Makefile | grep -v grep | sed 's/\# help\: //' | sed 's/\# help\://'
@if grep -q "^# deprecated:" Makefile; then \
printf '\n\033[33m⚠️ DEPRECATED TARGETS (still work, will be removed in stated version)\033[0m\n'; \
grep "^# deprecated:" Makefile | sed 's/^# deprecated: //' | while IFS= read -r line; do \
printf ' \033[2;33m%s\033[0m\n' "$$line"; \
done; \
fi
# -----------------------------------------------------------------------------
# 🔧 SYSTEM-LEVEL DEPENDENCIES
# -----------------------------------------------------------------------------
# help: 🔧 SYSTEM-LEVEL DEPENDENCIES (DEV BUILD ONLY)
# help: os-deps - Install Graphviz, Pandoc, SCC used for dev docs generation
OS_DEPS_SCRIPT := ./os_deps.sh
.PHONY: os-deps
os-deps: $(OS_DEPS_SCRIPT)
@bash $(OS_DEPS_SCRIPT)
# -----------------------------------------------------------------------------
# 🔧 HELPER SCRIPTS
# -----------------------------------------------------------------------------
# Boolean normalizer: returns non-empty only for explicit truth values.
# Usage: $(if $(call is_true,$(VAR)),yes-branch,no-branch)
is_true = $(filter 1 true yes,$(1))
# Deprecation warning for aliased targets.
# Usage: $(call deprecated_target,old-name,replacement invocation,removal-version)
define deprecated_target
@printf '\n ⚠️ WARNING: "%s" is deprecated. Use "%s" instead.\n' '$(1)' '$(2)'
@printf ' This alias will be removed in v%s.\n\n' '$(3)'
endef
# Helper to ensure a Python package is installed in venv (uses uv to avoid pip corruption)
define ensure_pip_package
@test -d "$(VENV_DIR)" || $(MAKE) venv
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
$(UV_BIN) pip show $(1) >/dev/null 2>&1 || \
$(UV_BIN) pip install -q $(1)"
endef
# =============================================================================
# 🌱 VIRTUAL ENVIRONMENT & INSTALLATION
# =============================================================================
# help: 🌱 VIRTUAL ENVIRONMENT & INSTALLATION
# help: uv - Ensure uv is installed or install it if needed
# help: venv - Create a fresh virtual environment with uv & friends
# help: activate - Activate the virtual environment in the current shell
# help: install - Install project into the venv
# help: install-dev - Install project (incl. dev deps) into the venv
# help: install-db - Install project (incl. postgres and redis) into venv
# help: update - Update all installed deps inside the venv
.PHONY: uv
uv:
@if ! type uv >/dev/null 2>&1 && ! test -x "$(HOME)/.local/bin/uv"; then \
echo "❌ 'uv' not found."; \
if type brew >/dev/null 2>&1; then \
echo "💡 Install 'uv' via Homebrew or another trusted package manager:"; \
echo " brew install uv"; \
exit 1; \
else \
echo "💡 Install uv from a trusted package manager or pinned release:"; \
echo " https://docs.astral.sh/uv/getting-started/installation/"; \
exit 1; \
fi; \
fi
# UV_BIN: prefer uv in PATH, fallback to ~/.local/bin/uv
UV_BIN := $(shell type -p uv 2>/dev/null || echo "$(HOME)/.local/bin/uv")
export UV_BIN
# ----------------------------------------------------------------------------
# Virtual environment execution policy
# ----------------------------------------------------------------------------
# Targets in this Makefile deliberately split how they use `uv`:
#
# * Execution: invoke tools via `$(VENV_DIR)/bin/<tool>` directly (e.g.
# pytest, black, ruff, pylint, python). `uv run` — even with `--active` —
# has historically resolved against an unexpected environment when the
# caller has already `source`d the project venv, producing confusing
# "works on my machine" failures. Direct invocation removes the ambiguity:
# the tool that runs is unambiguously the one installed in $(VENV_DIR).
#
# * Package management: continue to use `uv pip install` / `uv pip show` /
# `uv pip list`. These are intentionally NOT rewritten to
# `$(VENV_DIR)/bin/pip` because `uv venv` does not seed `pip` into the
# created environment (no `--seed` flag is passed in the `venv` target
# above), so `$(VENV_DIR)/bin/pip` simply does not exist. `uv pip` is also
# materially faster than vanilla pip and is the supported way to manage
# packages in a uv-managed venv.
#
# If you add a new target: use `$(VENV_DIR)/bin/<tool>` to *run* something and
# `uv pip ...` to *install* something. Do not reintroduce `uv run`.
#
# Exception — tools invoked via `uvx`: `black`, `isort`, `ruff`, `pylint`,
# `vulture`, `interrogate`, `radon`, `yamllint`, `tomlcheck`, and
# `detect-secrets` are invoked through `uv tool run <spec>` with pinned
# versions (see the pins just below). This isolates the tool versions from
# whatever is resolved into $(VENV_DIR) by the dev dependency group, so CI
# and local runs always use the same version regardless of when the venv was
# last rebuilt. These targets still depend on the `uv` target so `uvx` is
# guaranteed present. `detect-secrets` is special-cased to use a git-URL
# spec because the project uses IBM's hardened fork, which is not published
# to PyPI — see DETECT_SECRETS_SPEC below.
#
# Sub-exception — pylint needs project context: unlike the pure-AST tools
# (ruff, black, isort, vulture, interrogate, radon), pylint does deep type
# inference via astroid and relies on being able to *import* the project
# modules and their runtime dependencies (pydantic, fastapi, …) to avoid
# false positives like E1133 (not-an-iterable) and spurious W0246
# (useless-parent-delegation) suppressions from pylint-pydantic that only
# activate when the pydantic class hierarchy is resolvable. The `pylint` and
# `images`/pyreverse targets therefore pass `--with-editable .` to `uv tool
# run` so the project and its deps are installed into pylint's isolated
# tool environment. This costs ~5–10s of resolve/install on a cold uvx
# cache but restores the inference behavior that the previous
# venv-installed pylint (via `pip install -e .[dev]`) had for free.
# ----------------------------------------------------------------------------
# ----------------------------------------------------------------------------
# Pinned linter/formatter versions (invoked via `uvx`)
# ----------------------------------------------------------------------------
# Bump these in lockstep with the lower bounds in pyproject.toml's dev group
# so editors (which typically use the venv-installed version) and Makefile
# targets (which use these pins via uvx) stay aligned.
BLACK_VERSION ?= 26.3.1
ISORT_VERSION ?= 6.1.0
RUFF_VERSION ?= 0.15.1
PYLINT_VERSION ?= 3.3.9
PYLINT_PYDANTIC_VERSION ?= 0.3.5
VULTURE_VERSION ?= 2.14
INTERROGATE_VERSION ?= 1.7.0
RADON_VERSION ?= 6.0.1
YAMLLINT_VERSION ?= 1.38.0
TOMLCHECK_VERSION ?= 0.2.3
PYSPELLING_VERSION ?= 2.11
# detect-secrets: pinned to IBM's hardened fork (Tag 0.13.1+ibm.64.dss).
# Uses a git-URL + commit SHA rather than a PyPI version because the IBM
# fork is not published to PyPI.
DETECT_SECRETS_SPEC ?= git+https://github.com/ibm/detect-secrets.git@076672a9a01abdfc7ecee2e7d14f08cdccb73976
.PHONY: venv
venv: uv
@rm -Rf "$(VENV_DIR)"
@mkdir -p "$(VENV_DIR)"
@$(UV_BIN) venv "$(VENV_DIR)"
@echo -e "✅ Virtual env created.\n💡 Enter it with:\n . $(VENV_DIR)/bin/activate\n"
.PHONY: activate
activate:
@echo -e "💡 Enter the venv using:\n. $(VENV_DIR)/bin/activate\n"
.PHONY: install
install: venv
@/bin/bash -c "source $(VENV_DIR)/bin/activate && $(UV_BIN) pip install ."
.PHONY: install-db
install-db: venv
@/bin/bash -c "source $(VENV_DIR)/bin/activate && $(UV_BIN) pip install .[redis,postgres]"
.PHONY: install-dev
install-dev: venv
@/bin/bash -c "source $(VENV_DIR)/bin/activate && $(UV_BIN) pip install --group dev '.[plugins]'"
@if [ "$(ENABLE_RUST_BUILD)" = "1" ]; then \
echo "🦀 Building Rust..."; \
$(MAKE) rust-dev || echo "⚠️ Rust not available (optional)"; \
else \
echo "⏭️ Rust builds disabled (set ENABLE_RUST_BUILD=1 to enable)"; \
fi
@$(MAKE) build-ui
# help: build-ui - Build Admin UI JS bundle with Vite (requires npm; set SKIP_UI_BUILD=1 to bypass)
.PHONY: build-ui
build-ui:
@if [ "$(SKIP_UI_BUILD)" = "1" ]; then \
echo "⏭️ SKIP_UI_BUILD=1 — skipping Admin UI build (the Admin UI will not load at runtime)"; \
elif command -v npm >/dev/null 2>&1; then \
echo "🔨 Building Admin UI bundle..."; \
if [ -f package-lock.json ]; then \
npm ci --no-audit --no-fund; \
else \
echo "ℹ️ package-lock.json not found — falling back to 'npm install'"; \
npm install --no-audit --no-fund; \
fi && \
npm run vite:build; \
else \
echo "❌ npm not found — install Node.js (https://nodejs.org) to build the Admin UI."; \
echo " Without the bundle, /admin will fail to load at runtime."; \
echo " To bypass this step intentionally, re-run with SKIP_UI_BUILD=1."; \
exit 1; \
fi
.PHONY: update
update:
@echo "⬆️ Updating installed dependencies..."
@/bin/bash -c "source $(VENV_DIR)/bin/activate && $(UV_BIN) pip install -U --group dev ."
# help: check-env - Verify all required env vars in .env are present
.PHONY: check-env check-env-dev
# Validate .env in production mode
check-env:
@echo "🔎 Validating .env against .env.example using Python (prod)..."
@python -m mcpgateway.scripts.validate_env .env.example
# Validate .env in development mode (warnings do not fail)
check-env-dev:
@echo "🔎 Validating .env (dev, warnings do not fail)..."
@python -c "import sys; from mcpgateway.scripts import validate_env as ve; sys.exit(ve.main(env_file='.env', exit_on_warnings=False))"
# =============================================================================
# ▶️ SERVE
# =============================================================================
# help: ▶️ SERVE
# help: serve - Run production Gunicorn server on :4444
# help: certs - Generate self-signed TLS cert & key in ./certs (won't overwrite)
# help: certs-passphrase - Generate self-signed cert with passphrase-protected key
# help: certs-remove-passphrase - Remove passphrase from encrypted key
# help: certs-jwt - Generate JWT RSA keys in ./certs/jwt/ (idempotent)
# help: certs-jwt-ecdsa - Generate JWT ECDSA keys in ./certs/jwt/ (idempotent)
# help: certs-all - Generate both TLS certs and JWT keys (combo target)
# help: certs-mcp-ca - Generate MCP CA for plugin mTLS (./certs/mcp/ca/)
# help: certs-mcp-gateway - Generate gateway client certificate (./certs/mcp/gateway/)
# help: certs-mcp-plugin - Generate plugin server certificate (requires PLUGIN_NAME=name)
# help: certs-mcp-all - Generate complete MCP mTLS infrastructure (reads plugins from config.yaml)
# help: certs-mcp-check - Check expiry dates of MCP certificates
# help: serve-ssl - Run Gunicorn behind HTTPS on :4444 (uses ./certs)
# help: dev - Run fast-reload dev server (uvicorn)
# help: dev-echo - Run dev server with SQL query logging (N+1 debugging)
# help: dev-remote - Run dev server with remote debugging (debugpy on port 5678)
# help: stop - Stop all mcpgateway server processes
# help: stop-dev - Stop uvicorn dev server (port 8000)
# help: stop-serve - Stop gunicorn production server (port 4444)
# help: run - Execute helper script ./run.sh
.PHONY: serve serve-ssl serve-granian serve-granian-ssl serve-granian-http2 dev dev-remote stop stop-dev stop-serve run \
certs certs-jwt certs-jwt-ecdsa certs-all certs-mcp-ca certs-mcp-gateway certs-mcp-plugin certs-mcp-all certs-mcp-check \
js-build
## --- JS build ----------------------------------------------------------------
js-build: ## Install npm dependencies and build JS bundle with Vite
@if command -v npm >/dev/null 2>&1; then \
npm install --no-audit --no-fund && npm run vite:build; \
else \
echo "WARNING: npm not found — skipping JS bundle build (admin UI may not load)"; \
fi
## --- Primary servers ---------------------------------------------------------
serve: install js-build ## Run production server with Gunicorn + Uvicorn (default)
./run-gunicorn.sh
serve-ssl: js-build certs ## Run Gunicorn with TLS enabled
SSL=true CERT_FILE=certs/cert.pem KEY_FILE=certs/key.pem ./run-gunicorn.sh
serve-granian: js-build ## Run production server with Granian (Rust-based, alternative)
./run-granian.sh
serve-granian-ssl: js-build certs ## Run Granian with TLS enabled
SSL=true CERT_FILE=certs/cert.pem KEY_FILE=certs/key.pem ./run-granian.sh
serve-granian-http2: js-build certs ## Run Granian with HTTP/2 and TLS
SSL=true GRANIAN_HTTP=2 CERT_FILE=certs/cert.pem KEY_FILE=certs/key.pem ./run-granian.sh
dev: js-build
@TEMPLATES_AUTO_RELOAD=true $(VENV_DIR)/bin/uvicorn mcpgateway.main:app --host 0.0.0.0 --port 8000 --reload --reload-exclude='public/'
.PHONY: dev-echo
dev-echo: js-build ## Run dev server with SQL query logging enabled
@echo "🔍 Starting dev server with SQL query logging (N+1 detection)"
@echo " Docs: docs/docs/development/db-performance.md"
@SQLALCHEMY_ECHO=true TEMPLATES_AUTO_RELOAD=true $(VENV_DIR)/bin/uvicorn mcpgateway.main:app --host 0.0.0.0 --port 8000 --reload --reload-exclude='public/'
dev-remote: DEBUG_IP = 127.0.0.1
dev-remote: DEBUG_WAIT = --wait-for-client
dev-remote: js-build ## Run dev server with remote debugging (debugpy on port 5678, remote: make dev-remote DEBUG_IP=0.0.0.0 DEBUG_WAIT=)
@TEMPLATES_AUTO_RELOAD=true $(VENV_DIR)/bin/python -m debugpy \
--listen $(DEBUG_IP):5678 \
$(DEBUG_WAIT) \
$(VENV_DIR)/bin/uvicorn mcpgateway.main:app \
--host 0.0.0.0 --port 8000 --reload --reload-exclude='public/'
stop: ## Stop all mcpgateway server processes
@echo "Stopping all mcpgateway processes..."
@if [ -f /tmp/mcpgateway-gunicorn.lock ]; then kill -9 $$(cat /tmp/mcpgateway-gunicorn.lock) 2>/dev/null || true; rm -f /tmp/mcpgateway-gunicorn.lock; fi
@if [ -f /tmp/mcpgateway-granian.lock ]; then kill -9 $$(cat /tmp/mcpgateway-granian.lock) 2>/dev/null || true; rm -f /tmp/mcpgateway-granian.lock; fi
@lsof -ti:8000 2>/dev/null | xargs -r kill -9 || true
@lsof -ti:4444 2>/dev/null | xargs -r kill -9 || true
@echo "Done."
stop-dev: ## Stop uvicorn dev server (port 8000)
@lsof -ti:8000 2>/dev/null | xargs -r kill -9 || true
stop-serve: ## Stop gunicorn production server (port 4444)
@if [ -f /tmp/mcpgateway-gunicorn.lock ]; then kill -9 $$(cat /tmp/mcpgateway-gunicorn.lock) 2>/dev/null || true; rm -f /tmp/mcpgateway-gunicorn.lock; fi
@lsof -ti:4444 2>/dev/null | xargs -r kill -9 || true
run: js-build
./run.sh
## --- Certificate helper ------------------------------------------------------
.PHONY: certs
certs: ## Generate ./certs/cert.pem & ./certs/key.pem (idempotent)
@if [ -f certs/cert.pem ] && [ -f certs/key.pem ]; then \
echo "🔏 Existing certificates found in ./certs - skipping generation."; \
else \
echo "🔏 Generating self-signed certificate (1 year)..."; \
mkdir -p certs; \
openssl req -x509 -newkey rsa:4096 -sha256 -days 365 -nodes \
-keyout certs/key.pem -out certs/cert.pem \
-subj "/CN=localhost" \
-addext "subjectAltName=DNS:localhost,IP:127.0.0.1"; \
echo "✅ TLS certificate written to ./certs"; \
fi
@echo "🔐 Setting file permissions for container access..."
@chmod 644 certs/cert.pem # Public certificate - world-readable is OK
@chmod 640 certs/key.pem # Private key - owner+group only, no world access
@echo "🔧 Setting group to 0 (root) for container access (requires sudo)..."
@sudo chgrp 0 certs/key.pem certs/cert.pem || \
(echo "⚠️ Warning: Could not set group to 0 (container may not be able to read key)" && \
echo " Run manually: sudo chgrp 0 certs/key.pem certs/cert.pem")
.PHONY: certs-passphrase
certs-passphrase: ## Generate self-signed cert with passphrase-protected key
@if [ -f certs/cert.pem ] && [ -f certs/key-encrypted.pem ]; then \
echo "🔏 Existing passphrase-protected certificates found - skipping."; \
else \
echo "🔏 Generating passphrase-protected certificate (1 year)..."; \
mkdir -p certs; \
read -sp "Enter passphrase for private key: " PASSPHRASE; echo; \
read -sp "Confirm passphrase: " PASSPHRASE2; echo; \
if [ "$$PASSPHRASE" != "$$PASSPHRASE2" ]; then \
echo "❌ Passphrases do not match!"; \
exit 1; \
fi; \
openssl genrsa -aes256 -passout pass:"$$PASSPHRASE" -out certs/key-encrypted.pem 4096; \
openssl req -x509 -sha256 -days 365 \
-key certs/key-encrypted.pem \
-passin pass:"$$PASSPHRASE" \
-out certs/cert.pem \
-subj "/CN=localhost" \
-addext "subjectAltName=DNS:localhost,IP:127.0.0.1"; \
echo "✅ Passphrase-protected certificate created (AES-256)"; \
fi
@echo "🔐 Setting file permissions for container access..."
@chmod 644 certs/cert.pem # Public certificate - world-readable is OK
@chmod 640 certs/key-encrypted.pem # Private key - owner+group only, no world access
@echo "🔧 Setting group to 0 (root) for container access (requires sudo)..."
@sudo chgrp 0 certs/key-encrypted.pem certs/cert.pem || \
(echo "⚠️ Warning: Could not set group to 0 (container may not be able to read key)" && \
echo " Run manually: sudo chgrp 0 certs/key-encrypted.pem certs/cert.pem")
@echo "📁 Certificate: ./certs/cert.pem"
@echo "📁 Encrypted Key: ./certs/key-encrypted.pem"
@echo ""
@echo "💡 To use this certificate:"
@echo " 1. Set KEY_FILE_PASSWORD environment variable"
@echo " 2. Run: KEY_FILE_PASSWORD='your-passphrase' SSL=true CERT_FILE=certs/cert.pem KEY_FILE=certs/key-encrypted.pem make serve-ssl"
.PHONY: certs-remove-passphrase
certs-remove-passphrase: ## Remove passphrase from encrypted key (creates key.pem from key-encrypted.pem)
@if [ ! -f certs/key-encrypted.pem ]; then \
echo "❌ No encrypted key found at certs/key-encrypted.pem"; \
echo "💡 Generate one with: make certs-passphrase"; \
exit 1; \
fi
@echo "🔓 Removing passphrase from private key..."
@openssl rsa -in certs/key-encrypted.pem -out certs/key.pem
@chmod 640 certs/key.pem
@echo "🔧 Setting group to 0 (root) for container access (requires sudo)..."
@sudo chgrp 0 certs/key.pem || \
(echo "⚠️ Warning: Could not set group to 0 (container may not be able to read key)" && \
echo " Run manually: sudo chgrp 0 certs/key.pem")
@echo "✅ Passphrase removed - unencrypted key saved to certs/key.pem"
@echo "⚠️ Keep this file secure! It contains your unencrypted private key."
.PHONY: certs-jwt
certs-jwt: ## Generate JWT RSA keys in ./certs/jwt/ (idempotent)
@if [ -f certs/jwt/private.pem ] && [ -f certs/jwt/public.pem ]; then \
echo "🔐 Existing JWT RSA keys found in ./certs/jwt - skipping generation."; \
else \
echo "🔐 Generating JWT RSA key pair (4096-bit)..."; \
mkdir -p certs/jwt; \
openssl genrsa -out certs/jwt/private.pem 4096; \
openssl rsa -in certs/jwt/private.pem -pubout -out certs/jwt/public.pem; \
echo "✅ JWT RSA keys written to ./certs/jwt"; \
fi
@chmod 600 certs/jwt/private.pem
@chmod 644 certs/jwt/public.pem
@echo "🔒 Permissions set: private.pem (600), public.pem (644)"
.PHONY: certs-jwt-ecdsa
certs-jwt-ecdsa: ## Generate JWT ECDSA keys in ./certs/jwt/ (idempotent)
@if [ -f certs/jwt/ec_private.pem ] && [ -f certs/jwt/ec_public.pem ]; then \
echo "🔐 Existing JWT ECDSA keys found in ./certs/jwt - skipping generation."; \
else \
echo "🔐 Generating JWT ECDSA key pair (P-256 curve)..."; \
mkdir -p certs/jwt; \
openssl ecparam -genkey -name prime256v1 -noout -out certs/jwt/ec_private.pem; \
openssl ec -in certs/jwt/ec_private.pem -pubout -out certs/jwt/ec_public.pem; \
echo "✅ JWT ECDSA keys written to ./certs/jwt"; \
fi
@chmod 600 certs/jwt/ec_private.pem
@chmod 644 certs/jwt/ec_public.pem
@echo "🔒 Permissions set: ec_private.pem (600), ec_public.pem (644)"
.PHONY: certs-all
certs-all: certs certs-jwt ## Generate both TLS certificates and JWT RSA keys
@echo "🎯 All certificates and keys generated successfully!"
@echo "📁 TLS: ./certs/{cert,key}.pem"
@echo "📁 JWT: ./certs/jwt/{private,public}.pem"
@echo "💡 Use JWT_ALGORITHM=RS256 with JWT_PUBLIC_KEY_PATH=certs/jwt/public.pem"
## --- MCP Plugin mTLS Certificate Management ----------------------------------
# Default validity period for MCP certificates (in days)
MCP_CERT_DAYS ?= 825
# Plugin configuration file for automatic certificate generation
MCP_PLUGIN_CONFIG ?= plugins/external/config.yaml
.PHONY: certs-mcp-ca
certs-mcp-ca: ## Generate CA for MCP plugin mTLS
@if [ -f certs/mcp/ca/ca.key ] && [ -f certs/mcp/ca/ca.crt ]; then \
echo "🔐 Existing MCP CA found in ./certs/mcp/ca - skipping generation."; \
echo "⚠️ To regenerate, delete ./certs/mcp/ca and run again."; \
else \
echo "🔐 Generating MCP Certificate Authority ($(MCP_CERT_DAYS) days validity)..."; \
mkdir -p certs/mcp/ca; \
openssl genrsa -out certs/mcp/ca/ca.key 4096; \
openssl req -new -x509 -key certs/mcp/ca/ca.key -out certs/mcp/ca/ca.crt \
-days $(MCP_CERT_DAYS) \
-subj "/CN=ContextForge-CA/O=ContextForge/OU=Plugins"; \
echo "01" > certs/mcp/ca/ca.srl; \
echo "✅ MCP CA created: ./certs/mcp/ca/ca.{key,crt}"; \
fi
@chmod 600 certs/mcp/ca/ca.key
@chmod 644 certs/mcp/ca/ca.crt
@echo "🔒 Permissions set: ca.key (600), ca.crt (644)"
.PHONY: certs-mcp-gateway
certs-mcp-gateway: certs-mcp-ca ## Generate gateway client certificate
@if [ -f certs/mcp/gateway/client.key ] && [ -f certs/mcp/gateway/client.crt ]; then \
echo "🔐 Existing gateway client certificate found - skipping generation."; \
else \
echo "🔐 Generating gateway client certificate ($(MCP_CERT_DAYS) days)..."; \
mkdir -p certs/mcp/gateway; \
openssl genrsa -out certs/mcp/gateway/client.key 4096; \
openssl req -new -key certs/mcp/gateway/client.key \
-out certs/mcp/gateway/client.csr \
-subj "/CN=mcp-gateway-client/O=MCPGateway/OU=Gateway"; \
openssl x509 -req -in certs/mcp/gateway/client.csr \
-CA certs/mcp/ca/ca.crt -CAkey certs/mcp/ca/ca.key \
-CAcreateserial -out certs/mcp/gateway/client.crt \
-days $(MCP_CERT_DAYS) -sha256; \
rm certs/mcp/gateway/client.csr; \
cp certs/mcp/ca/ca.crt certs/mcp/gateway/ca.crt; \
echo "✅ Gateway client certificate created: ./certs/mcp/gateway/"; \
fi
@chmod 600 certs/mcp/gateway/client.key
@chmod 644 certs/mcp/gateway/client.crt certs/mcp/gateway/ca.crt
@echo "🔒 Permissions set: client.key (600), client.crt (644), ca.crt (644)"
.PHONY: certs-mcp-plugin
certs-mcp-plugin: certs-mcp-ca ## Generate plugin server certificate (PLUGIN_NAME=name)
@if [ -z "$(PLUGIN_NAME)" ]; then \
echo "❌ ERROR: PLUGIN_NAME not set"; \
echo "💡 Usage: make certs-mcp-plugin PLUGIN_NAME=my-plugin"; \
exit 1; \
fi
@if [ -f certs/mcp/plugins/$(PLUGIN_NAME)/server.key ] && \
[ -f certs/mcp/plugins/$(PLUGIN_NAME)/server.crt ]; then \
echo "🔐 Existing certificate for plugin '$(PLUGIN_NAME)' found - skipping."; \
else \
echo "🔐 Generating server certificate for plugin '$(PLUGIN_NAME)' ($(MCP_CERT_DAYS) days)..."; \
mkdir -p certs/mcp/plugins/$(PLUGIN_NAME); \
openssl genrsa -out certs/mcp/plugins/$(PLUGIN_NAME)/server.key 4096; \
openssl req -new -key certs/mcp/plugins/$(PLUGIN_NAME)/server.key \
-out certs/mcp/plugins/$(PLUGIN_NAME)/server.csr \
-subj "/CN=mcp-plugin-$(PLUGIN_NAME)/O=MCPGateway/OU=Plugins"; \
openssl x509 -req -in certs/mcp/plugins/$(PLUGIN_NAME)/server.csr \
-CA certs/mcp/ca/ca.crt -CAkey certs/mcp/ca/ca.key \
-CAcreateserial -out certs/mcp/plugins/$(PLUGIN_NAME)/server.crt \
-days $(MCP_CERT_DAYS) -sha256 \
-extfile <(printf "subjectAltName=DNS:$(PLUGIN_NAME),DNS:mcp-plugin-$(PLUGIN_NAME),DNS:localhost"); \
rm certs/mcp/plugins/$(PLUGIN_NAME)/server.csr; \
cp certs/mcp/ca/ca.crt certs/mcp/plugins/$(PLUGIN_NAME)/ca.crt; \
echo "✅ Plugin '$(PLUGIN_NAME)' certificate created: ./certs/mcp/plugins/$(PLUGIN_NAME)/"; \
fi
@chmod 600 certs/mcp/plugins/$(PLUGIN_NAME)/server.key
@chmod 644 certs/mcp/plugins/$(PLUGIN_NAME)/server.crt certs/mcp/plugins/$(PLUGIN_NAME)/ca.crt
@echo "🔒 Permissions set: server.key (600), server.crt (644), ca.crt (644)"
.PHONY: certs-mcp-all
certs-mcp-all: certs-mcp-ca certs-mcp-gateway ## Generate complete mTLS infrastructure
@echo "🔐 Generating certificates for plugins..."
@# Read plugin names from config file if it exists
@if [ -f "$(MCP_PLUGIN_CONFIG)" ]; then \
echo "📋 Reading plugin names from $(MCP_PLUGIN_CONFIG)"; \
python3 -c "import yaml; \
config = yaml.safe_load(open('$(MCP_PLUGIN_CONFIG)')); \
plugins = [p['name'] for p in config.get('plugins', []) if p.get('kind') == 'external']; \
print('\n'.join(plugins))" 2>/dev/null | while read plugin_name; do \
if [ -n "$$plugin_name" ]; then \
echo " Generating for: $$plugin_name"; \
$(MAKE) certs-mcp-plugin PLUGIN_NAME="$$plugin_name"; \
fi; \
done || echo "⚠️ PyYAML not installed or config parse failed, generating example plugins..."; \
fi
@# Fallback to example plugins if no config or parsing failed
@if [ ! -f "$(MCP_PLUGIN_CONFIG)" ] || ! python3 -c "import yaml" 2>/dev/null; then \
echo "🔐 Generating certificates for example plugins..."; \
$(MAKE) certs-mcp-plugin PLUGIN_NAME=example-plugin-a; \
$(MAKE) certs-mcp-plugin PLUGIN_NAME=example-plugin-b; \
fi
@echo ""
@echo "🎯 MCP mTLS infrastructure generated successfully!"
@echo "📁 Structure:"
@echo " certs/mcp/ca/ - Certificate Authority"
@echo " certs/mcp/gateway/ - Gateway client certificate"
@echo " certs/mcp/plugins/*/ - Plugin server certificates"
@echo ""
@echo "💡 Generate additional plugin certificates with:"
@echo " make certs-mcp-plugin PLUGIN_NAME=your-plugin-name"
@echo ""
@echo "💡 Certificate validity: $(MCP_CERT_DAYS) days"
@echo " To change: make certs-mcp-all MCP_CERT_DAYS=365"
.PHONY: certs-mcp-check
certs-mcp-check: ## Check expiry dates of MCP certificates
@echo "🔍 Checking MCP certificate expiry dates..."
@echo ""
@if [ -f certs/mcp/ca/ca.crt ]; then \
echo "📋 CA Certificate:"; \
openssl x509 -in certs/mcp/ca/ca.crt -noout -enddate | sed 's/notAfter=/ Expires: /'; \
echo ""; \
fi
@if [ -f certs/mcp/gateway/client.crt ]; then \
echo "📋 Gateway Client Certificate:"; \
openssl x509 -in certs/mcp/gateway/client.crt -noout -enddate | sed 's/notAfter=/ Expires: /'; \
echo ""; \
fi
@if [ -d certs/mcp/plugins ]; then \
echo "📋 Plugin Certificates:"; \
for plugin_dir in certs/mcp/plugins/*; do \
if [ -f "$$plugin_dir/server.crt" ]; then \
plugin_name=$$(basename "$$plugin_dir"); \
expiry=$$(openssl x509 -in "$$plugin_dir/server.crt" -noout -enddate | sed 's/notAfter=//'); \
echo " $$plugin_name: $$expiry"; \
fi; \
done; \
echo ""; \
fi
@echo "💡 To regenerate expired certificates, delete the cert directory and run make certs-mcp-all"
## --- gRPC Protocol Buffer Generation -----------------------------------------
# help: grpc-proto - Generate Python gRPC stubs from .proto files
.PHONY: grpc-proto
grpc-proto: ## Generate gRPC stubs for external plugin transport
@echo "🔧 Generating gRPC protocol buffer stubs..."
@test -d "$(VENV_DIR)" || $(MAKE) venv
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
$(UV_BIN) pip show grpcio-tools >/dev/null 2>&1 || \
$(UV_BIN) pip install -q grpcio-tools"
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
python -m grpc_tools.protoc \
-I mcpgateway/plugins/framework/external/grpc/proto \
--python_out=mcpgateway/plugins/framework/external/grpc/proto \
--pyi_out=mcpgateway/plugins/framework/external/grpc/proto \
--grpc_python_out=mcpgateway/plugins/framework/external/grpc/proto \
mcpgateway/plugins/framework/external/grpc/proto/plugin_service.proto"
@echo "🔧 Fixing imports in generated files..."
@if [ "$$(uname)" = "Darwin" ]; then \
sed -i '' 's/^import plugin_service_pb2/from mcpgateway.plugins.framework.external.grpc.proto import plugin_service_pb2/' \
mcpgateway/plugins/framework/external/grpc/proto/plugin_service_pb2_grpc.py; \
else \
sed -i 's/^import plugin_service_pb2/from mcpgateway.plugins.framework.external.grpc.proto import plugin_service_pb2/' \
mcpgateway/plugins/framework/external/grpc/proto/plugin_service_pb2_grpc.py; \
fi
@echo "🔧 Adding noqa comments to generated files..."
@if [ "$$(uname)" = "Darwin" ]; then \
sed -i '' '1s/^/# noqa: D100, D101, D102, D103, D104, D107, D400, D415\n# ruff: noqa\n# type: ignore\n# pylint: skip-file\n# Generated by protoc - do not edit\n/' \
mcpgateway/plugins/framework/external/grpc/proto/plugin_service_pb2.py \
mcpgateway/plugins/framework/external/grpc/proto/plugin_service_pb2_grpc.py \
mcpgateway/plugins/framework/external/grpc/proto/plugin_service_pb2.pyi; \
else \
sed -i '1s/^/# noqa: D100, D101, D102, D103, D104, D107, D400, D415\n# ruff: noqa\n# type: ignore\n# pylint: skip-file\n# Generated by protoc - do not edit\n/' \
mcpgateway/plugins/framework/external/grpc/proto/plugin_service_pb2.py \
mcpgateway/plugins/framework/external/grpc/proto/plugin_service_pb2_grpc.py \
mcpgateway/plugins/framework/external/grpc/proto/plugin_service_pb2.pyi; \
fi
@echo "✅ gRPC stubs generated in mcpgateway/plugins/framework/external/grpc/proto/"
## --- House-keeping -----------------------------------------------------------
# help: clean - Remove caches, build artefacts, virtualenv, docs, certs, coverage, SBOM, database files, etc.
.PHONY: clean
clean:
@echo "🧹 Cleaning workspace..."
@set +e; \
for dir in $(DIRS_TO_CLEAN); do \
find . -type d -name "$$dir" -prune -exec rm -rf {} +; \
done; \
set -e
@rm -f $(FILES_TO_CLEAN)
@rm -rf $(EXTRA_DIRS_TO_CLEAN)
@rm -f $(EXTRA_FILES_TO_CLEAN)
@find . -name "*.py[cod]" -delete
@find . -name "*.py,cover" -delete
@echo "✅ Clean complete."
# =============================================================================
# 🧪 TESTING
# =============================================================================
# help: 🧪 TESTING
# help: smoketest - Run smoketest.py --verbose (build container, add MCP server, test endpoints)
# help: test-protocol-compliance - MCP protocol compliance harness: full (target, transport) matrix across reference + gateway (K=<filter> to pick one)
# help: test-protocol-compliance-reference - Protocol compliance harness, reference server only (fast, always-on)
# help: test-protocol-compliance-gateway - Protocol compliance harness, gateway-proxy + gateway-virtual targets (requires working gateway boot)
# help: test-protocol-compliance-matrix - Protocol compliance matrix across every runnable engine; summary table (pass MATRIX_ARGS='--format markdown --out X' to override)
# help: test-mcp-protocol-e2e - MCP protocol E2E via FastMCP client against live gateway (K=<filter> to pick one; MCP_E2E_CLIENT_TIMEOUT env to extend the 5s client timeout)
# help: test-mcp-cli - [DEPRECATED] Alias for test-mcp-protocol-e2e (accepts same K=<filter>)
# help: test - Run unit tests with pytest
# help: test-verbose - Run tests sequentially with real-time test name output
# help: test-profile - Run tests and show slowest 20 tests (durations >= 1s)
# help: coverage - Run tests with coverage, emit HTML/XML + badge
# help: coverage-pytest - Run pytest unit tests with coverage collection
# help: coverage-annotated - Run coverage and generate annotated source files (.py,cover)
# help: test-docs - Run coverage and generate docs/docs/test/unittest.md report
# 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%)
# help: test-db-perf - Run database performance and N+1 query detection tests
# help: test-db-perf-verbose - Run database performance tests with full SQL query output
# help: 2025-11-25 - Run full MCP 2025-11-25 compliance suite (manual)
# help: 2025-11-25-core - Run MCP core compliance subset
# help: 2025-11-25-tasks - Run MCP tasks compliance subset
# help: 2025-11-25-auth - Run MCP authorization compliance subset
# help: 2025-11-25-report - Run MCP suite and emit JUnit XML + Markdown reports
# help: dev-query-log - Run dev server with query logging to file (N+1 detection)
# help: query-log-tail - Tail the database query log file
# help: query-log-analyze - Analyze query log for N+1 patterns and slow queries
# help: query-log-clear - Clear database query log files
.PHONY: smoketest test-mcp-cli test-mcp-rbac test-mcp-plugin-parity test-mcp-access-matrix test-mcp-session-isolation test-mcp-session-isolation-load test test-verbose test-profile coverage test-docs pytest-examples test-curl htmlcov doctest doctest-verbose doctest-coverage doctest-check test-db-perf test-db-perf-verbose 2025-11-25 2025-11-25-core 2025-11-25-tasks 2025-11-25-auth 2025-11-25-report dev-query-log query-log-tail query-log-analyze query-log-clear load-test load-test-ui load-test-light load-test-heavy load-test-sustained load-test-stress load-test-report load-test-compose load-test-timeserver load-test-fasttime load-test-1000 load-test-summary load-test-baseline load-test-baseline-ui load-test-baseline-stress load-test-agentgateway-mcp-server-time
# Dirs/files always excluded from standard pytest runs
PYTEST_IGNORE := tests/fuzz tests/manual test.py \
tests/e2e/test_entra_id_integration.py \
tests/e2e/test_mcp_protocol_e2e.py \
tests/e2e/test_mcp_rbac_transport.py \
tests/e2e_rust \
tests/protocol_compliance
# Expand to --ignore=<path> flags for pytest CLI
PYTEST_IGNORE_FLAGS := $(foreach p,$(PYTEST_IGNORE),--ignore=$(p))
## --- Automated checks --------------------------------------------------------
smoketest:
@echo "🚀 Running smoketest..."
@test -d "$(VENV_DIR)" || $(MAKE) venv install install-dev
@$(VENV_DIR)/bin/python ./smoketest.py --verbose || { echo "❌ Smoketest failed!"; exit 1; }
@echo "✅ Smoketest passed!"
test-mcp-protocol-e2e: ## MCP protocol E2E via FastMCP client (K=<filter> to pick one)
@echo "🔌 Running MCP protocol E2E tests against $${MCP_CLI_BASE_URL:-http://localhost:8080}..."
@echo " Env: MCP_CLI_BASE_URL (gateway URL) JWT_SECRET_KEY PLATFORM_ADMIN_EMAIL"
@echo " Timeout: $${MCP_E2E_CLIENT_TIMEOUT:-5.0}s per client operation (override MCP_E2E_CLIENT_TIMEOUT)"
@if [ -n "$(K)" ]; then echo " Filter: -k \"$(K)\""; fi
@/bin/bash -c 'source $(VENV_DIR)/bin/activate && \
$(VENV_DIR)/bin/pytest tests/e2e/test_mcp_protocol_e2e.py $(if $(K),-k "$(K)") -v -s --tb=short \
|| { echo "❌ MCP protocol E2E tests failed!"; exit 1; }; \
echo "✅ MCP protocol E2E tests passed!"'
test-mcp-cli: ## [DEPRECATED] Alias for test-mcp-protocol-e2e (subprocess + mcp-cli path removed)
@echo "⚠️ 'make test-mcp-cli' is deprecated — use 'make test-mcp-protocol-e2e'."
@echo " The mcp-cli + mcpgateway.wrapper subprocess path was replaced by the FastMCP client."
@$(MAKE) test-mcp-protocol-e2e
test-protocol-compliance: ## MCP protocol compliance harness — full (target, transport) matrix (K=<filter> to pick one)
@echo "📜 Running MCP protocol compliance harness (tests/protocol_compliance)..."
@if [ -n "$(K)" ]; then echo " Filter: -k \"$(K)\""; fi
@/bin/bash -c 'source $(VENV_DIR)/bin/activate && \
$(VENV_DIR)/bin/pytest tests/protocol_compliance $(if $(K),-k "$(K)") -v --tb=short \
|| { echo "❌ protocol compliance harness failed!"; exit 1; }; \
echo "✅ protocol compliance harness passed!"'
test-protocol-compliance-reference: ## Protocol compliance harness — reference server only (fast, always-on)
@echo "📜 Running MCP protocol compliance harness (reference target only)..."
@/bin/bash -c 'source $(VENV_DIR)/bin/activate && \
$(VENV_DIR)/bin/pytest tests/protocol_compliance -k "reference-stdio" -v --tb=short \
|| { echo "❌ reference-target compliance harness failed!"; exit 1; }; \
echo "✅ reference-target compliance harness passed!"'
test-protocol-compliance-gateway: ## Protocol compliance harness — gateway-proxy + gateway-virtual (needs in-process gateway boot to succeed)
@echo "📜 Running MCP protocol compliance harness (gateway targets)..."
@/bin/bash -c 'source $(VENV_DIR)/bin/activate && \
$(VENV_DIR)/bin/pytest tests/protocol_compliance -k "gateway_proxy or gateway_virtual" -v --tb=short \
|| { echo "❌ gateway-target compliance harness failed!"; exit 1; }; \
echo "✅ gateway-target compliance harness passed!"'
test-protocol-compliance-matrix: ## MCP compliance matrix across every runnable engine (reference, python, rust_edge, rust_full) with aggregated summary
@/bin/bash -c 'source $(VENV_DIR)/bin/activate && \
$(VENV_DIR)/bin/python scripts/compliance_matrix.py $(MATRIX_ARGS)'
test-mcp-rbac: ## RBAC + multi-transport MCP protocol tests (needs live gateway + SSE)
@echo "🔐 Running RBAC + multi-transport MCP protocol tests against $${MCP_CLI_BASE_URL:-http://localhost:8080}..."
@echo " Requires: docker-compose stack with SSE gateway registered"
@/bin/bash -c 'source $(VENV_DIR)/bin/activate && \
$(UV_BIN) pip show pytest-playwright >/dev/null 2>&1 || \
{ echo "📦 Installing playwright dependencies..."; $(UV_BIN) pip install -q ".[playwright]" && $(VENV_DIR)/bin/playwright install --with-deps chromium; } && \
$(VENV_DIR)/bin/pytest tests/e2e/test_mcp_rbac_transport.py -v -s --tb=short \
|| { echo "❌ MCP RBAC transport tests failed!"; exit 1; }; \
echo "✅ MCP RBAC transport tests passed!"'
test-mcp-access-matrix: ## Detailed Rust MCP role/access matrix test with strong tool/resource/prompt sentinels
@echo "🧪 Running MCP role/access matrix tests against $${MCP_CLI_BASE_URL:-http://localhost:8080}..."
@echo " Requires: docker-compose stack rebuilt in Rust edge/full mode"
@/bin/bash -c 'source $(VENV_DIR)/bin/activate && \
$(VENV_DIR)/bin/pytest tests/e2e_rust/test_mcp_access_matrix.py -v -s --tb=short \
|| { echo "❌ MCP role/access matrix tests failed!"; exit 1; }; \
echo "✅ MCP role/access matrix tests passed!"'
test-mcp-plugin-parity: ## MCP plugin parity E2E for current Python or Rust stack using a test-specific plugin config
@echo "🧪 Running MCP plugin parity tests against $${MCP_CLI_BASE_URL:-http://localhost:8080}..."
@echo " Requires: stack started with PLUGINS_CONFIG_FILE=plugins/plugin_parity_config.yaml"
@/bin/bash -c 'source $(VENV_DIR)/bin/activate && \
$(VENV_DIR)/bin/pytest tests/e2e/test_mcp_plugin_parity.py -v -s --tb=short \
|| { echo "❌ MCP plugin parity tests failed!"; exit 1; }; \
echo "✅ MCP plugin parity tests passed!"'
test-mcp-session-isolation: ## MCP session/auth isolation tests for the Rust public transport path
@echo "🧪 Running MCP session/auth isolation tests against $${MCP_CLI_BASE_URL:-http://localhost:8080}..."
@echo " Requires: docker-compose stack rebuilt in Rust edge/full mode"
@/bin/bash -c 'source $(VENV_DIR)/bin/activate && \
$(VENV_DIR)/bin/pytest tests/e2e_rust/test_mcp_session_isolation.py -v -s --tb=short \
|| { echo "❌ MCP session/auth isolation tests failed!"; exit 1; }; \
echo "✅ MCP session/auth isolation tests passed!"'
MCP_ISOLATION_LOCUSTFILE ?= tests/loadtest/locustfile_mcp_isolation.py
MCP_ISOLATION_LOAD_HOST ?= http://localhost:8080
MCP_ISOLATION_LOAD_USERS ?= 12
MCP_ISOLATION_LOAD_SPAWN_RATE ?= 3
MCP_ISOLATION_LOAD_RUN_TIME ?= 60s
test-mcp-session-isolation-load: ## Multi-user MCP session/auth isolation correctness load test
@echo "🧪 Running MCP session/auth isolation load test against $(MCP_ISOLATION_LOAD_HOST)..."
@echo " Requires: docker-compose stack rebuilt in Rust full mode"
@test -d "$(VENV_DIR)" || $(MAKE) venv
@/bin/bash -eu -o pipefail -c 'source $(VENV_DIR)/bin/activate && \
locust -f $(MCP_ISOLATION_LOCUSTFILE) \
--host=$(MCP_ISOLATION_LOAD_HOST) \
--users=$(MCP_ISOLATION_LOAD_USERS) \
--spawn-rate=$(MCP_ISOLATION_LOAD_SPAWN_RATE) \
--run-time=$(MCP_ISOLATION_LOAD_RUN_TIME) \
--headless \
--stop-timeout=30 \
--exit-code-on-error=1 \
--only-summary'
test:
@echo "🧪 Running tests..."
@test -d "$(VENV_DIR)" || $(MAKE) venv
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
export DATABASE_URL='sqlite:///:memory:' && \
export TEST_DATABASE_URL='sqlite:///:memory:' && \
export ARGON2ID_TIME_COST=1 && \
export ARGON2ID_MEMORY_COST=1024 && \
$(VENV_DIR)/bin/pytest -n auto --maxfail=0 -v --durations=5 \
$(PYTEST_IGNORE_FLAGS)"
test-verbose:
@echo "🧪 Running tests (verbose, sequential)..."
@test -d "$(VENV_DIR)" || $(MAKE) venv
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
export DATABASE_URL='sqlite:///:memory:' && \
export TEST_DATABASE_URL='sqlite:///:memory:' && \
export ARGON2ID_TIME_COST=1 && \
export ARGON2ID_MEMORY_COST=1024 && \
$(VENV_DIR)/bin/pytest --maxfail=0 -v --tb=short --instafail $(PYTEST_IGNORE_FLAGS)"
test-profile:
@echo "🧪 Running tests with profiling (showing slowest tests)..."
@test -d "$(VENV_DIR)" || $(MAKE) venv
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
export DATABASE_URL='sqlite:///:memory:' && \
export TEST_DATABASE_URL='sqlite:///:memory:' && \
export ARGON2ID_TIME_COST=1 && \
export ARGON2ID_MEMORY_COST=1024 && \
$(VENV_DIR)/bin/pytest -n 16 --durations=20 --durations-min=1.0 --disable-warnings -v $(PYTEST_IGNORE_FLAGS)"
.PHONY: coverage-pytest
coverage-pytest: install-dev
@test -d "$(VENV_DIR)" || $(MAKE) venv
@mkdir -p $(TEST_DOCS_DIR)
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
export DATABASE_URL='sqlite:///:memory:' && \
export TEST_DATABASE_URL='sqlite:///:memory:' && \
export BASIC_AUTH_PASSWORD='TestCoveragePassw0rd!42' && \
export PLATFORM_ADMIN_PASSWORD='TestCoveragePassw0rd!42' && \
export DEFAULT_USER_PASSWORD='TestCoveragePassw0rd!42' && \
export JWT_SECRET_KEY='coverage-test-jwt-secret-key-1234567890' && \
export AUTH_ENCRYPTION_SECRET='coverage-test-auth-encryption-1234567890' && \
python3 -m pytest -p pytest_cov --reruns=1 --reruns-delay 30 \
--dist loadgroup -n auto -rfE --cov-append --capture=fd -v \
--durations=120 --cov-report=term --cov=mcpgateway \
$(PYTEST_IGNORE_FLAGS) tests/ || true"
coverage: coverage-pytest install-dev
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
export DATABASE_URL='sqlite:///:memory:' && \
export TEST_DATABASE_URL='sqlite:///:memory:' && \
export BASIC_AUTH_PASSWORD='TestCoveragePassw0rd!42' && \
export PLATFORM_ADMIN_PASSWORD='TestCoveragePassw0rd!42' && \
export DEFAULT_USER_PASSWORD='TestCoveragePassw0rd!42' && \
export JWT_SECRET_KEY='coverage-test-jwt-secret-key-1234567890' && \
export AUTH_ENCRYPTION_SECRET='coverage-test-auth-encryption-1234567890' && \
python3 -m pytest -p pytest_cov --reruns=1 --reruns-delay 30 \
--dist loadgroup -n auto -rfE --cov-append --capture=fd -v \
--durations=120 --doctest-modules mcpgateway/ --cov-report=term \
--cov=mcpgateway mcpgateway/ || true"
@/bin/bash -c "source $(VENV_DIR)/bin/activate && coverage html -d $(COVERAGE_DIR) --include=mcpgateway/*"
@/bin/bash -c "source $(VENV_DIR)/bin/activate && coverage xml"
@/bin/bash -c "source $(VENV_DIR)/bin/activate && coverage report -m --no-skip-covered"
@echo "✅ Coverage artefacts: HTML in $(COVERAGE_DIR) & XML ✔"
.PHONY: coverage-annotated
coverage-annotated: coverage
@echo "🔍 Generating annotated coverage files..."
@/bin/bash -c "source $(VENV_DIR)/bin/activate && coverage annotate -d ."
@echo "✅ Annotated files (.py,cover) generated ✔"
test-docs:
@echo "📝 Generating test documentation (docs/docs/test/unittest.md)..."
@test -d "$(VENV_DIR)" || $(MAKE) venv
@mkdir -p $(TEST_DOCS_DIR)
@printf "# Unit tests\n\n" > $(DOCS_DIR)/docs/test/unittest.md
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
export DATABASE_URL='sqlite:///:memory:' && \
export TEST_DATABASE_URL='sqlite:///:memory:' && \
python3 -m pytest -p pytest_cov --reruns=1 --reruns-delay 30 \
--dist loadgroup -n 8 -rA --cov-append --capture=fd -v \
--durations=120 --doctest-modules mcpgateway/ --cov-report=term \
--cov=mcpgateway mcpgateway/ || true"
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
export DATABASE_URL='sqlite:///:memory:' && \
export TEST_DATABASE_URL='sqlite:///:memory:' && \
python3 -m pytest -p pytest_cov --reruns=1 --reruns-delay 30 \
--md-report --md-report-output=$(DOCS_DIR)/docs/test/unittest.md \
--dist loadgroup -n 8 -rA --cov-append --capture=fd -v \
--durations=120 --cov-report=term --cov=mcpgateway \
$(PYTEST_IGNORE_FLAGS) tests/ || true"
@printf '\n## Coverage report\n\n' >> $(DOCS_DIR)/docs/test/unittest.md
@/bin/bash -c "source $(VENV_DIR)/bin/activate && \
coverage report --format=markdown -m --no-skip-covered \
>> $(DOCS_DIR)/docs/test/unittest.md"
@echo "✅ Test docs generated → $(DOCS_DIR)/docs/test/unittest.md"
htmlcov:
@echo "📊 Generating HTML coverage report..."
@test -d "$(VENV_DIR)" || $(MAKE) venv
@mkdir -p $(COVERAGE_DIR)
# If there's no existing coverage data, fall back to the full test-run
@if [ ! -f .coverage ]; then \