dataify-sdk 0.1.0__py3-none-any.whl

dataify_mcp/tools/user.py

@@ -0,0 +1,79 @@
+"""User management tools.
+
+Wraps MCP tools for querying user account info, balance, API keys,
+and credit usage.
+
+Auto-generated.  Regenerate with: python scripts/codegen.py
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel
+
+
+# ---------------------------------------------------------------------------
+# query_user_info — no parameters
+# ---------------------------------------------------------------------------
+
+
+async def query_user_info(self) -> Any:
+    """Call ``query_user_info`` — 查询用户账号信息。
+
+    根据链接 token 查询 Dataify 用户账号信息、注册日期、
+    脱敏手机号和实名认证信息。
+    """
+    return await self.call_tool("query_user_info", {})
+
+
+# ---------------------------------------------------------------------------
+# query_user_balance — no parameters
+# ---------------------------------------------------------------------------
+
+
+async def query_user_balance(self) -> Any:
+    """Call ``query_user_balance`` — 查询用户余额。
+
+    查询 Dataify 用户剩余积分或余额、累计充值和累计使用。
+    """
+    return await self.call_tool("query_user_balance", {})
+
+
+# ---------------------------------------------------------------------------
+# query_user_api_keys — no parameters
+# ---------------------------------------------------------------------------
+
+
+async def query_user_api_keys(self) -> Any:
+    """Call ``query_user_api_keys`` — 查询用户 API Token 列表。
+
+    根据链接 token 查询当前 Dataify 用户的 API Token 列表。
+    """
+    return await self.call_tool("query_user_api_keys", {})
+
+
+# ---------------------------------------------------------------------------
+# query_user_credit_usage — no parameters
+# ---------------------------------------------------------------------------
+
+
+async def query_user_credit_usage(self) -> Any:
+    """Call ``query_user_credit_usage`` — 查询用户积分使用明细。
+
+    查询 Dataify 用户的每日积分消耗统计。
+    """
+    return await self.call_tool("query_user_credit_usage", {})
+
+
+# ---------------------------------------------------------------------------
+# Attach methods to DataifyClient
+# ---------------------------------------------------------------------------
+
+
+def _attach(client_cls: type) -> None:
+    """Attach all user management methods to the client class."""
+    client_cls.query_user_info = query_user_info
+    client_cls.query_user_balance = query_user_balance
+    client_cls.query_user_api_keys = query_user_api_keys
+    client_cls.query_user_credit_usage = query_user_credit_usage

dataify_mcp/tools/web_unlocker.py

@@ -0,0 +1,53 @@
+"""Web unlocker tool.
+
+Wraps the ``request_web_unlocker`` MCP tool for bypassing CAPTCHAs
+and extracting rendered page content.
+
+Auto-generated.  Regenerate with: python scripts/codegen.py
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class RequestWebUnlockerParams(BaseModel):
+    """Parameters for the ``request_web_unlocker`` tool.
+
+    调用 Dataify 通用采集 API，输入任意 URL，智能识别 CAPTCHA、
+    自动执行 JS 渲染，返回完整 PNG 截图或 HTML 源码。
+    """
+
+    url: str = Field(..., description="解锁网址，必填项")
+    type: str | None = Field(default="html", description="输出格式。html 和/或 png，逗号分隔，默认 html")
+    js_render: str | None = Field(default="True", description="JS 渲染，建议开启。True/False，默认 True")
+    block_resources: str | None = Field(default="", description="阻止加载的资源类型，逗号分隔 (javascript,css)")
+    clean_content: str | None = Field(default="", description="清除返回内容中的 JS 或 CSS 代码")
+    country: str | None = Field(default="us", description="代理所在国家/地区代码，默认 us")
+    headers: str | None = Field(default="", description='自定义请求 Headers，JSON 格式 {"aaa":"bbb"}')
+    cookies: str | None = Field(default="", description='自定义请求 Cookies，JSON 格式 {"aaa":"bbb"}')
+    wait: str | None = Field(default="", description="页面加载后额外等待的时间（毫秒）")
+    wait_for: str | None = Field(default="", description="等待指定的 CSS 选择器出现后再返回内容")
+    follow_redirect: str | None = Field(default="True", description="跟随 HTTP 重定向。True/False，默认 True")
+
+
+async def request_web_unlocker(self, params: RequestWebUnlockerParams | None = None) -> Any:
+    """Call ``request_web_unlocker`` — 通用网页解锁。
+
+    调用 Dataify 通用采集 API，输入任意 URL，智能识别 CAPTCHA、
+    自动执行 JS 渲染，返回完整 PNG 截图或 HTML 源码。
+    """
+    arguments = params.model_dump(exclude_none=True) if params else {}
+    return await self.call_tool("request_web_unlocker", arguments)
+
+
+# ---------------------------------------------------------------------------
+# Attach methods to DataifyClient
+# ---------------------------------------------------------------------------
+
+
+def _attach(client_cls: type) -> None:
+    """Attach all web unlocker methods to the client class."""
+    client_cls.request_web_unlocker = request_web_unlocker

