dataify-sdk 0.1.0__py3-none-any.whl

dataify_mcp/__init__.py

@@ -0,0 +1,37 @@
+"""Dataify MCP SDK — Python client for the Dataify MCP API.
+
+Provides access to web unlocker, search engines (Google, Bing, Yandex, DuckDuckGo),
+and platform scrapers (Amazon, YouTube, TikTok, Facebook, Instagram, etc.) through
+the Model Context Protocol.
+"""
+
+from dataify_mcp._version import __version__
+from dataify_mcp.client._base import DataifyClient
+from dataify_mcp.client._http import HTTPTransport
+from dataify_mcp.client._sse import SSETransport
+from dataify_mcp.types._errors import (
+    AuthenticationError,
+    ConnectionError,
+    DataifyError,
+    ProtocolError,
+    ServerError,
+    TimeoutError,
+    ToolAccessError,
+    ToolError,
+)
+
+__all__ = [
+    "__version__",
+    "DataifyClient",
+    "HTTPTransport",
+    "SSETransport",
+    # Errors
+    "DataifyError",
+    "AuthenticationError",
+    "ToolAccessError",
+    "ConnectionError",
+    "ProtocolError",
+    "ToolError",
+    "TimeoutError",
+    "ServerError",
+]

dataify_mcp/_version.py

@@ -0,0 +1,3 @@
+"""Single source of truth for the package version."""
+
+__version__ = "0.1.0"

dataify_mcp/client/__init__.py

@@ -0,0 +1,7 @@
+"""Client transports and the main DataifyClient."""
+
+from dataify_mcp.client._base import DataifyClient
+from dataify_mcp.client._http import HTTPTransport
+from dataify_mcp.client._sse import SSETransport
+
+__all__ = ["DataifyClient", "HTTPTransport", "SSETransport"]

dataify_mcp/client/_base.py

