wayfinder-paths 0.1.22__py3-none-any.whl → 0.1.24__py3-none-any.whl

wayfinder_paths/mcp/preview.py

@@ -0,0 +1,185 @@
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+
+from wayfinder_paths.core.constants.hyperliquid import (
+    ARBITRUM_USDC_TOKEN_ID,
+    HYPE_FEE_WALLET,
+    HYPERLIQUID_BRIDGE_ADDRESS,
+)
+from wayfinder_paths.mcp.utils import (
+    find_wallet_by_label,
+    normalize_address,
+    read_text_excerpt,
+    repo_root,
+)
+
+
+def build_execution_preview(tool_input: dict[str, Any]) -> dict[str, Any]:
+    req = tool_input.get("request") if isinstance(tool_input, dict) else None
+    if not isinstance(req, dict):
+        return {
+            "summary": "Execute request missing 'request' object.",
+            "recipient_mismatch": False,
+        }
+
+    kind = str(req.get("kind") or "").strip()
+    wallet_label = str(req.get("wallet_label") or "").strip()
+    w = find_wallet_by_label(wallet_label) if wallet_label else None
+    sender = normalize_address((w or {}).get("address")) if w else None
+
+    recipient = normalize_address(req.get("recipient"))
+    if kind == "swap":
+        recipient = recipient or sender
+        summary = (
+            "EXECUTE swap\n"
+            f"wallet_label: {wallet_label}\n"
+            f"from_token: {req.get('from_token')}\n"
+            f"to_token: {req.get('to_token')}\n"
+            f"amount: {req.get('amount')}\n"
+            f"slippage_bps: {req.get('slippage_bps')}\n"
+            f"sender: {sender or '(unknown)'}\n"
+            f"recipient: {recipient or '(unknown)'}"
+        )
+    elif kind == "hyperliquid_deposit":
+        recipient = normalize_address(HYPERLIQUID_BRIDGE_ADDRESS)
+        summary = (
+            "EXECUTE hyperliquid_deposit (Bridge2)\n"
+            f"wallet_label: {wallet_label}\n"
+            f"token: {ARBITRUM_USDC_TOKEN_ID}\n"
+            f"amount: {req.get('amount')}\n"
+            "chain_id: 42161\n"
+            f"sender: {sender or '(unknown)'}\n"
+            f"recipient: {recipient or '(missing)'}"
+        )
+    elif kind == "send":
+        summary = (
+            "EXECUTE send\n"
+            f"wallet_label: {wallet_label}\n"
+            f"token: {req.get('token')}\n"
+            f"amount: {req.get('amount')}\n"
+            f"chain_id: {req.get('chain_id')}\n"
+            f"sender: {sender or '(unknown)'}\n"
+            f"recipient: {recipient or '(missing)'}"
+        )
+    else:
+        summary = f"EXECUTE {kind or '(unknown kind)'}\nwallet_label: {wallet_label}"
+
+    mismatch = bool(sender and recipient and sender.lower() != recipient.lower())
+    if kind == "hyperliquid_deposit":
+        mismatch = False  # deposit recipient is fixed; mismatch is expected
+    return {"summary": summary, "recipient_mismatch": mismatch}
+
+
+def build_run_script_preview(tool_input: dict[str, Any]) -> dict[str, Any]:
+    ti = tool_input if isinstance(tool_input, dict) else {}
+    path_raw = ti.get("script_path") or ti.get("path")
+    args = ti.get("args") if isinstance(ti.get("args"), list) else []
+    dry_run = bool(ti.get("dry_run", True))
+
+    if not isinstance(path_raw, str) or not path_raw.strip():
+        return {"summary": "RUN_SCRIPT missing script_path."}
+
+    root = repo_root()
+    p = Path(path_raw)
+    if not p.is_absolute():
+        p = root / p
+    resolved = p.resolve(strict=False)
+
+    rel = str(resolved)
+    try:
+        rel = str(resolved.relative_to(root))
+    except Exception:
+        pass
+
+    sha = None
+    try:
+        if resolved.exists():
+            sha = hashlib.sha256(resolved.read_bytes()).hexdigest()
+    except Exception:
+        sha = None
+
+    excerpt = read_text_excerpt(resolved, max_chars=1200) if resolved.exists() else None
+
+    summary = (
+        "RUN_SCRIPT (executes local python)\n"
+        f"script_path: {rel}\n"
+        f"dry_run: {dry_run}\n"
+        f"args: {args or []}\n"
+        f"script_sha256: {(sha[:12] + '…') if sha else '(unavailable)'}"
+    )
+    if excerpt:
+        summary += "\n\n" + excerpt
+    else:
+        summary += "\n\n(no script contents available)"
+
+    return {"summary": summary}
+
+
+def build_hyperliquid_execute_preview(tool_input: dict[str, Any]) -> dict[str, Any]:
+    # hyperliquid_execute uses direct parameters, not a 'request' wrapper
+    req = tool_input if isinstance(tool_input, dict) else {}
+    if not req:
+        return {"summary": "HYPERLIQUID_EXECUTE missing parameters."}
+
+    action = str(req.get("action") or "").strip()
+    wallet_label = str(req.get("wallet_label") or "").strip()
+    w = find_wallet_by_label(wallet_label) if wallet_label else None
+    sender = normalize_address((w or {}).get("address")) if w else None
+
+    dry_run = req.get("dry_run")
+    coin = req.get("coin")
+    asset_id = req.get("asset_id")
+
+    header = "HYPERLIQUID_EXECUTE\n"
+    base = (
+        f"action: {action or '(missing)'}\n"
+        f"wallet_label: {wallet_label}\n"
+        f"address: {sender or '(unknown)'}\n"
+        f"dry_run: {dry_run}\n"
+        f"coin: {coin}\n"
+        f"asset_id: {asset_id}"
+    )
+
+    if action == "place_order":
+        details = (
+            "\n\nORDER\n"
+            f"order_type: {req.get('order_type')}\n"
+            f"is_buy: {req.get('is_buy')}\n"
+            f"size: {req.get('size')}\n"
+            f"usd_amount: {req.get('usd_amount')}\n"
+            f"usd_amount_kind: {req.get('usd_amount_kind')}\n"
+            f"price: {req.get('price')}\n"
+            f"slippage: {req.get('slippage')}\n"
+            f"reduce_only: {req.get('reduce_only')}\n"
+            f"cloid: {req.get('cloid')}\n"
+            f"leverage: {req.get('leverage')}\n"
+            f"is_cross: {req.get('is_cross')}\n"
+            f"builder_wallet: {HYPE_FEE_WALLET}\n"
+            f"builder_fee_tenths_bp: {req.get('builder_fee_tenths_bp') or '(from config/default)'}"
+        )
+        return {"summary": header + base + details}
+
+    if action == "cancel_order":
+        details = (
+            "\n\nCANCEL\n"
+            f"order_id: {req.get('order_id')}\n"
+            f"cancel_cloid: {req.get('cancel_cloid')}"
+        )
+        return {"summary": header + base + details}
+
+    if action == "update_leverage":
+        details = (
+            "\n\nLEVERAGE\n"
+            f"leverage: {req.get('leverage')}\n"
+            f"is_cross: {req.get('is_cross')}"
+        )
+        return {"summary": header + base + details}
+
+    if action == "withdraw":
+        details = f"\n\nWITHDRAW\namount_usdc: {req.get('amount_usdc')}"
+        return {"summary": header + base + details}
+
+    return {"summary": header + base}

