addressed review comments

Author: blublinsky

Makefile

@@ -29,10 +29,10 @@ test-e2e-local: ## Run end to end tests for the service
 
 
 check-types: ## Checks type hints in sources
-	uv run mypy --explicit-package-bases --disallow-untyped-calls --disallow-untyped-defs --disallow-incomplete-defs --ignore-missing-imports --disable-error-code attr-defined src/ tests/unit tests/integration tests/e2e/
+	uv run mypy --explicit-package-bases --disallow-untyped-calls --disallow-untyped-defs --disallow-incomplete-defs --ignore-missing-imports --disable-error-code attr-defined src/ tests/unit tests/integration tests/e2e/ dev-tools/
 
 security-check: ## Check the project for security issues
-	bandit -c pyproject.toml -r src tests
+	uv run bandit -c pyproject.toml -r src tests dev-tools
 
 format: ## Format the code into unified format
 	uv run black .
@@ -82,13 +82,13 @@ black:	## Check source code using Black code formatter
 	uv run black --check .
 
 pylint:	## Check source code using Pylint static code analyser
-	uv run pylint src tests
+	uv run pylint src tests dev-tools
 
 pyright:	## Check source code using Pyright static type checker
-	uv run pyright src
+	uv run pyright src dev-tools
 
 docstyle:	## Check the docstring style using Docstyle checker
