asm-protocol 0.5.0__py3-none-any.whl

asm_selector_mcp.py

@@ -0,0 +1,94 @@
+#!/usr/bin/env python3
+"""ASM Selector — an MCP server that lets any MCP client (Claude Desktop, Cursor,
+agent hosts) query the ASM tool-value library and pick a tool for a task.
+
+This is ASM's productization wedge: the agent doesn't adopt a schema, it just
+calls `select_tool` and gets back which tool to use, why, and the operational
+policy (risk / approval / side-effects) to gate the action.
+
+Run (stdio):  python asm_selector_mcp.py     (or `asm-selector` once installed)
+Requires:     pip install mcp   (or: pip install "asm-protocol[mcp]")
+"""
+from __future__ import annotations
+
+from mcp.server.fastmcp import FastMCP
+
+from library_select import load_library, monthly_cost, select
+
+mcp = FastMCP("asm-selector")
+
+
+@mcp.tool()
+def select_tool(
+    task: str,
+    taxonomy: str | None = None,
+    agent_reach: str = "cloud",
+    user_platform: str = "any",
+    required_functions: list[str] | None = None,
+    require_approval_for: list[str] | None = None,
+    require_agent_completable_setup: bool = False,
+) -> dict:
+    """Pick the best tool from the ASM library for a task.
+
+    Filters out tools the agent can't drive (invocation/reach/platform), tools
+    that forbid automation, and tools missing the required functions; then ranks
+    the rest cheapest-first. Returns the selected tool plus its operational
+    policy so the caller can gate high-stakes actions before invoking.
+
+    Args:
+        task: natural-language description of what the agent must do.
+        taxonomy: optional ASM taxonomy to scope candidates (e.g. tool.booking.travel).
+        agent_reach: 'cloud' (remote/headless) or 'local_device' (runs on user's machine).
+        user_platform: e.g. windows, macos, ios, android, web, any.
+        required_functions: capability names the tool must have (e.g. ["flight_search"]).
+        require_approval_for: side-effects that should force approval (e.g. ["financial_charge","sends_message"]).
+        require_agent_completable_setup: if true, drop tools that need a human-in-the-loop
+            step (paid signup, OAuth consent, manual approval) the agent cannot complete unattended.
+    """
+    return select(
+        task,
+        taxonomy=taxonomy,
+        agent_reach=agent_reach,
+        user_platform=user_platform,
+        required_functions=required_functions or [],
+        require_approval_for=require_approval_for or [],
+        require_agent_completable_setup=require_agent_completable_setup,
+    )
+
+
+@mcp.tool()
+def list_library_tools(taxonomy: str | None = None) -> list[dict]:
+    """List tools in the ASM library (optionally filtered by taxonomy), with
+    interface/reach and monthly cost so a client can browse what's selectable."""
+    out = []
+    for m in load_library():
+        if taxonomy and m.get("taxonomy") != taxonomy:
+            continue
+        inv = m.get("invocation") or {}
+        out.append({
+            "service_id": m.get("service_id"),
+            "display_name": m.get("display_name"),
+            "taxonomy": m.get("taxonomy"),
+            "interface": inv.get("interface"),
+            "reach": inv.get("reach"),
+            "agent_operable": inv.get("agent_operable"),
+            "monthly_cost_usd": round(monthly_cost(m), 2),
+        })
+    return out
+
+
+@mcp.tool()
+def get_tool_manifest(service_id: str) -> dict:
+    """Return the full ASM manifest for a given service_id."""
+    for m in load_library():
+        if m.get("service_id") == service_id:
+            return m
+    return {"error": f"no tool with service_id={service_id}"}
+
+
+def main() -> None:
+    mcp.run()
+
+
+if __name__ == "__main__":
+    main()

library_select.py