@@ -0,0 +1,223 @@
+"""DataifyClient — the main entry point for the Dataify MCP SDK.
+
+Usage::
+
+    import asyncio
+    from dataify_mcp import DataifyClient
+
+    async def main():
+        async with DataifyClient(
+            base_url="http://localhost:7780",
+            token="your-api-token",
+        ) as client:
+            tools = await client.list_tools()
+            print(f"Available tools: {len(tools)}")
+
+            result = await client.call_tool("google_search", {"q": "weather"})
+            print(result)
+
+    asyncio.run(main())
+"""
+
+from __future__ import annotations
+
+import logging
+from types import TracebackType
+from typing import Any
+
+from dataify_mcp._version import __version__
+from dataify_mcp.client._http import HTTPTransport
+from dataify_mcp.client._protocol import MCPProtocol
+from dataify_mcp.client._sse import SSETransport
+from dataify_mcp.types._errors import ConnectionError
+from dataify_mcp.types._mcp import ServerInfo, ToolDefinition
+
+logger = logging.getLogger(__name__)
+
+CLIENT_NAME = "dataify-mcp-sdk"
+
+
+class DataifyClient:
+    """Async client for the Dataify MCP API.
+
+    Wraps an MCP transport and protocol to provide a simple, Pythonic
+    interface for listing and calling MCP tools.
+
+    Parameters
+    ----------
+    base_url:
+        Base URL of the MCP server, e.g. ``http://localhost:7780``.
+    token:
+        Dataify API token. Obtain from https://dashboard.dataify.com.
+    tool_codes:
+        Optional comma-separated list of ``class_code,tool_code`` pairs
+        to filter which tools are available.  Without this parameter only
+        free tools are visible.
+    timeout:
+        HTTP request timeout in seconds (default 30).
+    transport:
+        Transport mode: ``"http"`` (default) or ``"sse"``.
+    """
+
+    def __init__(
+        self,
+        base_url: str,
+        token: str,
+        *,
+        tool_codes: str | None = None,
+        timeout: float = 30.0,
+        transport: str = "http",
+    ) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._token = token
+        self._tool_codes = tool_codes
+        self._timeout = timeout
+
+        self._protocol = MCPProtocol()
+
+        if transport == "sse":
+            self._transport = SSETransport(
+                base_url=base_url,
+                token=token,
+                tool_codes=tool_codes,
+                timeout=timeout,
+            )
+        else:
+            self._transport = HTTPTransport(
+                base_url=base_url,
+                token=token,
+                tool_codes=tool_codes,
+                timeout=timeout,
+            )
+
+        self._transport_type = transport
+
+    # ------------------------------------------------------------------
+    # Context manager
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> "DataifyClient":
+        await self.initialize()
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        await self.close()
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def initialize(self) -> ServerInfo:
+        """Open the transport, perform the MCP handshake, and return server info.
+
+        This is called automatically when using the async context manager.
+        If you create a client manually you must call this before using it.
+        """
+        await self._transport.open()
+
+        # Step 1: initialize
+        init_req = self._protocol.build_initialize_request(CLIENT_NAME, __version__)
+        init_resp = await self._transport.send_request(init_req)
+        info = self._protocol.process_initialize_response(init_resp)
+
+        logger.info(
+            "Connected to %s v%s (protocol %s)",
+            info.name,
+            info.version,
+            info.protocol_version,
+        )
+
+        # Step 2: send initialized notification
+        notif = self._protocol.build_initialized_notification()
+        await self._transport.send_notification(notif)
+
+        return info
+
+    async def close(self) -> None:
+        """Close the underlying transport."""
+        await self._transport.close()
+
+    @property
+    def server_info(self) -> ServerInfo | None:
+        """Information returned by the server during initialization."""
+        return self._protocol.server_info
+
+    @property
+    def is_initialized(self) -> bool:
+        """Whether the MCP handshake has completed."""
+        return self._protocol.initialized
+
+    # ------------------------------------------------------------------
+    # MCP operations
+    # ------------------------------------------------------------------
+
+    async def list_tools(self) -> list[ToolDefinition]:
+        """Fetch the list of available tools from the server.
+
+        The returned list respects the ``tool_codes`` filter if one was
+        provided at construction time.
+        """
+        if not self.is_initialized:
+            raise ConnectionError("Client not initialized. Call initialize() first.")
+
+        req = self._protocol.build_list_tools_request()
+        resp = await self._transport.send_request(req)
+        return self._protocol.process_list_tools_response(resp)
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        """Call an MCP tool by name with the given keyword arguments.
+
+        Parameters
+        ----------
+        name:
+            Tool name (e.g. ``"google_search"``, ``"request_web_unlocker"``).
+        arguments:
+            Tool parameters as a dictionary.  All values are passed as
+            strings matching the server's expected format.
+
+        Returns
+        -------
+        Any
+            The tool result content (usually a dict).
+
+        Raises
+        ------
+        ToolError
+            When the tool execution fails on the server side.
+        ConnectionError
+            When the transport is not initialized or has been closed.
+        """
+        if not self.is_initialized:
+            raise ConnectionError("Client not initialized. Call initialize() first.")
+
+        req = self._protocol.build_call_tool_request(name, arguments)
+        resp = await self._transport.send_request(req)
+        return self._protocol.process_call_tool_response(resp)
+
+    async def ping(self) -> None:
+        """Send a ping to verify the server is reachable."""
+        req = self._protocol.build_ping_request()
+        resp = await self._transport.send_request(req)
+        self._protocol.process_ping_response(resp)
+
+    # ------------------------------------------------------------------
+    # -- High-level convenience methods (auto-attached) --
+    #
+    # Typed tool methods (google_search, request_web_unlocker, etc.) are
+    # attached to this class at import time by ``dataify_mcp.tools.attach_all``.
+    # See ``src/dataify_mcp/tools/__init__.py``.
+    #
+    # When the server adds new tools, regenerate the tool modules by running:
+    #     python scripts/codegen.py --server http://localhost:7780
+    # ------------------------------------------------------------------
+
+
+# Attach all typed tool methods to the DataifyClient class at import time.
+from dataify_mcp.tools import attach_all  # noqa: E402
+
+attach_all(DataifyClient)

dataify_mcp/client/_http.py

