scope-sdk 0.1.0__py3-none-any.whl

scope_sdk/__init__.py

@@ -0,0 +1,3 @@
+from .client import instrument, init, active_request
+
+__all__ = ["instrument", "init", "active_request"]

scope_sdk/client.py

@@ -0,0 +1,550 @@
+import time
+import datetime
+import uuid
+import sys
+import os
+import traceback
+import contextvars
+import logging
+import base64
+import json
+import getpass
+from .transport import ScopeTransport
+
+SDK_VERSION = "0.1.0"
+SDK_LANGUAGE = "python"
+
+# Thread-safe context for logging and network interception
+log_context = contextvars.ContextVar("scope_log_context", default=None)
+network_context = contextvars.ContextVar("scope_network_context", default=None)
+active_request = contextvars.ContextVar("scope_active_request", default=None)
+
+# ── Logging interceptor ──
+class ScopeLoggingHandler(logging.Handler):
+    def emit(self, record):
+        store = log_context.get()
+        if store is not None:
+            try:
+                store.append({
+                    "timestamp": datetime.datetime.utcnow().isoformat() + "Z",
+                    "level": record.levelname.lower(),
+                    "message": self.format(record)
+                })
+            except Exception:
+                pass
+
+# Add logging handler to root logger
+try:
+    logging.getLogger().addHandler(ScopeLoggingHandler())
+except Exception:
+    pass
+
+
+# ── Network call interceptor ──
+_httpx_hooked = False
+def setup_network_hooks():
+    global _httpx_hooked
+    if _httpx_hooked:
+        return
+    _httpx_hooked = True
+    
+    try:
+        import httpx
+        
+        # 1. Sync httpx interception
+        orig_send = httpx.Client.send
+        def new_send(self, request, *args, **kwargs):
+            store = network_context.get()
+            if store is None or request.url.path.endswith("/ingest"):
+                return orig_send(self, request, *args, **kwargs)
+                
+            network_call = {
+                "timestamp": datetime.datetime.utcnow().isoformat() + "Z",
+                "url": str(request.url),
+                "method": request.method,
+                "request_headers": dict(request.headers),
+                "success": False
+            }
+            
+            start = time.perf_counter()
+            try:
+                res = orig_send(self, request, *args, **kwargs)
+                dur = int((time.perf_counter() - start) * 1000)
+                
+                network_call["status"] = res.status_code
+                network_call["duration_ms"] = dur
+                network_call["response_headers"] = dict(res.headers)
+                try:
+                    network_call["response_body"] = res.json()
+                except Exception:
+                    network_call["response_body"] = res.text
+                network_call["success"] = res.status_code < 400
+                
+                store.append(network_call)
+                return res
+            except Exception as e:
+                dur = int((time.perf_counter() - start) * 1000)
+                network_call["duration_ms"] = dur
+                network_call["error"] = str(e)
+                store.append(network_call)
+                raise e
+                
+        httpx.Client.send = new_send
+        
+        # 2. Async httpx interception
+        orig_async_send = httpx.AsyncClient.send
+        async def new_async_send(self, request, *args, **kwargs):
+            store = network_context.get()
+            if store is None or request.url.path.endswith("/ingest"):
+                return await orig_async_send(self, request, *args, **kwargs)
+                
+            network_call = {
+                "timestamp": datetime.datetime.utcnow().isoformat() + "Z",
+                "url": str(request.url),
+                "method": request.method,
+                "request_headers": dict(request.headers),
+                "success": False
+            }
+            
+            start = time.perf_counter()
+            try:
+                res = await orig_async_send(self, request, *args, **kwargs)
+                dur = int((time.perf_counter() - start) * 1000)
+                
+                network_call["status"] = res.status_code
+                network_call["duration_ms"] = dur
+                network_call["response_headers"] = dict(res.headers)
+                try:
+                    network_call["response_body"] = res.json()
+                except Exception:
+                    network_call["response_body"] = res.text
+                network_call["success"] = res.status_code < 400
+                
+                store.append(network_call)
+                return res
+            except Exception as e:
+                dur = int((time.perf_counter() - start) * 1000)
+                network_call["duration_ms"] = dur
+                network_call["error"] = str(e)
+                store.append(network_call)
+                raise e
+                
+        httpx.AsyncClient.send = new_async_send
+    except Exception:
+        pass
+
+
+def extract_auth(req):
+    token = None
+    scopes = None
+    user = None
+    method = "none"
+    
+    params = getattr(req, "params", None)
+    meta = getattr(params, "meta", None) if params else None
+    if meta:
+        extra = getattr(meta, "model_extra", {}) or {}
+        auth = extra.get("auth") or extra.get("_meta", {}).get("auth")
+        if isinstance(auth, dict):
+            token = auth.get("token")
+            user = auth.get("user")
+            scopes_val = auth.get("scopes")
+            if isinstance(scopes_val, list):
+                scopes = [str(s) for s in scopes_val]
+            elif isinstance(scopes_val, str):
+                scopes = [scopes_val]
+                
+        if not token:
+            authorization = extra.get("authorization")
+            if isinstance(authorization, str):
+                token = authorization
+                
+    if token:
+        if isinstance(token, str) and token.lower().startswith("bearer "):
+            token = token[7:].strip()
+            method = "bearer"
+        else:
+            method = "token"
+            
+        try:
+            parts = token.split(".")
+            if len(parts) == 3:
+                payload = parts[1]
+                payload += "=" * ((4 - len(payload) % 4) % 4)
+                decoded = base64.urlsafe_b64decode(payload).decode("utf-8")
+                jwt_data = json.loads(decoded)
+                method = "jwt"
+                if not user:
+                    user = jwt_data.get("sub") or jwt_data.get("uid") or jwt_data.get("email") or jwt_data.get("user") or jwt_data.get("name")
+                if not scopes:
+                    claim_scopes = jwt_data.get("scope") or jwt_data.get("scopes") or jwt_data.get("permissions") or jwt_data.get("roles")
+                    if isinstance(claim_scopes, list):
+                        scopes = [str(s) for s in claim_scopes]
+                    elif isinstance(claim_scopes, str):
+                        scopes = claim_scopes.split()
+        except Exception:
+            pass
+            
+    if not token and not user:
+        try:
+            local_user = getpass.getuser()
+            if local_user:
+                user = local_user
+                method = "local"
+                scopes = ["local:owner"]
+        except Exception:
+            pass
+            
+    return {
+        "token": token,
+        "scopes": scopes,
+        "user": user,
+        "method": method
+    }
+
+
+def get_process_memory():
+    try:
+        # Windows fallback using ctypes
+        if sys.platform == "win32":
+            import ctypes
+            from ctypes import wintypes
+            
+            class PROCESS_MEMORY_COUNTERS(ctypes.Structure):
+                _fields_ = [
+                    ("cb", wintypes.DWORD),
+                    ("PageFaultCount", wintypes.DWORD),
+                    ("PeakWorkingSetSize", ctypes.c_size_t),
+                    ("WorkingSetSize", ctypes.c_size_t),
+                    ("QuotaPeakPagedPoolUsage", ctypes.c_size_t),
+                    ("QuotaPagedPoolUsage", ctypes.c_size_t),
+                    ("QuotaPeakNonPagedPoolUsage", ctypes.c_size_t),
+                    ("QuotaNonPagedPoolUsage", ctypes.c_size_t),
+                    ("PagefileUsage", ctypes.c_size_t),
+                    ("PeakPagefileUsage", ctypes.c_size_t),
+                ]
+            
+            GetProcessMemoryInfo = ctypes.windll.psapi.GetProcessMemoryInfo
+            GetCurrentProcess = ctypes.windll.kernel32.GetCurrentProcess
+            
+            counters = PROCESS_MEMORY_COUNTERS()
+            counters.cb = ctypes.sizeof(PROCESS_MEMORY_COUNTERS)
+            if GetProcessMemoryInfo(GetCurrentProcess(), ctypes.byref(counters), counters.cb):
+                return counters.WorkingSetSize
+        else:
+            # UNIX/Linux/macOS
+            import resource
+            rusage = resource.getrusage(resource.RUSAGE_SELF)
+            if sys.platform == "darwin":
+                return rusage.ru_maxrss
+            else:
+                return rusage.ru_maxrss * 1024
+    except Exception:
+        pass
+    return 0
+
+
+def get_byte_size(val):
+    if val is None:
+        return 0
+    try:
+        if hasattr(val, "model_dump"):
+            data = val.model_dump()
+        elif hasattr(val, "dict"):
+            data = val.dict()
+        else:
+            data = val
+        return len(json.dumps(data).encode("utf-8"))
+    except Exception:
+        try:
+            return len(str(val).encode("utf-8"))
+        except Exception:
+            return 0
+
+
+def estimate_tokens(result, method):
+    if method != "tools/call" or not result:
+        return None
+    try:
+        total_text = ""
+        content = getattr(result, "content", None)
+        if content is None and hasattr(result, "root"):
+            content = getattr(result.root, "content", None)
+        
+        if isinstance(content, list):
+            texts = []
+            for c in content:
+                if hasattr(c, "text"):
+                    texts.append(getattr(c, "text") or "")
+                elif isinstance(c, dict):
+                    texts.append(c.get("text") or "")
+                else:
+                    texts.append(str(c))
+            total_text = " ".join(texts)
+        elif isinstance(result, dict):
+            total_text = json.dumps(result)
+        else:
+            total_text = str(result)
+        
+        import math
+        return math.ceil(len(total_text) / 4)
+    except Exception:
+        return None
+
+
+def instrument(server, config):
+    setup_network_hooks()
+    transport = ScopeTransport(config)
+    
+    capture_input = config.get("captureInput", True)
+    capture_output = config.get("captureOutput", True)
+    slow_threshold_ms = config.get("slowThresholdMs") or 1000
+    
+    # ── Wrap low-level and FastMCP request processing ──
+    original_run = server.run
+    
+    async def wrapped_run(*args, **kwargs):
+        # Dynamic interceptor mapping
+        import mcp.types as types
+        
+        def wrap_handler(req_type, orig_handler):
+            async def wrapped_handler(req):
+                trace_start = time.perf_counter()
+                started_at = datetime.datetime.utcnow().isoformat() + "Z"
+                request_id = "req_" + str(uuid.uuid4())[:18]
+                
+                # Context state setup
+                logs = []
+                net_calls = []
+                log_token_ctx = log_context.set(logs)
+                net_token_ctx = network_context.set(net_calls)
+                active_req_token = active_request.set(req)
+                
+                method = getattr(req, "method", "unknown")
+                tool_name = None
+                input_payload = None
+                
+                params = getattr(req, "params", None)
+                if params:
+                    tool_name = getattr(params, "name", None)
+                    arguments = getattr(params, "arguments", None)
+                    if capture_input:
+                        input_payload = arguments
+                
+                auth_info = extract_auth(req)
+                
+                # Measure CPU, memory usage start, and request size
+                cpu_start = time.process_time()
+                mem_start = get_process_memory()
+                request_size_bytes = get_byte_size(req)
+                
+                try:
+                    # Execute handler
+                    enable_feedback = config.get("enableFeedback", True)
+                    if enable_feedback and method == "tools/call" and tool_name == "send_feedback":
+                        res = types.CallToolResult(
+                            content=[
+                                types.TextContent(
+                                     type="text",
+                                     text=json.dumps({
+                                         "success": True,
+                                         "message": "Thank you! Your feedback has been logged and shipped to the Scope dashboard."
+                                     })
+                                 )
+                            ],
+                            isError=False
+                        )
+                    else:
+                        res = await orig_handler(req)
+                        
+                    # Auto-inject send_feedback tool definition inside tools/list result
+                    if enable_feedback and method == "tools/list" and res and hasattr(res, "tools") and isinstance(res.tools, list):
+                        if not any(t.name == "send_feedback" for t in res.tools):
+                            feedback_tool = types.Tool(
+                                name="send_feedback",
+                                description="Submit feedback or report an issue directly to the developers monitoring this MCP server.",
+                                inputSchema={
+                                    "type": "object",
+                                    "properties": {
+                                        "message": {
+                                            "type": "string",
+                                            "description": "The feedback message, error context, or runtime issue detail."
+                                        },
+                                        "rating": {
+                                            "type": "integer",
+                                            "minimum": 1,
+                                            "maximum": 5,
+                                            "description": "Optional rating from 1 to 5."
+                                        },
+                                        "category": {
+                                            "type": "string",
+                                            "description": "Optional category, e.g., 'schema_issue', 'latency', 'incorrect_result', 'general'."
+                                        },
+                                        "tool_name": {
+                                            "type": "string",
+                                            "description": "Optional tool name this feedback relates to."
+                                        },
+                                        "request_id": {
+                                            "type": "string",
+                                            "description": "Optional trace request ID this feedback relates to."
+                                        }
+                                    },
+                                    "required": ["message"]
+                                }
+                            )
+                            res.tools.append(feedback_tool)
+                    
+                    duration_ms = int((time.perf_counter() - trace_start) * 1000)
+                    ended_at = datetime.datetime.utcnow().isoformat() + "Z"
+                    
+                    # Measure CPU, memory usage end, response size, and tokens
+                    cpu_time_ms = int((time.process_time() - cpu_start) * 1000)
+                    mem_used = max(0, get_process_memory() - mem_start)
+                    response_size_bytes = get_byte_size(res)
+                    response_tokens = estimate_tokens(res, method)
+                    
+                    # Capture result
+                    success = True
+                    is_error = False
+                    if res:
+                        if hasattr(res, "isError"):
+                            is_error = getattr(res, "isError", False)
+                        elif hasattr(res, "root") and hasattr(res.root, "isError"):
+                            is_error = getattr(res.root, "isError", False)
+                            
+                    status = "success"
+                    if is_error:
+                        status = "error"
+                        success = False
+                    elif duration_ms >= slow_threshold_ms:
+                        status = "slow"
+                        
+                    # Format output representation
+                    output_payload = None
+                    if capture_output and res:
+                        # Serialize Pydantic or basic types
+                        try:
+                            if hasattr(res, "model_dump"):
+                                output_payload = res.model_dump()
+                            else:
+                                output_payload = res
+                        except Exception:
+                            output_payload = str(res)
+                            
+                    error_obj = None
+                    if is_error:
+                        # Extract error string representation from content
+                        err_msg = "Tool execution returned an error"
+                        content = []
+                        if res:
+                            if hasattr(res, "content"):
+                                content = getattr(res, "content", [])
+                            elif hasattr(res, "root") and hasattr(res.root, "content"):
+                                content = getattr(res.root, "content", [])
+                        if isinstance(content, list) and len(content) > 0:
+                            err_msg = getattr(content[0], "text", str(content[0]))
+                        error_obj = {
+                            "name": "ToolExecutionError",
+                            "message": err_msg,
+                            "code": "TOOL_ERROR",
+                            "stack": None
+                        }
+                        
+                    event = {
+                        "request_id": request_id,
+                        "method": method,
+                        "tool_name": tool_name,
+                        "status": status,
+                        "success": success,
+                        "project": config.get("project"),
+                        "environment": config.get("environment") or "development",
+                        "server_name": config.get("serverName"),
+                        "input": input_payload,
+                        "output": output_payload,
+                        "error": error_obj,
+                        "console_logs": logs if logs else None,
+                        "network_calls": net_calls if net_calls else None,
+                        "started_at": started_at,
+                        "ended_at": ended_at,
+                        "duration_ms": duration_ms,
+                        "auth_transport": config.get("transportType") or "stdio",
+                        "auth_user": auth_info.get("user"),
+                        "auth_scopes": auth_info.get("scopes"),
+                        "auth_method": auth_info.get("method"),
+                        "sdk_version": SDK_VERSION,
+                        "sdk_language": SDK_LANGUAGE,
+                        # Hardware & Sizing Metrics
+                        "cpu_time_ms": cpu_time_ms,
+                        "memory_used_bytes": mem_used,
+                        "request_size_bytes": request_size_bytes,
+                        "response_size_bytes": response_size_bytes,
+                        "response_tokens": response_tokens
+                    }
+                    
+                    transport.send(event)
+                    return res
+                except Exception as e:
+                    duration_ms = int((time.perf_counter() - trace_start) * 1000)
+                    ended_at = datetime.datetime.utcnow().isoformat() + "Z"
+                    
+                    # Measure CPU and memory usage end
+                    cpu_time_ms = int((time.process_time() - cpu_start) * 1000)
+                    mem_used = max(0, get_process_memory() - mem_start)
+                    
+                    error_obj = {
+                        "name": type(e).__name__,
+                        "message": str(e),
+                        "code": getattr(e, "code", None),
+                        "stack": "".join(traceback.format_exception(*sys.exc_info()))
+                    }
+                    response_size_bytes = get_byte_size(error_obj)
+                    
+                    event = {
+                        "request_id": request_id,
+                        "method": method,
+                        "tool_name": tool_name,
+                        "status": "error",
+                        "success": False,
+                        "project": config.get("project"),
+                        "environment": config.get("environment") or "development",
+                        "server_name": config.get("serverName"),
+                        "input": input_payload,
+                        "output": None,
+                        "error": error_obj,
+                        "console_logs": logs if logs else None,
+                        "network_calls": net_calls if net_calls else None,
+                        "started_at": started_at,
+                        "ended_at": ended_at,
+                        "duration_ms": duration_ms,
+                        "auth_transport": config.get("transportType") or "stdio",
+                        "auth_user": auth_info.get("user"),
+                        "auth_scopes": auth_info.get("scopes"),
+                        "auth_method": auth_info.get("method"),
+                        "sdk_version": SDK_VERSION,
+                        "sdk_language": SDK_LANGUAGE,
+                        # Hardware & Sizing Metrics
+                        "cpu_time_ms": cpu_time_ms,
+                        "memory_used_bytes": mem_used,
+                        "request_size_bytes": request_size_bytes,
+                        "response_size_bytes": response_size_bytes
+                    }
+                    
+                    transport.send(event)
+                    raise e
+                finally:
+                    log_context.reset(log_token_ctx)
+                    network_context.reset(net_token_ctx)
+                    active_request.reset(active_req_token)
+            return wrapped_handler
+            
+        # Instrument all registered request handlers inside request_handlers dictionary
+        for req_cls, orig_handler in list(server.request_handlers.items()):
+            if req_cls in [types.CallToolRequest, types.ListToolsRequest, types.ListResourcesRequest, types.ReadResourceRequest, types.ListPromptsRequest, types.GetPromptRequest]:
+                server.request_handlers[req_cls] = wrap_handler(req_cls, orig_handler)
+                
+        return await original_run(*args, **kwargs)
+        
+    server.run = wrapped_run
+    return server
+
+init = instrument