wayfinder_paths/mcp/scripting.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import inspect
+from typing import Any
+
+from eth_account import Account
+
+from wayfinder_paths.mcp.utils import find_wallet_by_label, load_config_json
+
+# Known signing callback parameter names used by adapters
+_SIGNING_CALLBACK_PARAMS = frozenset(
+    {
+        "strategy_wallet_signing_callback",
+        "sign_callback",
+        "signing_callback",
+    }
+)
+
+
+def _make_sign_callback(private_key: str):
+    account = Account.from_key(private_key)
+
+    async def sign_callback(transaction: dict) -> bytes:
+        signed = account.sign_transaction(transaction)
+        return signed.raw_transaction
+
+    return sign_callback
+
+
+def _detect_callback_params(adapter_class: type) -> set[str]:
+    try:
+        sig = inspect.signature(adapter_class.__init__)
+    except (ValueError, TypeError):
+        return set()
+
+    return {
+        name
+        for name in sig.parameters
+        if name in _SIGNING_CALLBACK_PARAMS or name.endswith("_signing_callback")
+    }
+
+
+def get_adapter[T](
+    adapter_class: type[T],
+    wallet_label: str | None = None,
+    *,
+    config_overrides: dict[str, Any] | None = None,
+    **kwargs: Any,
+) -> T:
+    config = load_config_json()
+
+    if config_overrides:
+        config = {**config, **config_overrides}
+
+    sign_callback = None
+    if wallet_label:
+        wallet = find_wallet_by_label(wallet_label)
+        if not wallet:
+            raise ValueError(
+                f"Wallet '{wallet_label}' not found in wallets.json. "
+                "Run 'just create-wallets' or check WALLETS_PATH."
+            )
+
+        private_key = wallet.get("private_key") or wallet.get("private_key_hex")
+        if not private_key:
+            raise ValueError(
+                f"Wallet '{wallet_label}' is missing private_key_hex. "
+                "Local signing requires a private key."
+            )
+
+        config["strategy_wallet"] = wallet
+        sign_callback = _make_sign_callback(private_key)
+
+    callback_params = _detect_callback_params(adapter_class)
+    adapter_kwargs: dict[str, Any] = {"config": config}
+
+    if sign_callback and callback_params:
+        for param_name in callback_params:
+            if param_name not in kwargs:
+                adapter_kwargs[param_name] = sign_callback
+
+    adapter_kwargs.update(kwargs)
+
+    return adapter_class(**adapter_kwargs)

