mcp-commands

Instructions

Log one AI command usage.

Args:
    command:  The command name, e.g. '/commit', '/recap', 'deep-research'
    category: Optional group, e.g. 'git', 'research', 'oracle', 'session'
    context:  Optional free-text note about where/why it was used

Implementation Reference

• src/mcp_commands/server.py:39-58 (handler)

  The main log_command_tool handler function decorated with @mcp.tool() that logs AI command usage. Accepts command (required), category (optional), and context (optional) parameters, calls the storage layer, and returns a confirmation message with the new row ID.

  @mcp.tool()
  def log_command_tool(
      command: str,
      category: str = "",
      context: str = "",
  ) -> str:
      """
      Log one AI command usage.
  
      Args:
          command:  The command name, e.g. '/commit', '/recap', 'deep-research'
          category: Optional group, e.g. 'git', 'research', 'oracle', 'session'
          context:  Optional free-text note about where/why it was used
      """
      row_id = log_command(
          command=command,
          category=category or None,
          context=context or None,
      )
      return f"✅ Logged command '{command}' (id={row_id})"

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

  Tool registration using @mcp.tool() decorator that registers log_command_tool as an available MCP tool.

  @mcp.tool()

• src/mcp_commands/storage.py:50-76 (helper)

  The log_command helper function in the storage layer that handles the actual database insertion. Opens a PostgreSQL connection, inserts the command record with command, category, context, and extra fields, and returns the new row ID.

  def log_command(
      command: str,
      category: Optional[str] = None,
      context: Optional[str] = None,
      extra: Optional[dict] = None,
  ) -> int:
      """Insert one command-usage record. Returns the new row id."""
      conn = get_connection()
      with conn.cursor() as cur:
          cur.execute(
              """
              INSERT INTO command_log (command, category, context, extra, used_at)
              VALUES (%s, %s, %s, %s, %s)
              RETURNING id
              """,
              (
                  command,
                  category,
                  context,
                  json.dumps(extra) if extra else None,
                  datetime.now().isoformat(timespec="seconds"),
              ),
          )
          row_id = cur.fetchone()[0]
      conn.commit()
      conn.close()
      return row_id