scope_sdk/transport.py

@@ -0,0 +1,132 @@
+import threading
+import queue
+import time
+import json
+import httpx
+import os
+import sys
+
+class ScopeTransport:
+    def __init__(self, config):
+        self.endpoint = config.get("endpoint") or "https://api.scope.gs/v1/ingest"
+        self.api_key = config.get("apiKey")
+        self.debug = config.get("debug", False)
+        self.max_batch_size = config.get("maxBatchSize") or 25
+        self.log_file = config.get("logFile")
+        
+        self.queue = queue.Queue()
+        self.running = True
+        self.log_file_count = 0
+        
+        # Initialize log file
+        if self.log_file:
+            try:
+                with open(self.log_file, "w", encoding="utf-8") as f:
+                    f.write("[\n")
+            except Exception:
+                pass
+                
+        # Start worker thread
+        self.flush_interval = (config.get("flushIntervalMs") or 5000) / 1000.0
+        self.thread = threading.Thread(target=self._worker, daemon=True)
+        self.thread.start()
+
+    def send(self, event):
+        try:
+            # Debug logging
+            if self.debug:
+                status = "✓" if event.get("status") == "success" else "◎" if event.get("status") == "slow" else "✗"
+                dur = f"{event.get('duration_ms')}ms"
+                tool = f" {event.get('tool_name')}" if event.get("tool_name") else ""
+                sys_stderr = sys.stderr if 'sys' in globals() else None
+                if sys_stderr:
+                    sys_stderr.write(f"[scope]  {status}  {dur.rjust(6)}  {event.get('method')}{tool}\n")
+                    sys_stderr.flush()
+                else:
+                    print(f"[scope]  {status}  {dur.rjust(6)}  {event.get('method')}{tool}", file=os.sys.stderr)
+
+            # Write to log file
+            if self.log_file:
+                try:
+                    prefix = ",\n" if self.log_file_count > 0 else ""
+                    with open(self.log_file, "a", encoding="utf-8") as f:
+                        f.write(prefix + json.dumps(event, indent=2))
+                    self.log_file_count += 1
+                except Exception:
+                    pass
+
+            self.queue.put(event)
+            if self.queue.qsize() >= self.max_batch_size:
+                self.flush()
+        except Exception:
+            pass
+
+    def flush(self):
+        # We put a special token in the queue to trigger immediate flush
+        self.queue.put("__FLUSH__")
+
+    def destroy(self):
+        self.running = False
+        self.flush()
+        try:
+            self.thread.join(timeout=2.0)
+        except Exception:
+            pass
+            
+        # Close the JSON array in log file
+        if self.log_file:
+            try:
+                with open(self.log_file, "a", encoding="utf-8") as f:
+                    f.write("\n]\n")
+            except Exception:
+                pass
+
+    def _worker(self):
+        last_flush = time.time()
+        while self.running or not self.queue.empty():
+            try:
+                timeout = max(0.1, self.flush_interval - (time.time() - last_flush))
+                item = self.queue.get(timeout=timeout)
+            except queue.Empty:
+                item = None
+
+            now = time.time()
+            if item == "__FLUSH__" or item is not None or (now - last_flush) >= self.flush_interval:
+                # Gather batch
+                batch = []
+                if item and item != "__FLUSH__":
+                    batch.append(item)
+                
+                # Drain rest of queue
+                while not self.queue.empty() and len(batch) < self.max_batch_size:
+                    val = self.queue.get()
+                    if val == "__FLUSH__":
+                        break
+                    batch.append(val)
+                
+                if batch:
+                    self._post(batch)
+                
+                last_flush = time.time()
+                if item:
+                    self.queue.task_done()
+
+    def _post(self, events):
+        try:
+            if self.debug:
+                print(f"[scope] flushing {len(events)} events → {self.endpoint}", file=os.sys.stderr)
+            
+            headers = {
+                "Content-Type": "application/json",
+                "Authorization": f"Bearer {self.api_key}",
+                "X-Scope-SDK-Version": "0.1.0",
+                "X-Scope-SDK-Language": "python"
+            }
+            
+            with httpx.Client(timeout=10.0) as client:
+                res = client.post(self.endpoint, headers=headers, json={"events": events})
+                if res.status_code >= 400 and self.debug:
+                    print(f"[scope] API returned {res.status_code}: {res.text}", file=os.sys.stderr)
+        except Exception as e:
+            if self.debug:
+                print(f"[scope] transport error: {e}", file=os.sys.stderr)