-	uv run pydocstyle -v src
+	uv run pydocstyle -v src dev-tools
 
 ruff:	## Check source code using Ruff linter
 	uv run ruff check . --per-file-ignores=tests/*:S101 --per-file-ignores=scripts/*:S101

README.md

@@ -302,21 +302,21 @@ MCP (Model Context Protocol) servers provide tools and capabilities to the AI ag
 
 **Basic Configuration Structure:**
 
-Each MCP server requires three fields:
+Each MCP server requires two fields:
 - `name`: Unique identifier for the MCP server
-- `provider_id`: MCP provider identification (typically `"model-context-protocol"`)
 - `url`: The endpoint where the MCP server is running
 
+And one optional field:
+- `provider_id`: MCP provider identification (defaults to `"model-context-protocol"`)
+
 **Minimal Example:**
 
 ```yaml
 mcp_servers:
   - name: "filesystem-tools"
-    provider_id: "model-context-protocol"
-    url: "http://localhost:3000"
+    url: "http://localhost:9000"
   - name: "git-tools"
-    provider_id: "model-context-protocol"
-    url: "http://localhost:3001"
+    url: "http://localhost:9001"
 ```
 
 In addition to the basic configuration above, you can configure authentication headers for your MCP servers to securely communicate with services that require credentials.
@@ -332,7 +332,6 @@ Store authentication tokens in secret files and reference them in your configura
 ```yaml
 mcp_servers:
   - name: "api-service"
-    provider_id: "model-context-protocol"
     url: "http://api-service:8080"
     authorization_headers:
       Authorization: "/var/secrets/api-token"      # Path to file containing token
@@ -356,7 +355,6 @@ Use the special `"kubernetes"` keyword to automatically use the authenticated us
 ```yaml
 mcp_servers:
   - name: "k8s-internal-service"
-    provider_id: "model-context-protocol"
     url: "http://internal-mcp.default.svc.cluster.local:8080"
     authorization_headers:
       Authorization: "kubernetes"    # Uses user's k8s token from request auth
@@ -371,7 +369,6 @@ Use the special `"client"` keyword to allow clients to provide custom tokens per
 ```yaml
 mcp_servers:
   - name: "user-specific-service"
-    provider_id: "model-context-protocol"
     url: "http://user-service:8080"
     authorization_headers:
       Authorization: "client"         # Token provided via MCP-HEADERS
@@ -387,7 +384,9 @@ curl -X POST "http://localhost:8080/v1/query" \
   -d '{"query": "Get my data"}'
 ```
 
-**Note**: The `MCP-HEADERS` dictionary is keyed by **server name** (not URL), matching the `name` field in your MCP server configuration.
+**Note**: `MCP-HEADERS` is an **HTTP request header** containing a JSON-encoded dictionary. The dictionary is keyed by **server name** (not URL), matching the `name` field in your MCP server configuration. Each server name maps to another dictionary containing the HTTP headers to forward to that specific MCP server.
+
+**Structure**: `MCP-HEADERS: {"<server-name>": {"<header-name>": "<header-value>", ...}, ...}`
 
 ##### Combining Authentication Methods
 
@@ -397,21 +396,18 @@ You can mix and match authentication methods across different MCP servers, and e
 mcp_servers:
   # Static credentials for public API
   - name: "weather-api"
-    provider_id: "model-context-protocol"
     url: "http://weather-api:8080"
     authorization_headers:
       X-API-Key: "/var/secrets/weather-api-key"
   
   # Kubernetes auth for internal services
   - name: "internal-db"
-    provider_id: "model-context-protocol"
     url: "http://db-mcp.cluster.local:8080"
     authorization_headers:
       Authorization: "kubernetes"
   
   # Mixed: static API key + per-user token
   - name: "multi-tenant-service"
-    provider_id: "model-context-protocol"
     url: "http://multi-tenant:8080"
     authorization_headers:
       X-Service-Key: "/var/secrets/service-key"    # Static service credential
@@ -1118,7 +1114,7 @@ python dev-tools/mcp-mock-server/server.py
 # Add to lightspeed-stack.yaml:
 mcp_servers:
   - name: "mock-test"
-    url: "http://localhost:3000"
+    url: "http://localhost:9000"
     authorization_headers:
       Authorization: "/tmp/test-token"
 ```

dev-tools/MANUAL_TESTING.md

@@ -59,6 +59,30 @@ curl -X POST http://localhost:8080/v1/streaming_query \
   -d '{"query": "Test all MCP auth types"}'
 ```
 
+<details>
+<summary><b>Optional: Using Real Tokens (for production testing)</b></summary>
+
+If you want to test with actual tokens instead of mock values:
+
+```bash
+# Extract real Kubernetes token (requires oc or kubectl)
+K8S_TOKEN=$(oc whoami -t 2>/dev/null || kubectl get secret -o jsonpath='{.data.token}' | base64 -d)
+
+# Set your client token
+CLIENT_TOKEN="your-actual-client-token"
+
+# Make request with real tokens
+curl -X POST http://localhost:8080/v1/streaming_query \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer ${K8S_TOKEN}" \
+  -H "MCP-HEADERS: {\"mock-client-auth\": {\"Authorization\": \"Bearer ${CLIENT_TOKEN}\"}}" \
+  -d '{"query": "Test with real tokens"}'
+```
+
+**Note:** The mock MCP server doesn't validate tokens, so the simple example above is sufficient for local testing.
+
+</details>
+
 **What This Tests:**
 - **`mock-file-auth`**: Uses static token from `/tmp/lightspeed-mcp-test-token`
 - **`mock-k8s-auth`**: Forwards the Kubernetes token from your `Authorization` header
@@ -91,7 +115,7 @@ The mock server should return unique tool names for each auth type:
 - `mock_tool_client` - from `mock-client-auth`
 
 Check the Lightspeed Core logs, you should see:
-```
+```text
 DEBUG    Configured 3 MCP tools: ['mock-file-auth', 'mock-k8s-auth', 'mock-client-auth']
 ```
 

dev-tools/mcp-mock-server/README.md

@@ -11,6 +11,8 @@ This mock server helps developers:
 - Develop and test MCP-related features
 - Test both HTTP and HTTPS connections
 
+**⚠️ Testing Only:** This server is single-threaded and handles requests sequentially. It is designed purely for development and testing purposes, not for production or high-load scenarios.
+
 ## Features
 
 - ✅ **Pure Python** - No external dependencies (uses stdlib only)

dev-tools/mcp-mock-server/server.py

@@ -23,19 +23,19 @@
 from http.server import HTTPServer, BaseHTTPRequestHandler
 from datetime import datetime
 from pathlib import Path
-from typing import Dict
+from typing import Any
 
 
 # Global storage for captured headers (last request)
-last_headers: Dict[str, str] = {}
+last_headers: dict[str, str] = {}
 request_log: list = []
 
 
 class MCPMockHandler(BaseHTTPRequestHandler):
     """HTTP request handler for mock MCP server."""
 
-    def log_message(self, format, *args) -> None:  # pylint: disable=redefined-builtin
-        """Log requests with timestamp."""
+    def log_message(self, format: str, *args: Any) -> None:
+        """Log requests with timestamp."""  # pylint: disable=redefined-builtin
         timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
         print(f"[{timestamp}] {format % args}")
 
@@ -79,19 +79,22 @@ def do_POST(self) -> None:  # pylint: disable=invalid-name
 
         # Determine tool name based on authorization header to avoid collisions
         auth_header = self.headers.get("Authorization", "")
-        if "test-secret-token" in auth_header:
-            tool_name = "mock_tool_file"
-            tool_desc = "Mock tool with file-based auth"
-        elif "my-k8s-token" in auth_header:
-            tool_name = "mock_tool_k8s"
-            tool_desc = "Mock tool with Kubernetes token"
-        elif "my-client-token" in auth_header:
-            tool_name = "mock_tool_client"
-            tool_desc = "Mock tool with client-provided token"
-        else:
-            # No auth header or unrecognized token
-            tool_name = "mock_tool_no_auth"
-            tool_desc = "Mock tool with no authorization"
+
+        # Match based on token content
+        match auth_header:
+            case _ if "test-secret-token" in auth_header:
+                tool_name = "mock_tool_file"
+                tool_desc = "Mock tool with file-based auth"
+            case _ if "my-k8s-token" in auth_header:
+                tool_name = "mock_tool_k8s"
+                tool_desc = "Mock tool with Kubernetes token"
+            case _ if "my-client-token" in auth_header:
+                tool_name = "mock_tool_client"
+                tool_desc = "Mock tool with client-provided token"
+            case _:
+                # No auth header or unrecognized token
+                tool_name = "mock_tool_no_auth"
+                tool_desc = "Mock tool with no authorization"
 
         # Handle MCP protocol methods
         if method == "initialize":
@@ -150,51 +153,53 @@ def do_POST(self) -> None:  # pylint: disable=invalid-name
 
     def do_GET(self) -> None:  # pylint: disable=invalid-name
         """Handle GET requests (debug endpoints)."""
-        # Debug endpoint to view captured headers
-        if self.path == "/debug/headers":
-            self.send_response(200)
-            self.send_header("Content-Type", "application/json")
-            self.end_headers()
-            response = {
-                "last_headers": last_headers,
-                "request_count": len(request_log),
-            }
-            self.wfile.write(json.dumps(response, indent=2).encode())
-
-        # Debug endpoint to view request log
-        elif self.path == "/debug/requests":
-            self.send_response(200)
-            self.send_header("Content-Type", "application/json")
-            self.end_headers()
-            self.wfile.write(json.dumps(request_log, indent=2).encode())
-
-        # Root endpoint - show help
-        elif self.path == "/":
-            self.send_response(200)
-            self.send_header("Content-Type", "text/html")
-            self.end_headers()
-            help_html = """
-            <html>
-            <head><title>MCP Mock Server</title></head>
-            <body>
-                <h1>MCP Mock Server</h1>
-                <p>This is a development mock server for testing MCP integrations.</p>
-                <h2>Debug Endpoints:</h2>
-                <ul>
-                    <li><a href="/debug/headers">/debug/headers</a> - View last captured headers</li>
-                    <li><a href="/debug/requests">/debug/requests</a> - View recent request log</li>
-                </ul>
-                <h2>MCP Endpoints:</h2>
-                <ul>
-                    <li>POST /mcp/v1/list_tools - Mock MCP tools endpoint</li>
-                </ul>
-            </body>
-            </html>
-            """
-            self.wfile.write(help_html.encode())
-        else:
-            self.send_response(404)
-            self.end_headers()
+        # Handle different GET endpoints
+        match self.path:
+            case "/debug/headers":
+                self._send_json_response(
+                    {"last_headers": last_headers, "request_count": len(request_log)}
+                )
+            case "/debug/requests":
+                self._send_json_response(request_log)
+            case "/":
+                self._send_help_page()
+            case _:
+                self.send_response(404)
+                self.end_headers()
+
+    def _send_json_response(self, data: dict | list) -> None:
+        """Send a JSON response."""
+        self.send_response(200)
+        self.send_header("Content-Type", "application/json")
+        self.end_headers()
+        self.wfile.write(json.dumps(data, indent=2).encode())
+
+    def _send_help_page(self) -> None:
+        """Send HTML help page for root endpoint."""
+        self.send_response(200)
+        self.send_header("Content-Type", "text/html")
+        self.end_headers()
+        help_html = """<!DOCTYPE html>
+        <html>
+        <head><title>MCP Mock Server</title></head>
+        <body>
+            <h1>MCP Mock Server</h1>
+            <p>Development mock server for testing MCP integrations.</p>
+            <h2>Debug Endpoints:</h2>
+            <ul>
+                <li><a href="/debug/headers">/debug/headers</a> - View captured headers</li>
+                <li><a href="/debug/requests">/debug/requests</a> - View request log</li>
+            </ul>
+            <h2>MCP Protocol:</h2>
+            <p>POST requests to any path with JSON-RPC format:</p>
+            <ul>
+                <li><code>{"jsonrpc": "2.0", "id": 1, "method": "initialize"}</code></li>
+                <li><code>{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}</code></li>
+            </ul>
+        </body>
+        </html>
+        """
+        self.wfile.write(help_html.encode())
 
 
 def generate_self_signed_cert(cert_dir: Path) -> tuple[Path, Path]:
@@ -263,7 +268,7 @@ def run_https_server(port: int, httpd: HTTPServer) -> None:
         print(f"HTTPS server error: {e}")
 
 
-def main():
+def main() -> None:
     """Start the mock MCP server with both HTTP and HTTPS."""
     http_port = int(sys.argv[1]) if len(sys.argv) > 1 else 3000
     https_port = http_port + 1
@@ -294,7 +299,7 @@ def main():
     print("  • /debug/headers  - View captured headers")
     print("  • /debug/requests - View request log")
     print("MCP endpoint:")
-    print("  • POST /mcp/v1/list_tools")
+    print("  • POST to any path (e.g., / or /mcp/v1/list_tools)")
     print("=" * 70)
     print("Note: HTTPS uses a self-signed certificate (for testing only)")
     print("Press Ctrl+C to stop")