Add v3 service abstractions and MCP endpoint config

Introduces a new 'services' module under v3/common with BaseAPIService, MCPService, and FoundryService for async HTTP and Azure AI Foundry interactions. Updates AppConfig to support an optional MCP server endpoint and fixes credential method references. These changes provide a foundation for modular service access and easier integration with MCP and Foundry APIs.

Author: Fr4nc3

src/backend/common/config/app_config.py

@@ -67,13 +67,17 @@ def __init__(self):
         # Azure Search settings
         self.AZURE_SEARCH_ENDPOINT = self._get_optional("AZURE_SEARCH_ENDPOINT")
 
+        # Optional MCP server endpoint (for local MCP server or remote)
+        # Example: http://127.0.0.1:8000/mcp
+        self.MCP_SERVER_ENDPOINT = self._get_optional("MCP_SERVER_ENDPOINT")
+
         # Cached clients and resources
         self._azure_credentials = None
         self._cosmos_client = None
         self._cosmos_database = None
         self._ai_project_client = None
 
-    def get_azure_credential(cself, client_id=None):
+    def get_azure_credential(self, client_id=None):
         """
         Returns an Azure credential based on the application environment.
 
@@ -96,7 +100,7 @@ def get_azure_credential(cself, client_id=None):
     def get_azure_credentials(self):
         """Retrieve Azure credentials, either from environment variables or managed identity."""
         if self._azure_credentials is None:
-            self._azure_credentials = get_azure_credential()
+            self._azure_credentials = self.get_azure_credential()
         return self._azure_credentials
 
     async def get_access_token(self) -> str:
@@ -168,7 +172,7 @@ def get_ai_project_client(self):
             return self._ai_project_client
 
         try:
-            credential = get_azure_credential()
+            credential = self.get_azure_credential()
             if credential is None:
                 raise RuntimeError(
                     "Unable to acquire Azure credentials; ensure Managed Identity is configured"

src/backend/v3/common/services/__init__.py

@@ -0,0 +1,17 @@
+"""Service abstractions for v3.
+
+Exports:
+- BaseAPIService: minimal async HTTP wrapper using endpoints from AppConfig
+- MCPService: service targeting a local/remote MCP server
+- FoundryService: helper around Azure AI Foundry (AIProjectClient)
+"""
+
+from .base_api_service import BaseAPIService
+from .mcp_service import MCPService
+from .foundry_service import FoundryService
+
+__all__ = [
+    "BaseAPIService",
+    "MCPService",
+    "FoundryService",
+]

src/backend/v3/common/services/base_api_service.py

@@ -0,0 +1,116 @@
+import asyncio
+from typing import Any, Dict, Optional, Union
+
+import aiohttp
+
+from common.config.app_config import config
+
+
+class BaseAPIService:
+    """Minimal async HTTP API service.
+
+    - Reads base endpoints from AppConfig using `from_config` factory.
+    - Provides simple GET/POST helpers with JSON payloads.
+    - Designed to be subclassed (e.g., MCPService, FoundryService).
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        default_headers: Optional[Dict[str, str]] = None,
+        timeout_seconds: int = 30,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> None:
+        if not base_url:
+            raise ValueError("base_url is required")
+        self.base_url = base_url.rstrip("/")
+        self.default_headers = default_headers or {}
+        self.timeout = aiohttp.ClientTimeout(total=timeout_seconds)
+        self._session_external = session is not None
+        self._session: Optional[aiohttp.ClientSession] = session
+
+    @classmethod
+    def from_config(
+        cls,
+        endpoint_attr: str,
+        *,
+        default: Optional[str] = None,
+        **kwargs: Any,
+    ) -> "BaseAPIService":
+        """Create a service using an endpoint attribute from AppConfig.
+
+        Args:
+            endpoint_attr: Name of the attribute on AppConfig (e.g., 'AZURE_AI_AGENT_ENDPOINT').
+            default: Optional default if attribute missing or empty.
+            **kwargs: Passed through to the constructor.
+        """
+        base_url = getattr(config, endpoint_attr, None) or default
+        if not base_url:
+            raise ValueError(
+                f"Endpoint '{endpoint_attr}' not configured in AppConfig and no default provided"
+            )
+        return cls(base_url, **kwargs)
+
+    async def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(timeout=self.timeout)
+        return self._session
+
+    def _url(self, path: str) -> str:
+        path = path or ""
+        if not path:
+            return self.base_url
+        return f"{self.base_url}/{path.lstrip('/')}"
+
+    async def _request(
+        self,
+        method: str,
+        path: str = "",
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Union[str, int, float]]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> aiohttp.ClientResponse:
+        session = await self._ensure_session()
+        url = self._url(path)
+        merged_headers = {**self.default_headers, **(headers or {})}
+        return await session.request(
+            method.upper(), url, headers=merged_headers, params=params, json=json
+        )
+
+    async def get_json(
+        self,
+        path: str = "",
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Union[str, int, float]]] = None,
+    ) -> Any:
+        resp = await self._request("GET", path, headers=headers, params=params)
+        resp.raise_for_status()
+        return await resp.json()
+
+    async def post_json(
+        self,
+        path: str = "",
+        *,
+        headers: Optional[Dict[str, str]] = None,
+        params: Optional[Dict[str, Union[str, int, float]]] = None,
+        json: Optional[Dict[str, Any]] = None,
+    ) -> Any:
+        resp = await self._request(
+            "POST", path, headers=headers, params=params, json=json
+        )
+        resp.raise_for_status()
+        return await resp.json()
+
+    async def close(self) -> None:
+        if self._session and not self._session.closed and not self._session_external:
+            await self._session.close()
+
+    async def __aenter__(self) -> "BaseAPIService":
+        await self._ensure_session()
+        return self
+
+    async def __aexit__(self, exc_type, exc, tb) -> None:
+        await self.close()