@@ -0,0 +1,149 @@
+#!/usr/bin/env python3
+"""Importable ASM tool-selector over the library/ manifests.
+
+One selector, shared by the demo, the CLI, and the MCP server. Implements the
+confirmed priority order:
+
+  gate 1: agent can invoke it      (agent_operable; reach matches the agent env)
+  gate 2: automated use is allowed (usage_terms.automation_allowed != 'no')
+  gate 3: meets task requirements  (required functions present; platform fits)
+  rank  : among survivors, cheapest first, then feature-richest
+
+It also surfaces the operational policy of the pick (risk_class / approval /
+side_effects) so the caller can gate high-stakes actions (send message, spend
+money, mutate a repo) before invoking.
+"""
+from __future__ import annotations
+
+import glob
+import json
+import os
+from pathlib import Path
+
+# Default to the library/ next to this module (works from a checkout); override
+# with ASM_LIBRARY_DIR so the MCP server / API can point at any library location.
+LIBRARY_DIR = Path(os.environ.get("ASM_LIBRARY_DIR")
+                   or (Path(__file__).resolve().parent / "library"))
+
+
+def load_library(library_dir: str | Path | None = None) -> list[dict]:
+    d = Path(library_dir) if library_dir else LIBRARY_DIR
+    return [json.loads(Path(p).read_text(encoding="utf-8"))
+            for p in glob.glob(str(d / "**" / "*.asm.json"), recursive=True)]
+
+
+def monthly_cost(m: dict) -> float:
+    dims = (m.get("pricing") or {}).get("billing_dimensions") or []
+    free = "free_tier" in (m.get("payment") or {}).get("methods", [])
+    base = 0.0 if free else 1e9
+    saw_zero = False
+    for d in dims:
+        c, u = d.get("cost_per_unit", 0), d.get("unit", "")
+        if c == 0:
+            saw_zero = True
+            continue
+        base = min(base, c if "month" in u else c / 12 if "year" in u else c / 24)
+    if base == 1e9 and saw_zero:
+        return 0.0
+    return 0.0 if free else base
+
+
+def eligibility(m: dict, agent_reach: str, user_platform: str, required_functions,
+                require_agent_completable_setup: bool = False) -> str | None:
+    """Return None if the tool is eligible, else a human-readable rejection reason."""
+    inv = m.get("invocation", {})
+    if not inv.get("agent_operable"):
+        return "not agent-operable"
+    if inv.get("reach") == "local_device" and agent_reach != "local_device":
+        return f"reach=local_device but agent is {agent_reach} (can't drive remotely)"
+    if require_agent_completable_setup and inv.get("agent_completable_setup") is False:
+        req = ", ".join(inv.get("setup_requires") or []) or "human-in-the-loop"
+        return f"setup not agent-completable (requires {req})"
+    if (m.get("usage_terms") or {}).get("automation_allowed") == "no":
+        return "ToS forbids automated use"
+    plats = inv.get("platforms", [])
+    if not ({"any", "web"} & set(plats)) and user_platform not in plats:
+        return f"platform {user_platform} unsupported ({plats})"
+    funcs = set((m.get("capabilities") or {}).get("functions", []))
+    missing = [f for f in required_functions if f not in funcs]
+    if missing:
+        return f"missing required functions: {missing}"
+    return None
+
+
+def policy_of(m: dict, require_approval_for=()) -> dict:
+    ops = m.get("operational_constraints") or {}
+    approval = ops.get("approval") or {}
+    side = ops.get("side_effects", []) or []
+    req = approval.get("required")
+    approval_required = (req == "always") or bool(set(side) & set(require_approval_for or ()))
+    return {
+        "risk_class": ops.get("risk_class", "unknown"),
+        "approval_policy": req or "unknown",
+        "approval_required": approval_required,
+        "side_effects": side,
+    }
+
+
+def rank(task: str, *, taxonomy: str | None = None, agent_reach: str = "cloud",
+         user_platform: str = "any", required_functions=(),
+         require_agent_completable_setup: bool = False, library=None):
+    """Return (kept_manifests_sorted, rejected[{service, service_id, reason}])."""
+    entries = library if library is not None else load_library()
+    pool = [m for m in entries if taxonomy is None or m.get("taxonomy") == taxonomy]
+    kept, rejected = [], []
+    for m in pool:
+        why = eligibility(m, agent_reach, user_platform, list(required_functions),
+                          require_agent_completable_setup=require_agent_completable_setup)
+        if why:
+            rejected.append({"service": m.get("display_name"),
+                             "service_id": m.get("service_id"), "reason": why})
+        else:
+            kept.append(m)
+    kept.sort(key=lambda m: (monthly_cost(m),
+                             -len((m.get("capabilities") or {}).get("functions", []))))
+    return kept, rejected
+
+
+def select(task: str, *, taxonomy: str | None = None, agent_reach: str = "cloud",
+           user_platform: str = "any", required_functions=(),
+           require_approval_for=(), require_agent_completable_setup: bool = False,
+           library=None) -> dict:
+    """Structured selection decision (used by the CLI, MCP server, hosted API)."""
+    kept, rejected = rank(task, taxonomy=taxonomy, agent_reach=agent_reach,
+                          user_platform=user_platform,
+                          required_functions=required_functions,
+                          require_agent_completable_setup=require_agent_completable_setup,
+                          library=library)
+    out = {
+        "task": task, "taxonomy": taxonomy,
+        "selected": None, "reason": "no eligible tool",
+        "risk_class": None, "approval_required": None, "side_effects": [],
+        "alternatives": [], "rejected": rejected,
+    }
+    if kept:
+        top = kept[0]
+        pol = policy_of(top, require_approval_for)
+        inv = top.get("invocation") or {}
+        out["selected"] = {
+            "service_id": top.get("service_id"),
+            "display_name": top.get("display_name"),
+            "monthly_cost_usd": round(monthly_cost(top), 2),
+            "interface": inv.get("interface"),
+            "reach": inv.get("reach"),
+            "agent_completable_setup": inv.get("agent_completable_setup"),
+            "setup_requires": inv.get("setup_requires", []),
+        }
+        out["risk_class"] = pol["risk_class"]
+        out["approval_required"] = pol["approval_required"]
+        out["side_effects"] = pol["side_effects"]
+        out["reason"] = (
+            f"Eligible {pol['risk_class']}-risk tool with the required functions; "
+            + ("approval required before invocation." if pol["approval_required"]
+               else "no approval gate triggered.")
+        )
+        out["alternatives"] = [
+            {"service_id": m.get("service_id"), "display_name": m.get("display_name"),
+             "monthly_cost_usd": round(monthly_cost(m), 2)} for m in kept[1:]
+        ]
+    return out