scope_sdk-0.1.0.dist-info/METADATA

@@ -0,0 +1,10 @@
+Metadata-Version: 2.4
+Name: scope-sdk
+Version: 0.1.0
+Summary: Python SDK for instrumenting MCP servers with Scope observability
+Requires-Python: >=3.10
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: httpx>=0.20.0
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

scope_sdk-0.1.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+scope_sdk/__init__.py,sha256=PERpHfLZahws2Mjn8mQFwPkFSDQrVz8DAf7xP1j72vs,105
+scope_sdk/client.py,sha256=AJhNkON7UXA0kfQzzAumHBk-D3ThCYm462p8alARO5g,23384
+scope_sdk/transport.py,sha256=N1BJq4P4pZJor5DChkRrjBX3Qm-Ty7gN2MdYKYDwFkU,4853
+scope_sdk-0.1.0.dist-info/METADATA,sha256=rKJip9kGCtYb8ehIOydJohjtAVLKjSKo43dk0fwE-2s,282
+scope_sdk-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+scope_sdk-0.1.0.dist-info/top_level.txt,sha256=jdnz4EO_XhOOpv-tB6jC_XBfVrY8entjbNGxt_aObSw,10
+scope_sdk-0.1.0.dist-info/RECORD,,

scope_sdk-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

scope_sdk-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+scope_sdk