DebtStack MCP Server

Instructions

Implementation Reference

• debtstack/mcp_server.py:449-475 (handler)

  The MCP tool handler that processes resolve_bond requests. It detects the identifier type (CUSIP, ISIN, or free-text), builds the appropriate parameters, calls the API endpoint, and formats the response with confidence scores.

  elif name == "resolve_bond":
      query = arguments.get("query", "").strip()
      params = {}
  
      # Detect identifier type
      if len(query) == 9 and query.isalnum():
          params["cusip"] = query
      elif len(query) == 12 and query[:2].isalpha():
          params["isin"] = query
      else:
          params["q"] = query
          params["match_mode"] = "fuzzy"
  
      result = api_get("/bonds/resolve", params)
      matches = result.get("data", {}).get("matches", [])
  
      if not matches:
          return [TextContent(type="text", text=f"No bonds found matching '{query}'.")]
  
      text = f"Found {len(matches)} match(es) for '{query}':\n\n"
      for m in matches:
          conf = m.get("confidence", 0)
          bond = m.get("bond", {})
          text += f"**Confidence: {conf:.0%}**\n"
          text += format_bond(bond) + "\n\n"
  
      return [TextContent(type="text", text=text)]

• debtstack/mcp_server.py:278-295 (registration)

  MCP tool registration for resolve_bond with its name, description, and input schema defining the 'query' parameter as required.

  Tool(
      name="resolve_bond",
      description=(
          "Look up a bond by CUSIP, ISIN, or description. "
          "Use when you have a partial bond identifier and need full details. "
          "Example: 'RIG 8% 2027' or 'CUSIP 893830AK8'"
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Bond identifier - CUSIP, ISIN, or description (e.g., 'RIG 8% 2027')"
              }
          },
          "required": ["query"]
      }
  ),

• debtstack/langchain.py:202-207 (schema)

  Pydantic BaseModel schema defining the ResolveBondInput with a required 'query' field for bond identifier resolution.

  class ResolveBondInput(BaseModel):
      """Input for bond resolution tool."""
      query: str = Field(
          ...,
          description="Bond identifier to resolve - can be CUSIP, ISIN, or description (e.g., 'RIG 8% 2027')"
      )

• debtstack/client.py:325-378 (handler)

  Async API client method that implements the actual resolve_bond call, accepting various parameters (q, cusip, isin, ticker, coupon, maturity_year) and making an HTTP GET request to /bonds/resolve endpoint.

  async def resolve_bond(
      self,
      q: Optional[str] = None,
      cusip: Optional[str] = None,
      isin: Optional[str] = None,
      ticker: Optional[str] = None,
      coupon: Optional[float] = None,
      maturity_year: Optional[int] = None,
      match_mode: str = "fuzzy",
      limit: int = 5,
  ) -> Dict[str, Any]:
      """
      Resolve bond identifiers - map descriptions to CUSIPs, ISINs, etc.
  
      Args:
          q: Free-text search (e.g., "RIG 8% 2027")
          cusip: Exact CUSIP lookup
          isin: Exact ISIN lookup
          ticker: Company ticker
          coupon: Coupon rate (%)
          maturity_year: Maturity year
          match_mode: "exact" or "fuzzy"
          limit: Max matches to return
  
      Returns:
          Dictionary with matches and confidence scores
  
      Example:
          # Resolve a bond description
          result = await client.resolve_bond(q="RIG 8% 2027")
          print(result["data"]["matches"][0]["bond"]["cusip"])
      """
      params = {
          "match_mode": match_mode,
          "limit": limit,
      }
  
      if q:
          params["q"] = q
      if cusip:
          params["cusip"] = cusip
      if isin:
          params["isin"] = isin
      if ticker:
          params["ticker"] = ticker
      if coupon is not None:
          params["coupon"] = coupon
      if maturity_year is not None:
          params["maturity_year"] = maturity_year
  
      client = await self._get_client()
      response = await client.get("/bonds/resolve", params=params)
      response.raise_for_status()
      return response.json()

• debtstack/langchain.py:389-420 (handler)

  LangChain BaseTool implementation for resolve_bond that provides the same identifier detection logic (CUSIP/ISIN/fuzzy text) and delegates to the API wrapper's resolve_bond method.

  class DebtStackResolveBondTool(BaseTool):
      """Resolve bond identifiers - CUSIP, ISIN, or descriptions."""
  
      name: str = "debtstack_resolve_bond"
      description: str = (
          "Resolve a bond identifier to get full details. "
          "Accepts CUSIP, ISIN, or free-text description (e.g., 'RIG 8% 2027'). "
          "Returns matching bonds with confidence scores, useful for identifier lookup "
          "or when you have a partial bond description."
      )
      args_schema: Type[BaseModel] = ResolveBondInput
      api_wrapper: DebtStackAPIWrapper
  
      def _run(
          self,
          query: str,
          run_manager: Optional[CallbackManagerForToolRun] = None,
      ) -> str:
          # Detect if it's a CUSIP (9 chars alphanumeric) or ISIN (12 chars starting with letters)
          query = query.strip()
          params = {}
  
          if len(query) == 9 and query.isalnum():
              params["cusip"] = query
          elif len(query) == 12 and query[:2].isalpha():
              params["isin"] = query
          else:
              params["q"] = query
              params["match_mode"] = "fuzzy"
  
          result = self.api_wrapper.resolve_bond(**params)
          return json.dumps(result, indent=2, default=str)