mcp_server_json_asm.py

@@ -0,0 +1,177 @@
+#!/usr/bin/env python3
+"""Extract and validate ASM metadata embedded in MCP Registry server.json files."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+try:
+    from jsonschema import Draft202012Validator
+except Exception:  # pragma: no cover - exercised only without optional dependency
+    Draft202012Validator = None
+
+
+ROOT = Path(__file__).resolve().parent
+SCHEMA_PATH = ROOT / "schema" / "asm-v0.3.schema.json"
+PUBLISHER_META_KEY = "io.modelcontextprotocol.registry/publisher-provided"
+RECOMMENDED_VALUE_FIELDS = ("pricing", "sla", "quality", "provenance", "payment")
+
+
+@dataclass
+class InspectionResult:
+    path: str
+    has_asm: bool
+    valid_asm: bool
+    can_convert: bool
+    asm_service_id: str | None = None
+    asm_taxonomy: str | None = None
+    missing_recommended_fields: list[str] = field(default_factory=list)
+    warnings: list[str] = field(default_factory=list)
+    errors: list[str] = field(default_factory=list)
+    asm_manifest: dict[str, Any] | None = None
+
+    def as_dict(self) -> dict[str, Any]:
+        data = {
+            "path": self.path,
+            "has_asm": self.has_asm,
+            "valid_asm": self.valid_asm,
+            "can_convert": self.can_convert,
+            "asm_service_id": self.asm_service_id,
+            "asm_taxonomy": self.asm_taxonomy,
+            "missing_recommended_fields": self.missing_recommended_fields,
+            "warnings": self.warnings,
+            "errors": self.errors,
+        }
+        if self.asm_manifest is not None:
+            data["asm_manifest"] = self.asm_manifest
+        return data
+
+
+def load_json(path: Path) -> dict[str, Any]:
+    with path.open("r", encoding="utf-8-sig") as fp:
+        data = json.load(fp)
+    if not isinstance(data, dict):
+        raise ValueError("server.json root must be an object")
+    return data
+
+
+def extract_asm(server_json: dict[str, Any]) -> tuple[dict[str, Any] | None, list[str], list[str]]:
+    warnings: list[str] = []
+    errors: list[str] = []
+    meta = server_json.get("_meta")
+    if not isinstance(meta, dict):
+        return None, ["No _meta object found; this server.json has no inline ASM metadata."], errors
+
+    publisher = meta.get(PUBLISHER_META_KEY)
+    if not isinstance(publisher, dict):
+        return None, [f"No _meta.{PUBLISHER_META_KEY} object found; no publisher-provided ASM metadata."], errors
+
+    asm = publisher.get("asm")
+    asm_url = publisher.get("asm_url")
+    if asm is None and asm_url:
+        return None, [f"ASM is referenced by asm_url={asm_url!r}; inline conversion is unavailable."], errors
+    if asm is None:
+        return None, ["No publisher-provided asm object found."], errors
+    if not isinstance(asm, dict):
+        return None, warnings, ["publisher-provided asm must be a JSON object."]
+    return asm, warnings, errors
+
+
+def validate_manifest(manifest: dict[str, Any]) -> list[str]:
+    if Draft202012Validator is None:
+        required = {"asm_version", "service_id", "taxonomy"}
+        return [f"Missing required field: {field}" for field in sorted(required - set(manifest))]
+
+    schema = load_json(SCHEMA_PATH)
+    validator = Draft202012Validator(schema)
+    errors = []
+    for err in sorted(validator.iter_errors(manifest), key=lambda e: list(e.path)):
+        path = ".".join(str(p) for p in err.path) or "<root>"
+        errors.append(f"{path}: {err.message}")
+    return errors
+
+
+def inspect_server_json(path: str | Path) -> InspectionResult:
+    path = Path(path)
+    try:
+        server_json = load_json(path)
+    except Exception as exc:
+        return InspectionResult(path=str(path), has_asm=False, valid_asm=False, can_convert=False, errors=[str(exc)])
+
+    asm, warnings, extraction_errors = extract_asm(server_json)
+    if asm is None:
+        return InspectionResult(
+            path=str(path),
+            has_asm=False,
+            valid_asm=False,
+            can_convert=False,
+            warnings=warnings,
+            errors=extraction_errors,
+        )
+
+    validation_errors = validate_manifest(asm)
+    missing = [field for field in RECOMMENDED_VALUE_FIELDS if field not in asm]
+    return InspectionResult(
+        path=str(path),
+        has_asm=True,
+        valid_asm=not validation_errors,
+        can_convert=not validation_errors,
+        asm_service_id=asm.get("service_id"),
+        asm_taxonomy=asm.get("taxonomy"),
+        missing_recommended_fields=missing,
+        warnings=warnings,
+        errors=extraction_errors + validation_errors,
+        asm_manifest=asm,
+    )
+
+
+def print_human(result: InspectionResult) -> None:
+    print(f"File: {result.path}")
+    if not result.has_asm:
+        print("ASM metadata: missing")
+    else:
+        print("ASM metadata: found")
+        print(f"Service: {result.asm_service_id or 'unknown'}")
+        print(f"Taxonomy: {result.asm_taxonomy or 'unknown'}")
+        print(f"Schema validation: {'pass' if result.valid_asm else 'fail'}")
+        if result.missing_recommended_fields:
+            print("Missing recommended value fields: " + ", ".join(result.missing_recommended_fields))
+        else:
+            print("Recommended value fields: complete")
+
+    for warning in result.warnings:
+        print(f"Warning: {warning}")
+    for error in result.errors:
+        print(f"Error: {error}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Validate ASM metadata embedded in MCP Registry server.json files")
+    parser.add_argument("server_json", help="Path to server.json")
+    parser.add_argument("--json", action="store_true", help="Print machine-readable inspection JSON")
+    parser.add_argument("--write-out", help="Write extracted ASM manifest to this .asm.json path")
+    args = parser.parse_args(argv)
+
+    result = inspect_server_json(args.server_json)
+    if args.write_out and result.asm_manifest and result.valid_asm:
+        out = Path(args.write_out)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        out.write_text(json.dumps(result.asm_manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+    if args.json:
+        print(json.dumps(result.as_dict(), indent=2, ensure_ascii=False))
+    else:
+        print_human(result)
+
+    if result.errors:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())