mcp-commands

Instructions

Get command usage statistics.

Args:
    top_n: How many top items to show per category (default 10)

Returns JSON with:
- total usage count
- top commands ranked by usage
- top categories ranked by usage
- daily counts for the last 7 days

Implementation Reference

• src/mcp_commands/server.py:85-100 (handler)

  The get_stats_tool function decorated with @mcp.tool() that serves as the MCP tool handler. It takes a top_n parameter and returns command usage statistics as JSON.

  @mcp.tool()
  def get_stats_tool(top_n: int = 10) -> str:
      """
      Get command usage statistics.
  
      Args:
          top_n: How many top items to show per category (default 10)
  
      Returns JSON with:
      - total usage count
      - top commands ranked by usage
      - top categories ranked by usage
      - daily counts for the last 7 days
      """
      stats = get_stats(top_n=top_n)
      return json.dumps(stats, ensure_ascii=False, indent=2)

• src/mcp_commands/storage.py:114-169 (helper)

  The get_stats function that implements the core logic for retrieving command usage statistics from PostgreSQL, including total count, top commands, top categories, and daily counts.

  def get_stats(top_n: int = 10) -> dict:
      """Return usage statistics."""
      conn = get_connection()
  
      with conn.cursor() as cur:
          cur.execute("SELECT COUNT(*) FROM command_log")
          total = cur.fetchone()[0]
  
      with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
          cur.execute(
              """
              SELECT command, COUNT(*) AS count
              FROM command_log
              GROUP BY command
              ORDER BY count DESC
              LIMIT %s
              """,
              (top_n,),
          )
          top_commands = [dict(r) for r in cur.fetchall()]
  
      with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
          cur.execute(
              """
              SELECT COALESCE(category, '(none)') AS category, COUNT(*) AS count
              FROM command_log
              GROUP BY category
              ORDER BY count DESC
              LIMIT %s
              """,
              (top_n,),
          )
          top_categories = [dict(r) for r in cur.fetchall()]
  
      with conn.cursor(cursor_factory=psycopg2.extras.RealDictCursor) as cur:
          cur.execute(
              """
              SELECT DATE(used_at) AS day, COUNT(*) AS count
              FROM command_log
              WHERE used_at >= NOW() - INTERVAL '6 days'
              GROUP BY day
              ORDER BY day
              """
          )
          daily = [
              {"day": r["day"].isoformat() if hasattr(r["day"], "isoformat") else r["day"], "count": r["count"]}
              for r in cur.fetchall()
          ]
  
      conn.close()
      return {
          "total": total,
          "top_commands": top_commands,
          "top_categories": top_categories,
          "last_7_days": daily,
      }

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

  The @mcp.tool() decorator that registers get_stats_tool as an available MCP tool in the FastMCP server.

  @mcp.tool()