get_pitfalls

Instructions

Implementation Reference

• server.py:123-140 (registration)

  The `get_pitfalls` tool is registered via the `@mcp.tool()` decorator. This is the MCP entry point that exposes the tool to clients.

  @mcp.tool()
  def get_pitfalls(
      category: str | None = None,
      ai_source: str | None = None,
  ) -> dict:
      """
      Return known LSL pitfalls for AI coding assistants.
  
      Call with no arguments for a full briefing before starting an LSL task.
      Filter by category or by which AI tool produced the mistake.
  
      Args:
          category:  reserved_words | nonexistent_functions | unsupported_syntax
                     | scoping | type_coercion | state_behavior
          ai_source: kiro | claude-code | both
      """
      log.info("get_pitfalls(category=%r, ai_source=%r)", category, ai_source)
      return lsl_get_pitfalls(category, ai_source)

• tools/pitfalls.py:58-104 (handler)

  The actual implementation of `lsl_get_pitfalls`. It queries an SQLite database for pitfalls, optionally filtering by category and/or AI source, and returns a dict with count, filters, and pitfalls list.

  def lsl_get_pitfalls(category: str | None = None, ai_source: str | None = None) -> dict:
      """
      Return known LSL pitfalls for AI coding assistants.
  
      Call with no arguments to get all pitfalls. Filter by category or by
      which AI tool produced the mistake.
  
      Args:
          category:  One of: reserved_words, nonexistent_functions,
                     unsupported_syntax, scoping, type_coercion, state_behavior.
                     Omit to return all categories.
          ai_source: One of: kiro, claude-code, both.
                     Omit to return pitfalls from all sources.
  
      Returns:
          dict with keys:
              count    — number of pitfalls returned
              filters  — the filters that were applied
              pitfalls — list of pitfall records
      """
      if category and category not in VALID_CATEGORIES:
          return {
              "error": f"Unknown category '{category}'.",
              "valid_categories": sorted(VALID_CATEGORIES),
          }
  
      con    = _connect()
      query  = "SELECT * FROM pitfalls WHERE 1=1"
      params: list = []
  
      if category:
          query += " AND category = ?"
          params.append(category)
  
      if ai_source:
          query += " AND (ai_source = ? OR ai_source = 'both')"
          params.append(ai_source)
  
      query += " ORDER BY category, id"
  
      rows = con.execute(query, params).fetchall()
  
      return {
          "count":   len(rows),
          "filters": {"category": category, "ai_source": ai_source},
          "pitfalls": [_row_to_dict(r) for r in rows],
      }

• tools/pitfalls.py:48-55 (schema)

  The VALID_CATEGORIES set defines the allowed values for the 'category' parameter, enforced by the handler.

  VALID_CATEGORIES = {
      "reserved_words",
      "nonexistent_functions",
      "unsupported_syntax",
      "scoping",
      "type_coercion",
      "state_behavior",
  }

• tools/pitfalls.py:31-43 (helper)

  Helper function `_row_to_dict` converts a SQLite row into a dict used by the handler when building the response.

  def _row_to_dict(row: sqlite3.Row) -> dict:
      return {
          "id":           row["id"],
          "category":     row["category"],
          "title":        row["title"],
          "bad_example":  row["bad_example"],
          "good_example": row["good_example"],
          "notes":        row["notes"],
          "ai_specific":  bool(row["ai_specific"]),
          "portable_only": bool(row["portable_only"]),
          "ai_source":    row["ai_source"],
          "created_at":   row["created_at"],
      }

• tools/pitfalls.py:19-28 (helper)

  Helper function `_connect` sets up the SQLite database connection used by the handler.

  def _connect() -> sqlite3.Connection:
      if not DB_PATH.exists():
          raise RuntimeError(
              f"Database not found at {DB_PATH}. "
              "Run scripts/scrape_wiki.py then scripts/load_db.py first."
          )
      con = sqlite3.connect(DB_PATH)
      con.row_factory = sqlite3.Row
      con.execute("PRAGMA foreign_keys=ON")
      return con