Merge pull request #650 from gargnipungarg/main

MCP Client code for inspector and ADK

Author: SudhiMurthy

model-deployment/mcp-servers/clients-remote-mcp-server/agent-development-kit-adk/Readme.MD

@@ -0,0 +1,24 @@
+# Description
+OCI Generative AI Agents is a fully managed service that combines the power of large language models (LLMs) with AI technologies to create intelligent virtual agents that can provide personalized, context-aware, and highly engaging customer experiences.
+
+The OCI Agent Development Kit (ADK) is a client-side library that simplifies building agentic applications on top of OCI Generative AI Agents Service.
+When pairing the ADK with OCI Generative AI Agents Service, you can use simple but powerful primitives to build complex, production-grade agentic applications.
+
+In this document, we will use mcp tool integration of [ADK library](https://agents.oraclecorp.com/adk/examples/agent-mcp-tool) to connect to remote hosted agent on model deployment service.
+
+# Prerequisites
+
+- Install pip dependencies mentioned in [requirements.txt](./requirements.txt)
+```
+pip install -r requirements.txt
+```
+
+- Create OCI session and populate your local OCI config files with valid [session details](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm)
+```
+oci session authenticate
+```
+
+- Start [mcp_client.py](./mcp_client.py)
+```
+python3 mcp_client.py
+```

model-deployment/mcp-servers/clients-remote-mcp-server/agent-development-kit-adk/mcp_client.py

@@ -0,0 +1,60 @@
+import asyncio
+import requests
+import oci
+from mcp.client.session_group import StreamableHttpParameters
+from oracle.adk import Agent, AgentClient
+from oracle.adk.mcp import MCPClientStreamableHttp
+
+MCP_SERVER_URL = <MODEL_DEPLOYMENT_URL>
+GENAI_ENDPOINT = "<ocid1.genaiagentendpoint.oc....>"
+def get_auth():
+    PROFILE_NAME = 'DEFAULT'
+    SECURITY_TOKEN_FILE_KEY = 'security_token_file'
+    KEY_FILE_KEY = 'key_file'
+    config = oci.config.from_file(profile_name=PROFILE_NAME)
+    token_file = config[SECURITY_TOKEN_FILE_KEY]
+    token = None
+    with open(token_file, 'r') as f:
+      token = f.read()
+    private_key = oci.signer.load_private_key_from_file(config[KEY_FILE_KEY])
+    signer = oci.auth.signers.SecurityTokenSigner(token, private_key, body_headers=["content-type", "x-content-sha256"])
+    return signer
+
+def oci_auth_headers():
+    signer=get_auth()
+    request = requests.Request("POST", MCP_SERVER_URL, auth=signer, headers={'Content-Type': 'application/json'})
+    prepared = request.prepare()
+    signer(prepared)
+    del(prepared.headers['content-length'])
+    return prepared.headers
+
+async def main():
+
+    headers = oci_auth_headers()
+    client = AgentClient(
+        auth_type="security_token",
+        profile="DEFAULT",
+        region="us-ashburn-1",
+    )
+
+    params = StreamableHttpParameters(
+        url=MCP_SERVER_URL,
+        headers=headers
+    )
+
+    async with MCPClientStreamableHttp(
+        params=params,
+        name="Streamable MCP Server",
+    ) as mcp_client:
+        agent = Agent(
+            client=client,
+            agent_endpoint_id=GENAI_ENDPOINT,
+            instructions="Use the tools to answer the questions.",
+            tools=[await mcp_client.as_toolkit()],
+        )
+        agent.setup()
+        print("Done", mcp_client, agent)
+        #mcp_client.list_tools()
+
+if __name__ == "__main__":
+    asyncio.run(main())

model-deployment/mcp-servers/clients-remote-mcp-server/agent-development-kit-adk/requirements.txt

@@ -0,0 +1,58 @@
+# Oracle Agent Development Kit - Core package
+oci[adk]
+
+# OCI SDK for authentication and cloud services
+oci>=2.100.0
+
+# WebSocket support for MCP connections
+websockets>=11.0
+
+# Async HTTP client for additional API calls
+aiohttp>=3.8.0
+
+# JSON schema validation for MCP messages
+jsonschema>=4.17.0
+
+# Certificate handling and SSL support
+cryptography>=40.0.0
+
+# Configuration file handling
+pyyaml>=6.0
+
+# Logging and debugging
+structlog>=22.3.0
+
+# HTTP/HTTPS client with connection pooling
+httpx>=0.24.0
+
+# URL parsing and validation
+yarl>=1.8.0
+
+# Retry logic and backoff strategies
+tenacity>=8.2.0
+
+# Type hints support for Python < 3.9
+typing-extensions>=4.5.0
+
+# Date/time handling
+python-dateutil>=2.8.2
+
+# Environment variable management
+python-dotenv>=1.0.0
+
+# Development and testing dependencies (optional)
+pytest>=7.2.0
+pytest-asyncio>=0.21.0
+pytest-mock>=3.10.0
+black>=23.1.0
+isort>=5.12.0
+mypy>=1.0.0
+
+# Security and certificate validation
+certifi>=2022.12.7
+
+# Protocol buffer support (if needed for some ADK features)
+protobuf>=4.21.0
+
+# JWT token handling (for some auth scenarios)
+PyJWT>=2.6.0

model-deployment/mcp-servers/clients-remote-mcp-server/mcp-inspector/Readme.MD

@@ -0,0 +1,34 @@
+# Description
+This readme explains how to use [mcp inspector](https://modelcontextprotocol.io/docs/tools/inspector) to connect to OCI hosted remote MCP server. Once you have an ACTIVE Model deployment resource hosting your MCP server, we can use MCP inspector to connect and make list/call tools to MCP server.
+
+# Prerequisites
+
+To enable generating OCI Auth credentials before making API calls to Model deployment endpoints, we will create a local proxy server, which will intercept calls from inspector, created OCI auth and adds required header for outgoing calls.
+
+- Install pip dependencies mentioned in [requirements.txt](./requirements.txt)
+```
+pip install -r requirements.txt
+```
+
+- Start [oci_proxy.py](./oci_proxy.py)
+```
+python3 oci_proxy.py
+```
+
+- Create OCI session and populate your local OCI config files with valid [session details](https://docs.oracle.com/en-us/iaas/Content/API/SDKDocs/clitoken.htm)
+```
+oci session authenticate
+```
+
+- Start mcp inspector on your local
+```
+npx @modelcontextprotocol/inspector
+```
+
+- Configure MCP inspector with configuration as:
+   - Transport type: Streamble HTTP
+   - URL: http://localhost:8000/proxy/{endpoint-URI-Path}/predict?target_host={endpoint-region-host}
+
+   (Use model deployment invoke endpoint details from console to fill these values. For example : endpoint-URI-Path = ocid1.datasciencemodeldeployment.oc1....... and endpoint-region-host = modeldeployment.us-ashburn-1.oci.customer-oci.com)
+
+- Click connect and the status should show "Connected", as shown in [screenshot](./screenshot.png)

model-deployment/mcp-servers/clients-remote-mcp-server/mcp-inspector/oci_proxy.py

@@ -0,0 +1,197 @@
+import hashlib
+import base64
+from datetime import datetime
+from typing import Dict
+from urllib.parse import urlparse, parse_qs
+
+import httpx
+from fastapi import FastAPI, Request, HTTPException, Depends
+from fastapi.responses import JSONResponse
+import oci
+import requests
+
+app = FastAPI(title="OCI Authentication Proxy", version="1.0.0")
+
+class OCIAuthProxy:
+    def __init__(self, config_profile: str = "DEFAULT"):
+        """Initialize OCI configuration and signer"""
+        try:
+            # Load OCI config
+            PROFILE_NAME = config_profile
+            SECURITY_TOKEN_FILE_KEY = 'security_token_file'
+            KEY_FILE_KEY = 'key_file'
+            self.config = oci.config.from_file(profile_name=PROFILE_NAME)
+            token_file = self.config[SECURITY_TOKEN_FILE_KEY]
+            token = None
+            with open(token_file, 'r') as f:
+              token = f.read()
+            private_key = oci.signer.load_private_key_from_file(self.config[KEY_FILE_KEY])
+            self.signer = oci.auth.signers.SecurityTokenSigner(token, private_key, body_headers=["content-type", "x-content-sha256"]) 
+        except Exception as e:
+            raise Exception(f"Failed to initialize OCI config: {str(e)}")
+    
+    def _get_content_hash(self, body: bytes) -> str:
+        """Generate SHA256 hash of request body"""
+        return base64.b64encode(hashlib.sha256(body).digest()).decode('utf-8')
+    
+    def _prepare_headers(self, method: str, url: str, headers: Dict[str, str], body: bytes) -> Dict[str, str]:
+        """Prepare headers for OCI authentication"""
+        parsed_url = urlparse(url)
+        
+        # Required headers for OCI
+        auth_headers = {
+            'date': datetime.utcnow().strftime('%a, %d %b %Y %H:%M:%S GMT'),
+            'host': parsed_url.netloc,
+            '(request-target)': f"{method.lower()} {parsed_url.path}"
+        }
+        
+        # Add query parameters to request-target if present
+        if parsed_url.query:
+            auth_headers['(request-target)'] += f"?{parsed_url.query}"
+        
+        # Add content headers for POST/PUT/PATCH requests
+        if method.upper() in ['POST', 'PUT', 'PATCH'] and body:
+            auth_headers['content-type'] = headers.get('content-type', 'application/json')
+            auth_headers['content-length'] = str(len(body))
+            auth_headers['x-content-sha256'] = self._get_content_hash(body)
+        
+        return auth_headers
+    
+    async def make_authenticated_request(
+        self, 
+        method: str, 
+        target_url: str, 
+        headers: Dict[str, str], 
+        body: bytes = b''
+    ) -> httpx.Response:
+        """Make an authenticated request to OCI API"""
+        
+        request = requests.Request("POST", target_url, auth=self.signer, headers={'Content-Type': 'application/json', 'accept': 'application/json, text/event-stream'})
+        prepared = request.prepare()
+        del(prepared.headers['content-length'])
+        
+        # Prepare final headers
+        final_headers = prepared.headers
+        
+        # Make the request
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.request(
+                method=method,
+                url=target_url,
+                headers=final_headers,
+                content=body
+            )
+        return response
+
+# Global proxy instance
+proxy = None
+
+async def get_proxy() -> OCIAuthProxy:
+    """Dependency to get or create proxy instance"""
+    global proxy
+    if proxy is None:
+        try:
+            proxy = OCIAuthProxy()
+        except Exception as e:
+            raise HTTPException(status_code=500, detail=f"Failed to initialize OCI proxy: {str(e)}")
+    return proxy
+
+@app.on_event("startup")
+async def startup_event():
+    """Initialize the proxy on startup"""
+    await get_proxy()
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {"status": "healthy", "service": "OCI Authentication Proxy"}
+
+@app.api_route("/proxy/{path:path}", methods=["GET", "POST", "PUT", "DELETE", "PATCH"])
+async def proxy_request(
+    request: Request, 
+    path: str,
+    target_host: str,
+    proxy_instance: OCIAuthProxy = Depends(get_proxy)
+):
+    """
+    Proxy requests to OCI with authentication
+    
+    Query Parameters:
+    - target_host: The OCI service hostname (e.g., iaas.us-ashburn-1.oraclecloud.com)
+    
+    Example:
+    GET /proxy/20160918/instances?target_host=iaas.us-ashburn-1.oraclecloud.com
+    """
+    
+    if not target_host:
+        raise HTTPException(
+            status_code=400, 
+            detail="target_host query parameter is required"
+        )
+    
+    # Construct target URL
+    scheme = "https"  # OCI APIs are always HTTPS
+    query_string = str(request.url.query)
+    
+    # Remove target_host from query parameters for the actual request
+    if query_string:
+        query_params = parse_qs(query_string)
+        if 'target_host' in query_params:
+            del query_params['target_host']
+        # Reconstruct query string
+        query_parts = []
+        for key, values in query_params.items():
+            for value in values:
+                query_parts.append(f"{key}={value}")
+        query_string = "&".join(query_parts)
+    
+    target_url = f"{scheme}://{target_host}/{path}"
+    if query_string:
+        target_url += f"?{query_string}"
+    
+    # Get request body
+    body = await request.body()
+    
+    # Get headers (excluding host and other proxy-specific headers)
+    headers = dict(request.headers)
+    
+    try:
+        # Make authenticated request
+        response = await proxy_instance.make_authenticated_request(
+            method=request.method,
+            target_url=target_url,
+            headers=headers,
+            body=body
+        )
+        print(response)
+        
+        # Return response
+        return JSONResponse(
+            content=response.json() if response.headers.get("content-type", "").startswith("application/json") else response.text,
+            status_code=response.status_code,
+            headers=dict(response.headers)
+        )
+        
+    except httpx.TimeoutException:
+        raise HTTPException(status_code=504, detail="Gateway timeout")
+    except httpx.RequestError as e:
+        raise HTTPException(status_code=502, detail=f"Request failed: {str(e)}")
+    except Exception as e:
+        print(e)
+        raise HTTPException(status_code=500, detail=f"Internal server error: {str(e)}")
+
+@app.get("/")
+async def root():
+    """Root endpoint with usage instructions"""
+    return {
+        "message": "OCI Authentication Proxy",
+        "usage": {
+            "endpoint": "/proxy/{path}",
+            "required_param": "target_host",
+            "example": "/proxy/20160918/instances?target_host=iaas.us-ashburn-1.oraclecloud.com"
+        }
+    }
+
+if __name__ == "__main__":
+    import uvicorn
+    uvicorn.run(app, host="0.0.0.0", port=8000)

model-deployment/mcp-servers/clients-remote-mcp-server/mcp-inspector/requirements.txt

@@ -0,0 +1,6 @@
+fastapi
+uvicorn
+httpx
+oci
+python-multipart
+requests