dataify_mcp/tools/youtube.py

@@ -0,0 +1,163 @@
+"""YouTube scraper tools.
+
+Wraps all YouTube-related MCP tools: video, video_post, profiles,
+comment, transcript, product, and audio.
+
+Auto-generated.  Regenerate with: python scripts/codegen.py
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class _YouTubeFileParams(BaseModel):
+    """Base params for YouTube tools with file_name."""
+
+    file_name: str | None = Field(default="{{TasksID}}", description="Builder file_name")
+
+
+# ---------------------------------------------------------------------------
+# scrape_youtube_video
+# ---------------------------------------------------------------------------
+
+
+class ScrapeYouTubeVideoParams(_YouTubeFileParams):
+    """Parameters for ``scrape_youtube_video`` — YouTube 视频文件下载。
+
+    下载 YouTube 视频文件，支持字幕、分辨率、视频编码、音频格式等配置。
+    """
+
+    url: str = Field(default="https://www.youtube.com/watch?v=_SdpvpvVrLY", description="YouTube 视频 URL")
+    subtitles_language: str | None = Field(default="ab", description="字幕语言代码")
+    selected_only: str | None = Field(default="false", description="仅下载已选规格: true/false")
+    resolution: str | None = Field(default="<=360p", description="分辨率，如 <=1080p")
+    video_codec: str | None = Field(default="vp9", description="视频编码: vp9, avc1, av01")
+    audio_format: str | None = Field(default="opus", description="音频格式: opus, m4a")
+    bitrate: str | None = Field(default="<=320", description="比特率，如 <=320")
+
+
+async def scrape_youtube_video(self, params: ScrapeYouTubeVideoParams | None = None) -> Any:
+    """Call ``scrape_youtube_video`` — YouTube 视频文件下载。"""
+    arguments = params.model_dump(exclude_none=True) if params else {}
+    return await self.call_tool("scrape_youtube_video", arguments)
+
+
+# ---------------------------------------------------------------------------
+# scrape_youtube_video_post
+# ---------------------------------------------------------------------------
+
+
+class ScrapeYouTubeVideoPostParams(_YouTubeFileParams):
+    """Parameters for ``scrape_youtube_video_post`` — YouTube 视频帖子采集。"""
+
+    url: str = Field(..., description="YouTube 视频 URL")
+
+
+async def scrape_youtube_video_post(self, params: ScrapeYouTubeVideoPostParams | None = None) -> Any:
+    """Call ``scrape_youtube_video_post`` — YouTube 视频帖子采集。"""
+    arguments = params.model_dump(exclude_none=True) if params else {}
+    return await self.call_tool("scrape_youtube_video_post", arguments)
+
+
+# ---------------------------------------------------------------------------
+# scrape_youtube_profiles
+# ---------------------------------------------------------------------------
+
+
+class ScrapeYouTubeProfilesParams(_YouTubeFileParams):
+    """Parameters for ``scrape_youtube_profiles`` — YouTube 频道信息采集。"""
+
+    url: str = Field(..., description="YouTube 频道 URL")
+
+
+async def scrape_youtube_profiles(self, params: ScrapeYouTubeProfilesParams | None = None) -> Any:
+    """Call ``scrape_youtube_profiles`` — YouTube 频道信息采集。"""
+    arguments = params.model_dump(exclude_none=True) if params else {}
+    return await self.call_tool("scrape_youtube_profiles", arguments)
+
+
+# ---------------------------------------------------------------------------
+# scrape_youtube_comment
+# ---------------------------------------------------------------------------
+
+
+class ScrapeYouTubeCommentParams(_YouTubeFileParams):
+    """Parameters for ``scrape_youtube_comment`` — YouTube 评论采集。"""
+
+    url: str = Field(..., description="YouTube 视频 URL")
+
+
+async def scrape_youtube_comment(self, params: ScrapeYouTubeCommentParams | None = None) -> Any:
+    """Call ``scrape_youtube_comment`` — YouTube 评论采集。"""
+    arguments = params.model_dump(exclude_none=True) if params else {}
+    return await self.call_tool("scrape_youtube_comment", arguments)
+
+
+# ---------------------------------------------------------------------------
+# scrape_youtube_transcript
+# ---------------------------------------------------------------------------
+
+
+class ScrapeYouTubeTranscriptParams(_YouTubeFileParams):
+    """Parameters for ``scrape_youtube_transcript`` — YouTube 字幕采集。"""
+
+    url: str = Field(..., description="YouTube 视频 URL")
+
+
+async def scrape_youtube_transcript(self, params: ScrapeYouTubeTranscriptParams | None = None) -> Any:
+    """Call ``scrape_youtube_transcript`` — YouTube 字幕采集。"""
+    arguments = params.model_dump(exclude_none=True) if params else {}
+    return await self.call_tool("scrape_youtube_transcript", arguments)
+
+
+# ---------------------------------------------------------------------------
+# scrape_youtube_product
+# ---------------------------------------------------------------------------
+
+
+class ScrapeYouTubeProductParams(_YouTubeFileParams):
+    """Parameters for ``scrape_youtube_product`` — YouTube 商品采集。"""
+
+    url: str = Field(..., description="YouTube 商品相关 URL")
+
+
+async def scrape_youtube_product(self, params: ScrapeYouTubeProductParams | None = None) -> Any:
+    """Call ``scrape_youtube_product`` — YouTube 商品采集。"""
+    arguments = params.model_dump(exclude_none=True) if params else {}
+    return await self.call_tool("scrape_youtube_product", arguments)
+
+
+# ---------------------------------------------------------------------------
+# scrape_youtube_audio
+# ---------------------------------------------------------------------------
+
+
+class ScrapeYouTubeAudioParams(_YouTubeFileParams):
+    """Parameters for ``scrape_youtube_audio`` — YouTube 音频采集。"""
+
+    url: str = Field(..., description="YouTube 视频 URL")
+
+
+async def scrape_youtube_audio(self, params: ScrapeYouTubeAudioParams | None = None) -> Any:
+    """Call ``scrape_youtube_audio`` — YouTube 音频采集。"""
+    arguments = params.model_dump(exclude_none=True) if params else {}
+    return await self.call_tool("scrape_youtube_audio", arguments)
+
+
+# ---------------------------------------------------------------------------
+# Attach methods to DataifyClient
+# ---------------------------------------------------------------------------
+
+
+def _attach(client_cls: type) -> None:
+    """Attach all YouTube scraper methods to the client class."""
+    client_cls.scrape_youtube_video = scrape_youtube_video
+    client_cls.scrape_youtube_video_post = scrape_youtube_video_post
+    client_cls.scrape_youtube_profiles = scrape_youtube_profiles
+    client_cls.scrape_youtube_comment = scrape_youtube_comment
+    client_cls.scrape_youtube_transcript = scrape_youtube_transcript
+    client_cls.scrape_youtube_product = scrape_youtube_product
+    client_cls.scrape_youtube_audio = scrape_youtube_audio

dataify_mcp/types/__init__.py

@@ -0,0 +1,39 @@
+"""Type definitions for the Dataify MCP SDK."""
+
+from dataify_mcp.types._errors import (
+    AuthenticationError,
+    ConnectionError,
+    DataifyError,
+    ProtocolError,
+    ServerError,
+    TimeoutError,
+    ToolAccessError,
+    ToolError,
+)
+from dataify_mcp.types._mcp import (
+    JSONRPCError,
+    JSONRPCRequest,
+    JSONRPCResponse,
+    MCPServerCapabilities,
+    ServerInfo,
+    ToolDefinition,
+)
+
+__all__ = [
+    # MCP types
+    "JSONRPCRequest",
+    "JSONRPCResponse",
+    "JSONRPCError",
+    "ToolDefinition",
+    "ServerInfo",
+    "MCPServerCapabilities",
+    # Errors
+    "DataifyError",
+    "AuthenticationError",
+    "ToolAccessError",
+    "ConnectionError",
+    "ProtocolError",
+    "ToolError",
+    "TimeoutError",
+    "ServerError",
+]

dataify_mcp/types/_enums.py

@@ -0,0 +1,220 @@
+"""Enums for common Dataify parameter values.
+
+These provide type-safe alternatives to raw string literals when
+constructing tool parameters.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+# ---------------------------------------------------------------------------
+# Web Unlocker
+# ---------------------------------------------------------------------------
+
+
+class UnlockerOutputType(str, Enum):
+    """Output format for request_web_unlocker 'type' parameter."""
+
+    HTML = "html"
+    PNG = "png"
+    HTML_PNG = "html,png"
+
+
+# ---------------------------------------------------------------------------
+# Google / Bing / Search Engine
+# ---------------------------------------------------------------------------
+
+
+class JSONOutputFormat(str, Enum):
+    """JSON output format for search engine results."""
+
+    JSON = "1"
+    JSON_HTML = "2"
+    HTML = "3"
+    LIGHT_JSON = "4"
+
+
+class Device(str, Enum):
+    """Device type for search engine emulation."""
+
+    DESKTOP = "desktop"
+    TABLET = "tablet"
+    MOBILE = "mobile"
+
+
+class SafeSearch(str, Enum):
+    """SafeSearch / adult content filtering."""
+
+    ACTIVE = "active"
+    OFF = "off"
+
+
+class BingSafeSearch(str, Enum):
+    """Bing SafeSearch levels."""
+
+    OFF = "Off"
+    MODERATE = "Moderate"
+    STRICT = "Strict"
+
+
+class DuckDuckGoSafeSearch(str, Enum):
+    """DuckDuckGo SafeSearch levels."""
+
+    STRICT = "1"
+    MODERATE = "-1"
+    OFF = "-2"
+
+
+class DateFilter(str, Enum):
+    """Date filter shortcuts for search results."""
+
+    PAST_DAY = "d"
+    PAST_WEEK = "w"
+    PAST_MONTH = "m"
+    PAST_YEAR = "y"
+
+
+class TaskStatus(str, Enum):
+    """Generic task status codes."""
+
+    ALL = "-1"
+    PROCESSING = "-1"
+    SUCCESS = "0"
+    FAILED = "1"
+
+
+class ScraperTaskStatus(str, Enum):
+    """Scraper task status codes."""
+
+    ALL = "0"
+    PROCESSING = "-1"
+    SUCCESS = "200"
+    FAILED = "400"
+
+
+class ScraperType(str, Enum):
+    """Scraper product type."""
+
+    ALL = "-1"
+    WEB_SCRAPER = "0"
+    SERP = "1"
+
+
+class TaskType(str, Enum):
+    """Scraper task type."""
+
+    ALL = "0"
+    SERP = "1"
+    WEB_SCRAPER = "2"
+
+
+# ---------------------------------------------------------------------------
+# Yandex
+# ---------------------------------------------------------------------------
+
+
+class YandexFamilyMode(str, Enum):
+    """Yandex SafeSearch / family filter."""
+
+    OFF = "0"
+    MODERATE = "1"
+    STRICT = "2"
+
+
+# ---------------------------------------------------------------------------
+# Amazon
+# ---------------------------------------------------------------------------
+
+
+class AmazonSpiderID(str, Enum):
+    """Amazon product spider identifiers."""
+
+    BY_ASIN = "amazon_product_by-asin"
+    BY_URL = "amazon_product_by-url"
+    BY_KEYWORDS = "amazon_product_by-keywords"
+    BY_CATEGORY_URL = "amazon_product_by-category-url"
+    BY_BEST_SELLERS = "amazon_product_by-best-sellers"
+
+
+class AmazonDomain(str, Enum):
+    """Amazon marketplace domains."""
+
+    COM = "amazon.com"
+    JP = "amazon.co.jp"
+    DE = "amazon.de"
+    UK = "amazon.co.uk"
+    FR = "amazon.fr"
+    IT = "amazon.it"
+    ES = "amazon.es"
+    CA = "amazon.ca"
+    IN = "amazon.in"
+    BR = "amazon.com.br"
+    MX = "amazon.com.mx"
+    AU = "amazon.com.au"
+
+
+class AmazonSortBy(str, Enum):
+    """Amazon product sorting options (Chinese)."""
+
+    BEST_SELLERS = "畅销排行"
+    NEWEST_ARRIVALS = "最新上架"
+    AVG_CUSTOMER_REVIEW = "平均评价"
+    PRICE_HIGH_TO_LOW = "价格：从高到低"
+    PRICE_LOW_TO_HIGH = "价格：从低到高"
+    FEATURED = "精选推荐"
+
+
+# ---------------------------------------------------------------------------
+# YouTube
+# ---------------------------------------------------------------------------
+
+
+class YouTubeVideoCodec(str, Enum):
+    """YouTube video codec options."""
+
+    VP9 = "vp9"
+    AVC1 = "avc1"  # Also: h264, avc
+    AV01 = "av01"  # Also: av1
+
+
+class YouTubeAudioFormat(str, Enum):
+    """YouTube audio format options."""
+
+    OPUS = "opus"
+    M4A = "m4a"  # Also: aac
+
+
+class YouTubeResolution(str, Enum):
+    """YouTube video resolution options (bare value, no operator)."""
+
+    P360 = "360p"
+    P480 = "480p"
+    P720 = "720p"
+    P1080 = "1080p"
+    P1440 = "1440p"
+    P2160 = "2160p"
+
+
+class YouTubeBitrate(str, Enum):
+    """YouTube audio bitrate options (bare value, no operator)."""
+
+    K48 = "48"
+    K64 = "64"
+    K128 = "128"
+    K160 = "160"
+    K256 = "256"
+    K320 = "320"
+
+
+# ---------------------------------------------------------------------------
+# Comparison operators
+# ---------------------------------------------------------------------------
+
+
+class ComparisonOp(str, Enum):
+    """Comparison operators used in YouTube resolution/bitrate."""
+
+    LE = "<="
+    GE = ">="

