mcpscraper-memory-sdk 0.49.0__tar.gz → 0.50.0__tar.gz

mcpscraper_memory_sdk-0.50.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.5
+Name: mcpscraper-memory-sdk
+Version: 0.50.0
+Summary: Official Python clients for the unified 347-tool MCP Scraper catalog, including Memory, Research, and CRM
+Project-URL: Repository, https://github.com/VilovietaSEO/mcpscraper-sdk
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: pydantic>=2
+Requires-Dist: requests>=2.31
+Description-Content-Type: text/markdown
+
+# mcpscraper-memory-sdk (Python)
+
+Official Python clients for the unified [mcpscraper.dev](https://mcpscraper.dev) MCP catalog.
+The direct Memory manifest remains checked for runtime compatibility.
+
+[Release history](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/main/CHANGELOG.md)
+
+This is a thin JSON-RPC client generated against [`../../contracts/memory.tools.json`](../../contracts/memory.tools.json), the public contract for the hosted API. It contains no product source — only typed request/response plumbing.
+
+## Install
+
+```bash
+pip install mcpscraper-memory-sdk
+```
+
+## Usage
+
+```python
+import os
+from mcpscraper_memory import MemoryClient, MemoryApiError
+
+client = MemoryClient(api_key=os.environ["MCP_SCRAPER_API_KEY"])
+
+try:
+    result = client.memory.search(query="competitor pricing pages")
+    for hit in result.results or []:
+        print(hit["source"], hit["score"])
+except MemoryApiError as err:
+    print(f"memory call failed: {err}")
+```
+
+## Namespaces
+
+`client.access`, `client.capture`, `client.channels`, `client.crm`, `client.facts`, `client.files`, `client.graph`, `client.library`, `client.memory`, `client.recall`, `client.research`, `client.artifacts`, `client.storage`, `client.tables`, `client.tags`, `client.vaults`, `client.video`, `client.webhooks` — one method per tool, snake_case, typed with generated Pydantic models. Use Research for sourced knowledge and CRM for an actual relationship; counterpart operations link records without copying fields. External CRM providers remain unavailable, with no setup or write wrapper. Original Gmail attachment bytes saved to Memory are available through `client.files.file_asset_save(...)` and `client.files.file_asset_get(...)`.
+
+Use the same key with `McpToolsClient` for all unified scraper and Memory tools.
+
+Use `client.call_tool_result(name, args)` for native MCP image, audio, or resource blocks. The existing `call_tool` method keeps returning the parsed structured/text value.
+
+The unified MCP client accepts `pages=2` on
+`client.other.harvest_paa_start(...)`. It keeps one page as the default, adds
+page-two organic results when available, and expands PAA only on the preserved
+first page. Poll the same job with `harvest_paa_status`; pagination remains
+nullable for results saved under older contracts.
+
+## Authentication
+
+Set `MCP_SCRAPER_API_KEY` once. `MemoryClient`, `McpToolsClient`, and the scraper SDK all use that
+same customer credential against `https://mcpscraper.dev/mcp`.
+
+## Regenerating models
+
+`src/mcpscraper_memory/models/` and `_generated_client.py` are generated from `../../contracts/memory.tools.json`. After editing the manifest, regenerate with:
+
+```bash
+python scripts/generate_models.py
+```
+
+## See also
+
+[Repo README](../../README.md) (multi-language examples with real sample output) · [`mcpscraper-memory-sdk` on npm](../memory) (Node) · [`mcpscraper-sdk` on PyPI](https://pypi.org/project/mcpscraper-sdk/) (also reaches these Memory tools via a scraper key) · [`mcpscraper-cli`](../cli)
+
+Release changes: [SDK 0.55.0 release notes](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.55.0).
+
+## Client attribution and full results
+
+Clients accept `client_attribution={"install_channel": ..., "ai_client": ..., "ai_model": ...}` and default to calling surface `sdk`. Set only known caller labels; unspecified labels stay unknown. `on_response` receives a metadata dictionary with `request_id` and `status` per response, and errors keep their own `request_id`. These options also apply to `McpToolsClient` and `MemoryClient`; labels are reporting declarations, not authorization.
+
+Generated output unions return the matching model directly, preserving attributes such as `transcript_text`. Use `pydantic.TypeAdapter(Output)` when independently validating an output union. Large outputs may have `delivery`, `scope` and `recovery` instead of inline data. Preserve them, then use `tools.artifacts.describe`, `read_retained` (follow `next_offset` to None), or `download` with the artifact ID. The legacy `artifacts.read` method remains the report reader. `call_tool_result` preserves native content/resource links. Download URL expiry differs from retention; renew through `download` without rerunning acquisition. Use the returned capability for binary files.
+
+Artifact delivery may include optional `delivery.availableExports` handles. Use the
+export artifact ID with `artifact_download`, `artifact_read` or `artifact_describe`
+to generate Markdown from retained JSON without repeating acquisition. The
+[on-demand export example](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/v0.55.0/examples/serp-on-demand-export.mjs)
+shows the complete flow and preserves a retry key for uncertain search responses.

mcpscraper_memory_sdk-0.50.0/README.md

@@ -0,0 +1,75 @@
+# mcpscraper-memory-sdk (Python)
+
+Official Python clients for the unified [mcpscraper.dev](https://mcpscraper.dev) MCP catalog.
+The direct Memory manifest remains checked for runtime compatibility.
+
+[Release history](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/main/CHANGELOG.md)
+
+This is a thin JSON-RPC client generated against [`../../contracts/memory.tools.json`](../../contracts/memory.tools.json), the public contract for the hosted API. It contains no product source — only typed request/response plumbing.
+
+## Install
+
+```bash
+pip install mcpscraper-memory-sdk
+```
+
+## Usage
+
+```python
+import os
+from mcpscraper_memory import MemoryClient, MemoryApiError
+
+client = MemoryClient(api_key=os.environ["MCP_SCRAPER_API_KEY"])
+
+try:
+    result = client.memory.search(query="competitor pricing pages")
+    for hit in result.results or []:
+        print(hit["source"], hit["score"])
+except MemoryApiError as err:
+    print(f"memory call failed: {err}")
+```
+
+## Namespaces
+
+`client.access`, `client.capture`, `client.channels`, `client.crm`, `client.facts`, `client.files`, `client.graph`, `client.library`, `client.memory`, `client.recall`, `client.research`, `client.artifacts`, `client.storage`, `client.tables`, `client.tags`, `client.vaults`, `client.video`, `client.webhooks` — one method per tool, snake_case, typed with generated Pydantic models. Use Research for sourced knowledge and CRM for an actual relationship; counterpart operations link records without copying fields. External CRM providers remain unavailable, with no setup or write wrapper. Original Gmail attachment bytes saved to Memory are available through `client.files.file_asset_save(...)` and `client.files.file_asset_get(...)`.
+
+Use the same key with `McpToolsClient` for all unified scraper and Memory tools.
+
+Use `client.call_tool_result(name, args)` for native MCP image, audio, or resource blocks. The existing `call_tool` method keeps returning the parsed structured/text value.
+
+The unified MCP client accepts `pages=2` on
+`client.other.harvest_paa_start(...)`. It keeps one page as the default, adds
+page-two organic results when available, and expands PAA only on the preserved
+first page. Poll the same job with `harvest_paa_status`; pagination remains
+nullable for results saved under older contracts.
+
+## Authentication
+
+Set `MCP_SCRAPER_API_KEY` once. `MemoryClient`, `McpToolsClient`, and the scraper SDK all use that
+same customer credential against `https://mcpscraper.dev/mcp`.
+
+## Regenerating models
+
+`src/mcpscraper_memory/models/` and `_generated_client.py` are generated from `../../contracts/memory.tools.json`. After editing the manifest, regenerate with:
+
+```bash
+python scripts/generate_models.py
+```
+
+## See also
+
+[Repo README](../../README.md) (multi-language examples with real sample output) · [`mcpscraper-memory-sdk` on npm](../memory) (Node) · [`mcpscraper-sdk` on PyPI](https://pypi.org/project/mcpscraper-sdk/) (also reaches these Memory tools via a scraper key) · [`mcpscraper-cli`](../cli)
+
+Release changes: [SDK 0.55.0 release notes](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.55.0).
+
+## Client attribution and full results
+
+Clients accept `client_attribution={"install_channel": ..., "ai_client": ..., "ai_model": ...}` and default to calling surface `sdk`. Set only known caller labels; unspecified labels stay unknown. `on_response` receives a metadata dictionary with `request_id` and `status` per response, and errors keep their own `request_id`. These options also apply to `McpToolsClient` and `MemoryClient`; labels are reporting declarations, not authorization.
+
+Generated output unions return the matching model directly, preserving attributes such as `transcript_text`. Use `pydantic.TypeAdapter(Output)` when independently validating an output union. Large outputs may have `delivery`, `scope` and `recovery` instead of inline data. Preserve them, then use `tools.artifacts.describe`, `read_retained` (follow `next_offset` to None), or `download` with the artifact ID. The legacy `artifacts.read` method remains the report reader. `call_tool_result` preserves native content/resource links. Download URL expiry differs from retention; renew through `download` without rerunning acquisition. Use the returned capability for binary files.
+
+Artifact delivery may include optional `delivery.availableExports` handles. Use the
+export artifact ID with `artifact_download`, `artifact_read` or `artifact_describe`
+to generate Markdown from retained JSON without repeating acquisition. The
+[on-demand export example](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/v0.55.0/examples/serp-on-demand-export.mjs)
+shows the complete flow and preserves a retry key for uncertain search responses.

mcpscraper_memory_sdk-0.50.0/pyproject.toml

@@ -0,0 +1,30 @@
+[project]
+name = "mcpscraper-memory-sdk"
+version = "0.50.0"
+description = "Official Python clients for the unified 347-tool MCP Scraper catalog, including Memory, Research, and CRM"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = [
+    "requests>=2.31",
+    "pydantic>=2",
+]
+
+[project.urls]
+Repository = "https://github.com/VilovietaSEO/mcpscraper-sdk"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "responses>=0.25",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/mcpscraper_memory"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/mcpscraper_memory", "README.md", "pyproject.toml"]

mcpscraper_memory_sdk-0.50.0/src/mcpscraper_memory/_artifact_delivery.py

@@ -0,0 +1,86 @@
+"""Generated from artifact_describe in contracts/mcp.tools.json."""
+
+from typing import Annotated, Any, Literal, TypeVar, Union
+from typing_extensions import NotRequired, Required, TypedDict
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter
+
+ArtifactDeliveryDeliveryArtifactsItem = TypedDict('ArtifactDeliveryDeliveryArtifactsItem', {
+    'artifactId': Required[str],
+    'filename': Required[str],
+    'contentType': Required[str],
+    'bytes': Required[Union[float, int]],
+    'sha256': Required[str],
+    'expiresAt': Required[str],
+    'capabilities': Required[list[str]],
+    'downloadUrl': Required[Union[str, None]],
+    'downloadUrlExpiresAt': Required[Union[str, None]],
+    'downloadState': Required[Literal['available', 'local', 'unavailable']],
+})
+ArtifactDeliveryDeliveryArtifactsItem.__pydantic_config__ = ConfigDict(extra="allow", strict=True)
+
+
+ArtifactDeliveryDeliveryAvailableExportsItem = TypedDict('ArtifactDeliveryDeliveryAvailableExportsItem', {
+    'artifactId': Required[str],
+    'sourceArtifactId': Required[str],
+    'filename': Required[Literal['result.md']],
+    'contentType': Required[Literal['text/markdown; charset=utf-8']],
+    'state': Required[Literal['on-demand']],
+})
+ArtifactDeliveryDeliveryAvailableExportsItem.__pydantic_config__ = ConfigDict(extra="allow", strict=True)
+
+
+ArtifactDeliveryDeliveryStorageFailureVariant1 = TypedDict('ArtifactDeliveryDeliveryStorageFailureVariant1', {
+    'artifactId': Required[Union[str, None]],
+    'outcome': Required[Literal['unknown', 'bytes-stored-metadata-pending', 'failed']],
+})
+ArtifactDeliveryDeliveryStorageFailureVariant1.__pydantic_config__ = ConfigDict(extra="allow", strict=True)
+
+
+ArtifactDeliveryDelivery = TypedDict('ArtifactDeliveryDelivery', {
+    'mode': Required[Literal['artifact']],
+    'status': Required[Literal['complete', 'partial', 'unavailable']],
+    'retainedRepresentation': Required[Literal['formatted-tool-result']],
+    'sourceIsError': Required[bool],
+    'artifacts': Required[list[ArtifactDeliveryDeliveryArtifactsItem]],
+    'availableExports': NotRequired[list[ArtifactDeliveryDeliveryAvailableExportsItem]],
+    'downloadLinksOmitted': Required[bool],
+    'scopeOmittedFields': Required[Annotated[int, Field(ge=0, le=9007199254740991)]],
+    'storageFailure': Required[Union[ArtifactDeliveryDeliveryStorageFailureVariant1, None]],
+    'nextAction': Required[str],
+})
+ArtifactDeliveryDelivery.__pydantic_config__ = ConfigDict(extra="allow", strict=True)
+
+
+ArtifactDeliveryRecoveryOperation = TypedDict('ArtifactDeliveryRecoveryOperation', {
+    'runId': Required[Union[Annotated[str, Field(max_length=200)], None]],
+    'idempotencyKey': Required[Annotated[str, Field(max_length=512)]],
+    'state': Required[Annotated[str, Field(max_length=100)]],
+})
+ArtifactDeliveryRecoveryOperation.__pydantic_config__ = ConfigDict(extra="allow", strict=True)
+
+
+ArtifactDeliveryRecovery = TypedDict('ArtifactDeliveryRecovery', {
+    'idempotencyKey': NotRequired[Annotated[str, Field(max_length=512)]],
+    'operationId': NotRequired[Annotated[str, Field(max_length=200)]],
+    'runId': NotRequired[Annotated[str, Field(max_length=200)]],
+    'jobId': NotRequired[Annotated[str, Field(max_length=200)]],
+    'operation': NotRequired[ArtifactDeliveryRecoveryOperation],
+})
+ArtifactDeliveryRecovery.__pydantic_config__ = ConfigDict(extra="allow", strict=True)
+
+
+class ArtifactDelivery(BaseModel):
+    model_config = ConfigDict(populate_by_name=True, extra="allow", strict=True)
+
+    delivery: ArtifactDeliveryDelivery = Field(..., alias='delivery', description='')
+    preview: str = Field(..., alias='preview', description='')
+    scope: dict[str, Union[str, Union[float, int], bool, None]] = Field(..., alias='scope', description='')
+    recovery: ArtifactDeliveryRecovery = Field(..., alias='recovery', description='')
+
+_ArtifactDeliveryAdapter = TypeAdapter(ArtifactDelivery)
+_OutputModel = TypeVar("_OutputModel", bound=BaseModel)
+
+def validate_tool_output(value: Any, output_model: type[_OutputModel]) -> _OutputModel | ArtifactDelivery:
+    if isinstance(value, dict) and "delivery" in value:
+        return _ArtifactDeliveryAdapter.validate_python(value)
+    return output_model.model_validate(value)