src/backend/v3/common/services/foundry_service.py

@@ -0,0 +1,33 @@
+from typing import Any, Dict
+
+from azure.ai.projects.aio import AIProjectClient
+
+from common.config.app_config import config
+
+
+class FoundryService:
+    """Helper around Azure AI Foundry's AIProjectClient.
+
+    Uses AppConfig.get_ai_project_client() to obtain a properly configured
+    asynchronous client. Provides a small set of convenience methods and
+    can be extended for specific project operations.
+    """
+
+    def __init__(self, client: AIProjectClient | None = None) -> None:
+        self._client = client
+
+    async def get_client(self) -> AIProjectClient:
+        if self._client is None:
+            self._client = config.get_ai_project_client()
+        return self._client
+
+    # Example convenience wrappers – adjust as your project needs evolve
+    async def list_connections(self) -> list[Dict[str, Any]]:
+        client = await self.get_client()
+        conns = await client.connections.list()
+        return [c.as_dict() if hasattr(c, "as_dict") else dict(c) for c in conns]
+
+    async def get_connection(self, name: str) -> Dict[str, Any]:
+        client = await self.get_client()
+        conn = await client.connections.get(name=name)
+        return conn.as_dict() if hasattr(conn, "as_dict") else dict(conn)

src/backend/v3/common/services/mcp_service.py

@@ -0,0 +1,37 @@
+from typing import Any, Dict, Optional
+
+from common.config.app_config import config
+
+from .base_api_service import BaseAPIService
+
+
+class MCPService(BaseAPIService):
+    """Service for interacting with an MCP server.
+
+    Base URL is taken from AppConfig.MCP_SERVER_ENDPOINT if present,
+    otherwise falls back to v3 MCP default in settings or localhost.
+    """
+
+    def __init__(self, base_url: str, *, token: Optional[str] = None, **kwargs):
+        headers = {"Content-Type": "application/json"}
+        if token:
+            headers["Authorization"] = f"Bearer {token}"
+        super().__init__(base_url, default_headers=headers, **kwargs)
+
+    @classmethod
+    def from_app_config(cls, **kwargs) -> "MCPService":
+        # Prefer explicit MCP endpoint if defined; otherwise use the v3 settings default.
+        endpoint = config.MCP_SERVER_ENDPOINT
+        if not endpoint:
+            # fall back to typical local dev default
+            return None  # or handle the error appropriately
+        token = None  # add token retrieval if you enable auth later
+        return cls(endpoint, token=token, **kwargs)
+
+    async def health(self) -> Dict[str, Any]:
+        return await self.get_json("health")
+
+    async def invoke_tool(
+        self, tool_name: str, payload: Dict[str, Any]
+    ) -> Dict[str, Any]:
+        return await self.post_json(f"tools/{tool_name}", json=payload)