dataify_mcp/types/_errors.py

@@ -0,0 +1,73 @@
+"""Error hierarchy for the Dataify MCP SDK.
+
+Every exception raised by the SDK inherits from `DataifyError`, making it
+easy to catch any SDK-related error with a single except clause.
+"""
+
+from __future__ import annotations
+
+
+class DataifyError(Exception):
+    """Base exception for all SDK errors."""
+
+
+class AuthenticationError(DataifyError):
+    """Raised when the API token is missing, invalid, or expired.
+
+    The user should obtain a valid token from https://dashboard.dataify.com
+    and pass it to the client constructor or as a query parameter.
+    """
+
+
+class ToolAccessError(DataifyError):
+    """Raised when the token does not have permission to use a specific tool.
+
+    This typically means the tool is not in the user's plan.  The user can
+    upgrade via https://dashboard.dataify.com or pass a ``tools=`` query
+    parameter to limit which tools are requested.
+    """
+
+
+class ConnectionError(DataifyError):
+    """Raised when the SDK cannot connect to the MCP server.
+
+    This covers DNS resolution failures, TCP connection refused, TLS errors,
+    and other transport-level issues.
+    """
+
+
+class ProtocolError(DataifyError):
+    """Raised when the server sends an invalid or unexpected JSON-RPC response.
+
+    Examples include missing ``id`` fields, invalid JSON, or responses that
+    don't match any pending request.
+    """
+
+
+class ToolError(DataifyError):
+    """Raised when a tool call returns ``isError: true``.
+
+    The tool executed on the server side but failed (e.g. upstream API
+    returned an error, invalid parameters, etc.).  The error message
+    comes from the server.
+    """
+
+
+class TimeoutError(DataifyError):
+    """Raised when a request to the MCP server exceeds the configured timeout."""
+
+
+class ServerError(DataifyError):
+    """Raised when the server returns an HTTP 5xx status code."""
+
+
+# Maps JSON-RPC error codes to SDK exception types.
+# Reference: https://www.jsonrpc.org/specification#error_object
+ERROR_CODE_MAP: dict[int, type[DataifyError]] = {
+    -32000: ServerError,      # Server error (generic)
+    -32600: ProtocolError,    # Invalid Request
+    -32601: ProtocolError,    # Method not found
+    -32602: ProtocolError,    # Invalid params
+    -32603: ServerError,      # Internal error
+    -32001: AuthenticationError,  # Unauthorized (common MCP convention)
+}