@@ -0,0 +1,205 @@
+"""Streamable HTTP transport for MCP.
+
+Implements the Streamable HTTP transport defined by the MCP spec:
+POST ``/mcp`` with JSON-RPC bodies; the server may return the response
+directly or stream it via SSE.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from dataify_mcp.types._errors import (
+    ConnectionError,
+    ProtocolError,
+    ServerError,
+    TimeoutError,
+)
+from dataify_mcp.types._mcp import JSONRPCError, JSONRPCRequest, JSONRPCResponse
+
+logger = logging.getLogger(__name__)
+
+# Headers used by the MCP Streamable HTTP transport.
+HEADER_SESSION_ID = "Mcp-Session-Id"
+HEADER_LAST_EVENT_ID = "Last-Event-ID"
+HEADER_CONTENT_TYPE = "Content-Type"
+MIME_JSON = "application/json"
+
+
+@dataclass
+class HTTPTransport:
+    """Streamable HTTP transport that talks to the ``/mcp`` endpoint.
+
+    Parameters
+    ----------
+    base_url:
+        Base URL of the MCP server, e.g. ``http://localhost:7780``.
+        Must not include a trailing slash.
+    token:
+        Dataify API token passed as the ``?token=`` query parameter.
+    tool_codes:
+        Optional comma-separated tool codes passed as ``?tools=``.
+    timeout:
+        HTTP request timeout in seconds (default 30).
+    """
+
+    base_url: str
+    token: str
+    tool_codes: str | None = None
+    timeout: float = 30.0
+
+    # --- internal state -------------------------------------------------
+
+    _client: httpx.AsyncClient | None = None
+    _session_id: str | None = None
+
+    # --- URL construction -----------------------------------------------
+
+    @property
+    def endpoint(self) -> str:
+        """Full URL of the MCP endpoint including auth query params."""
+        url = f"{self.base_url.rstrip('/')}/mcp?token={self.token}"
+        if self.tool_codes:
+            url += f"&tools={self.tool_codes}"
+        return url
+
+    # --- lifecycle ------------------------------------------------------
+
+    async def open(self) -> None:
+        """Create the underlying HTTP client if not already open."""
+        if self._client is not None:
+            return
+        self._client = httpx.AsyncClient(timeout=httpx.Timeout(self.timeout))
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        if self._client is not None:
+            await self._client.aclose()
+            self._client = None
+            self._session_id = None
+
+    @property
+    def is_open(self) -> bool:
+        """Check whether the transport is currently open."""
+        return self._client is not None and not self._client.is_closed
+
+    # --- request/response -----------------------------------------------
+
+    async def send_request(self, request: JSONRPCRequest) -> JSONRPCResponse:
+        """Send a JSON-RPC request and return the parsed response.
+
+        Raises
+        ------
+        ConnectionError
+            On network-level failures.
+        ProtocolError
+            When the server response is not valid JSON or lacks the expected fields.
+        ServerError
+            When the server returns HTTP 5xx.
+        TimeoutError
+            When the request exceeds the configured timeout.
+        """
+        if self._client is None:
+            raise ConnectionError("Transport is not open. Call open() first.")
+
+        headers: dict[str, str] = {
+            HEADER_CONTENT_TYPE: MIME_JSON,
+            "Accept": MIME_JSON,
+        }
+        if self._session_id:
+            headers[HEADER_SESSION_ID] = self._session_id
+
+        body = {
+            "jsonrpc": request.jsonrpc,
+            "id": request.id,
+            "method": request.method,
+            "params": request.params or {},
+        }
+
+        logger.debug("MCP request  id=%d method=%s", request.id, request.method)
+
+        try:
+            http_resp = await self._client.post(
+                self.endpoint,
+                json=body,
+                headers=headers,
+            )
+        except httpx.TimeoutException as exc:
+            raise TimeoutError(
+                f"Request id={request.id} method={request.method} timed out "
+                f"after {self.timeout}s"
+            ) from exc
+        except httpx.NetworkError as exc:
+            raise ConnectionError(
+                f"Network error sending request id={request.id}: {exc}"
+            ) from exc
+
+        # Capture session id from server response
+        session_id = http_resp.headers.get(HEADER_SESSION_ID)
+        if session_id:
+            self._session_id = session_id
+
+        # Handle HTTP errors
+        if http_resp.status_code >= 500:
+            raise ServerError(
+                f"Server returned HTTP {http_resp.status_code}: {http_resp.text[:500]}"
+            )
+        if http_resp.status_code == 401 or http_resp.status_code == 403:
+            from dataify_mcp.types._errors import AuthenticationError
+
+            raise AuthenticationError(
+                f"Authentication failed (HTTP {http_resp.status_code}). "
+                "Check your API token at https://dashboard.dataify.com"
+            )
+
+        # Try to parse the response body as JSON
+        try:
+            data = http_resp.json()
+        except json.JSONDecodeError as exc:
+            raise ProtocolError(
+                f"Invalid JSON response for id={request.id}: {http_resp.text[:500]}"
+            ) from exc
+
+        # Build JSONRPCResponse
+        return JSONRPCResponse(
+            jsonrpc=data.get("jsonrpc", "2.0"),
+            id=data.get("id", request.id),
+            result=data.get("result"),
+            error=JSONRPCError(**data["error"]) if "error" in data and data["error"] else None,
+        )
+
+    async def send_notification(self, request: JSONRPCRequest) -> None:
+        """Send a JSON-RPC notification (no response expected)."""
+        if self._client is None:
+            raise ConnectionError("Transport is not open. Call open() first.")
+
+        headers: dict[str, str] = {
+            HEADER_CONTENT_TYPE: MIME_JSON,
+            "Accept": MIME_JSON,
+        }
+        if self._session_id:
+            headers[HEADER_SESSION_ID] = self._session_id
+
+        body = {
+            "jsonrpc": request.jsonrpc,
+            "method": request.method,
+            "params": request.params or {},
+        }
+
+        logger.debug("MCP notification method=%s", request.method)
+
+        try:
+            await self._client.post(
+                self.endpoint,
+                json=body,
+                headers=headers,
+            )
+        except httpx.TimeoutException:
+            logger.warning("Notification %s timed out (ignoring)", request.method)
+        except httpx.NetworkError as exc:
+            logger.warning("Notification %s failed: %s", request.method, exc)

dataify_mcp/client/_protocol.py

@@ -0,0 +1,204 @@
+"""MCP protocol lifecycle management.
+
+Handles JSON-RPC 2.0 message IDs, the ``initialize`` → ``initialized``
+handshake, ``tools/list``, ``tools/call``, and ``ping``.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from dataify_mcp.types._errors import ERROR_CODE_MAP, ProtocolError, ToolError
+from dataify_mcp.types._mcp import (
+    JSONRPCError,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    ServerInfo,
+    ToolDefinition,
+)
+
+logger = logging.getLogger(__name__)
+
+# MCP protocol version requested by this SDK.
+MCP_PROTOCOL_VERSION = "2024-11-05"
+
+# Standard MCP method names.
+METHOD_INITIALIZE = "initialize"
+METHOD_INITIALIZED = "notifications/initialized"
+METHOD_TOOLS_LIST = "tools/list"
+METHOD_TOOLS_CALL = "tools/call"
+METHOD_PING = "ping"
+
+
+class MCPProtocol:
+    """Manages the MCP JSON-RPC conversation with a single transport.
+
+    The protocol is responsible for:
+
+    * Tracking monotonically increasing message IDs.
+    * Performing the MCP handshake (``initialize`` + ``initialized``).
+    * Exposing high-level methods that match MCP capabilities
+      (``list_tools``, ``call_tool``, ``ping``).
+    """
+
+    def __init__(self) -> None:
+        self._next_id = 0
+        self._server_info: ServerInfo | None = None
+        self._initialized = False
+
+    # ------------------------------------------------------------------
+    # ID management
+    # ------------------------------------------------------------------
+
+    def _allocate_id(self) -> int:
+        """Return the next JSON-RPC message id."""
+        self._next_id += 1
+        return self._next_id
+
+    @property
+    def server_info(self) -> ServerInfo | None:
+        """Information returned by the server during initialization."""
+        return self._server_info
+
+    @property
+    def initialized(self) -> bool:
+        """Whether the MCP handshake has completed."""
+        return self._initialized
+
+    # ------------------------------------------------------------------
+    # Request builders
+    # ------------------------------------------------------------------
+
+    def build_initialize_request(self, client_name: str, client_version: str) -> JSONRPCRequest:
+        """Build the ``initialize`` request."""
+        return JSONRPCRequest(
+            method=METHOD_INITIALIZE,
+            id=self._allocate_id(),
+            params={
+                "protocolVersion": MCP_PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": {
+                    "name": client_name,
+                    "version": client_version,
+                },
+            },
+        )
+
+    def build_initialized_notification(self) -> JSONRPCRequest:
+        """Build the ``notifications/initialized`` notification."""
+        return JSONRPCRequest(
+            method=METHOD_INITIALIZED,
+            id=self._allocate_id(),
+            params={},
+        )
+
+    def build_list_tools_request(self) -> JSONRPCRequest:
+        """Build the ``tools/list`` request."""
+        return JSONRPCRequest(
+            method=METHOD_TOOLS_LIST,
+            id=self._allocate_id(),
+            params={},
+        )
+
+    def build_call_tool_request(self, name: str, arguments: dict[str, Any]) -> JSONRPCRequest:
+        """Build the ``tools/call`` request."""
+        return JSONRPCRequest(
+            method=METHOD_TOOLS_CALL,
+            id=self._allocate_id(),
+            params={"name": name, "arguments": arguments},
+        )
+
+    def build_ping_request(self) -> JSONRPCRequest:
+        """Build the ``ping`` request."""
+        return JSONRPCRequest(
+            method=METHOD_PING,
+            id=self._allocate_id(),
+            params={},
+        )
+
+    # ------------------------------------------------------------------
+    # Response processors
+    # ------------------------------------------------------------------
+
+    def process_initialize_response(self, response: JSONRPCResponse) -> ServerInfo:
+        """Validate and extract server info from an ``initialize`` response."""
+        self._check_response(response)
+        result = response.result
+
+        capabilities_raw = result.get("capabilities", {})
+        from dataify_mcp.types._mcp import MCPServerCapabilities
+
+        info = ServerInfo(
+            name=result.get("serverInfo", {}).get("name", "unknown"),
+            version=result.get("serverInfo", {}).get("version", "0.0.0"),
+            protocol_version=result.get("protocolVersion", ""),
+            capabilities=MCPServerCapabilities(
+                tools=capabilities_raw.get("tools"),
+                resources=capabilities_raw.get("resources"),
+                prompts=capabilities_raw.get("prompts"),
+                logging=capabilities_raw.get("logging"),
+                experimental=capabilities_raw.get("experimental"),
+            ),
+            instructions=result.get("instructions"),
+        )
+        self._server_info = info
+        self._initialized = True
+        return info
+
+    def process_list_tools_response(self, response: JSONRPCResponse) -> list[ToolDefinition]:
+        """Extract tool definitions from a ``tools/list`` response."""
+        self._check_response(response)
+        tools_data: list[dict[str, Any]] = response.result.get("tools", [])
+        return [
+            ToolDefinition(
+                name=t["name"],
+                description=t.get("description", ""),
+                inputSchema=t.get("inputSchema", {}),
+            )
+            for t in tools_data
+        ]
+
+    def process_call_tool_response(self, response: JSONRPCResponse) -> Any:
+        """Extract the tool result from a ``tools/call`` response.
+
+        Returns the ``content`` field of the result.  Raises ``ToolError``
+        when ``isError`` is true.
+        """
+        self._check_response(response)
+
+        # MCP tools/call result may be nested inside content array
+        result = response.result
+        is_error = result.get("isError", False)
+
+        content = result.get("content", result)
+        if isinstance(content, list) and len(content) == 1:
+            item = content[0]
+            if isinstance(item, dict) and "text" in item:
+                content = item["text"]
+            elif isinstance(item, dict) and "data" in item:
+                content = item["data"]
+            else:
+                content = item
+
+        if is_error:
+            error_text = content if isinstance(content, str) else result.get("content", [{}])[0].get("text", str(content)) if isinstance(result.get("content"), list) else str(content)
+            raise ToolError(error_text)
+
+        return content
+
+    def process_ping_response(self, response: JSONRPCResponse) -> None:
+        """Validate a ``ping`` response (no-op on success)."""
+        self._check_response(response)
+
+    # ------------------------------------------------------------------
+    # Helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _check_response(response: JSONRPCResponse) -> None:
+        """Raise the appropriate SDK exception if the response is an error."""
+        if response.error is not None:
+            err = response.error
+            exc_cls = ERROR_CODE_MAP.get(err.code, ProtocolError)
+            raise exc_cls(f"[{err.code}] {err.message}" + (f": {err.data}" if err.data else ""))