Cleanup docs, add roadmap, update dependencies, add smoketest.py

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

Author: crivetimihai

README.md

@@ -78,6 +78,7 @@ export MCPGATEWAY_BEARER_TOKEN=$(python3 -m mcpgateway.utils.create_jwt_token --
 # Run a local MCP Server (github) listening on SSE http://localhost:8000/sse
 pip install uvenv
 npx -y supergateway --stdio "uvenv run mcp-server-git"
+# or time: npx -y supergateway --stdio "uvenv run mcp_server_time -- --local-timezone=Europe/Dublin" --port 8002
 
 #--------------------------------------------
 # Register the MCP Server with the gateway and test it

docs/docs/architecture/.pages

@@ -1,3 +1,4 @@
 nav:
   - Overview: index.md
+  - Roadmap: roadmap.md
   - Decision Records: adr

docs/docs/architecture/roadmap.md

@@ -0,0 +1,164 @@
+# Roadmap
+
+---
+
+## 🔐 Authentication & Identity
+
+### 🧭 [#87 Epic: JWT Token Catalog with Per-User Expiry and Revocation](https://github.com/IBM/mcp-context-forge/issues/87)
+
+???+ "Token Lifecycle Management"
+    **Generate Tokens:** As a platform admin, I want to generate one-time API tokens so I can issue short-lived credentials.
+
+    **Revoke Tokens:** As a platform admin, I want to revoke tokens so I can disable exposed or obsolete tokens.
+
+    **API Token Management:** As a user or automation client, I want to list, create, and revoke tokens via API so I can automate credential workflows.
+
+🧭 Epic: Per-Virtual-Server API Keys
+
+???+ "Scoped Server Access"
+    **Server-Scoped Keys:** As a platform admin, I want to create API keys tied to a specific virtual server so that credentials are limited in scope.
+
+    **Key Rotation & Revocation:** As a platform admin, I want to rotate or revoke a virtual server's API keys so I can maintain security without affecting other servers.
+
+    **API Management UI & API:** As a developer, I want to list, create, rotate, and revoke server API keys via the Admin UI and REST API so I can automate credential lifecycle for each virtual server.
+
+---
+
+## 📈 Observability & Telemetry
+
+### 🧭 Epic: OpenTelemetry Tracing & Metrics Export
+
+???+ "Trace & Metric Visibility"
+    **Distributed Tracing:** As a developer, I want traces spanning tools, prompts, and gateways so I can understand multi-step flows.
+
+    **Metrics Scraping:** As an SRE, I want a Prometheus-compatible `/metrics` endpoint so I can alert on latency and error rate.
+
+### 🧭 Epic: Structured JSON Logging with Correlation IDs
+
+???+ "Context-Rich Logging"
+    **Correlation IDs:** As a DevOps user, I want logs with correlation and trace IDs so I can trace a request across services.
+
+---
+
+## ⚙️ Lifecycle & Management
+
+### 🧭 Epic: Hot Configuration Reload
+
+???+ "Dynamic Config Updates"
+    **In-Place Reload:** As a system admin, I want to apply config changes (tools, servers, resources) without restarts so I maintain zero-downtime.
+
+### 🧭 Epic: CLI Enhancements for Admin Operations
+
+???+ "Automated Admin Commands"
+    **Admin CLI:** As a DevOps engineer, I want CLI subcommands to register tools, flush caches, and export configs so I can integrate with CI/CD.
+
+### 🧭 Epic: Config Import/Export (JSON Gateways & Virtual Servers)
+
+???+ "JSON Config Portability"
+    **Individual Entity Export/Import:** As a platform admin, I want to export or import a single gateway or virtual server's config in JSON so I can backup or migrate that one entity.
+
+    **Bulk Export/Import:** As a platform admin, I want to export or import the full configuration (all gateways, virtual servers, prompts, resources) at once so I can replicate environments or perform large-scale updates.
+
+    **Encrypted Credentials:** As a security-conscious operator, I want passwords and sensitive fields in exported JSON to be encrypted so my backups remain secure.
+
+???+ "Automated Admin Commands"
+    **Admin CLI:** As a DevOps engineer, I want CLI subcommands to register tools, flush caches, and export configs so I can integrate with CI/CD.
+
+### 🧭 Epic: Cache Management API
+
+???+ "Cache Control"
+    **Cache Inspection & Flush:** As a site admin, I want endpoints to view cache stats and clear entries so I can manage data freshness.
+
+---
+
+## 🌐 Federation & Routing
+
+### 🧭 Epic: Dynamic Federation Management
+
+???+ "Peer Gateway Management"
+    **Register/Remove Peers:** As a platform admin, I want to add or remove federated gateways at runtime so I can scale and maintain federation.
+
+### 🧭 Epic: Circuit Breakers for Unstable Backends
+
+???+ "Backend Isolation"
+    **Circuit Breaker:** As the gateway, I want to trip circuits for backends after repeated failures so I prevent cascading retries.
+
+### 🧭 Epic: Intelligent Load Balancing for Redundant Servers
+
+???+ "Smart Request Routing"
+    **Adaptive Balancing:** As an orchestrator, I want to route to the fastest healthy backend instance so I optimize response times.
+
+---
+
+## 🛠️ Developer Experience
+
+### 🧭 Epic: Prompt Template Tester & Validator
+
+???+ "Prompt Validation"
+    **Template Linting:** As a prompt engineer, I want to preview and validate Jinja2 templates with sample data so I avoid runtime errors.
+
+### 🧭 Epic: System Diagnostics & Self-Check Report
+
+???+ "Diagnostics Bundle"
+    **Diagnostic Export:** As an operator, I want a self-contained system report (config, health, metrics) so I can troubleshoot effectively.
+
+### 🧭 Epic: Auto-Tuning of Timeout & Retry Policies
+
+???+ "Adaptive Policy Tuning"
+    **Auto-Tuning:** As the gateway, I want to adjust timeouts and retry intervals based on observed latencies so I balance reliability and speed.
+
+---
+
+## 📦 Resilience & Runtime
+
+### 🧭 Epic: Graceful Startup and Shutdown
+
+???+ "Graceful Lifecycle"
+    **In-Flight Draining:** As the gateway, I want to complete active requests before shutdown so I prevent dropped connections.
+
+### 🧭 Epic: High Availability via Stateless Clustering
+
+???+ "Clustered Scaling"
+    **Stateless Instances:** As an architect, I want multiple interchangeable gateway nodes so I can load-balance and ensure failover.
+
+---
+
+## 🧭 Namespaces & Catalog Integrity
+
+### 🧭 Epic: Name Collision Handling in Federated Catalogs
+
+???+ "Unified Naming"
+    **Namespaced Tools:** As an operator, I want to distinguish identical tool names from different servers (e.g. `ServerA/toolX` vs `ServerB/toolX`) so I avoid conflicts.
+
+---
+
+## 🔐 Secrets & Sensitive Data
+
+### 🧭 Epic: Secure Secrets Management & Masking
+
+???+ "Externalized Secrets"
+    **Secret Store Integration:** As an operator, I want to fetch credentials from a secrets manager so I avoid storing secrets in static configs.
+
+    **Log Scrubbing:** As a compliance officer, I want sensitive data masked in logs and metrics so I maintain data security.
+
+---
+
+### 🧭 Epic: LDAP & External Identity Integration
+
+???+ "Corporate Directory Auth"
+    **LDAP Authentication:** As a platform admin, I want to configure LDAP/Active Directory so that users authenticate with corporate credentials.
+
+    **Group Sync:** As a platform admin, I want to sync LDAP/AD groups into gateway roles so I can manage permissions via directory groups.
+
+    **SSO Integration:** As a platform admin, I want to support SAML/OIDC so that teams can use existing single sign-on.
+
+---
+
+### 🧭 Epic: Role-Based Access Control (User/Team/Global Scopes)
+
+???+ "RBAC & Scoping"
+    **User-Level Scopes:** As a platform admin, I want to assign permissions at the individual user level so that I can grant fine-grained access.
+
+    **Team-Level Scopes:** As a platform admin, I want to define teams and grant scopes to teams so that I can manage permissions for groups of users.
+
+    **Global Scopes:** As a platform admin, I want to set global default scopes so that baseline permissions apply to all users.

docs/requirements.txt

@@ -14,9 +14,9 @@ colorama>=0.4.6
 csscompressor>=0.9.5
 cssselect2>=0.8.0
 defusedxml>=0.7.1
-EditorConfig>=0.17.0
+EditorConfig>=0.17.1
 flatten-json>=0.1.14
-fonttools>=4.58.0
+fonttools>=4.58.2
 funcparserlib>=1.0.1
 ghp-import>=2.1.0
 gitdb>=4.0.12
@@ -38,8 +38,8 @@ mkdocs>=1.6.1
 mkdocs-awesome-pages-plugin>=2.10.1
 mkdocs-blog-plugin>=0.25
 mkdocs-enumerate-headings-plugin>=0.6.2
-mkdocs-git-authors-plugin>=0.9.5
-mkdocs-git-revision-date-localized-plugin>=1.4.5
+mkdocs-git-authors-plugin>=0.10.0
+mkdocs-git-revision-date-localized-plugin>=1.4.7
 mkdocs-glightbox>=0.4.0
 mkdocs-include-markdown-plugin>=7.1.5
 mkdocs-material>=9.6.14
@@ -49,15 +49,15 @@ mkdocs-mermaid2-plugin>=1.2.1
 mkdocs-minify-plugin>=0.8.0
 mkdocs-pdf-export-plugin>=0.5.10
 mkdocs-plugin-inline-svg>=0.1.0
-mkdocs-rss-plugin>=1.17.1
+mkdocs-rss-plugin>=1.17.3
 mkdocs-table-reader-plugin>=3.1.0
 mkdocs-with-pdf>=0.9.3
 natsort>=8.4.0
-numpy>=2.2.6
+numpy>=2.3.0
 nwdiag>=3.0.0
 packaging>=25.0
 paginate>=0.5.7
-pandas>=2.2.3
+pandas>=2.3.0
 pathspec>=0.12.1
 pillow>=11.2.1
 platformdirs>=4.3.8
@@ -72,7 +72,7 @@ pytz>=2025.2
 PyYAML>=6.0.2
 pyyaml_env_tag>=1.1
 regex>=2024.11.6
-requests>=2.32.3
+requests>=2.32.4
 seqdiag>=3.0.0
 six>=1.17.0
 smmap>=5.0.2
@@ -86,5 +86,5 @@ wcmatch>=10.0
 weasyprint>=65.1
 webcolors>=24.11.1
 webencodings>=0.5.1
-zipp>=3.21.0
+zipp>=3.23.0
 zopfli>=0.2.3.post1

mcpgateway/services/gateway_service.py

@@ -37,6 +37,7 @@
 
 try:
     import redis
+
     REDIS_AVAILABLE = True
 except ImportError:
     REDIS_AVAILABLE = False
@@ -110,9 +111,9 @@ def __init__(self):
 
         if self.redis_url and REDIS_AVAILABLE:
             self._redis_client = redis.from_url(self.redis_url)
-            self._instance_id = str(uuid.uuid4())             # Unique ID for this process
+            self._instance_id = str(uuid.uuid4())  # Unique ID for this process
             self._leader_key = "gateway_service_leader"
-            self._leader_ttl = 40                             # seconds
+            self._leader_ttl = 40  # seconds
         elif settings.cache_type != "none":
             # Fallback: File-based lock
             self._redis_client = None

mcpgateway/version.py

@@ -395,6 +395,7 @@ async def version_endpoint(
     if partial:
         # Return partial HTML fragment for HTMX embedding
         from fastapi.templating import Jinja2Templates
+
         templates = Jinja2Templates(directory="mcpgateway/templates")
         return templates.TemplateResponse("version_info_partial.html", {"request": request, "payload": payload})
     wants_html = fmt == "html" or "text/html" in request.headers.get("accept", "")

pyproject.toml

@@ -46,15 +46,16 @@ maintainers = [
 # Runtime dependencies
 # ----------------------------------------------------------------
 dependencies = [
-    "cryptography>=45.0.3",
+    "cryptography>=45.0.4",
     "fastapi>=0.115.12",
+    "filelock>=3.18.0",
     "gunicorn>=23.0.0",
     "httpx>=0.28.1",
     "jinja2>=3.1.6",
     "jq>=1.8.0",
     "jsonpath-ng>=1.7.0",
     "jsonschema>=4.24.0",
-    "mcp>=1.9.3",
+    "mcp>=1.9.4",
     "parse>=1.20.2",
     "psutil>=7.0.0",
     "pydantic>=2.11.5",
@@ -65,7 +66,6 @@ dependencies = [
     "starlette>=0.46.2",
     "uvicorn>=0.34.3",
     "zeroconf>=0.147.0",
-    "filelock>=3.18.0",
 ]
 
 # ----------------------------------------------------------------
@@ -102,7 +102,7 @@ dev = [
     "check-manifest>=0.50",
     "code2flow>=2.5.1",
     "cookiecutter>=2.6.0",
-    "coverage>=7.8.2",
+    "coverage>=7.9.0",
     "coverage-badge>=1.1.2",
     "darglint>=1.8.1",
     "fawltydeps>=0.20.0",
@@ -119,12 +119,12 @@ dev = [
     "pylint>=3.3.7",
     "pylint-pydantic>=0.3.5",
     "pyre-check>=0.9.23",
-    "pyright>=1.1.401",
+    "pyright>=1.1.402",
     "pyroma>=4.2",
     "pyspelling>=2.10",
     "pytest>=8.4.0",
     "pytest-asyncio>=1.0.0",
-    "pytest-cov>=6.1.1",
+    "pytest-cov>=6.2.1",
     "pytest-examples>=0.0.18",
     "pytest-md-report>=0.7.0",
     "pytest-rerunfailures>=15.1",
@@ -136,7 +136,7 @@ dev = [
     "snakeviz>=2.2.2",
     "tomlcheck>=0.2.3",
     "twine>=6.1.0",
-    "ty>=0.0.1a8",
+    "ty>=0.0.1a9",
     "types-tabulate>=0.9.0.20241207",
 ]