explain_why

Instructions

Implementation Reference

• src/mcpilot/server.py:97-122 (handler)

  The main handler for the 'explain_why' tool. Decorated with @mcp.tool(), it looks up a server by name using lookup_by_name(), generates a rationale via generate_rationale(), and returns a formatted markdown explanation.

  @mcp.tool()
  def explain_why(server_name: str, project_description: str) -> str:
      """
      Explain why a specific MCP server is a good fit for a given project.
      Example: server_name="github", project_description="open source Python library with CI/CD"
      """
      try:
          _ensure_index()
          server = lookup_by_name(server_name)
          if server is None:
              return (
                  f"Could not find '{server_name}' in the index. "
                  f"Try a partial name or check spelling."
              )
  
          rationale = generate_rationale(server, project_description)
          return (
              f"## Why {server['name']} fits your project\n\n"
              f"**Server:** {server['name']}\n"
              f"**URL:** {server['url']}\n"
              f"**Category:** {server['category']}\n"
              f"**Description:** {server['description']}\n\n"
              f"**Rationale:** {rationale}"
          )
      except Exception as e:
          return _error_response(f"explaining fit for '{server_name}'", e)

• src/mcpilot/server.py:97-97 (registration)

  The tool is registered as an MCP tool via the @mcp.tool() decorator on line 97.

  @mcp.tool()

• src/mcpilot/search.py:89-115 (helper)

  generate_rationale() generates a template-based rationale string explaining why a server fits a project. No LLM call — grounded, fast, offline.

  def generate_rationale(server: dict, project_description: str) -> str:
      """
      Template-based rationale: why this server fits this project.
      No LLM call — grounded, fast, offline.
      """
      name = server["name"]
      desc = server["description"]
      category = server["category"]
      score = server.get("score", 0)
  
      # Extract key nouns from project description (simple word overlap)
      proj_words = set(re.findall(r"[a-z0-9]+", project_description.lower()))
      desc_words = set(re.findall(r"[a-z0-9]+", desc.lower()))
      overlap = (proj_words & desc_words) - STOPWORDS
  
      if overlap:
          match_hint = f"It shares focus on: {', '.join(sorted(overlap)[:5])}."
      else:
          match_hint = f"It falls under the '{category}' category, which aligns with your project's needs."
  
      confidence = "strong" if score > 0.55 else "moderate" if score > 0.40 else "potential"
  
      return (
          f"{name} — {desc} "
          f"[{confidence} match | category: {category}] "
          f"{match_hint}"
      )

• src/mcpilot/search.py:118-147 (helper)

  lookup_by_name() finds a server by name in the index with ranked matching: exact → short-name exact → prefix → substring.

  def lookup_by_name(server_name: str) -> dict | None:
      """Find a server by name, ranked: exact → short-name exact → prefix → substring."""
      if not server_name or not server_name.strip():
          return None
      q = server_name.strip().lower()
      con = get_connection()
      rows = con.execute(
          "SELECT name, description, url, category FROM servers WHERE lower(name) LIKE ?",
          [f"%{q}%"],
      ).fetchall()
      con.close()
      if not rows:
          return None
  
      def _rank(row):
          n = row[0].lower()
          parts = n.split("/", 1)
          owner = parts[0] if len(parts) == 2 else ""
          short = parts[-1]
          if n == q or short == q:
              return (0, 0)
          # owner exact match is a stronger prefix signal
          if owner == q:
              return (1, 0)
          if n.startswith(q) or short.startswith(q):
              return (1, 1)
          return (2, 0)
  
      name, desc, url, cat = min(rows, key=_rank)
      return {"name": name, "description": desc, "url": url, "category": cat}