AutoEQ MCP Server

Instructions

Implementation Reference

• autoeq_mcp.py:785-842 (handler)

  The implementation of the eq_recommend tool handler.

  async def eq_recommend(
      preference: str = Field(
          default="neutral",
          description="Sound preference: neutral, warm, bright, bass, vocal, analytical, fun. Or free text.",
      ),
      form_factor: str = Field(default="", description="Type: over-ear, in-ear, earbud"),
      limit: int = Field(default=10, description="Number of recommendations"),
  ) -> str:
      """Recommend headphones based on sound preference and type. Sorted by Harman preference score."""
      conn = get_db()
  
      pref_map = {
          "neutral": ["Neutral", "Harman-like"],
          "warm": ["Warm"],
          "bright": ["Bright"],
          "bass": ["Bass-heavy", "Warm"],
          "vocal": ["Mid-forward", "Neutral"],
          "analytical": ["Bright", "Neutral"],
          "fun": ["V-shaped", "U-shaped"],
      }
  
      pref_lower = preference.lower().strip()
      target_sigs = pref_map.get(pref_lower, [])
  
      if target_sigs:
          sig_conditions = " OR ".join(["signature LIKE ?"] * len(target_sigs))
          params = [f"%{s}%" for s in target_sigs]
          where = f"({sig_conditions})"
      else:
          where = "signature LIKE ?"
          params = [f"%{preference}%"]
  
      if form_factor:
          where += " AND form_factor = ?"
          params.append(form_factor)
  
      params.append(min(limit, 30))
      rows = conn.execute(
          f"""SELECT name, source, coupler, form_factor, signature, score, std_db, slope
              FROM headphones
              WHERE {where} AND signature != ''
              ORDER BY score DESC NULLS LAST, std_db ASC NULLS LAST
              LIMIT ?""",
          params,
      ).fetchall()
      conn.close()
  
      if not rows:
          return f"No headphones found for '{preference}' preference."
  
      lines = [f"## Recommendations ({preference}, {form_factor or 'all types'})"]
      for i, r in enumerate(rows, 1):
          score = f" score:{r['score']}" if r["score"] else ""
          std = f" STD:{r['std_db']}dB" if r["std_db"] else ""
          lines.append(
              f"{i}. **{r['name']}** — {r['source']} | {r['form_factor']} | {r['signature']}{score}{std}"
          )
      return "\n".join(lines)

• autoeq_mcp.py:776-784 (registration)

  The registration of the eq_recommend tool.

      name="eq_recommend",
      annotations={
          "title": "Recommend headphones",
          "readOnlyHint": True,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": False,
      },
  )