Merge pull request IBM#156 from IBM/flake8

Setup linters github action

Author: crivetimihai

.github/workflows/lint.yml

@@ -0,0 +1,132 @@
+# ===============================================================
+# 🔍  Lint & Static Analysis – Code Quality Gate
+# ===============================================================
+#
+#   - runs each linter in its own matrix job for visibility
+#   - mirrors the actual CLI commands used locally (no `make`)
+#   - ensures fast-failure isolation: one failure doesn't hide others
+#   - each job installs the project in dev-editable mode
+#   - logs are grouped and plain-text for readability
+# ---------------------------------------------------------------
+
+name: Lint & Static Analysis
+
+on:
+  push:
+    branches: ["main"]
+  pull_request:
+    branches: ["main"]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          # -------------------------------------------------------
+          # 🧼 Syntax & Format Checkers
+          # -------------------------------------------------------
+          - id: yamllint
+            setup: pip install yamllint
+            cmd: yamllint -c .yamllint .
+
+          - id: jsonlint
+            setup: |
+              sudo apt-get update -qq
+              sudo apt-get install -y jq
+            cmd: |
+              find . -type f -name '*.json' -not -path './node_modules/*' -print0 |
+                xargs -0 -I{} jq empty "{}"
+
+          - id: tomllint
+            setup: pip install tomlcheck
+            cmd: |
+              find . -type f -name '*.toml' -print0 |
+                xargs -0 -I{} tomlcheck "{}"
+
+          # -------------------------------------------------------
+          # 🐍 Python Linters & Type Checkers
+          # -------------------------------------------------------
+          - id: flake8
+            setup: pip install flake8
+            cmd: flake8 mcpgateway
+
+          - id: ruff
+            setup: pip install ruff
+            cmd: |
+              ruff check mcpgateway
+
+          # - id: pylint
+          #   setup: pip install pylint
+          #   cmd: pylint mcpgateway
+
+          # - id: mypy
+          #   setup: pip install mypy
+          #   cmd: mypy mcpgateway
+
+          # - id: pycodestyle
+          #   setup: pip install pycodestyle
+          #   cmd: pycodestyle mcpgateway --max-line-length=200
+
+          # - id: pydocstyle
+          #   setup: pip install pydocstyle
+          #   cmd: pydocstyle mcpgateway
+
+          # - id: pyright
+          #   setup: npm install -g pyright
+          #   cmd: pyright mcpgateway tests
+
+          # -------------------------------------------------------
+          # 🔒 Security & Packaging Checks
+          # -------------------------------------------------------
+          # - id: bandit
+          #   setup: pip install bandit
+          #   cmd: bandit -r mcpgateway
+
+          # - id: check-manifest
+          #   setup: pip install check-manifest
+          #   cmd: check-manifest
+
+    name: ${{ matrix.id }}
+    runs-on: ubuntu-latest
+
+    steps:
+      # -----------------------------------------------------------
+      # 0️⃣  Checkout
+      # -----------------------------------------------------------
+      - name: ⬇️  Checkout source
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 1
+
+      # -----------------------------------------------------------
+      # 1️⃣  Python Setup
+      # -----------------------------------------------------------
+      - name: 🐍  Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+
+      # -----------------------------------------------------------
+      # 2️⃣  Install Project + Dev Dependencies
+      # -----------------------------------------------------------
+      - name: 📦  Install project (editable mode)
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .[dev]
+
+      # -----------------------------------------------------------
+      # 3️⃣  Install Tool-Specific Requirements
+      # -----------------------------------------------------------
+      - name: 🔧  Install tool - ${{ matrix.id }}
+        run: ${{ matrix.setup }}
+
+      # -----------------------------------------------------------
+      # 4️⃣  Run Linter / Validator
+      # -----------------------------------------------------------
+      - name: 🔍  Run ${{ matrix.id }}
+        run: ${{ matrix.cmd }}

README.md

