giskard-search

Instructions

agent_id: your identity in Giskard Marks (optional). High karma = lower price.
Tiers: no mark=10 sats | karma 1-20=7 sats | 21-50=5 sats | 50+=3 sats.

Implementation Reference

• server.py:75-94 (handler)

  Main handler function for 'get_invoice' tool. Decorated with @mcp.tool(), it takes an optional agent_id, applies karma-based pricing discounts, creates a Lightning invoice via create_invoice(), and returns payment_request and payment_hash for the user to pay before searching.

  @mcp.tool()
  def get_invoice(agent_id: str = "") -> str:
      """Get a Lightning invoice to pay before searching.
  
      agent_id: your identity in Giskard Marks (optional). High karma = lower price.
      Tiers: no mark=10 sats | karma 1-20=7 sats | 21-50=5 sats | 50+=3 sats."""
      agent_id = sanitize_agent_id(agent_id)
      price, karma = karma_discount(agent_id, SEARCH_PRICE_SATS)
      invoice = create_invoice(price, "Giskard Search")
  
      discount_note = ""
      if agent_id and price < SEARCH_PRICE_SATS:
          discount_note = f"\nKarma discount applied ({karma} karma): {SEARCH_PRICE_SATS} → {price} sats."
  
      return (
          f"Pay {price} sats to search.{discount_note}\n\n"
          f"payment_request: {invoice['payment_request']}\n"
          f"payment_hash: {invoice['payment_hash']}\n\n"
          f"After paying, call search_web or search_news with the payment_hash."
      )

• server.py:75-75 (registration)

  Registration of the 'get_invoice' tool via the @mcp.tool() decorator from FastMCP framework. This registers the function as an MCP tool named 'get_invoice'.

  @mcp.tool()

• server.py:35-43 (helper)

  Helper function create_invoice() that makes HTTP POST request to phoenixd Lightning node to create an actual Lightning invoice with specified amount and description. Returns payment_request and payment_hash.

  def create_invoice(amount: int, description: str) -> dict:
      response = httpx.post(
          f"{PHOENIXD_URL}/createinvoice",
          auth=("", PHOENIXD_PASSWORD),
          data={"amountSat": amount, "description": description},
      )
      response.raise_for_status()
      data = response.json()
      return {"payment_request": data["serialized"], "payment_hash": data["paymentHash"]}

• karma_pricing.py:1-35 (helper)

  Helper module providing karma_discount() and sanitize_agent_id() functions. Applies tiered pricing based on agent karma scores: no mark=10 sats | karma 1-20=7 sats | 21-50=5 sats | 50+=3 sats.

  """
  Módulo compartido — karma-tiered pricing para Giskard MCP servers.
  
  Cadena: Marks (identidad) → Argentum (karma) → precio del servicio
  
  Uso:
      from karma_pricing import karma_discount
  
      price = karma_discount(agent_id, base_price=21)
  
  KNOWN GAP: agent_id es autodeclarado. Sin firma criptográfica todavía.
  Cualquier failure en Marks/Argentum retorna base_price sin romper el flujo.
  """
  import re
  import httpx
  
  ARGENTUM_URL = "http://localhost:8017"
  MARKS_URL    = "http://localhost:8015"
  
  # Descuentos: (karma_minimo, fraccion_del_precio_base)
  # Se aplica floor() para quedarse en sats enteros
  TIERS = [
      (50, 0.25),   # 75% off
      (21, 0.50),   # 50% off
      (1,  0.70),   # 30% off
      (0,  1.00),   # precio base
  ]
  
  
  def sanitize_agent_id(agent_id: str) -> str:
      return re.sub(r"[^a-zA-Z0-9\-_]", "", agent_id)[:64]
  
  
  def _verify_mark(agent_id: str) -> bool:
      try: