feat: support Python 3.9+ with optional MCP server support (#28)

* fix: add type ignore for unreachable code in MCP server

This is needed because mypy sees the Python version check as always false
when running on Python 3.10+, making the subsequent code unreachable.
The code is actually reachable at runtime when Python 3.10+ is used.

* docs: update README with Python version requirements

- Add Requirements section with Python 3.9+ for core SDK
- Add installation options for optional features
- Document MCP server requiring Python 3.10+
- Add note about CrewAI requiring Python 3.10+

* refactor: rename [server] to [mcp] for clarity

- Rename optional dependency group from 'server' to 'mcp' for better clarity
- Update CI workflows to use --without mcp instead of --without server
- Update README installation instructions
- Update error message in MCP server module

* fix: correct uv sync syntax in CI workflows

Use --all-extras --no-extra mcp instead of --without-group mcp
for excluding optional dependencies in uv sync command.

* fix: add eval-type-backport for Python 3.9 Pydantic compatibility

- Add eval-type-backport dependency for Python <3.10 to handle union types
- Fix mypy exclusion syntax for server.py when MCP is not available

* docs: add TODO comments for Python 3.9 compatibility code

- Add TODO for zip strict parameter
- Add TODO for eval-type-backport dependency

* fix: use Python 3.11 for docs build to support MCP examples

The build_docs.py script requires Python 3.11+ and processes MCP examples,
so we need Python 3.11 with all extras for proper documentation generation.

* docs: quote extras in pip install commands to prevent shell globbing

- Add quotes around extras in all pip install examples
- Prevents 'no matches found' errors in zsh and similar shells
- Affects both installation section and inline examples

* security: fix SSRF vulnerability in URL path parameter replacement

- Add urllib.parse.quote to safely encode path parameters
- Use safe='' to encode all special characters including '/', ':', '@'
- Prevents attackers from injecting malicious hosts or internal service paths
- Applies to both explicit PATH parameters and default path replacement logic

* ci: add Python 3.11 support to lint workflow

- Add matrix strategy to test both Python 3.9 and 3.11
- Configure appropriate dependency installation for each version
- Python 3.9: excludes MCP extras (not supported)
- Python 3.11: includes all extras for full coverage
- Aligns with existing test workflow pattern for consistency

* ci: update lint workflow to test Python 3.9 and 3.10

- Change from 3.9/3.11 matrix to 3.9/3.10 for better coverage
- Maintains appropriate dependency configurations for each version

* ci: fix versions

Author: ryoppippi

.github/workflows/lint.yml

@@ -8,22 +8,30 @@ on:
 jobs:
   lint:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10"]
+        include:
+          - python-version: "3.9"
+            sync-extras: "--all-extras --no-extra mcp"
+          - python-version: "3.10"
+            sync-extras: "--all-extras"
     steps:
       - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
 
       - name: Install uv
         uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc # v6.4.3
         with:
-          python-version: "3.11"
+          python-version: ${{ matrix.python-version }}
           enable-cache: true
 
       - name: Install dependencies
-        run: uv sync --all-extras
+        run: uv sync ${{ matrix.sync-extras }}
 
       - name: Run Ruff
         uses: astral-sh/ruff-action@0c50076f12c38c3d0115b7b519b54a91cb9cf0ad # v3.5.0
         with:
           args: check .
 
       - name: Run Mypy
-        run: uv run mypy stackone_ai
+        run: uv run mypy stackone_ai --exclude stackone_ai/server.py

.github/workflows/test.yml

@@ -8,6 +8,16 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.13"]
+        include:
+          - python-version: "3.9"
+            test-extras: "--all-extras --no-extra mcp"
+          - python-version: "3.10"
+            test-extras: "--all-extras"
+          - python-version: "3.13"
+            test-extras: "--all-extras"
     env:
       STACKONE_API_KEY: ${{ secrets.STACKONE_API_KEY }}
       OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
@@ -17,11 +27,11 @@ jobs:
       - name: Install uv
         uses: astral-sh/setup-uv@e92bafb6253dcd438e0484186d7669ea7a8ca1cc # v6.4.3
         with:
-          python-version: "3.11"
+          python-version: ${{ matrix.python-version }}
           enable-cache: true
 
       - name: Install dependencies
-        run: uv sync --all-extras
+        run: uv sync ${{ matrix.test-extras }}
 
       - name: Run tests
         run: uv run pytest

README.md

@@ -18,12 +18,32 @@ StackOne AI provides a unified interface for accessing various SaaS tools throug
   - CrewAI Tools
   - LangGraph Tool Node
 
+## Requirements
+
+- Python 3.9+ (core SDK functionality)
+- Python 3.10+ (for MCP server and CrewAI examples)
+
 ## Installation
 
+### Basic Installation
+
 ```bash
 pip install stackone-ai
 ```
 
+### Optional Features
+
+```bash
+# Install with MCP server support (requires Python 3.10+)
+pip install 'stackone-ai[mcp]'
+
+# Install with CrewAI examples (requires Python 3.10+)
+pip install 'stackone-ai[examples]'
+
+# Install everything
+pip install 'stackone-ai[mcp,examples]'
+```
+
 ## Quick Start
 
 ```python
@@ -82,10 +102,12 @@ for tool_call in response.tool_calls:
 </details>
 
 <details>
-<summary>CrewAI Integration</summary>
+<summary>CrewAI Integration (Python 3.10+)</summary>
 
 CrewAI uses LangChain tools natively, making integration seamless:
 
+> **Note**: CrewAI requires Python 3.10+. Install with `pip install 'stackone-ai[examples]'`
+
 ```python
 from crewai import Agent, Crew, Task
 from stackone_ai import StackOneToolSet

pyproject.toml

@@ -3,7 +3,7 @@ name = "stackone-ai"
 version = "0.3.1"
 description = "agents performing actions on your SaaS"
 readme = "README.md"
-requires-python = ">=3.11"
+requires-python = ">=3.9"
 authors = [
     { name = "StackOne", email = "[email protected]" }
 ]
@@ -12,16 +12,21 @@ classifiers = [
     "Intended Audience :: Developers",
     "License :: OSI Approved :: MIT License",
     "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 dependencies = [
     "pydantic>=2.10.6",
     "requests>=2.32.3",
     "langchain-core>=0.1.0",
-    "mcp[cli]>=1.3.0",
     "bm25s>=0.2.2",
     "numpy>=1.24.0",
+    "typing-extensions>=4.0.0",
+    "eval-type-backport; python_version<'3.10'",  # TODO: Remove when Python 3.9 support is dropped
 ]
 
 [project.scripts]
@@ -41,8 +46,12 @@ packages = ["stackone_ai"]
 "py.typed" = "py.typed"
 
 [project.optional-dependencies]
+# TODO: Remove python_version conditions when Python 3.9 support is dropped
+mcp = [
+    "mcp[cli]>=1.3.0; python_version>='3.10'",
+]
 examples = [
-    "crewai>=0.102.0",
+    "crewai>=0.102.0; python_version>='3.10'",
     "langchain-openai>=0.3.6",
     "openai>=1.63.2",
     "python-dotenv>=1.0.1",
@@ -82,7 +91,7 @@ markers = [
 
 [tool.ruff]
 line-length = 110
-target-version = "py311"
+target-version = "py39"
 
 [tool.ruff.lint]
 select = [
@@ -96,7 +105,7 @@ select = [
 ]
 
 [tool.mypy]
-python_version = "3.11"
+python_version = "3.9"
 disallow_untyped_defs = true
 disallow_incomplete_defs = true
 check_untyped_defs = true

stackone_ai/meta_tools.py

@@ -82,7 +82,8 @@ def search(self, query: str, limit: int = 5, min_score: float = 0.0) -> list[Met
 
         # Process results
         search_results = []
-        for idx, score in zip(results[0], scores[0], strict=False):
+        # TODO: Add strict=False when Python 3.9 support is dropped
+        for idx, score in zip(results[0], scores[0]):
             if score < min_score:
                 continue
 

stackone_ai/models.py

@@ -1,16 +1,23 @@
+# TODO: Remove when Python 3.9 support is dropped
+from __future__ import annotations
+
 import asyncio
 import base64
 import json
 from collections.abc import Sequence
 from enum import Enum
 from functools import partial
-from typing import Annotated, Any, TypeAlias, cast
+from typing import Annotated, Any, cast
+from urllib.parse import quote
 
 import requests
 from langchain_core.tools import BaseTool
 from pydantic import BaseModel, BeforeValidator, Field, PrivateAttr
 from requests.exceptions import RequestException
 
+# TODO: Remove when Python 3.9 support is dropped
+from typing_extensions import TypeAlias
+
 # Type aliases for common types
 JsonDict: TypeAlias = dict[str, Any]
 Headers: TypeAlias = dict[str, str]
@@ -140,21 +147,24 @@ def _prepare_request_params(self, kwargs: JsonDict) -> tuple[str, JsonDict, Json
         for key, value in kwargs.items():
             param_location = self._execute_config.parameter_locations.get(key)
 
-            match param_location:
-                case ParameterLocation.PATH:
-                    url = url.replace(f"{{{key}}}", str(value))
-                case ParameterLocation.QUERY:
+            if param_location == ParameterLocation.PATH:
+                # Safely encode path parameters to prevent SSRF attacks
+                encoded_value = quote(str(value), safe="")
+                url = url.replace(f"{{{key}}}", encoded_value)
+            elif param_location == ParameterLocation.QUERY:
+                query_params[key] = value
+            elif param_location in (ParameterLocation.BODY, ParameterLocation.FILE):
+                body_params[key] = value
+            else:
+                # Default behavior
+                if f"{{{key}}}" in url:
+                    # Safely encode path parameters to prevent SSRF attacks
+                    encoded_value = quote(str(value), safe="")
+                    url = url.replace(f"{{{key}}}", encoded_value)
+                elif self._execute_config.method in {"GET", "DELETE"}:
                     query_params[key] = value
-                case ParameterLocation.BODY | ParameterLocation.FILE:
+                else:
                     body_params[key] = value
-                case _:
-                    # Default behavior
-                    if f"{{{key}}}" in url:
-                        url = url.replace(f"{{{key}}}", str(value))
-                    elif self._execute_config.method in {"GET", "DELETE"}:
-                        query_params[key] = value
-                    else:
-                        body_params[key] = value
 
         return url, body_params, query_params
 
@@ -355,13 +365,12 @@ def to_langchain(self) -> BaseTool:
             python_type: type = str  # Default to str
             if isinstance(details, dict):
                 type_str = details.get("type", "string")
-                match type_str:
-                    case "number":
-                        python_type = float
-                    case "integer":
-                        python_type = int
-                    case "boolean":
-                        python_type = bool
+                if type_str == "number":
+                    python_type = float
+                elif type_str == "integer":
+                    python_type = int
+                elif type_str == "boolean":
+                    python_type = bool
 
                 field = Field(description=details.get("description", ""))
             else:
@@ -480,7 +489,7 @@ def to_langchain(self) -> Sequence[BaseTool]:
         """
         return [tool.to_langchain() for tool in self.tools]
 
-    def meta_tools(self) -> "Tools":
+    def meta_tools(self) -> Tools:
         """Return meta tools for tool discovery and execution
 
         Meta tools enable dynamic tool discovery and execution based on natural language queries.

stackone_ai/server.py

@@ -1,16 +1,31 @@
+# TODO: Remove when Python 3.9 support is dropped
+from __future__ import annotations
+
 import argparse
 import asyncio
 import logging
 import os
 import sys
 from typing import Any, TypeVar
 
-import mcp.types as types
-from mcp.server import NotificationOptions, Server
-from mcp.server.models import InitializationOptions
-from mcp.server.stdio import stdio_server
-from mcp.shared.exceptions import McpError
-from mcp.types import EmbeddedResource, ErrorData, ImageContent, TextContent, Tool
+# Check Python version for MCP server functionality
+if sys.version_info < (3, 10):
+    raise RuntimeError(
+        "MCP server functionality requires Python 3.10+. Current version: {}.{}.{}".format(
+            *sys.version_info[:3]
+        )
+    )
+
+try:  # type: ignore[unreachable]
+    import mcp.types as types
+    from mcp.server import NotificationOptions, Server
+    from mcp.server.models import InitializationOptions
+    from mcp.server.stdio import stdio_server
+    from mcp.shared.exceptions import McpError
+    from mcp.types import EmbeddedResource, ErrorData, ImageContent, TextContent, Tool
+except ImportError as e:
+    raise ImportError("MCP dependencies not found. Install with: pip install 'stackone-ai[mcp]'") from e
+
 from pydantic import ValidationError
 
 from stackone_ai import StackOneToolSet
@@ -41,7 +56,7 @@ def tool_needs_account_id(tool_name: str) -> bool:
     return True
 
 
-@app.list_tools()  # type: ignore[misc]
+@app.list_tools()
 async def list_tools() -> list[Tool]:
     """List all available StackOne tools as MCP tools."""
     if not toolset:
@@ -99,7 +114,7 @@ async def list_tools() -> list[Tool]:
         ) from e
 
 
-@app.call_tool()  # type: ignore[misc]
+@app.call_tool()
 async def call_tool(
     name: str, arguments: dict[str, Any]
 ) -> list[TextContent | ImageContent | EmbeddedResource]:

stackone_ai/specs/parser.py

@@ -1,3 +1,6 @@
+# TODO: Remove when Python 3.9 support is dropped
+from __future__ import annotations
+
 import json
 from pathlib import Path
 from typing import Any
@@ -73,7 +76,7 @@ def _resolve_schema(
             visited = set()
 
         # Handle primitive types (str, int, etc)
-        if not isinstance(schema, dict | list):
+        if not isinstance(schema, (dict, list)):
             return schema
 
         if isinstance(schema, list):

stackone_ai/toolset.py

@@ -1,3 +1,6 @@
+# TODO: Remove when Python 3.9 support is dropped
+from __future__ import annotations
+
 import fnmatch
 import os
 import warnings