DebtStack MCP Server

Instructions

Implementation Reference

• debtstack/mcp_server.py:547-558 (handler)

  MCP tool handler for search_documents that calls the API endpoint and formats results for the user

  elif name == "search_documents":
      params = {k: v for k, v in arguments.items() if v is not None}
      params.setdefault("limit", 10)
      result = api_get("/documents/search", params)
  
      docs = result.get("data", [])
      if not docs:
          return [TextContent(type="text", text=f"No documents found for '{params.get('q', '')}'.")]
  
      text = f"Found {len(docs)} matching sections:\n\n"
      text += "\n\n---\n\n".join(format_document_result(d) for d in docs)
      return [TextContent(type="text", text=text)]

• debtstack/mcp_server.py:363-392 (registration)

  Tool registration in list_tools() with name, description, and input schema defining query, ticker, section_type, and limit parameters

      name="search_documents",
      description=(
          "Search SEC filing sections for specific terms. "
          "Section types: debt_footnote, credit_agreement, indenture, covenants, mda_liquidity. "
          "Use to find covenant language, credit agreement terms, or debt descriptions."
      ),
      inputSchema={
          "type": "object",
          "properties": {
              "query": {
                  "type": "string",
                  "description": "Search terms"
              },
              "ticker": {
                  "type": "string",
                  "description": "Company ticker(s)"
              },
              "section_type": {
                  "type": "string",
                  "enum": ["debt_footnote", "credit_agreement", "indenture", "covenants", "mda_liquidity", "exhibit_21", "guarantor_list"],
                  "description": "Section type to search"
              },
              "limit": {
                  "type": "integer",
                  "description": "Maximum results (default 10)"
              }
          },
          "required": ["query"]
      }
  ),

• debtstack/mcp_server.py:177-189 (helper)

  Helper function format_document_result() that formats individual document search results with section type, ticker, filing info, and snippet

  def format_document_result(d: dict) -> str:
      """Format document search result."""
      lines = [
          f"**{d.get('section_type', 'Document')}** - {d.get('ticker', '?')}",
          f"Filing: {d.get('doc_type', '?')} ({d.get('filing_date', '?')})"
      ]
  
      if d.get('snippet'):
          # Clean up HTML tags in snippet
          snippet = d['snippet'].replace('<b>', '**').replace('</b>', '**')
          lines.append(f"...{snippet}...")
  
      return "\n".join(lines)

• debtstack/client.py:513-582 (handler)

  Async client method search_documents() that performs the actual HTTP GET request to /documents/search with query parameters and returns the JSON response

  async def search_documents(
      self,
      q: str,
      ticker: Optional[str] = None,
      doc_type: Optional[str] = None,
      section_type: Optional[str] = None,
      filed_after: Optional[Union[str, date]] = None,
      filed_before: Optional[Union[str, date]] = None,
      fields: Optional[str] = None,
      sort: str = "-relevance",
      limit: int = 50,
      offset: int = 0,
  ) -> Dict[str, Any]:
      """
      Full-text search across SEC filing sections.
  
      Args:
          q: Search query (required)
          ticker: Comma-separated company tickers
          doc_type: Filing type: 10-K, 10-Q, 8-K
          section_type: Section type:
              - exhibit_21: Subsidiary list
              - debt_footnote: Long-term debt details
              - mda_liquidity: Liquidity and Capital Resources
              - credit_agreement: Full credit facility documents
              - indenture: Bond indentures
              - guarantor_list: Guarantor subsidiaries
              - covenants: Financial covenant details
          filed_after: Minimum filing date
          filed_before: Maximum filing date
          fields: Comma-separated fields to return
          sort: -relevance (default), -filing_date, filing_date
          limit: Results per page (max 100)
          offset: Pagination offset
  
      Returns:
          Dictionary with search results and snippets
  
      Example:
          # Search for covenant language
          result = await client.search_documents(
              q="maintenance covenant",
              section_type="credit_agreement",
              ticker="CHTR"
          )
      """
      params = {
          "q": q,
          "sort": sort,
          "limit": limit,
          "offset": offset,
      }
  
      if ticker:
          params["ticker"] = ticker
      if doc_type:
          params["doc_type"] = doc_type
      if section_type:
          params["section_type"] = section_type
      if filed_after:
          params["filed_after"] = str(filed_after)
      if filed_before:
          params["filed_before"] = str(filed_before)
      if fields:
          params["fields"] = fields
  
      client = await self._get_client()
      response = await client.get("/documents/search", params=params)
      response.raise_for_status()
      return response.json()