alloc-context 0.1.0__py3-none-any.whl

alloccontext/mcp/server.py

@@ -0,0 +1,319 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from alloccontext.config import load_config
+from alloccontext.mcp import handlers
+from alloccontext.store.db import connect
+
+
+def _transport_security_settings(*, host: str):
+    from urllib.parse import urlparse
+
+    from mcp.server.transport_security import TransportSecuritySettings
+
+    from alloccontext.mcp.bazaar import resolve_public_base_url
+
+    public = resolve_public_base_url()
+    if not public:
+        return None
+
+    parsed = urlparse(public if "://" in public else f"https://{public}")
+    hostname = parsed.hostname
+    if not hostname:
+        return None
+
+    scheme = parsed.scheme or "https"
+    return TransportSecuritySettings(
+        enable_dns_rebinding_protection=True,
+        allowed_hosts=[
+            "127.0.0.1:*",
+            "localhost:*",
+            "[::1]:*",
+            hostname,
+            f"{hostname}:*",
+        ],
+        allowed_origins=[
+            f"{scheme}://{hostname}:*",
+            public.rstrip("/"),
+        ],
+    )
+
+
+def _require_mcp():
+    try:
+        from mcp.server.fastmcp import FastMCP
+    except ImportError as exc:
+        raise RuntimeError(
+            "MCP support requires the mcp package: pip install 'alloc-context[mcp]'"
+        ) from exc
+    return FastMCP
+
+
+def create_server(
+    *,
+    config_path: str | None = None,
+    host: str = "127.0.0.1",
+    port: int = 8000,
+    stateless_http: bool = True,
+):
+    FastMCP = _require_mcp()
+    if config_path:
+        os.environ.setdefault("ALLOC_CONTEXT_CONFIG", config_path)
+
+    config = load_config(config_path)
+
+    mcp = FastMCP(
+        "alloc-context",
+        json_response=True,
+        host=host,
+        port=port,
+        stateless_http=stateless_http,
+        transport_security=_transport_security_settings(host=host),
+        instructions=(
+            "BTC/ETH allocation context: fused market backdrop from cached ingest, "
+            "USD rebalance moves, and allocation band checks. Facts only — no LLM."
+        ),
+    )
+
+    @mcp.tool(
+        name="get_context_bundle",
+        description=(
+            "Full ContextBundle JSON: portfolio, market, sentiment, macro, regime "
+            "hints, and delta vs the prior saved snapshot. Optional assets filter "
+            "(default BTC, ETH), target_pct, and band override server config for "
+            "drift math. freshness=cached uses the local ingest DB; freshness=live "
+            "runs ingest first."
+        ),
+    )
+    def get_context_bundle(
+        scope: str = "daily",
+        freshness: str = "cached",
+        assets: list[str] | None = None,
+        target_pct: dict[str, float] | None = None,
+        band: float | None = None,
+    ) -> dict[str, Any]:
+        """Return the full deterministic context bundle for daily or weekly scope."""
+        validated_scope = handlers.validate_scope(scope)
+        validated_freshness = handlers.validate_freshness(freshness)
+        conn = connect(config.paths.db)
+        try:
+            return handlers.get_context_bundle(
+                conn,
+                config,
+                scope=validated_scope,
+                freshness=validated_freshness,
+                assets=assets,
+                target_pct=target_pct,
+                band=band,
+            )
+        finally:
+            conn.close()
+
+    @mcp.tool(
+        name="get_market_context",
+        description=(
+            "Fused market backdrop: sentiment (Fear & Greed, Kalshi), macro events, "
+            "FRED indicators, ETF flows, and market breadth. Optional assets filter "
+            "(default BTC, ETH). freshness=cached uses the local ingest DB; "
+            "freshness=live runs ingest first (requires ingest API keys on the host)."
+        ),
+    )
+    def get_market_context(
+        scope: str = "daily",
+        freshness: str = "cached",
+        assets: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Return ContextBundle subset for daily or weekly scope."""
+        validated_scope = handlers.validate_scope(scope)
+        validated_freshness = handlers.validate_freshness(freshness)
+        conn = connect(config.paths.db)
+        try:
+            return handlers.get_market_context(
+                conn,
+                config,
+                scope=validated_scope,
+                freshness=validated_freshness,
+                assets=assets,
+            )
+        finally:
+            conn.close()
+
+    @mcp.tool(
+        name="get_rebalance_plan",
+        description=(
+            "USD deltas and exchange-style move lines to reach a target BTC/ETH/CASH "
+            "split. Requires allocation_pct, target_pct, and nav_usd. Optional band "
+            "returns a band_check block alongside the plan. exchange=kraken|coinbase "
+            "adjusts move wording."
+        ),
+    )
+    def get_rebalance_plan(
+        allocation_pct: dict[str, float],
+        target_pct: dict[str, float],
+        nav_usd: float,
+        exchange: str = "kraken",
+        band: float | None = None,
+    ) -> dict[str, Any]:
+        """Compute rebalance plan from current allocation and NAV."""
+        return handlers.get_rebalance_plan(
+            allocation_pct,
+            target_pct,
+            nav_usd,
+            exchange=exchange,
+            band=band,
+        )
+
+    @mcp.tool(
+        name="get_portfolio_state",
+        description=(
+            "Live portfolio NAV, allocation, drift, and band hint from "
+            "read-only exchange credentials passed in the request. Credentials are "
+            "never stored. Supports kraken and coinbase."
+        ),
+    )
+    def get_portfolio_state(
+        exchange: str,
+        api_key: str,
+        api_secret: str,
+        target_pct: dict[str, float] | None = None,
+        band: float | None = None,
+    ) -> dict[str, Any]:
+        """Fetch live portfolio state using caller-supplied read-only API keys."""
+        return handlers.get_portfolio_state(
+            config,
+            exchange=exchange,
+            api_key=api_key,
+            api_secret=api_secret,
+            target_pct=target_pct,
+            band=band,
+        )
+
+    @mcp.tool(
+        name="check_allocation_band",
+        description=(
+            "Check whether BTC/ETH/CASH allocation is outside a drift band vs "
+            "target_pct and return hint (within_band, consider_rebalance, etc.). "
+            "All three inputs are required — use get_context_bundle with target_pct "
+            "and band when you want cached portfolio drift from server config."
+        ),
+    )
+    def check_allocation_band(
+        allocation_pct: dict[str, float],
+        target_pct: dict[str, float],
+        band: float = 0.15,
+    ) -> dict[str, Any]:
+        """Evaluate allocation drift against band width (default 0.15 = 15%)."""
+        return handlers.check_band(allocation_pct, target_pct, band)
+
+    @mcp.tool(
+        name="get_context_at",
+        description=(
+            "Load a saved ContextBundle snapshot from ingest history. "
+            "as_of is an ISO timestamp; match=at_or_before returns the latest "
+            "snapshot on or before that time."
+        ),
+    )
+    def get_context_at(
+        as_of: str,
+        scope: str = "daily",
+        match: str = "at_or_before",
+        assets: list[str] | None = None,
+        target_pct: dict[str, float] | None = None,
+        band: float | None = None,
+    ) -> dict[str, Any]:
+        validated_scope = handlers.validate_scope(scope)
+        if match not in ("exact", "at_or_before"):
+            raise ValueError("match must be 'exact' or 'at_or_before'")
+        conn = connect(config.paths.db)
+        try:
+            return handlers.get_context_at(
+                conn,
+                config,
+                scope=validated_scope,
+                as_of=as_of,
+                match=match,  # type: ignore[arg-type]
+                assets=assets,
+                target_pct=target_pct,
+                band=band,
+            )
+        finally:
+            conn.close()
+
+    @mcp.tool(
+        name="get_context_delta",
+        description=(
+            "Compare two ContextBundle snapshots and return notable_shifts. "
+            "prior_as_of is required; omit current_as_of for latest live bundle."
+        ),
+    )
+    def get_context_delta(
+        prior_as_of: str,
+        scope: str = "daily",
+        current_as_of: str | None = None,
+        assets: list[str] | None = None,
+    ) -> dict[str, Any]:
+        validated_scope = handlers.validate_scope(scope)
+        conn = connect(config.paths.db)
+        try:
+            return handlers.get_context_delta(
+                conn,
+                config,
+                scope=validated_scope,
+                prior_as_of=prior_as_of,
+                current_as_of=current_as_of,
+                assets=assets,
+            )
+        finally:
+            conn.close()
+
+    @mcp.tool(
+        name="check_allocation_bands",
+        description=(
+            "Evaluate allocation drift against multiple target_pct/band "
+            "scenarios in one call. Each scenario needs target_pct; optional "
+            "name and band (default 0.15)."
+        ),
+    )
+    def check_allocation_bands(
+        allocation_pct: dict[str, float],
+        scenarios: list[dict[str, Any]],
+    ) -> dict[str, Any]:
+        return handlers.check_allocation_bands(allocation_pct, scenarios)
+
+    schema_path = (
+        __import__("pathlib").Path(__file__).resolve().parent.parent.parent
+        / "schemas"
+        / "context-bundle.v1.json"
+    )
+
+    @mcp.resource("context-bundle://schema/v1")
+    def context_bundle_schema() -> str:
+        """ContextBundle JSON Schema for agent validation."""
+        return schema_path.read_text(encoding="utf-8")
+
+    @mcp.resource("alloc-context://tools/rebalance-hints")
+    def rebalance_hint_guide() -> str:
+        """Meaning of portfolio rebalance_hint codes."""
+        return (
+            "rebalance_hint codes: within_band — drift inside band; "
+            "consider_deploy_cash — cash above target; "
+            "consider_trim_to_cash — cash below target; "
+            "consider_rebalance — drift exceeds band."
+        )
+
+    return mcp
+
+
+def run_stdio(*, config_path: str | None = None) -> None:
+    mcp = create_server(config_path=config_path)
+    mcp.run(transport="stdio")
+
+
+def main() -> None:
+    run_stdio()
+
+
+if __name__ == "__main__":
+    main()

alloccontext/mcp/staleness.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+from alloccontext.timeutil import utc_now
+
+
+def parse_as_of(value: str) -> datetime:
+    dt = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if dt.tzinfo is None:
+        dt = dt.replace(tzinfo=timezone.utc)
+    return dt
+
+
+def age_seconds(as_of: datetime, *, now: datetime | None = None) -> int:
+    ref = now or utc_now()
+    if as_of.tzinfo is None:
+        as_of = as_of.replace(tzinfo=timezone.utc)
+    return max(0, int((ref - as_of).total_seconds()))
+
+
+def with_staleness(payload: dict[str, Any], *, as_of: datetime) -> dict[str, Any]:
+    if as_of.tzinfo is None:
+        as_of = as_of.replace(tzinfo=timezone.utc)
+    return {
+        "as_of": as_of.replace(microsecond=0).isoformat(),
+        "age_seconds": age_seconds(as_of),
+        **payload,
+    }

alloccontext/mcp/validation.py

@@ -0,0 +1,56 @@
+"""Input validation for MCP financial tools."""
+
+from __future__ import annotations
+
+from typing import Any
+
+_ASSETS = ("BTC", "ETH", "CASH")
+_PCT_SUM_TOLERANCE = 0.02
+
+
+class McpValidationError(ValueError):
+    """Raised when MCP tool inputs fail validation."""
+
+
+def validate_target_pct(values: dict[str, Any]) -> dict[str, float]:
+    if not isinstance(values, dict):
+        raise McpValidationError("target_pct must be an object")
+    normalized: dict[str, float] = {}
+    for asset in _ASSETS:
+        raw = values.get(asset)
+        if raw is None:
+            normalized[asset] = 0.0
+            continue
+        try:
+            pct = float(raw)
+        except (TypeError, ValueError) as exc:
+            raise McpValidationError(f"target_pct.{asset} must be a number") from exc
+        if pct < 0 or pct > 1:
+            raise McpValidationError(f"target_pct.{asset} must be between 0 and 1")
+        normalized[asset] = pct
+    total = sum(normalized.values())
+    if abs(total - 1.0) > _PCT_SUM_TOLERANCE:
+        raise McpValidationError(
+            f"target_pct must sum to approximately 1 (got {total:.4f})"
+        )
+    return normalized
+
+
+def validate_band(band: Any) -> float:
+    try:
+        value = float(band)
+    except (TypeError, ValueError) as exc:
+        raise McpValidationError("band must be a number") from exc
+    if not 0 < value < 1:
+        raise McpValidationError("band must be between 0 and 1 exclusive")
+    return value
+
+
+def validate_nav_usd(nav_usd: Any) -> float:
+    try:
+        value = float(nav_usd)
+    except (TypeError, ValueError) as exc:
+        raise McpValidationError("nav_usd must be a number") from exc
+    if value <= 0:
+        raise McpValidationError("nav_usd must be positive")
+    return value

alloccontext/mcp/x402_bazaar_dynamic.py

@@ -0,0 +1,104 @@
+"""Dynamic Bazaar metadata for MCP tools/call on POST /mcp."""
+
+from __future__ import annotations
+
+import dataclasses
+from contextvars import ContextVar, Token
+from typing import Any
+
+from alloccontext.mcp.bazaar import (
+    BAZAAR_INDEX_TAGS,
+    BAZAAR_SERVICE_NAME,
+    LISTING_DESCRIPTION,
+    build_http_route_extensions,
+    build_mcp_tool_extensions,
+    mcp_tool_specs,
+)
+from alloccontext.mcp.x402_pricing import read_mcp_request_json
+from x402.http.types import HTTPRequestContext, RouteConfig
+from x402.http.x402_http_server import x402HTTPResourceServer
+
+_mcp_tool_ctx: ContextVar[str | None] = ContextVar("alloc_mcp_bazaar_tool", default=None)
+_TOOL_EXTENSIONS = build_mcp_tool_extensions()
+_TOOL_DESCRIPTIONS = {spec["tool_name"]: spec["description"] for spec in mcp_tool_specs()}
+_RESOURCE_INFO_PATCHED = False
+
+
+@dataclasses.dataclass(frozen=True)
+class BazaarIndexResourceInfo:
+    service_name: str
+    tags: tuple[str, ...]
+
+
+def bazaar_index_resource_info() -> BazaarIndexResourceInfo:
+    return BazaarIndexResourceInfo(
+        service_name=BAZAAR_SERVICE_NAME,
+        tags=BAZAAR_INDEX_TAGS,
+    )
+
+
+def mcp_tool_name_from_body(body: dict[str, Any] | None) -> str | None:
+    if not body or body.get("method") != "tools/call":
+        return None
+    params = body.get("params")
+    if not isinstance(params, dict):
+        return None
+    name = params.get("name")
+    return name if isinstance(name, str) and name in _TOOL_EXTENSIONS else None
+
+
+def patch_resource_info_for_bazaar() -> None:
+    """Attach CDP service_name/tags to x402 ResourceInfo when unset."""
+    global _RESOURCE_INFO_PATCHED
+    if _RESOURCE_INFO_PATCHED:
+        return
+    from x402.schemas.payments import ResourceInfo
+
+    original_init = ResourceInfo.__init__
+
+    def _init_with_bazaar_metadata(self, *args: Any, **kwargs: Any) -> None:
+        meta = bazaar_index_resource_info()
+        kwargs.setdefault("service_name", meta.service_name)
+        kwargs.setdefault("tags", list(meta.tags))
+        original_init(self, *args, **kwargs)
+
+    ResourceInfo.__init__ = _init_with_bazaar_metadata  # type: ignore[method-assign]
+    _RESOURCE_INFO_PATCHED = True
+
+
+class AllocContextHTTPResourceServer(x402HTTPResourceServer):
+    """Select per-tool Bazaar extensions from tools/call JSON body."""
+
+    async def process_http_request(self, context, paywall_config=None):  # type: ignore[no-untyped-def]
+        token: Token[str | None] | None = None
+        if context.method == "POST" and context.path.rstrip("/").endswith("/mcp"):
+            body = await read_mcp_request_json(context)
+            tool_name = mcp_tool_name_from_body(body)
+            if tool_name:
+                token = _mcp_tool_ctx.set(tool_name)
+        try:
+            return await super().process_http_request(context, paywall_config)
+        finally:
+            if token is not None:
+                _mcp_tool_ctx.reset(token)
+
+    def _get_route_config(self, path: str, method: str):  # type: ignore[no-untyped-def]
+        match = super()._get_route_config(path, method)
+        if match is None:
+            return match
+        route_config, pattern = match
+        tool_name = _mcp_tool_ctx.get()
+        if not tool_name:
+            return match
+        tool_extension = _TOOL_EXTENSIONS.get(tool_name)
+        if tool_extension is None:
+            return match
+        description = _TOOL_DESCRIPTIONS.get(tool_name, route_config.description)
+        return (
+            dataclasses.replace(
+                route_config,
+                extensions=tool_extension,
+                description=description or LISTING_DESCRIPTION,
+            ),
+            pattern,
+        )

alloccontext/mcp/x402_config.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+from alloccontext.mcp.bazaar import (
+    LISTING_DESCRIPTION,
+    build_http_route_extensions,
+    public_mcp_url,
+    resolve_public_base_url,
+)
+from alloccontext.mcp.x402_pricing import DEFAULT_MCP_PRICE_HEAVY
+from alloccontext.mcp.x402_stables import (
+    build_payment_options_for_stables,
+    effective_accepted_stable_symbols,
+    load_accepted_stable_symbols,
+)
+from x402.extensions.bazaar import bazaar_resource_server_extension
+from x402.http import FacilitatorConfig, HTTPFacilitatorClient
+from x402.http.constants import DEFAULT_FACILITATOR_URL
+from x402.http.types import RouteConfig
+from x402.server import x402ResourceServer
+
+CDP_FACILITATOR_URL = "https://api.cdp.coinbase.com/platform/v2/x402"
+DEFAULT_NETWORK = "eip155:84532"  # Base Sepolia
+DEFAULT_MCP_PRICE = "$0.02"
+MCP_HTTP_PATH = "/mcp"
+
+
+@dataclass(frozen=True)
+class X402Settings:
+    enabled: bool
+    pay_to: str
+    facilitator_url: str
+    network: str
+    mcp_price: str
+    mcp_price_heavy: str = DEFAULT_MCP_PRICE_HEAVY
+    mcp_path: str = MCP_HTTP_PATH
+    accepted_stables: tuple[str, ...] = ()
+
+
+def load_x402_settings(*, require_payment: bool = False) -> X402Settings:
+    pay_to = os.environ.get("X402_PAY_TO", "").strip()
+    if require_payment and not pay_to:
+        raise RuntimeError("X402_PAY_TO is required when x402 is enabled")
+
+    facilitator_url = os.environ.get("X402_FACILITATOR_URL", DEFAULT_FACILITATOR_URL).strip()
+    network = os.environ.get("X402_NETWORK", DEFAULT_NETWORK).strip()
+    mcp_price = os.environ.get("X402_PRICE_MCP", DEFAULT_MCP_PRICE).strip()
+    mcp_price_heavy = os.environ.get(
+        "X402_PRICE_MCP_HEAVY", DEFAULT_MCP_PRICE_HEAVY
+    ).strip()
+    mcp_path = os.environ.get("X402_MCP_PATH", MCP_HTTP_PATH).strip() or MCP_HTTP_PATH
+    if mcp_path != MCP_HTTP_PATH:
+        raise RuntimeError(
+            f"X402_MCP_PATH must be {MCP_HTTP_PATH!r} (got {mcp_path!r}); "
+            "custom paths are unsupported until the MCP HTTP mount is configurable"
+        )
+    enabled = require_payment and bool(pay_to)
+
+    return X402Settings(
+        enabled=enabled,
+        pay_to=pay_to,
+        facilitator_url=facilitator_url,
+        network=network,
+        mcp_price=mcp_price,
+        mcp_price_heavy=mcp_price_heavy,
+        mcp_path=mcp_path,
+        accepted_stables=load_accepted_stable_symbols(),
+    )
+
+
+def _is_cdp_facilitator_url(url: str) -> bool:
+    return url.rstrip("/").startswith(CDP_FACILITATOR_URL.rstrip("/"))
+
+
+def build_x402_facilitator_client(settings: X402Settings) -> HTTPFacilitatorClient:
+    if _is_cdp_facilitator_url(settings.facilitator_url):
+        try:
+            from cdp.x402 import create_facilitator_config
+        except ImportError as exc:
+            raise RuntimeError(
+                "CDP facilitator requires cdp-sdk (pip install 'alloc-context[hosted]')"
+            ) from exc
+        if not cdp_facilitator_configured():
+            raise RuntimeError(
+                "CDP facilitator requires CDP_API_KEY_ID and CDP_API_KEY_SECRET"
+            )
+        return HTTPFacilitatorClient(create_facilitator_config())
+
+    return HTTPFacilitatorClient(FacilitatorConfig(url=settings.facilitator_url))
+
+
+def build_x402_resource_server(settings: X402Settings) -> x402ResourceServer:
+    from x402.mechanisms.evm.exact import ExactEvmServerScheme
+
+    facilitator = build_x402_facilitator_client(settings)
+    server = x402ResourceServer(facilitator)
+    server.register(settings.network, ExactEvmServerScheme())
+    server.register_extension(bazaar_resource_server_extension)
+    return server
+
+
+def _route_resource_url(settings: X402Settings) -> str | None:
+    public_base = resolve_public_base_url()
+    if not public_base:
+        return None
+    return public_mcp_url(base_url=public_base, mcp_path=settings.mcp_path)
+
+
+def build_x402_routes(settings: X402Settings) -> dict[str, RouteConfig]:
+    accepts = build_payment_options_for_stables(
+        pay_to=settings.pay_to,
+        network=settings.network,
+        light_price=settings.mcp_price,
+        heavy_price=settings.mcp_price_heavy,
+        symbols=effective_accepted_stable_symbols(settings.accepted_stables),
+    )
+    return {
+        f"POST {settings.mcp_path}": RouteConfig(
+            accepts=accepts,
+            resource=_route_resource_url(settings),
+            mime_type="application/json",
+            description=LISTING_DESCRIPTION,
+            extensions=build_http_route_extensions(),
+        ),
+    }
+
+
+def cdp_facilitator_configured() -> bool:
+    return bool(os.environ.get("CDP_API_KEY_ID") and os.environ.get("CDP_API_KEY_SECRET"))

alloccontext/mcp/x402_pricing.py

@@ -0,0 +1,55 @@
+from __future__ import annotations
+
+from typing import Any
+
+from x402.http.types import HTTPRequestContext
+
+DEFAULT_MCP_PRICE_HEAVY = "$0.05"
+
+HEAVY_MCP_TOOLS = frozenset({"get_portfolio_state"})
+
+
+def mcp_call_is_heavy(body: dict[str, Any] | None) -> bool:
+    """Return True when an MCP tools/call warrants the heavy x402 price."""
+    if not body or body.get("method") != "tools/call":
+        return False
+
+    params = body.get("params")
+    if not isinstance(params, dict):
+        return False
+
+    tool_name = params.get("name")
+    if isinstance(tool_name, str) and tool_name in HEAVY_MCP_TOOLS:
+        return True
+
+    arguments = params.get("arguments")
+    if not isinstance(arguments, dict):
+        return False
+
+    freshness = arguments.get("freshness")
+    return isinstance(freshness, str) and freshness.strip().lower() == "live"
+
+
+async def read_mcp_request_json(context: HTTPRequestContext) -> dict[str, Any] | None:
+    request = getattr(context.adapter, "_request", None)
+    if request is None:
+        return None
+    try:
+        body = await request.json()
+    except Exception:
+        return None
+    return body if isinstance(body, dict) else None
+
+
+def build_mcp_dynamic_price(*, light_price: str, heavy_price: str):
+    """Build an async x402 DynamicPrice callback for POST /mcp."""
+
+    async def resolve_price(context: HTTPRequestContext) -> str:
+        body = await read_mcp_request_json(context)
+        if body is None:
+            return heavy_price
+        if mcp_call_is_heavy(body):
+            return heavy_price
+        return light_price
+
+    return resolve_price