mcp-commands

Instructions

Get recent command-usage history.

Args:
    limit:    Max rows to return (default 20)
    command:  Filter by command name (partial match)
    category: Filter by category (exact match)

Implementation Reference

• src/mcp_commands/server.py:61-82 (handler)

  The main get_history_tool handler function. It's registered as an MCP tool with @mcp.tool() decorator, accepts limit/command/category parameters, calls get_history() from storage, and returns JSON results.

  @mcp.tool()
  def get_history_tool(
      limit: int = 20,
      command: str = "",
      category: str = "",
  ) -> str:
      """
      Get recent command-usage history.
  
      Args:
          limit:    Max rows to return (default 20)
          command:  Filter by command name (partial match)
          category: Filter by category (exact match)
      """
      rows = get_history(
          limit=limit,
          command=command or None,
          category=category or None,
      )
      if not rows:
          return "No records found."
      return json.dumps(rows, ensure_ascii=False, indent=2)

• src/mcp_commands/server.py:61-82 (registration)

  Tool registration using @mcp.tool() decorator. The decorator at line 61 registers get_history_tool as an available MCP tool with its schema defined via type hints and docstring.

  @mcp.tool()
  def get_history_tool(
      limit: int = 20,
      command: str = "",
      category: str = "",
  ) -> str:
      """
      Get recent command-usage history.
  
      Args:
          limit:    Max rows to return (default 20)
          command:  Filter by command name (partial match)
          category: Filter by category (exact match)
      """
      rows = get_history(
          limit=limit,
          command=command or None,
          category=category or None,
      )
      if not rows:
          return "No records found."
      return json.dumps(rows, ensure_ascii=False, indent=2)

• src/mcp_commands/storage.py:83-111 (helper)

  The get_history() storage helper function that performs the actual database query. Connects to PostgreSQL, builds SQL with optional command/category filters, and returns records sorted by used_at DESC.

  def get_history(
      limit: int = 50,
      command: Optional[str] = None,
      category: Optional[str] = None,
  ) -> list[dict]:
      """Return recent command-usage records (newest first)."""
      conn = get_connection()
  
      clauses = []
      params: list = []
  
      if command:
          clauses.append("command ILIKE %s")
          params.append(f"%{command}%")
      if category:
          clauses.append("category = %s")
          params.append(category)
  
      where = ("WHERE " + " AND ".join(clauses)) if clauses else ""
      params.append(limit)
  
      with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
          cur.execute(
              f"SELECT * FROM command_log {where} ORDER BY used_at DESC LIMIT %s",
              params,
          )
          rows = cur.fetchall()
      conn.close()
      return [_row_to_dict(r) for r in rows]