marcopolo-sdk 0.1.1__py3-none-any.whl

marcopolo/__init__.py

@@ -0,0 +1,29 @@
+"""Public package surface for the MarcoPolo Python SDK."""
+
+from marcopolo._version import __version__
+from marcopolo.client import MarcoPolo
+from marcopolo.execution import (
+    ConnectionListResult,
+    ConnectionSummary,
+    ExecutionError,
+    ExecutionResult,
+)
+from marcopolo.mcp_transport import MarcoPoloMCPTransport
+from marcopolo.query_files import (
+    AuthoredQueryFile,
+    MarcoPoloQueryFileAuthor,
+    PreparedQueryFile,
+)
+
+__all__ = [
+    "MarcoPolo",
+    "ConnectionListResult",
+    "ConnectionSummary",
+    "ExecutionError",
+    "ExecutionResult",
+    "MarcoPoloMCPTransport",
+    "MarcoPoloQueryFileAuthor",
+    "PreparedQueryFile",
+    "AuthoredQueryFile",
+    "__version__",
+]

marcopolo/_version.py

@@ -0,0 +1,3 @@
+"""Package version metadata."""
+
+__version__ = "0.1.1"

marcopolo/client.py

@@ -0,0 +1,121 @@
+"""Top-level client entry point."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from marcopolo.execution import (
+    ConnectionListResult,
+    ExecutionResult,
+    build_connection_list_command,
+    build_connection_query_command,
+    parse_workspace_shell_connection_list_result,
+    parse_workspace_shell_query_result,
+)
+from marcopolo.mcp_transport import MarcoPoloMCPTransport
+from marcopolo.query_files import MarcoPoloQueryFileAuthor, PayloadFormat
+
+
+class MarcoPolo:
+    """MarcoPolo client entry point.
+
+    Callers must pass explicit connection settings. Environment management stays
+    outside the library.
+    """
+
+    def __init__(
+        self,
+        api_token: str,
+        server_url: str,
+    ) -> None:
+        """Create a client from explicit settings."""
+
+        self.api_token = api_token
+        self.server_url = server_url
+
+    def transport(self) -> MarcoPoloMCPTransport:
+        """Create a low-level MCP transport configured for this client."""
+
+        return MarcoPoloMCPTransport(
+            api_token=self.api_token,
+            server_url=self.server_url,
+        )
+
+    def query_file_author(self) -> MarcoPoloQueryFileAuthor:
+        """Create the internal remote query-file authoring helper."""
+
+        return MarcoPoloQueryFileAuthor(self.transport())
+
+    async def execute(
+        self,
+        connection_name: str,
+        payload: dict[str, Any] | list[Any] | str,
+        *,
+        query_name: str,
+        context: str,
+        payload_format: PayloadFormat | None = None,
+        params: dict[str, Any] | None = None,
+        timeout: int | None = None,
+    ) -> ExecutionResult:
+        """Author a query file remotely and execute it with `connection query`."""
+
+        transport = self.transport()
+        authored = await MarcoPoloQueryFileAuthor(transport).author(
+            connection_name,
+            payload,
+            context=context,
+            query_name=query_name,
+            payload_format=payload_format,
+            timeout=timeout,
+        )
+        return await self.execute_query_file(
+            connection_name,
+            authored.query_file,
+            context=context,
+            params=params,
+            timeout=timeout,
+        )
+
+    async def execute_query_file(
+        self,
+        connection_name: str,
+        query_file: str,
+        *,
+        context: str,
+        params: dict[str, Any] | None = None,
+        timeout: int | None = None,
+    ) -> ExecutionResult:
+        """Execute an existing remote query file through `connection query`."""
+
+        transport = self.transport()
+        command = build_connection_query_command(
+            connection_name,
+            query_file,
+            params=params,
+        )
+        tool_result = await transport.workspace_shell(
+            command=command,
+            context=context,
+            timeout=timeout,
+        )
+        return parse_workspace_shell_query_result(
+            tool_result,
+            connection_name=connection_name,
+            query_file=query_file,
+        )
+
+    async def list_connections(
+        self,
+        *,
+        context: str,
+        timeout: int | None = None,
+    ) -> ConnectionListResult:
+        """List available MarcoPolo connections through `connection list`."""
+
+        transport = self.transport()
+        tool_result = await transport.workspace_shell(
+            command=build_connection_list_command(),
+            context=context,
+            timeout=timeout,
+        )
+        return parse_workspace_shell_connection_list_result(tool_result)

marcopolo/execution.py

@@ -0,0 +1,267 @@
+"""Execution helpers for running remote MarcoPolo connection commands."""
+
+from __future__ import annotations
+
+import json
+import shlex
+from dataclasses import dataclass
+from typing import Any
+
+
+@dataclass(frozen=True, slots=True)
+class ExecutionResult:
+    """Normalized result from a MarcoPolo `connection query` execution."""
+
+    connection_name: str
+    query_file: str
+    rows: list[dict[str, Any]]
+    row_count: int
+    run_id: str | None
+    raw_payload: dict[str, Any]
+    raw_command_result: dict[str, Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionSummary:
+    """Normalized metadata for one MarcoPolo connection."""
+
+    name: str
+    connection_type: str
+    capabilities: list[str]
+    display_name: str | None
+    workspace_path: str | None
+
+
+@dataclass(frozen=True, slots=True)
+class ConnectionListResult:
+    """Normalized result from a MarcoPolo `connection list` execution."""
+
+    connections: list[ConnectionSummary]
+    count: int
+    message: str | None
+    next_actions: list[str]
+    raw_payload: dict[str, Any]
+    raw_command_result: dict[str, Any]
+
+
+class ExecutionError(RuntimeError):
+    """Raised when remote command execution or result parsing fails."""
+
+
+def build_connection_query_command(
+    connection_name: str,
+    query_file: str,
+    *,
+    params: dict[str, Any] | None = None,
+) -> str:
+    """Build a `connection query` CLI invocation."""
+
+    command_parts = [
+        "connection",
+        "query",
+        shlex.quote(connection_name),
+        "--file",
+        shlex.quote(query_file),
+        "--json",
+        "--sample-rows",
+        "-1",
+    ]
+    if params is not None:
+        command_parts.extend(["--params-json", shlex.quote(json.dumps(params))])
+    return " ".join(command_parts)
+
+
+def build_connection_list_command() -> str:
+    """Build a `connection list` CLI invocation."""
+
+    return "connection list --json"
+
+
+def parse_workspace_shell_query_result(
+    tool_result: Any,
+    *,
+    connection_name: str,
+    query_file: str,
+) -> ExecutionResult:
+    """Normalize a `workspace_shell` result for `connection query --json`."""
+
+    command_result = _structured_mapping(tool_result)
+    payload = _parse_command_payload(
+        command_result,
+        empty_output_message=f"Query on connection '{connection_name}' produced no output.",
+        failure_message=f"Failed to execute query for connection '{connection_name}'.",
+    )
+    if payload.get("success") is False:
+        raise ExecutionError(
+            (
+                payload.get("message")
+                or payload.get("error")
+                or f"Failed to execute query for connection '{connection_name}'."
+            )
+        )
+
+    rows = _extract_rows(payload.get("data") or payload.get("preview"))
+    row_count = (
+        payload.get("row_count")
+        if isinstance(payload.get("row_count"), int)
+        else len(rows)
+    )
+    resolved_query_file = (
+        payload.get("query_file")
+        if isinstance(payload.get("query_file"), str)
+        else query_file
+    )
+
+    return ExecutionResult(
+        connection_name=connection_name,
+        query_file=resolved_query_file,
+        rows=rows,
+        row_count=row_count,
+        run_id=payload.get("run_id") if isinstance(payload.get("run_id"), str) else None,
+        raw_payload=payload,
+        raw_command_result=command_result,
+    )
+
+
+def parse_workspace_shell_connection_list_result(tool_result: Any) -> ConnectionListResult:
+    """Normalize a `workspace_shell` result for `connection list --json`."""
+
+    command_result = _structured_mapping(tool_result)
+    payload = _parse_command_payload(
+        command_result,
+        empty_output_message="Connection list command produced no output.",
+        failure_message="Failed to list connections.",
+    )
+    if payload.get("success") is False:
+        raise ExecutionError(
+            (
+                payload.get("message")
+                or payload.get("error")
+                or "Failed to list connections."
+            )
+        )
+
+    connections: list[ConnectionSummary] = []
+    for item in payload.get("connections") or []:
+        if not isinstance(item, dict):
+            continue
+        name = item.get("name")
+        connection_type = item.get("type")
+        if not isinstance(name, str) or not isinstance(connection_type, str):
+            continue
+        capabilities = [
+            capability
+            for capability in item.get("capabilities") or []
+            if isinstance(capability, str)
+        ]
+        display_name = (
+            item.get("display_name")
+            if isinstance(item.get("display_name"), str)
+            else None
+        )
+        workspace_path = (
+            item.get("workspace_path")
+            if isinstance(item.get("workspace_path"), str)
+            else None
+        )
+        connections.append(
+            ConnectionSummary(
+                name=name,
+                connection_type=connection_type,
+                capabilities=capabilities,
+                display_name=display_name,
+                workspace_path=workspace_path,
+            )
+        )
+
+    count = payload.get("count") if isinstance(payload.get("count"), int) else len(connections)
+    message = payload.get("message") if isinstance(payload.get("message"), str) else None
+    next_actions = [
+        action for action in payload.get("next_actions") or [] if isinstance(action, str)
+    ]
+
+    return ConnectionListResult(
+        connections=connections,
+        count=count,
+        message=message,
+        next_actions=next_actions,
+        raw_payload=payload,
+        raw_command_result=command_result,
+    )
+
+
+def _extract_rows(value: Any) -> list[dict[str, Any]]:
+    if isinstance(value, list):
+        return [row for row in value if isinstance(row, dict)]
+    if isinstance(value, str) and value:
+        parsed = json.loads(value)
+        if isinstance(parsed, list):
+            return [row for row in parsed if isinstance(row, dict)]
+    return []
+
+
+def _structured_mapping(tool_result: Any) -> dict[str, Any]:
+    if isinstance(tool_result, dict):
+        structured = tool_result.get("structuredContent")
+        if isinstance(structured, dict):
+            return structured
+        return tool_result
+
+    structured = getattr(tool_result, "structuredContent", None)
+    if isinstance(structured, dict):
+        return structured
+
+    if hasattr(tool_result, "model_dump"):
+        dumped = tool_result.model_dump(mode="python")
+        if isinstance(dumped, dict):
+            structured = dumped.get("structuredContent")
+            if isinstance(structured, dict):
+                return structured
+            return dumped
+
+    raise ExecutionError("Tool returned an unsupported result shape.")
+
+
+def _parse_command_payload(
+    command_result: dict[str, Any],
+    *,
+    empty_output_message: str,
+    failure_message: str,
+) -> dict[str, Any]:
+    stdout = (command_result.get("stdout") or "").strip()
+
+    if not command_result.get("success"):
+        raise ExecutionError(
+            _command_error_message(command_result, stdout) or failure_message
+        )
+    if not stdout:
+        raise ExecutionError(empty_output_message)
+
+    try:
+        payload = json.loads(stdout)
+    except json.JSONDecodeError as exc:
+        raise ExecutionError("Command returned non-JSON stdout.") from exc
+
+    if not isinstance(payload, dict):
+        raise ExecutionError("Command returned a non-object JSON payload.")
+
+    return payload
+
+
+def _command_error_message(command_result: dict[str, Any], stdout: str) -> str | None:
+    if stdout:
+        try:
+            payload = json.loads(stdout)
+        except json.JSONDecodeError:
+            if len(stdout) < 500:
+                return stdout
+        else:
+            if isinstance(payload, dict):
+                message = payload.get("message") or payload.get("error")
+                if isinstance(message, str) and message:
+                    return message
+    for key in ("message", "error", "stderr"):
+        value = command_result.get(key)
+        if isinstance(value, str) and value.strip():
+            return value.strip()
+    return None

marcopolo/mcp_transport.py

@@ -0,0 +1,109 @@
+"""Low-level MCP transport for MarcoPolo."""
+
+from __future__ import annotations
+
+from collections.abc import AsyncIterator, Callable, Mapping
+from contextlib import asynccontextmanager
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+from mcp import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+from mcp.shared._httpx_utils import create_mcp_http_client
+from mcp.types import CallToolResult, ListToolsResult
+
+
+class BearerTokenAuth(httpx.Auth):
+    """Attach a bearer token to outgoing HTTP requests."""
+
+    def __init__(self, token: str) -> None:
+        self._token = token
+
+    def auth_flow(
+        self, request: httpx.Request
+    ) -> Any:
+        request.headers["Authorization"] = f"Bearer {self._token}"
+        yield request
+
+
+@dataclass(slots=True)
+class MarcoPoloMCPTransport:
+    """Thin wrapper around the official Python MCP SDK."""
+
+    api_token: str
+    server_url: str
+    timeout_seconds: float = 30.0
+    sse_read_timeout_seconds: float = 300.0
+    extra_headers: Mapping[str, str] = field(default_factory=dict)
+    session_factory: Callable[..., ClientSession] = ClientSession
+    http_client_factory: Callable[..., httpx.AsyncClient] = create_mcp_http_client
+    streamable_http_factory: Callable[..., Any] = streamable_http_client
+
+    @asynccontextmanager
+    async def session(self) -> AsyncIterator[ClientSession]:
+        """Open an initialized MCP client session."""
+
+        headers = dict(self.extra_headers) or None
+        auth = BearerTokenAuth(self.api_token)
+        timeout = httpx.Timeout(
+            self.timeout_seconds,
+            read=self.sse_read_timeout_seconds,
+        )
+        async with self.http_client_factory(
+            headers=headers,
+            timeout=timeout,
+            auth=auth,
+        ) as http_client:
+            async with self.streamable_http_factory(
+                self.server_url,
+                http_client=http_client,
+            ) as (read_stream, write_stream, _get_session_id):
+                async with self.session_factory(read_stream, write_stream) as session:
+                    await session.initialize()
+                    yield session
+
+    async def list_tools(self) -> ListToolsResult:
+        """List tools exposed by the configured MarcoPolo MCP server."""
+
+        async with self.session() as session:
+            return await session.list_tools()
+
+    async def call_tool(
+        self, name: str, arguments: dict[str, Any] | None = None
+    ) -> CallToolResult:
+        """Call a named MCP tool with optional arguments."""
+
+        async with self.session() as session:
+            return await session.call_tool(name, arguments)
+
+    async def workspace_shell(
+        self, command: str, context: str, timeout: int | None = None
+    ) -> CallToolResult:
+        """Call MarcoPolo's `workspace_shell` tool."""
+
+        arguments: dict[str, Any] = {"command": command, "context": context}
+        if timeout is not None:
+            arguments["timeout"] = timeout
+        return await self.call_tool("workspace_shell", arguments)
+
+    async def data_query(
+        self,
+        connection_name: str,
+        query_file: str,
+        context: str,
+        max_rows: int | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> CallToolResult:
+        """Call MarcoPolo's `data_query` tool."""
+
+        arguments: dict[str, Any] = {
+            "connection_name": connection_name,
+            "query_file": query_file,
+            "context": context,
+        }
+        if max_rows is not None:
+            arguments["max_rows"] = max_rows
+        if params is not None:
+            arguments["params"] = params
+        return await self.call_tool("data_query", arguments)

marcopolo/py.typed

@@ -0,0 +1 @@
+

marcopolo/query_files.py

@@ -0,0 +1,170 @@
+"""Internal remote query-file authoring utilities."""
+
+from __future__ import annotations
+
+import base64
+import json
+import re
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+from typing import Any, Literal, Protocol
+
+PayloadFormat = Literal["json", "sql", "text"]
+_VALID_PAYLOAD_FORMATS = {"json", "sql", "text"}
+
+
+class SupportsWorkspaceShell(Protocol):
+    """Minimal protocol required for remote query-file authoring."""
+
+    async def workspace_shell(
+        self, command: str, context: str, timeout: int | None = None
+    ) -> Any:
+        """Run a command in the MarcoPolo workspace."""
+
+
+@dataclass(frozen=True, slots=True)
+class PreparedQueryFile:
+    """Locally prepared query-file metadata before remote write."""
+
+    connection_name: str
+    query_file: str
+    payload_format: PayloadFormat
+    content: str
+
+
+@dataclass(frozen=True, slots=True)
+class AuthoredQueryFile:
+    """Remote query-file metadata after workspace persistence."""
+
+    connection_name: str
+    query_file: str
+    payload_format: PayloadFormat
+
+
+class QueryFileAuthoringError(ValueError):
+    """Raised when payload serialization choices are ambiguous or invalid."""
+
+
+class MarcoPoloQueryFileAuthor:
+    """Prepare and persist query files in the remote MarcoPolo workspace."""
+
+    def __init__(self, transport: SupportsWorkspaceShell) -> None:
+        self._transport = transport
+
+    def prepare(
+        self,
+        connection_name: str,
+        payload: dict[str, Any] | list[Any] | str,
+        *,
+        query_name: str,
+        payload_format: PayloadFormat | None = None,
+    ) -> PreparedQueryFile:
+        """Prepare content and a workspace-relative query-file path."""
+
+        slug = _slugify(query_name)
+        if isinstance(payload, (dict, list)):
+            if payload_format not in (None, "json"):
+                raise QueryFileAuthoringError(
+                    "Structured payloads support only the 'json' payload_format."
+                )
+            content = json.dumps(payload, indent=2) + "\n"
+            resolved_format: PayloadFormat = "json"
+        elif isinstance(payload, str):
+            if payload_format is None:
+                raise QueryFileAuthoringError(
+                    "Raw string payloads require an explicit payload_format of "
+                    "'json', 'sql', or 'text'."
+                )
+            if payload_format not in _VALID_PAYLOAD_FORMATS:
+                raise QueryFileAuthoringError(
+                    "Unsupported payload_format. Use 'json', 'sql', or 'text'."
+                )
+            content = payload
+            resolved_format = payload_format
+        else:
+            raise QueryFileAuthoringError(
+                "Unsupported payload type. Use dict, list, or str."
+            )
+
+        query_file = (
+            PurePosixPath("connections")
+            / connection_name
+            / "queries"
+            / f"{slug}.{_extension_for(resolved_format)}"
+        ).as_posix()
+        return PreparedQueryFile(
+            connection_name=connection_name,
+            query_file=query_file,
+            payload_format=resolved_format,
+            content=content,
+        )
+
+    async def author(
+        self,
+        connection_name: str,
+        payload: dict[str, Any] | list[Any] | str,
+        *,
+        context: str,
+        query_name: str,
+        payload_format: PayloadFormat | None = None,
+        timeout: int | None = None,
+    ) -> AuthoredQueryFile:
+        """Write the prepared query file into the remote MarcoPolo workspace."""
+
+        prepared = self.prepare(
+            connection_name,
+            payload,
+            query_name=query_name,
+            payload_format=payload_format,
+        )
+        await self._transport.workspace_shell(
+            command=_build_remote_write_command(prepared),
+            context=context,
+            timeout=timeout,
+        )
+        return AuthoredQueryFile(
+            connection_name=prepared.connection_name,
+            query_file=prepared.query_file,
+            payload_format=prepared.payload_format,
+        )
+
+
+def _slugify(value: str) -> str:
+    """Create a readable underscore-based slug."""
+
+    slug = re.sub(r"[^a-z0-9]+", "_", value.strip().lower())
+    slug = re.sub(r"_+", "_", slug).strip("_")
+    if not slug:
+        raise QueryFileAuthoringError(
+            "query_name must contain at least one alphanumeric character."
+        )
+    return slug
+
+
+def _extension_for(payload_format: PayloadFormat) -> str:
+    """Map payload formats to file extensions."""
+
+    return {
+        "json": "json",
+        "sql": "sql",
+        "text": "txt",
+    }[payload_format]
+
+
+def _build_remote_write_command(prepared: PreparedQueryFile) -> str:
+    """Build a shell-safe command that writes content in `/workspace`."""
+
+    encoded = base64.b64encode(prepared.content.encode("utf-8")).decode("ascii")
+    return "\n".join(
+        [
+            "python3 - <<'PY'",
+            "from pathlib import Path",
+            "import base64",
+            f"path = Path('/workspace/{prepared.query_file}')",
+            f"content = base64.b64decode('{encoded}')",
+            "path.parent.mkdir(parents=True, exist_ok=True)",
+            "path.write_bytes(content)",
+            "print(path.as_posix())",
+            "PY",
+        ]
+    )

marcopolo_sdk-0.1.1.dist-info/METADATA

@@ -0,0 +1,503 @@
+Metadata-Version: 2.4
+Name: marcopolo-sdk
+Version: 0.1.1
+Summary: Python SDK for executing MarcoPolo MCP data operations.
+Project-URL: Homepage, https://github.com/immersa-co/marcopolo-python-sdk
+Project-URL: Repository, https://github.com/immersa-co/marcopolo-python-sdk
+Project-URL: Issues, https://github.com/immersa-co/marcopolo-python-sdk/issues
+Author: Immersa
+License: Proprietary
+Keywords: client,data,marcopolo,mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: mcp<2,>=1.28.1
+Provides-Extra: dev
+Requires-Dist: build>=1.2.2; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Requires-Dist: ruff>=0.5.0; extra == 'dev'
+Requires-Dist: twine>=5.1.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MarcoPolo Client
+
+Python client library for executing governed MarcoPolo MCP connection
+operations from application code.
+
+The initial public surface is intentionally small:
+
+- one async metadata API: `list_connections()`
+- one async top-level API: `execute()`
+- one async lower-level helper: `execute_query_file()`
+- internal handling for remote query-file authoring under
+  `connections/<connection_name>/queries/`
+
+The low-level MCP transport uses the official Python `mcp` SDK.
+
+## Status
+
+This repository implements the approved first cut of the client:
+
+- async connection discovery
+- async-only execution
+- required `context`
+- caller-provided `query_name`
+- syntax-agnostic payload handling
+- canonical execution through `workspace_shell("connection query ... --json")`
+
+## Install
+
+Install from PyPI:
+
+```bash
+python3 -m pip install marcopolo-sdk
+```
+
+Install for local development:
+
+```bash
+python3 -m pip install -e ".[dev]"
+```
+
+## Build Release Artifacts
+
+Build and validate the PyPI release artifacts locally:
+
+```bash
+python3 -m pip install -e ".[dev]"
+python3 -m build
+python3 -m twine check dist/*
+```
+
+The built source distribution and wheel are written under `dist/`.
+
+## Publish to PyPI
+
+This repository is set up for GitHub Actions based PyPI trusted publishing.
+
+High-level flow:
+
+1. Configure the one-time trusted publisher on PyPI for this repository.
+2. Push a version tag such as `v0.1.1`.
+3. Create a GitHub release from that tag.
+4. The `publish-pypi.yml` workflow builds the package and uploads it to PyPI.
+
+See [`PYPI_PUBLISHING.md`](PYPI_PUBLISHING.md) for the concrete setup steps.
+
+## Configuration
+
+`MarcoPolo` does not read `.env` files or process environment variables.
+Your application owns configuration loading and must pass explicit settings into
+the constructor.
+
+## Public API
+
+```python
+import os
+
+from marcopolo import MarcoPolo
+
+marcopolo = MarcoPolo(
+    api_token=os.environ["MARCOPOLO_API_TOKEN"],
+    server_url=os.environ["MARCOPOLO_MCP_SERVER_URL"],
+)
+```
+
+### `list_connections()`
+
+```python
+async def list_connections(
+    *,
+    context: str,
+    timeout: int | None = None,
+) -> ConnectionListResult
+```
+
+Behavior:
+
+- executes `workspace_shell("connection list --json")`
+- parses the returned shell payload and nested JSON `stdout`
+- returns normalized connection metadata including capabilities
+
+### `execute()`
+
+```python
+async def execute(
+    connection_name: str,
+    payload: dict | list | str,
+    *,
+    query_name: str,
+    context: str,
+    payload_format: Literal["json", "sql", "text"] | None = None,
+    params: dict | None = None,
+    timeout: int | None = None,
+) -> ExecutionResult
+```
+
+Behavior:
+
+- writes a durable remote query file under
+  `connections/<connection_name>/queries/`
+- executes it with `connection query <connection_name> --file <query_file> --json`
+- always requests the full result set by passing `--sample-rows -1` internally
+- normalizes the result into `ExecutionResult`
+
+### `execute_query_file()`
+
+```python
+async def execute_query_file(
+    connection_name: str,
+    query_file: str,
+    *,
+    context: str,
+    params: dict | None = None,
+    timeout: int | None = None,
+) -> ExecutionResult
+```
+
+Use this when the query file already exists in the MarcoPolo workspace and you
+only want execution.
+
+## Payload Rules
+
+The client is syntax-agnostic. It does not read connector `SYNTAX.md` files or
+infer connector semantics. The caller is responsible for sending a payload that
+is valid for the target connection.
+
+Serialization rules:
+
+- `dict` and `list` payloads are serialized as pretty JSON and written as
+  `.json`
+- raw `str` payloads require explicit `payload_format`
+- supported raw string formats are `json`, `sql`, and `text`
+- `query_name` is mandatory and is sanitized into a readable underscore-based
+  filename
+
+Examples:
+
+- `query_name="Top 5 Accounts By Revenue"` becomes
+  `top_5_accounts_by_revenue.json`
+- `query_name="Loki Errors Last 24h"` becomes
+  `loki_errors_last_24h.json`
+
+## Usage
+
+The client is async-only by design. A simple application entrypoint can use
+`asyncio.run(...)`.
+
+### Jira read
+
+```python
+import asyncio
+import os
+
+from marcopolo import MarcoPolo
+
+
+async def main() -> None:
+    marcopolo = MarcoPolo(
+        api_token=os.environ["MARCOPOLO_API_TOKEN"],
+        server_url=os.environ["MARCOPOLO_MCP_SERVER_URL"],
+    )
+    connections = await marcopolo.list_connections(
+        context="List available governed connections before choosing one.",
+    )
+    print(connections.count)
+    print(connections.connections[:2])
+
+    result = await marcopolo.execute(
+        "jira-jql-20260710-1527",
+        {
+            "jql": (
+                "assignee = currentUser() "
+                "AND statusCategory != Done ORDER BY updated DESC"
+            ),
+            "fields": [
+                "issuekey",
+                "summary",
+                "status",
+                "priority",
+                "project",
+                "assignee",
+                "created",
+                "updated",
+            ],
+        },
+        query_name="open_tickets_current_user",
+        context="Load current open Jira tickets for the current Jira user.",
+    )
+    print(result.row_count)
+    print(result.rows[:2])
+
+
+asyncio.run(main())
+```
+
+### Google Drive read
+
+Validated live against `google-drive-20260710-1517` and covered by
+`tests/test_integration_reads.py::test_execute_google_drive_sheet_read`.
+For the current connection scope, the working form is the plain display name
+`sales-by-quarter`; a folder-qualified path such as
+`some-folder/sales-by-quarter` does not resolve.
+
+```python
+result = await marcopolo.execute(
+    "google-drive-20260710-1517",
+    {
+        "file": "sales-by-quarter",
+        "sheet": "0",
+    },
+    query_name="sales_by_quarter_sheet0",
+    context="Read the sales-by-quarter spreadsheet from Google Drive.",
+)
+```
+
+### Loki read
+
+```python
+result = await marcopolo.execute(
+    "grafana-loki-20260519-2152",
+    {
+        "operation": "query_range",
+        "query": '{job=~".+"} |~ "(?i)error"',
+        "start": "now-24h",
+        "end": "now",
+        "limit": 200,
+        "direction": "backward",
+    },
+    query_name="errors_last_24h",
+    context="Read recent error logs from Loki.",
+)
+```
+
+### Salesforce update
+
+```python
+result = await marcopolo.execute(
+    "salesforce-demo-3841cee8-20260709-2149",
+    {
+        "endpoint": "/services/data/v47.0/sobjects/Account/001gK00000DFg5tQAD",
+        "method": "PATCH",
+        "body": {
+            "Description": "Customer since 2024-01-24. Tier: enterprise",
+        },
+    },
+    query_name="update_existing_account_description",
+    context="Apply a non-destructive Salesforce account update.",
+)
+```
+
+### Salesforce insert
+
+```python
+result = await marcopolo.execute(
+    "salesforce-demo-3841cee8-20260709-2149",
+    {
+        "endpoint": "/services/data/v47.0/sobjects/Opportunity",
+        "method": "POST",
+        "body": {
+            "Name": "MarcoPolo Client Example Opportunity",
+            "StageName": "Prospecting",
+            "CloseDate": "2026-07-31",
+            "Description": "Created from the MarcoPolo client README example",
+        },
+    },
+    query_name="create_example_opportunity",
+    context="Create a Salesforce opportunity through the MarcoPolo client.",
+)
+```
+
+### Execute an existing remote query file
+
+```python
+result = await marcopolo.execute_query_file(
+    "google-drive-20260710-1517",
+    "connections/google-drive-20260710-1517/queries/sales_by_quarter_sheet0.json",
+    context="Execute a pre-authored Google Drive query file.",
+)
+```
+
+## Result Model
+
+`execute()` and `execute_query_file()` return `ExecutionResult`:
+
+```python
+ExecutionResult(
+    connection_name: str,
+    query_file: str,
+    rows: list[dict[str, Any]],
+    row_count: int,
+    run_id: str | None,
+    raw_payload: dict[str, Any],
+    raw_command_result: dict[str, Any],
+)
+```
+
+Notes:
+
+- `rows` is extracted from `data` or `preview`
+- `row_count` uses the command payload value when present, otherwise `len(rows)`
+- write operations may still return useful rows, such as Salesforce create
+  responses with inserted record IDs
+- `raw_payload` and `raw_command_result` are preserved for debugging
+
+`list_connections()` returns `ConnectionListResult`:
+
+```python
+ConnectionListResult(
+    connections: list[ConnectionSummary],
+    count: int,
+    message: str | None,
+    next_actions: list[str],
+    raw_payload: dict[str, Any],
+    raw_command_result: dict[str, Any],
+)
+```
+
+Where each `ConnectionSummary` includes:
+
+```python
+ConnectionSummary(
+    name: str,
+    connection_type: str,
+    capabilities: list[str],
+    display_name: str | None,
+    workspace_path: str | None,
+)
+```
+
+## Observed Result Shapes
+
+The exact row schema is connector-specific. The client does not reshape rows
+beyond extracting them from the command response. These are representative
+live-observed examples from the validated connectors.
+
+### Jira rows
+
+```python
+[
+    {
+        "key": "IMMERSA-455",
+        "summary": "Example issue title",
+        "created": "2026-05-11T18:28:05.844+0000",
+        "project_key": "IMMERSA",
+        "project_name": "Immersa",
+        "assignee": "{\"displayName\": \"Example User\", ...}",
+        "priority_name": "Medium",
+        "updated": "2026-05-11T18:28:07.126+0000",
+        "status_name": "To Do",
+    },
+    ...,
+]
+```
+
+### Google Drive rows
+
+```python
+[
+    {
+        "customer_id": 1,
+        "quarter_end_dt": "03/31/2025",
+        "billing_amount_usd": 100,
+    },
+    ...,
+]
+```
+
+### Loki rows
+
+```python
+[
+    {
+        "timestamp": "2026-07-10T17:42:31.123456Z",
+        "line": "ERROR request failed for job=api",
+        "labels": "{\"job\": \"duploservices-prod01/mproxy\", ...}",
+    },
+    ...,
+]
+```
+
+### Salesforce insert rows
+
+```python
+[
+    {
+        "id": "006gK00000KlbtRQAR",
+        "success": True,
+        "errors": "[]",
+    },
+    ...,
+]
+```
+
+### Salesforce update and delete rows
+
+For successful update and delete operations, the command payload may report
+`row_count = 1` while `rows` is empty because the connector returned no tabular
+data:
+
+```python
+result.row_count == 1
+result.rows == []
+```
+
+### Raw command payload
+
+`ExecutionResult.raw_payload` is the parsed JSON body returned by
+`connection query --json`. Representative shape:
+
+```python
+{
+    "success": True,
+    "data": "[{\"id\":\"006gK00000KlbtRQAR\",\"success\":true,\"errors\":\"[]\"}]",
+    "preview": "[{\"id\":\"006gK00000KlbtRQAR\",\"success\":true,\"errors\":\"[]\"}]",
+    "row_count": 1,
+    "run_id": "run_123",
+    "query_file": (
+        "connections/salesforce-demo-3841cee8-20260709-2149/"
+        "queries/create_example_opportunity.json"
+    ),
+}
+```
+
+## Development
+
+Run lint:
+
+```bash
+ruff check .
+```
+
+Run tests:
+
+```bash
+pytest -q
+```
+
+The test suite is live-only. Before running it, load these variables into your
+shell by whatever mechanism your environment uses:
+
+```bash
+export MARCOPOLO_API_TOKEN=...
+export MARCOPOLO_MCP_SERVER_URL=...
+pytest -q -s
+```
+
+## Current Limitations
+
+- The client does not inspect connection `SYNTAX.md` files. Payload formation
+  is fully caller-owned.
+- The first version exposes execution only. Higher-level `query()` helpers and
+  connector-specific convenience wrappers are deferred.
+- Jira create/update is not documented by the currently validated Jira
+  connection surface, so the examples stay read-only.
+- The Google Drive spec example using `test1` / `test` is environment-dependent
+  and not currently available in the active validated connection scope.
+- For the validated Google Drive spreadsheet example, use the authorized file
+  display name `sales-by-quarter` or a file ID/URL. Folder-qualified display
+  paths such as `some-folder/sales-by-quarter` are not currently resolved by
+  the active connection.

marcopolo_sdk-0.1.1.dist-info/RECORD

@@ -0,0 +1,10 @@
+marcopolo/__init__.py,sha256=5efk9skLW0lnu7Pjj2iEGa4A63a0QhRsKRZFdwVtaNY,700
+marcopolo/_version.py,sha256=AZzdIzOEG4PaKjlDweBMtpvnedcGjSy4Un3qHoLRnDQ,55
+marcopolo/client.py,sha256=wQf_L6cv0Jf6VSiUF9-7qDeEv1rnHI3OB65Rkwx13NA,3572
+marcopolo/execution.py,sha256=H63KaxWy-tBBa44vzGJYrF_AAqbNhyY7usXMX7tPkEc,8151
+marcopolo/mcp_transport.py,sha256=MtdVf-o_WJbqY6TtXrvIVwCYbaqAjDFF0zEhm45G7Cg,3749
+marcopolo/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+marcopolo/query_files.py,sha256=BKb4bz4rmfngHwFjzAwwXKCTkeqnFDEhcH4Rsy4QDH8,5310
+marcopolo_sdk-0.1.1.dist-info/METADATA,sha256=7tpYjhKIeu5QCdjQ9Hf425JTTCUBnTCiCu7m3eyOyt4,12787
+marcopolo_sdk-0.1.1.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+marcopolo_sdk-0.1.1.dist-info/RECORD,,

marcopolo_sdk-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any