DebtStack MCP Server

Instructions

Implementation Reference

• debtstack/mcp_server.py:521-545 (handler)

  MCP server handler for search_pricing tool - processes arguments, calls API with has_pricing=true, and formats bond pricing results with price, YTM, and spread information

  elif name == "search_pricing":
      params = {k: v for k, v in arguments.items() if v is not None}
      params.setdefault("limit", 10)
      params["has_pricing"] = True
      result = api_get("/bonds", params)
  
      bonds = result.get("data", [])
      if not bonds:
          return [TextContent(type="text", text="No pricing data found.")]
  
      text = f"Bond pricing ({len(bonds)} bonds):\n\n"
      for b in bonds:
          text += f"**{b.get('name', b.get('cusip', '?'))}**\n"
          if b.get('company_ticker'):
              text += f"Issuer: {b['company_ticker']}\n"
          pricing = b.get('pricing', {}) or {}
          if pricing.get('last_price'):
              text += f"Price: {pricing['last_price']:.2f}\n"
          if pricing.get('ytm'):
              text += f"YTM: {pricing['ytm']:.2f}%\n"
          if pricing.get('spread'):
              text += f"Spread: {pricing['spread']} bps\n"
          text += "\n"
  
      return [TextContent(type="text", text=text)]

• debtstack/client.py:448-507 (handler)

  Core async implementation of search_pricing - makes GET request to /bonds endpoint with has_pricing=true, supports filtering by ticker, cusip, min_ytm, max_ytm, min_spread, and custom fields/sort

  async def search_pricing(
      self,
      ticker: Optional[str] = None,
      cusip: Optional[str] = None,
      min_ytm: Optional[float] = None,
      max_ytm: Optional[float] = None,
      min_spread: Optional[int] = None,
      fields: Optional[str] = None,
      sort: str = "-pricing.ytm",
      limit: int = 50,
  ) -> Dict[str, Any]:
      """
      Search bond pricing from FINRA TRACE.
  
      Uses /bonds endpoint with has_pricing=true. Pricing is included
      inline with each bond result.
  
      Args:
          ticker: Company ticker(s)
          cusip: CUSIP(s)
          min_ytm: Minimum YTM (%)
          max_ytm: Maximum YTM (%)
          min_spread: Minimum spread (bps)
          fields: Comma-separated fields to return (pricing fields always included)
          sort: Sort field (default: -pricing.ytm for highest yield first)
          limit: Results per page
  
      Returns:
          Dictionary with bond data including inline pricing
  
      Example:
          # Get current pricing for RIG bonds
          result = await client.search_pricing(
              ticker="RIG",
              fields="name,cusip,pricing"
          )
      """
      params = {
          "has_pricing": True,
          "sort": sort,
          "limit": limit,
      }
  
      if ticker:
          params["ticker"] = ticker
      if cusip:
          params["cusip"] = cusip
      if min_ytm is not None:
          params["min_ytm"] = min_ytm
      if max_ytm is not None:
          params["max_ytm"] = max_ytm
      if min_spread is not None:
          params["min_spread"] = min_spread
      if fields:
          params["fields"] = fields
  
      client = await self._get_client()
      response = await client.get("/bonds", params=params)
      response.raise_for_status()
      return response.json()

• debtstack/mcp_server.py:332-361 (registration)

  MCP tool registration with name, description, and input schema defining optional ticker, cusip, min_ytm, and limit parameters

  Tool(
      name="search_pricing",
      description=(
          "Get bond pricing from FINRA TRACE. "
          "Returns current price, yield to maturity, and spread to treasury. "
          "Use to find distressed bonds or compare relative value."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "ticker": {
                  "type": "string",
                  "description": "Company ticker(s)"
              },
              "cusip": {
                  "type": "string",
                  "description": "Bond CUSIP(s)"
              },
              "min_ytm": {
                  "type": "number",
                  "description": "Minimum yield to maturity (%)"
              },
              "limit": {
                  "type": "integer",
                  "description": "Maximum results (default 10)"
              }
          },
          "required": []
      }
  ),

• debtstack/langchain.py:230-251 (schema)

  Pydantic BaseModel schema for LangChain tool input - SearchPricingInput with optional ticker, cusip, min_ytm, fields and default limit of 10

  class SearchPricingInput(BaseModel):
      """Input for pricing search tool."""
      ticker: Optional[str] = Field(
          None,
          description="Company ticker(s) to filter by"
      )
      cusip: Optional[str] = Field(
          None,
          description="CUSIP(s) to look up"
      )
      min_ytm: Optional[float] = Field(
          None,
          description="Minimum yield to maturity (%)"
      )
      fields: Optional[str] = Field(
          None,
          description="Comma-separated fields to return"
      )
      limit: int = Field(
          10,
          description="Maximum results to return"
      )

• debtstack/langchain.py:96-99 (helper)

  Helper method in DebtStackAPIWrapper that adds has_pricing=True to kwargs and calls /bonds endpoint

  def search_pricing(self, **kwargs) -> Dict[str, Any]:
      """Search bond pricing via /bonds with has_pricing=true."""
      kwargs["has_pricing"] = True
      return self._get("/bonds", params=kwargs)