AutoEQ MCP Server

Instructions

Implementation Reference

• autoeq_mcp.py:649-706 (handler)

  The `eq_search` function performs a database query against the `headphones` table to find items matching the provided query, form factor, signature, and source, returning a formatted markdown list.

  async def eq_search(
      query: str = Field(default="", description="Search term (model name, brand, etc.)"),
      form_factor: str = Field(
          default="",
          description="Type filter: over-ear, in-ear, earbud",
      ),
      signature: str = Field(
          default="",
          description="Sound signature filter: Neutral, Warm, Bright, Dark, V-shaped, U-shaped, Bass-heavy, Mid-forward, Harman-like",
      ),
      source: str = Field(
          default="",
          description="Measurement source filter: oratory1990, crinacle, Rtings, etc.",
      ),
      limit: int = Field(default=20, description="Max results (up to 50)"),
  ) -> str:
      """Search the AutoEQ database for headphones/IEMs. Filter by name, type, sound signature, or measurement source."""
      conn = get_db()
      conditions = []
      params = []
  
      if query:
          conditions.append("name LIKE ?")
          params.append(f"%{query}%")
      if form_factor:
          conditions.append("form_factor = ?")
          params.append(form_factor)
      if signature:
          conditions.append("signature LIKE ?")
          params.append(f"%{signature}%")
      if source:
          conditions.append("source LIKE ?")
          params.append(f"%{source}%")
  
      where = " AND ".join(conditions) if conditions else "1=1"
      sql = f"""
          SELECT name, source, coupler, form_factor, signature, score
          FROM headphones
          WHERE {where}
          ORDER BY score DESC NULLS LAST, name
          LIMIT ?
      """
      params.append(min(limit, 50))
      rows = conn.execute(sql, params).fetchall()
      conn.close()
  
      if not rows:
          return "No results found."
  
      lines = [f"## Search results ({len(rows)} found)"]
      for r in rows:
          score = f" [score:{r['score']}]" if r["score"] else ""
          sig = f" ({r['signature']})" if r["signature"] else ""
          coupler = f" [{r['coupler']}]" if r["coupler"] else ""
          lines.append(
              f"- **{r['name']}** — {r['source']}{coupler} | {r['form_factor']}{sig}{score}"
          )
      return "\n".join(lines)