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

wayfinder_paths/mcp/tools/discovery.py

@@ -0,0 +1,158 @@
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from wayfinder_paths.mcp.utils import err, ok, read_text_excerpt, read_yaml, repo_root
+
+
+async def discover(
+    kind: Literal["adapters", "strategies"],
+    detail: Literal["summary", "full"] = "summary",
+) -> dict[str, Any]:
+    root = repo_root()
+    base = (
+        root / "wayfinder_paths" / ("adapters" if kind == "adapters" else "strategies")
+    )
+    if not base.exists():
+        return err("not_found", f"Directory not found: {base}")
+
+    items: list[dict[str, Any]] = []
+    for child in sorted(base.iterdir()):
+        if not child.is_dir():
+            continue
+        manifest_path = child / "manifest.yaml"
+        if not manifest_path.exists():
+            continue
+        manifest = read_yaml(manifest_path)
+        rel_manifest = str(manifest_path.relative_to(root))
+
+        if kind == "adapters":
+            item = {
+                "name": child.name,
+                "entrypoint": manifest.get("entrypoint"),
+                "capabilities": manifest.get("capabilities", []),
+                "dependencies": manifest.get("dependencies", []),
+                "manifest_path": rel_manifest,
+            }
+        else:
+            adapters = manifest.get("adapters", [])
+            item = {
+                "name": child.name,
+                "entrypoint": manifest.get("entrypoint"),
+                "adapters": adapters if isinstance(adapters, list) else [],
+                "permissions_policy_present": bool(
+                    isinstance(manifest.get("permissions"), dict)
+                    and (manifest.get("permissions") or {}).get("policy")
+                ),
+                "manifest_path": rel_manifest,
+            }
+
+        if detail == "full":
+            readme = read_text_excerpt(child / "README.md")
+            if readme:
+                item["readme_excerpt"] = readme
+            item["manifest"] = manifest
+
+        items.append(item)
+
+    return ok({"kind": kind, "items": items})
+
+
+def _default_claude_notes_for_adapter(name: str) -> dict[str, Any] | None:
+    # Keep this deliberately small; the real docs live in .claude/skills.
+    if name == "brap_adapter":
+        return {
+            "reads": [
+                {
+                    "name": "quote_swap (via mcp__wayfinder__quote_swap)",
+                    "summary": "Get best BRAP route + fees; no on-chain effects.",
+                }
+            ],
+            "writes": [
+                {
+                    "name": "swap (via mcp__wayfinder__execute kind=swap)",
+                    "risk": "funds",
+                    "summary": "May submit ERC20 approvals and a swap/bridge tx.",
+                }
+            ],
+            "gotchas": [
+                "USDT-style tokens may require setting allowance to 0 before approve.",
+                "Cross-chain swaps still broadcast a tx on the source chain.",
+            ],
+        }
+    if name == "balance_adapter":
+        return {
+            "reads": [
+                {
+                    "name": "balances (via mcp__wayfinder__balances)",
+                    "summary": "Read token/pool balances via Wayfinder API.",
+                }
+            ],
+            "writes": [
+                {
+                    "name": "send (via mcp__wayfinder__execute kind=send)",
+                    "risk": "funds",
+                    "summary": "Native/ERC20 sends from a local wallet.",
+                }
+            ],
+            "gotchas": ["Prefer DRY_RUN=1 until ready to broadcast."],
+        }
+    if name == "hyperliquid_adapter":
+        return {
+            "reads": [
+                {
+                    "name": "hyperliquid (via mcp__wayfinder__hyperliquid)",
+                    "summary": "User state + market reads (no signing).",
+                }
+            ],
+            "writes": [
+                {
+                    "name": "hyperliquid_execute (via mcp__wayfinder__hyperliquid_execute)",
+                    "risk": "funds",
+                    "summary": "Perp orders/leverage/withdraw with local signing (gated by review prompt).",
+                }
+            ],
+            "gotchas": [
+                "Perp coins are mapped to asset_id (<10000).",
+                "Builder fees are attributed to 0xaA1D89f333857eD78F8434CC4f896A9293EFE65c and use tenths-of-bp units.",
+                "Prefer DRY_RUN=1 until ready to execute.",
+            ],
+        }
+    return None
+
+
+async def describe(
+    kind: Literal["adapter", "strategy"],
+    name: str,
+    include_manifest: bool = True,
+    include_readme_excerpt: bool = True,
+    include_claude_notes: bool = True,
+) -> dict[str, Any]:
+    root = repo_root()
+    base = (
+        root / "wayfinder_paths" / ("adapters" if kind == "adapter" else "strategies")
+    )
+    target = base / name
+    if not target.exists():
+        return err("not_found", f"Unknown {kind}: {name}")
+
+    manifest_path = target / "manifest.yaml"
+    if not manifest_path.exists():
+        return err("not_found", f"Missing manifest.yaml for {kind}: {name}")
+
+    out: dict[str, Any] = {"kind": kind, "name": name}
+    if include_manifest:
+        out["manifest"] = read_yaml(manifest_path)
+        out["manifest_path"] = str(manifest_path.relative_to(root))
+
+    if include_readme_excerpt:
+        readme = read_text_excerpt(target / "README.md")
+        if readme:
+            out["readme_excerpt"] = readme
+
+    if include_claude_notes and kind == "adapter":
+        notes = _default_claude_notes_for_adapter(name)
+        if notes:
+            out["claude_notes"] = notes
+
+    return ok(out)