wayfinder_paths/mcp/server.py

@@ -0,0 +1,52 @@
+"""Wayfinder Paths MCP server (FastMCP).
+
+Run locally (via Claude Code .mcp.json):
+  poetry run python -m wayfinder_paths.mcp.server
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from mcp.server.fastmcp import FastMCP
+
+from wayfinder_paths.mcp.tools.balances import balances
+from wayfinder_paths.mcp.tools.discovery import describe, discover
+from wayfinder_paths.mcp.tools.execute import execute
+from wayfinder_paths.mcp.tools.hyperliquid import hyperliquid, hyperliquid_execute
+from wayfinder_paths.mcp.tools.quotes import quote_swap
+from wayfinder_paths.mcp.tools.run_script import run_script
+from wayfinder_paths.mcp.tools.strategies import run_strategy
+from wayfinder_paths.mcp.tools.tokens import tokens
+from wayfinder_paths.mcp.tools.wallets import wallets
+
+mcp = FastMCP("wayfinder")
+
+mcp.tool()(discover)
+mcp.tool()(describe)
+mcp.tool()(wallets)
+mcp.tool()(tokens)
+mcp.tool()(balances)
+mcp.tool()(quote_swap)
+mcp.tool()(hyperliquid)
+mcp.tool()(hyperliquid_execute)
+mcp.tool()(run_strategy)
+mcp.tool()(run_script)
+mcp.tool()(execute)
+
+
+def main() -> None:
+    # FastMCP is sync, but our tools are async; the library handles that.
+    mcp.run()
+
+
+if __name__ == "__main__":
+    # Some environments complain if an event loop is already running.
+    # FastMCP handles stdio and tool execution; we just start it.
+    try:
+        main()
+    except RuntimeError as exc:
+        if "asyncio.run()" in str(exc) and asyncio.get_event_loop().is_running():
+            main()
+        else:
+            raise

wayfinder_paths/mcp/state/profile_store.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+import json
+import logging
+import os
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from wayfinder_paths.mcp.utils import repo_root
+
+logger = logging.getLogger(__name__)
+
+
+def _now_iso() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def _runs_root() -> Path:
+    candidate = (os.getenv("WAYFINDER_RUNS_DIR") or ".wayfinder_runs").strip()
+    p = Path(candidate)
+    if not p.is_absolute():
+        p = repo_root() / p
+    return p.resolve(strict=False)
+
+
+class WalletProfileStore:
+    SCHEMA_VERSION = "1.0"
+    MAX_TRANSACTIONS = 100  # Bound history size per wallet
+
+    def __init__(self, path: Path | None = None):
+        if path is None:
+            path = _runs_root() / "wallet_profiles.json"
+        self.path = path
+
+    @staticmethod
+    def default() -> WalletProfileStore:
+        return WalletProfileStore()
+
+    def _ensure_dir(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+
+    def _load(self) -> dict[str, Any]:
+        if not self.path.exists():
+            return {"schema_version": self.SCHEMA_VERSION, "profiles": {}}
+        try:
+            data = json.loads(self.path.read_text())
+            if not isinstance(data, dict):
+                return {"schema_version": self.SCHEMA_VERSION, "profiles": {}}
+            if not isinstance(data.get("profiles"), dict):
+                data["profiles"] = {}
+            return data
+        except Exception as exc:
+            logger.warning(f"Failed to load wallet profiles: {exc}")
+            return {"schema_version": self.SCHEMA_VERSION, "profiles": {}}
+
+    def _save(self, data: dict[str, Any]) -> None:
+        self._ensure_dir()
+        data["schema_version"] = self.SCHEMA_VERSION
+        self.path.write_text(json.dumps(data, indent=2, sort_keys=False))
+
+    def _normalize_address(self, address: str) -> str:
+        addr = str(address).strip().lower()
+        if addr.startswith("0x"):
+            return addr
+        return addr
+
+    def get_profile(self, address: str) -> dict[str, Any] | None:
+        data = self._load()
+        norm = self._normalize_address(address)
+        profile = data["profiles"].get(norm)
+        if profile:
+            return {"address": norm, **profile}
+        return None
+
+    def list_profiles(self) -> list[dict[str, Any]]:
+        data = self._load()
+        results: list[dict[str, Any]] = []
+        for addr, profile in data.get("profiles", {}).items():
+            protocols = list((profile.get("protocols") or {}).keys())
+            tx_count = len(profile.get("transactions") or [])
+            results.append(
+                {
+                    "address": addr,
+                    "label": profile.get("label"),
+                    "protocols": protocols,
+                    "protocol_count": len(protocols),
+                    "transaction_count": tx_count,
+                    "last_activity": profile.get("last_activity"),
+                }
+            )
+        return results
+
+    def get_protocols_for_wallet(self, address: str) -> list[str]:
+        profile = self.get_profile(address)
+        if not profile:
+            return []
+        return list((profile.get("protocols") or {}).keys())
+
+    def annotate(
+        self,
+        *,
+        address: str,
+        label: str | None = None,
+        protocol: str,
+        action: str,
+        tool: str,
+        status: str,
+        chain_id: int | None = None,
+        details: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> None:
+        data = self._load()
+        norm = self._normalize_address(address)
+        now = _now_iso()
+
+        if norm not in data["profiles"]:
+            data["profiles"][norm] = {
+                "label": label,
+                "protocols": {},
+                "transactions": [],
+            }
+
+        profile = data["profiles"][norm]
+
+        if label:
+            profile["label"] = label
+
+        if protocol not in profile["protocols"]:
+            profile["protocols"][protocol] = {
+                "first_seen": now,
+                "last_seen": now,
+                "interaction_count": 0,
+                "chains": [],
+            }
+
+        proto_info = profile["protocols"][protocol]
+        proto_info["last_seen"] = now
+        proto_info["interaction_count"] = proto_info.get("interaction_count", 0) + 1
+        if chain_id is not None:
+            chains = proto_info.get("chains") or []
+            if chain_id not in chains:
+                chains.append(chain_id)
+                proto_info["chains"] = chains
+
+        tx = {
+            "timestamp": now,
+            "protocol": protocol,
+            "action": action,
+            "tool": tool,
+            "status": status,
+        }
+        if chain_id is not None:
+            tx["chain_id"] = chain_id
+        if details:
+            tx["details"] = details
+        if idempotency_key:
+            tx["idempotency_key"] = idempotency_key
+
+        transactions = profile.get("transactions") or []
+        transactions.insert(0, tx)
+        if len(transactions) > self.MAX_TRANSACTIONS:
+            transactions = transactions[: self.MAX_TRANSACTIONS]
+        profile["transactions"] = transactions
+        profile["last_activity"] = now
+        self._save(data)
+
+    def annotate_safe(
+        self,
+        *,
+        address: str,
+        label: str | None = None,
+        protocol: str,
+        action: str,
+        tool: str,
+        status: str,
+        chain_id: int | None = None,
+        details: dict[str, Any] | None = None,
+        idempotency_key: str | None = None,
+    ) -> None:
+        # Best-effort: logs but doesn't raise on failure so annotation doesn't block main operation
+        try:
+            self.annotate(
+                address=address,
+                label=label,
+                protocol=protocol,
+                action=action,
+                tool=tool,
+                status=status,
+                chain_id=chain_id,
+                details=details,
+                idempotency_key=idempotency_key,
+            )
+        except Exception as exc:
+            logger.warning(f"Failed to annotate wallet profile: {exc}")

wayfinder_paths/mcp/state/store.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+import json
+import os
+import sqlite3
+import time
+from pathlib import Path
+from typing import Any
+
+from wayfinder_paths.mcp.utils import repo_root
+
+
+class _HexBytesEncoder(json.JSONEncoder):
+    """JSON encoder that handles HexBytes and other byte-like objects."""
+
+    def default(self, obj: Any) -> Any:
+        if hasattr(obj, "hex") and callable(obj.hex):
+            return obj.hex()
+        if isinstance(obj, bytes):
+            return obj.hex()
+        return super().default(obj)
+
+
+class IdempotencyStore:
+    def __init__(self, db_path: Path):
+        self.db_path = db_path
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._init_db()
+
+    @staticmethod
+    def default() -> IdempotencyStore:
+        candidate = (
+            os.getenv("WAYFINDER_MCP_STATE_PATH") or ".cache/wayfinder_mcp.sqlite3"
+        )
+        path = Path(candidate)
+        if not path.is_absolute():
+            path = repo_root() / path
+        return IdempotencyStore(path)
+
+    def _connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(str(self.db_path))
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def _init_db(self) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS idempotency (
+                    idempotency_key TEXT PRIMARY KEY,
+                    created_at INTEGER NOT NULL,
+                    request_json TEXT NOT NULL,
+                    response_json TEXT NOT NULL
+                )
+                """
+            )
+            conn.commit()
+
+    def get(self, key: str) -> dict[str, Any] | None:
+        with self._connect() as conn:
+            row = conn.execute(
+                "SELECT response_json FROM idempotency WHERE idempotency_key = ?",
+                (key,),
+            ).fetchone()
+            if row is None:
+                return None
+            try:
+                parsed = json.loads(row["response_json"])
+            except Exception:
+                return None
+            return parsed if isinstance(parsed, dict) else None
+
+    def put(self, key: str, request: Any, response: Any) -> None:
+        with self._connect() as conn:
+            conn.execute(
+                """
+                INSERT OR REPLACE INTO idempotency
+                    (idempotency_key, created_at, request_json, response_json)
+                VALUES
+                    (?, ?, ?, ?)
+                """,
+                (
+                    key,
+                    int(time.time()),
+                    json.dumps(request, sort_keys=True, cls=_HexBytesEncoder),
+                    json.dumps(response, sort_keys=True, cls=_HexBytesEncoder),
+                ),
+            )
+            conn.commit()