alloc-context 0.2.3__tar.gz → 0.2.4__tar.gz

{alloc_context-0.2.3 → alloc_context-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alloc-context
-Version: 0.2.3
+Version: 0.2.4
 Summary: Portfolio-aware crypto context for agents — holdings-scoped market, sentiment, optional allocation analysis
 License: Elastic-2.0
 Project-URL: Homepage, https://mcp.alloc-context.com/llms.txt
@@ -40,12 +40,12 @@ Requires-Dist: mcp>=1.6; extra == "dev"
 Requires-Dist: x402[evm,fastapi]>=2.0; extra == "dev"
 Requires-Dist: cdp-sdk>=1.46; extra == "dev"
 Requires-Dist: uvicorn[standard]>=0.30; extra == "dev"
+Requires-Dist: langchain-core>=0.3.0; extra == "dev"
 Dynamic: license-file
 
 # AllocContext
 
-[![smithery badge](https://smithery.ai/badge/@AllocContext/alloc-context)](https://smithery.ai/server/@AllocContext/alloc-context)
-[![Glama MCP server](https://glama.ai/mcp/servers/AllocContext/alloc-context/badges/score.svg)](https://glama.ai/mcp/servers/AllocContext/alloc-context)
+[![smithery badge](https://smithery.ai/badge/alloccontext/alloc-context)](https://smithery.ai/servers/alloccontext/alloc-context)
 
 mcp-name: io.github.AllocContext/alloc-context
 
@@ -54,6 +54,10 @@ holdings, holdings-scoped market data, sentiment, macro, and regime; optional
 allocation analysis when you supply targets. Deterministic JSON over MCP with
 x402 pay-per-call on Base.
 
+**New here?** [Agent on-ramp (~2 min)](docs/agent-onramp.md) — copy-paste path to
+your first ContextBundle. **Organization:**
+[AllocContext on GitHub](https://github.com/AllocContext) — overview and integration links.
+
 > **Privacy:** nothing stored · one-time read-only · pass-through only — your
 > keys and portfolio never persist on our servers. See [USE.md](docs/USE.md).
 
@@ -143,8 +147,10 @@ See [mcp.md](docs/mcp.md) for arguments, pricing, and resources.
 ## Self-host and development
 
 Run ingest and MCP entirely on your machine — no x402 upstream required.
-See [self-hosting.md](docs/self-hosting.md) (`self_host: true` in user config)
-or [local-dev.md](docs/local-dev.md) for the dev stack.
+See [self-hosting.md](docs/self-hosting.md) (`self_host: true` in user config),
+[local-dev.md](docs/local-dev.md) for the native dev stack (`./scripts/dev-up.sh`),
+or `./docker/up.sh` / [docker-self-host.md](docs/docker-self-host.md) for Docker
+on loopback `:8000`.
 
 ```bash
 git clone git@github.com:AllocContext/alloc-context.git
@@ -173,6 +179,10 @@ HTTP MCP + x402: [mcp-http.md](docs/mcp-http.md). CLI entry point:
 
 | Document | Purpose |
 |----------|---------|
+| [docs/agent-onramp.md](docs/agent-onramp.md) | **Start here** — ~2 min to first ContextBundle |
+| [docs/deterministic-context-mcp-pattern.md](docs/deterministic-context-mcp-pattern.md) | Reusable ingest → rollup → MCP → x402 pattern |
+| [docs/langchain-integration.md](docs/langchain-integration.md) | LangChain tools for hosted MCP (x402) |
+| [docs/docker-self-host.md](docs/docker-self-host.md) | Docker Compose self-host evaluation |
 | [docs/cursor-mcp.md](docs/cursor-mcp.md) | Cursor stdio MCP (bridge default) |
 | [docs/user-config.md](docs/user-config.md) | Bridge `user.yaml` reference |
 | [docs/mcp.md](docs/mcp.md) | MCP tools and x402 |

{alloc_context-0.2.3 → alloc_context-0.2.4}/README.md

@@ -1,7 +1,6 @@
 # AllocContext
 
-[![smithery badge](https://smithery.ai/badge/@AllocContext/alloc-context)](https://smithery.ai/server/@AllocContext/alloc-context)
-[![Glama MCP server](https://glama.ai/mcp/servers/AllocContext/alloc-context/badges/score.svg)](https://glama.ai/mcp/servers/AllocContext/alloc-context)
+[![smithery badge](https://smithery.ai/badge/alloccontext/alloc-context)](https://smithery.ai/servers/alloccontext/alloc-context)
 
 mcp-name: io.github.AllocContext/alloc-context
 
@@ -10,6 +9,10 @@ holdings, holdings-scoped market data, sentiment, macro, and regime; optional
 allocation analysis when you supply targets. Deterministic JSON over MCP with
 x402 pay-per-call on Base.
 
+**New here?** [Agent on-ramp (~2 min)](docs/agent-onramp.md) — copy-paste path to
+your first ContextBundle. **Organization:**
+[AllocContext on GitHub](https://github.com/AllocContext) — overview and integration links.
+
 > **Privacy:** nothing stored · one-time read-only · pass-through only — your
 > keys and portfolio never persist on our servers. See [USE.md](docs/USE.md).
 
@@ -99,8 +102,10 @@ See [mcp.md](docs/mcp.md) for arguments, pricing, and resources.
 ## Self-host and development
 
 Run ingest and MCP entirely on your machine — no x402 upstream required.
-See [self-hosting.md](docs/self-hosting.md) (`self_host: true` in user config)
-or [local-dev.md](docs/local-dev.md) for the dev stack.
+See [self-hosting.md](docs/self-hosting.md) (`self_host: true` in user config),
+[local-dev.md](docs/local-dev.md) for the native dev stack (`./scripts/dev-up.sh`),
+or `./docker/up.sh` / [docker-self-host.md](docs/docker-self-host.md) for Docker
+on loopback `:8000`.
 
 ```bash
 git clone git@github.com:AllocContext/alloc-context.git
@@ -129,6 +134,10 @@ HTTP MCP + x402: [mcp-http.md](docs/mcp-http.md). CLI entry point:
 
 | Document | Purpose |
 |----------|---------|
+| [docs/agent-onramp.md](docs/agent-onramp.md) | **Start here** — ~2 min to first ContextBundle |
+| [docs/deterministic-context-mcp-pattern.md](docs/deterministic-context-mcp-pattern.md) | Reusable ingest → rollup → MCP → x402 pattern |
+| [docs/langchain-integration.md](docs/langchain-integration.md) | LangChain tools for hosted MCP (x402) |
+| [docs/docker-self-host.md](docs/docker-self-host.md) | Docker Compose self-host evaluation |
 | [docs/cursor-mcp.md](docs/cursor-mcp.md) | Cursor stdio MCP (bridge default) |
 | [docs/user-config.md](docs/user-config.md) | Bridge `user.yaml` reference |
 | [docs/mcp.md](docs/mcp.md) | MCP tools and x402 |

{alloc_context-0.2.3 → alloc_context-0.2.4}/alloc_context.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: alloc-context
-Version: 0.2.3
+Version: 0.2.4
 Summary: Portfolio-aware crypto context for agents — holdings-scoped market, sentiment, optional allocation analysis
 License: Elastic-2.0
 Project-URL: Homepage, https://mcp.alloc-context.com/llms.txt
@@ -40,12 +40,12 @@ Requires-Dist: mcp>=1.6; extra == "dev"
 Requires-Dist: x402[evm,fastapi]>=2.0; extra == "dev"
 Requires-Dist: cdp-sdk>=1.46; extra == "dev"
 Requires-Dist: uvicorn[standard]>=0.30; extra == "dev"
+Requires-Dist: langchain-core>=0.3.0; extra == "dev"
 Dynamic: license-file
 
 # AllocContext
 
-[![smithery badge](https://smithery.ai/badge/@AllocContext/alloc-context)](https://smithery.ai/server/@AllocContext/alloc-context)
-[![Glama MCP server](https://glama.ai/mcp/servers/AllocContext/alloc-context/badges/score.svg)](https://glama.ai/mcp/servers/AllocContext/alloc-context)
+[![smithery badge](https://smithery.ai/badge/alloccontext/alloc-context)](https://smithery.ai/servers/alloccontext/alloc-context)
 
 mcp-name: io.github.AllocContext/alloc-context
 
@@ -54,6 +54,10 @@ holdings, holdings-scoped market data, sentiment, macro, and regime; optional
 allocation analysis when you supply targets. Deterministic JSON over MCP with
 x402 pay-per-call on Base.
 
+**New here?** [Agent on-ramp (~2 min)](docs/agent-onramp.md) — copy-paste path to
+your first ContextBundle. **Organization:**
+[AllocContext on GitHub](https://github.com/AllocContext) — overview and integration links.
+
 > **Privacy:** nothing stored · one-time read-only · pass-through only — your
 > keys and portfolio never persist on our servers. See [USE.md](docs/USE.md).
 
@@ -143,8 +147,10 @@ See [mcp.md](docs/mcp.md) for arguments, pricing, and resources.
 ## Self-host and development
 
 Run ingest and MCP entirely on your machine — no x402 upstream required.
-See [self-hosting.md](docs/self-hosting.md) (`self_host: true` in user config)
-or [local-dev.md](docs/local-dev.md) for the dev stack.
+See [self-hosting.md](docs/self-hosting.md) (`self_host: true` in user config),
+[local-dev.md](docs/local-dev.md) for the native dev stack (`./scripts/dev-up.sh`),
+or `./docker/up.sh` / [docker-self-host.md](docs/docker-self-host.md) for Docker
+on loopback `:8000`.
 
 ```bash
 git clone git@github.com:AllocContext/alloc-context.git
@@ -173,6 +179,10 @@ HTTP MCP + x402: [mcp-http.md](docs/mcp-http.md). CLI entry point:
 
 | Document | Purpose |
 |----------|---------|
+| [docs/agent-onramp.md](docs/agent-onramp.md) | **Start here** — ~2 min to first ContextBundle |
+| [docs/deterministic-context-mcp-pattern.md](docs/deterministic-context-mcp-pattern.md) | Reusable ingest → rollup → MCP → x402 pattern |
+| [docs/langchain-integration.md](docs/langchain-integration.md) | LangChain tools for hosted MCP (x402) |
+| [docs/docker-self-host.md](docs/docker-self-host.md) | Docker Compose self-host evaluation |
 | [docs/cursor-mcp.md](docs/cursor-mcp.md) | Cursor stdio MCP (bridge default) |
 | [docs/user-config.md](docs/user-config.md) | Bridge `user.yaml` reference |
 | [docs/mcp.md](docs/mcp.md) | MCP tools and x402 |

{alloc_context-0.2.3 → alloc_context-0.2.4}/alloc_context.egg-info/SOURCES.txt

@@ -56,6 +56,8 @@ alloccontext/ingest/exchange/live.py
 alloccontext/ingest/exchange/portfolio.py
 alloccontext/ingest/exchange/registry.py
 alloccontext/ingest/exchange/types.py
+alloccontext/integrations/__init__.py
+alloccontext/integrations/langchain.py
 alloccontext/mcp/__init__.py
 alloccontext/mcp/assets.py
 alloccontext/mcp/bazaar.py
@@ -130,6 +132,7 @@ tests/test_ingest_runner.py
 tests/test_ingest_store_integration.py
 tests/test_kalshi_api.py
 tests/test_kraken_portfolio.py
+tests/test_langchain_integration.py
 tests/test_live_ingest_handlers.py
 tests/test_macro.py
 tests/test_market_breadth.py

{alloc_context-0.2.3 → alloc_context-0.2.4}/alloc_context.egg-info/requires.txt

@@ -12,6 +12,7 @@ mcp>=1.6
 x402[evm,fastapi]>=2.0
 cdp-sdk>=1.46
 uvicorn[standard]>=0.30
+langchain-core>=0.3.0
 
 [hosted]
 mcp>=1.6

{alloc_context-0.2.3 → alloc_context-0.2.4}/alloccontext/__init__.py

@@ -1,3 +1,3 @@
 """AllocContext — portfolio-aware crypto context for agents (MCP)."""
 
-__version__ = "0.2.3"
+__version__ = "0.2.4"

alloc_context-0.2.4/alloccontext/integrations/__init__.py

@@ -0,0 +1 @@
+"""Optional framework integrations (LangChain, etc.)."""

alloc_context-0.2.4/alloccontext/integrations/langchain.py

@@ -0,0 +1,125 @@
+"""LangChain tools for the hosted AllocContext MCP (x402 on Base)."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import replace
+from typing import Any
+
+from alloccontext.mcp.bazaar import OFFICIAL_HOSTED_MCP_URL, mcp_tool_specs
+from alloccontext.mcp.upstream import call_upstream_tool
+from alloccontext.user_config import (
+    DEFAULT_UPSTREAM_URL,
+    UserConfig,
+    load_user_config,
+    resolve_user_config_path,
+)
+
+DEFAULT_HOSTED_TOOLS = (
+    "get_market_context",
+    "get_context_bundle",
+    "get_rebalance_plan",
+    "check_allocation_band",
+)
+
+
+def hosted_user_config(*, upstream_url: str | None = None) -> UserConfig:
+    """Minimal bridge user config for hosted-only LangChain calls."""
+    base = UserConfig.empty()
+    return replace(
+        base,
+        upstream=upstream_url or DEFAULT_UPSTREAM_URL,
+        self_host=False,
+    )
+
+
+def resolve_hosted_user_config(*, upstream_url: str | None = None) -> UserConfig:
+    """Hosted bridge config: ``user.yaml`` when present, else env-only defaults.
+
+    Loads ``~/.config/alloc-context/user.yaml`` (or ``ALLOC_CONTEXT_USER_CONFIG``)
+    so ``x402.payer_private_key_file`` and inline payer keys work like the stdio
+    bridge. Exchange blocks in ``user.yaml`` are ignored for hosted tool calls.
+    """
+    path = resolve_user_config_path()
+    if path is None or not path.is_file():
+        return hosted_user_config(upstream_url=upstream_url)
+
+    loaded = load_user_config(path)
+    upstream = upstream_url or loaded.upstream
+    if loaded.self_host:
+        return replace(
+            hosted_user_config(upstream_url=upstream),
+            x402=loaded.x402,
+            path=loaded.path,
+        )
+    return replace(loaded, upstream=upstream, self_host=False)
+
+
+def _args_model(tool_name: str, input_schema: dict[str, Any]) -> type[Any]:
+    from pydantic import Field, create_model
+
+    properties = input_schema.get("properties") or {}
+    required = frozenset(input_schema.get("required") or [])
+    field_defs: dict[str, Any] = {}
+    for key, prop in properties.items():
+        description = str(prop.get("description") or "")
+        if key in required:
+            field_defs[key] = (Any, Field(description=description))
+        else:
+            field_defs[key] = (Any | None, Field(default=None, description=description))
+    model_name = "".join(part.title() for part in tool_name.split("_")) + "Input"
+    return create_model(model_name, **field_defs)
+
+
+def build_hosted_langchain_tools(
+    user: UserConfig | None = None,
+    *,
+    tool_names: tuple[str, ...] | None = None,
+) -> list[Any]:
+    """Return LangChain tools that call the hosted MCP with x402 payment.
+
+    Requires ``langchain-core`` and ``alloc-context[hosted]``. Configure an x402
+    payer via ``EVM_PRIVATE_KEY``, ``user.yaml`` (``x402.payer_private_key_file``),
+    or pass a ``UserConfig`` explicitly.
+    """
+    try:
+        from langchain_core.tools import StructuredTool
+    except ImportError as exc:
+        raise ImportError(
+            "LangChain integration requires langchain-core: pip install langchain-core"
+        ) from exc
+
+    user = user or resolve_hosted_user_config()
+    selected = frozenset(tool_names or DEFAULT_HOSTED_TOOLS)
+    specs = {spec["tool_name"]: spec for spec in mcp_tool_specs()}
+    missing = selected - specs.keys()
+    if missing:
+        raise ValueError(f"Unknown MCP tool(s): {', '.join(sorted(missing))}")
+
+    tools: list[Any] = []
+    for name in tool_names or DEFAULT_HOSTED_TOOLS:
+        spec = specs[name]
+
+        def _invoke(*, _tool_name: str = name, **kwargs: Any) -> str:
+            arguments = {key: value for key, value in kwargs.items() if value is not None}
+            payload = call_upstream_tool(user, _tool_name, arguments)
+            if payload.get("reason") == "upstream_payment_required":
+                message = payload.get("message") or (
+                    "Configure an x402 payer wallet to call hosted upstream."
+                )
+                raise RuntimeError(message)
+            return json.dumps(payload, separators=(",", ":"))
+
+        tools.append(
+            StructuredTool(
+                name=name,
+                description=spec["description"],
+                func=_invoke,
+                args_schema=_args_model(name, spec["input_schema"]),
+            )
+        )
+    return tools
+
+
+def official_hosted_mcp_url() -> str:
+    return OFFICIAL_HOSTED_MCP_URL

alloc_context-0.2.4/alloccontext/mcp/bazaar.py

@@ -0,0 +1,338 @@
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from x402.extensions.bazaar import (
+    DeclareMcpDiscoveryConfig,
+    OutputConfig,
+    declare_discovery_extension,
+    declare_mcp_discovery_extension,
+)
+
+from alloccontext.mcp.tool_catalog import (
+    MCP_SERVER_PROMPTS,
+    MCP_SERVER_RESOURCES,
+    MCP_TOOL_NAMES,
+    MCP_TOOL_SPECS,
+    mcp_tool_specs,
+    server_card_tool_entry,
+)
+
+SERVICE_NAME = "AllocContext"
+OFFICIAL_HOSTED_MCP_URL = "https://mcp.alloc-context.com/mcp"
+USE_DOCS_PATH = "docs/USE.md"
+
+PRIVACY_COMPACT_COPY = (
+    "Privacy: nothing stored. One-time read-only fetch. Pass-through only — "
+    "your keys and portfolio never persist on our servers."
+)
+
+PRIVACY_PILLAR_MARKERS = (
+    "nothing stored",
+    "one-time read-only",
+    "pass-through only",
+)
+
+LICENSE_DISCOVERY_LINE = (
+    "Source-available (Elastic License 2.0). Self-host friendly. Official hosted "
+    f"MCP only at {OFFICIAL_HOSTED_MCP_URL} — see {USE_DOCS_PATH}."
+)
+
+LICENSE_MARKERS = (
+    "elastic license",
+    "self-host",
+    USE_DOCS_PATH.lower(),
+    OFFICIAL_HOSTED_MCP_URL.lower(),
+)
+
+SERVICE_TITLE = (
+    "AllocContext — portfolio-aware crypto context for agents (MCP + x402)"
+)
+# CDP Bazaar indexes service_name (≤32 chars) and up to five tags from payments.
+BAZAAR_SERVICE_NAME = "AllocContext portfolio MCP"
+SERVICE_TAGS = (
+    "crypto",
+    "cryptocurrency",
+    "bitcoin",
+    "btc",
+    "ethereum",
+    "eth",
+    "holdings",
+    "portfolio",
+    "allocation",
+    "rebalance",
+    "sentiment",
+    "macro",
+    "coinbase",
+    "kraken",
+    "agent-tools",
+    "mcp",
+    "x402",
+)
+BAZAAR_INDEX_TAGS = (
+    "crypto",
+    "cryptocurrency",
+    "portfolio",
+    "holdings",
+    "btc",
+)
+
+DISCOVERY_KEYWORD_MARKERS = (
+    "crypto",
+    "cryptocurrency",
+    "digital assets",
+    "crypto portfolio",
+    "portfolio allocation",
+    "portfolio context",
+    "allocation drift",
+    "rebalance plan",
+    "fear and greed",
+    "etf flows",
+    "holdings",
+    "holdings-scoped",
+    "coinbase",
+    "kraken",
+    "market context",
+    "sentiment",
+)
+
+LISTING_DESCRIPTION = (
+    "Portfolio-aware crypto context for AI agents: discover holdings and "
+    "holdings-scoped market, sentiment, macro, and regime; optional allocation "
+    "analysis and rebalance math. Fused backdrop (Fear & Greed, Kalshi, ETF "
+    "flows), optional live portfolio reads (e.g. Coinbase, Kraken). Structured "
+    "JSON only — no LLM. "
+    f"{PRIVACY_COMPACT_COPY} "
+    "Source-available (Elastic License 2.0); self-host friendly; official hosted "
+    f"MCP at {OFFICIAL_HOSTED_MCP_URL} — see {USE_DOCS_PATH}."
+)
+
+def smoke_tool_arguments(tool_name: str) -> dict[str, Any]:
+    """Example args for paid smoke / re-index scripts (hosted-safe defaults)."""
+    from datetime import datetime, timedelta, timezone
+
+    for spec in MCP_TOOL_SPECS:
+        if spec["tool_name"] != tool_name:
+            continue
+        args = dict(spec["example"])
+        now = datetime.now(timezone.utc)
+        if tool_name == "get_context_at":
+            args["as_of"] = now.strftime("%Y-%m-%dT%H:%M:%S+00:00")
+            args["match"] = "at_or_before"
+            args.setdefault("scope", "daily")
+        elif tool_name == "get_context_delta":
+            # Hosted ingest keeps recent hourly snapshots; 2h back finds a prior point.
+            prior = now - timedelta(hours=2)
+            args["prior_as_of"] = prior.strftime("%Y-%m-%dT%H:%M:%S+00:00")
+            args.setdefault("scope", "daily")
+        return args
+    raise KeyError(f"unknown MCP tool: {tool_name}")
+
+
+def public_mcp_url(*, base_url: str, mcp_path: str) -> str:
+    return f"{base_url.rstrip('/')}{mcp_path}"
+
+
+def resolve_public_base_url() -> str | None:
+    for key in ("X402_PUBLIC_URL", "ALLOC_CONTEXT_MCP_PUBLIC_URL"):
+        value = os.environ.get(key, "").strip()
+        if value:
+            return value.rstrip("/")
+    return None
+
+
+def build_mcp_tool_extensions() -> dict[str, dict[str, Any]]:
+    """Per-tool Bazaar MCP extensions keyed by tool name."""
+    extensions: dict[str, dict[str, Any]] = {}
+    for spec in MCP_TOOL_SPECS:
+        extensions[spec["tool_name"]] = declare_mcp_discovery_extension(
+            DeclareMcpDiscoveryConfig(
+                tool_name=spec["tool_name"],
+                description=spec["description"],
+                transport="streamable-http",
+                input_schema=spec["input_schema"],
+                example=spec["example"],
+                output=OutputConfig(example=spec["output_example"]),
+            )
+        )
+    return extensions
+
+
+def build_http_route_extensions() -> dict[str, Any]:
+    """Bazaar extension for the paid POST /mcp streamable HTTP endpoint."""
+    primary = MCP_TOOL_SPECS[0]
+    return declare_discovery_extension(
+        input={
+            "jsonrpc": "2.0",
+            "method": "tools/call",
+            "params": {
+                "name": primary["tool_name"],
+                "arguments": primary["example"],
+            },
+            "id": 1,
+        },
+        input_schema={
+            "type": "object",
+            "properties": {
+                "jsonrpc": {"type": "string", "const": "2.0"},
+                "method": {
+                    "type": "string",
+                    "description": "MCP JSON-RPC method (e.g. tools/call).",
+                },
+                "params": {
+                    "type": "object",
+                    "properties": {
+                        "name": {
+                            "type": "string",
+                            "enum": list(MCP_TOOL_NAMES),
+                            "description": (
+                                "AllocContext tool: get_market_context, "
+                                "get_context_bundle, get_rebalance_plan, "
+                                "get_portfolio_state, check_allocation_band, "
+                                "get_context_at, get_context_delta, or "
+                                "check_allocation_bands."
+                            ),
+                        },
+                        "arguments": {
+                            "type": "object",
+                            "description": "Tool-specific arguments object.",
+                        },
+                    },
+                    "required": ["name"],
+                },
+                "id": {"type": ["integer", "string"]},
+            },
+            "required": ["jsonrpc", "method", "params"],
+        },
+        body_type="json",
+        output=OutputConfig(
+            example={
+                "jsonrpc": "2.0",
+                "id": 1,
+                "result": primary["output_example"],
+            }
+        ),
+    )
+
+
+def build_llms_txt(
+    *,
+    public_url: str,
+    mcp_path: str,
+    accepted_stables: tuple[str, ...] = ("USDC", "EURC"),
+) -> str:
+    endpoint = public_mcp_url(base_url=public_url, mcp_path=mcp_path)
+    tool_lines = "\n".join(
+        f"- `{spec['tool_name']}` — {spec['description']}" for spec in MCP_TOOL_SPECS
+    )
+    return f"""# {SERVICE_TITLE}
+
+{LISTING_DESCRIPTION}
+
+## Privacy
+
+Nothing stored. One-time read-only fetch. Pass-through only — your keys and
+portfolio never persist on our servers.
+
+## License
+
+{LICENSE_DISCOVERY_LINE}
+
+## Paid MCP (x402, Base stablecoins)
+
+- Endpoint: `{endpoint}`
+- Transport: streamable HTTP (`POST {mcp_path}`)
+- Health: `{public_url.rstrip('/')}/health` (free)
+- Payment: x402 exact scheme on Base; payer picks one of
+  **{", ".join(accepted_stables)}** (USD-pegged; bridge to Base first).
+- Pricing: **$0.02** cached context/math; **$0.05** live ingest or live portfolio.
+
+## Tools
+
+{tool_lines}
+
+## Search keywords
+
+bitcoin, ethereum, btc, eth, crypto, cryptocurrency, digital assets, altcoin,
+stablecoin, crypto portfolio, portfolio allocation, portfolio context, holdings,
+holdings-scoped, coinbase, kraken, market context, market data, sentiment,
+macro calendar, etf flows, allocation drift, allocation bands, rebalance plan,
+fear and greed, fear greed index, nav, agent tools, ai agents, mcp, x402,
+model context protocol, context bundle
+
+## Examples
+
+Redacted tool JSON samples (evaluate before paying):
+https://github.com/AllocContext/alloc-context/blob/main/docs/examples.md
+"""
+
+
+def build_well_known_x402(
+    *,
+    public_url: str,
+    mcp_path: str,
+    pay_to: str,
+    price_light: str = "$0.02",
+    price_heavy: str = "$0.05",
+    network: str = "eip155:84532",
+    accepted_stables: tuple[str, ...] = ("USDC", "EURC"),
+) -> dict[str, Any]:
+    endpoint = public_mcp_url(base_url=public_url, mcp_path=mcp_path)
+    return {
+        "name": SERVICE_NAME,
+        "title": SERVICE_TITLE,
+        "description": LISTING_DESCRIPTION,
+        "tags": list(SERVICE_TAGS),
+        "resources": [
+            {
+                "url": endpoint,
+                "type": "http",
+                "description": LISTING_DESCRIPTION,
+                "tools": [
+                    {
+                        "name": spec["tool_name"],
+                        "description": spec["description"],
+                        "inputSchema": spec["input_schema"],
+                    }
+                    for spec in MCP_TOOL_SPECS
+                ],
+            }
+        ],
+        "payment": {
+            "scheme": "exact",
+            "payTo": pay_to,
+            "pricing": {
+                "cached_context_and_math": price_light,
+                "live_ingest_or_portfolio": price_heavy,
+                "network": network,
+                "assets": list(accepted_stables),
+                "note": (
+                    "Payer chooses one listed stable on Base; amounts are "
+                    "USD-pegged per call tier."
+                ),
+            },
+        },
+    }
+
+
+def build_mcp_server_card(*, version: str) -> dict[str, Any]:
+    """Smithery static server card (SEP-1649) — free metadata when POST /mcp is x402."""
+    return {
+        "serverInfo": {
+            "name": SERVICE_TITLE,
+            "version": version,
+            "description": LISTING_DESCRIPTION,
+        },
+        "authentication": {
+            "required": True,
+            "schemes": ["x402"],
+            "description": (
+                "x402 exact payment on Base mainnet (USDC or EURC) per tool call; "
+                "see /.well-known/x402.json for pricing."
+            ),
+        },
+        "tools": [server_card_tool_entry(spec) for spec in MCP_TOOL_SPECS],
+        "resources": list(MCP_SERVER_RESOURCES),
+        "prompts": list(MCP_SERVER_PROMPTS),
+    }