@@ -10,6 +10,7 @@
 [![Bandit Security](https://github.com/IBM/mcp-context-forge/actions/workflows/bandit.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/bandit.yml) 
 [![Dependency Review](https://github.com/IBM/mcp-context-forge/actions/workflows/dependency-review.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/dependency-review.yml) 
 [![Tests & Coverage](https://github.com/IBM/mcp-context-forge/actions/workflows/pytest.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/pytest.yml) 
+[![Lint & Static Analysis](https://github.com/IBM/mcp-context-forge/actions/workflows/lint.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/lint.yml)
 
 <!-- === Container Build & Deploy === -->
 [![Secure Docker Build](https://github.com/IBM/mcp-context-forge/actions/workflows/docker-image.yml/badge.svg)](https://github.com/IBM/mcp-context-forge/actions/workflows/docker-image.yml)&nbsp;

mcpgateway/services/gateway_service.py

@@ -646,6 +646,7 @@ async def _initialize_gateway(self, url: str, authentication: Optional[Dict[str,
         Args:
             url: Gateway URL
             authentication: Optional authentication headers
+            transport: Transport type ("SSE" or "StreamableHTTP")
 
         Returns:
             Capabilities dictionary as provided by the gateway.

mcpgateway/translate.py

@@ -165,7 +165,17 @@ def _build_fastapi(
     # ----- GET /sse ---------------------------------------------------------#
     @app.get(sse_path)
     async def get_sse(request: Request) -> EventSourceResponse:  # noqa: D401
-        """Fan-out *stdout* of the subprocess to any number of SSE clients."""
+        """Stream subprocess stdout to any number of SSE clients.
+
+        Args:
+            request (Request): The incoming ``GET`` request that will be
+                upgraded to a Server-Sent Events (SSE) stream.
+
+        Returns:
+            EventSourceResponse: A streaming response that forwards JSON-RPC
+            messages from the child process and emits periodic ``keepalive``
+            frames so that clients and proxies do not time out.
+        """
         queue = pubsub.subscribe()
         session_id = uuid.uuid4().hex
 
@@ -210,7 +220,19 @@ async def event_gen() -> AsyncIterator[dict]:
     # ----- POST /message ----------------------------------------------------#
     @app.post(message_path, status_code=status.HTTP_202_ACCEPTED)
     async def post_message(raw: Request, session_id: str | None = None) -> Response:  # noqa: D401
-        """Forward the raw JSON body to the stdio process without modification."""
+        """Forward a raw JSON-RPC request to the stdio subprocess.
+
+        Args:
+            raw (Request): The incoming ``POST`` request whose body contains
+                a single JSON-RPC message.
+            session_id (str | None): The SSE session identifier that originated
+                this back-channel call (present when the client obtained the
+                endpoint URL from an ``endpoint`` bootstrap frame).
+
+        Returns:
+            Response: ``202 Accepted`` if the payload is forwarded successfully,
+            or ``400 Bad Request`` when the body is not valid JSON.
+        """
         payload = await raw.body()
         try:
             json.loads(payload)  # validate

mcpgateway/transports/streamablehttp_transport.py

@@ -56,7 +56,7 @@
 
 server_id_var: contextvars.ContextVar[str] = contextvars.ContextVar("server_id", default=None)
 
-## ------------------------------ Event store ------------------------------
+# ------------------------------ Event store ------------------------------
 
 
 @dataclass
@@ -92,7 +92,16 @@ def __init__(self, max_events_per_stream: int = 100):
         self.event_index: dict[EventId, EventEntry] = {}
 
     async def store_event(self, stream_id: StreamId, message: JSONRPCMessage) -> EventId:
-        """Stores an event with a generated event ID."""
+        """
+        Stores an event with a generated event ID.
+
+        Args:
+            stream_id (StreamId): The ID of the stream.
+            message (JSONRPCMessage): The message to store.
+
+        Returns:
+            EventId: The ID of the stored event.
+        """
         event_id = str(uuid4())
         event_entry = EventEntry(event_id=event_id, stream_id=stream_id, message=message)
 
@@ -117,7 +126,16 @@ async def replay_events_after(
         last_event_id: EventId,
         send_callback: EventCallback,
     ) -> StreamId | None:
-        """Replays events that occurred after the specified event ID."""
+        """
+        Replays events that occurred after the specified event ID.
+
+        Args:
+            last_event_id (EventId): The ID of the last received event. Replay starts after this event.
+            send_callback (EventCallback): Async callback to send each replayed event.
+
+        Returns:
+            StreamId | None: The stream ID if the event is found and replayed, otherwise None.
+        """
         if last_event_id not in self.event_index:
             logger.warning(f"Event ID {last_event_id} not found in store")
             return None
@@ -138,7 +156,7 @@ async def replay_events_after(
         return stream_id
 
 
-## ------------------------------ Streamable HTTP Transport ------------------------------
+# ------------------------------ Streamable HTTP Transport ------------------------------
 
 
 @asynccontextmanager
@@ -148,7 +166,7 @@ async def get_db():
 
     Yields:
         A database session instance from SessionLocal.
-    Ensures the session is closed after use.
+        Ensures the session is closed after use.
     """
     db = SessionLocal()
     try:
@@ -168,7 +186,7 @@ async def call_tool(name: str, arguments: dict) -> List[Union[types.TextContent,
 
     Returns:
         List of content (TextContent, ImageContent, or EmbeddedResource) from the tool response.
-    Logs and returns an empty list on failure.
+        Logs and returns an empty list on failure.
     """
     try:
         async with get_db() as db:
@@ -190,7 +208,7 @@ async def list_tools() -> List[types.Tool]:
 
     Returns:
         A list of Tool objects containing metadata such as name, description, and input schema.
-    Logs and returns an empty list on failure.
+        Logs and returns an empty list on failure.
     """
     server_id = server_id_var.get()
 
@@ -260,6 +278,10 @@ async def handle_streamable_http(self, scope: Scope, receive: Receive, send: Sen
             scope (Scope): ASGI scope object containing connection information.
             receive (Receive): ASGI receive callable.
             send (Send): ASGI send callable.
+
+        Raises:
+            Exception: Any exception raised during request handling is logged.
+
         Logs any exceptions that occur during request handling.
         """
 
@@ -277,20 +299,30 @@ async def handle_streamable_http(self, scope: Scope, receive: Receive, send: Sen
             raise
 
 
-## ------------------------- Authentication for /mcp routes ------------------------------
+# ------------------------- Authentication for /mcp routes ------------------------------
 
 
 async def streamable_http_auth(scope, receive, send):
     """
     Perform authentication check in middleware context (ASGI scope).
 
-    If path does not end with "/mcp", just continue (return True).
+    This function is intended to be used in middleware wrapping ASGI apps.
+    It authenticates only requests targeting paths ending in "/mcp" or "/mcp/".
 
-    Only check Authorization header for Bearer token.
-    If no Bearer token provided, allow (return True).
+    Behavior:
+    - If the path does not end with "/mcp", authentication is skipped.
+    - If there is no Authorization header, the request is allowed.
+    - If a Bearer token is present, it is verified using `verify_credentials`.
+    - If verification fails, a 401 Unauthorized JSON response is sent.
 
-    If auth_required is True and Bearer token provided, verify it.
-    If verification fails, send 401 JSONResponse and return False.
+    Args:
+        scope: The ASGI scope dictionary, which includes request metadata.
+        receive: ASGI receive callable used to receive events.
+        send: ASGI send callable used to send events (e.g. a 401 response).
+
+    Returns:
+        bool: True if authentication passes or is skipped.
+              False if authentication fails and a 401 response is sent.
     """
 
     path = scope.get("path", "")

pyproject.toml

@@ -220,13 +220,34 @@ profile = "black"
 multi_line_output = 3
 
 [tool.mypy]
-python_version = "3.10"
-warn_return_any = true
-warn_unused_configs = true
-disallow_untyped_defs = true
-strict = true
-show_error_codes = true
-warn_unreachable = true
+# Target Python version
+python_version = "3.11"
+
+# Full strictness and individual checks
+strict = true                           # Enable all strict checks
+
+check_untyped_defs = true              # Type-check the bodies of untyped functions
+no_implicit_optional = true            # Require explicit Optional for None default
+disallow_untyped_defs = true           # Require type annotations for all functions
+disallow_untyped_calls = true          # Disallow calling functions without type info
+disallow_any_unimported = true         # Disallow Any from missing imports
+warn_return_any = true                 # Warn if a function returns Any
+warn_unreachable = true                # Warn about unreachable code
+warn_unused_ignores = true             # Warn if a "# type: ignore" is unnecessary
+warn_unused_configs = true             # Warn about unused config options
+warn_redundant_casts = true            # Warn if a cast does nothing
+strict_equality = true                 # Disallow ==/!= between incompatible types
+
+# Output formatting
+show_error_codes = true                # Show error codes in output
+pretty = true                          # Format output nicely
+
+# Exclude these paths from analysis
+exclude = [
+  '^build/',
+  '^\\.venv/',
+  '^\\.mypy_cache/',
+]
 
 [tool.pytest.ini_options]
 minversion = "6.0"