__( 'Analytics', 'activity-log-for-mcp' ), 'description' => __( 'Abilities that provide analytical data and insights.', 'activity-log-for-mcp' ), ) ); } /** * Register all abilities. */ public static function register_abilities() { self::register_get_activity(); self::register_get_stats(); self::register_get_activity_by_session(); self::register_search_activity(); self::register_analyze_errors(); self::register_get_tool_performance(); self::register_clear_old_logs(); self::register_get_security_events(); self::register_get_security_stats(); self::register_acknowledge_event(); self::register_test_alert(); self::register_clear_all_logs(); } /** * Register the get-activity ability. */ private static function register_get_activity() { wp_register_ability( 'activity-log-for-mcp/get-activity', array( 'label' => __( 'Get MCP Activity', 'activity-log-for-mcp' ), 'description' => __( 'Retrieve a paginated log of MCP/AI interactions with optional filters.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'data' => array( 'type' => 'array' ), 'total' => array( 'type' => 'integer' ), ), ), 'input_schema' => array( 'type' => 'object', 'properties' => array( 'page' => array( 'type' => 'integer', 'default' => 1, ), 'per_page' => array( 'type' => 'integer', 'default' => 10, 'minimum' => 1, 'maximum' => self::MAX_PER_PAGE, ), 'tool' => array( 'type' => 'string' ), 'user_id' => array( 'type' => 'integer' ), 'date_from' => array( 'type' => 'string', 'format' => 'date', ), 'date_to' => array( 'type' => 'string', 'format' => 'date', ), ), ), 'execute_callback' => array( __CLASS__, 'execute_get_activity' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the get-stats ability. */ private static function register_get_stats() { wp_register_ability( 'activity-log-for-mcp/get-stats', array( 'label' => __( 'Get MCP Stats', 'activity-log-for-mcp' ), 'description' => __( 'Get summary statistics: total requests, success/error counts, success rate, calls per tool, and unique sessions.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'total_requests' => array( 'type' => 'integer' ), 'success_count' => array( 'type' => 'integer' ), 'error_count' => array( 'type' => 'integer' ), 'success_rate' => array( 'type' => 'number' ), 'unique_sessions' => array( 'type' => 'integer' ), 'by_tool' => array( 'type' => 'array' ), ), ), 'input_schema' => array( 'type' => 'object', 'properties' => array( 'date_from' => array( 'type' => 'string', 'format' => 'date', ), 'date_to' => array( 'type' => 'string', 'format' => 'date', ), ), ), 'execute_callback' => array( __CLASS__, 'execute_get_stats' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the get-activity-by-session ability. */ private static function register_get_activity_by_session() { wp_register_ability( 'activity-log-for-mcp/get-activity-by-session', array( 'label' => __( 'Get Activity By Session', 'activity-log-for-mcp' ), 'description' => __( 'Retrieve log entries for a specific MCP session ID, ordered chronologically. Use exclude_bodies=true to get a lightweight summary without request/response payloads.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'data' => array( 'type' => 'array' ), 'total' => array( 'type' => 'integer' ), ), ), 'input_schema' => array( 'type' => 'object', 'required' => array( 'session_id' ), 'properties' => array( 'session_id' => array( 'type' => 'string', 'description' => 'The MCP session ID to look up.', ), 'page' => array( 'type' => 'integer', 'default' => 1, ), 'per_page' => array( 'type' => 'integer', 'default' => 50, 'minimum' => 1, 'maximum' => self::MAX_PER_PAGE, ), 'exclude_bodies' => array( 'type' => 'boolean', 'default' => false, 'description' => 'If true, omits headers, request_body, and response_body to reduce payload size.', ), ), ), 'execute_callback' => array( __CLASS__, 'execute_get_activity_by_session' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the search-activity ability. */ private static function register_search_activity() { wp_register_ability( 'activity-log-for-mcp/search-activity', array( 'label' => __( 'Search MCP Activity', 'activity-log-for-mcp' ), 'description' => __( 'Full-text search across routes, tool names, request bodies, and response bodies.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'data' => array( 'type' => 'array' ), 'total' => array( 'type' => 'integer' ), ), ), 'input_schema' => array( 'type' => 'object', 'required' => array( 'query' ), 'properties' => array( 'query' => array( 'type' => 'string', 'description' => 'Search keyword.', ), 'page' => array( 'type' => 'integer', 'default' => 1, ), 'per_page' => array( 'type' => 'integer', 'default' => 10, 'minimum' => 1, 'maximum' => self::MAX_PER_PAGE, ), ), ), 'execute_callback' => array( __CLASS__, 'execute_search_activity' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the analyze-errors ability. */ private static function register_analyze_errors() { wp_register_ability( 'activity-log-for-mcp/analyze-errors', array( 'label' => __( 'Analyze MCP Errors', 'activity-log-for-mcp' ), 'description' => __( 'List recent failed tool executions and HTTP errors with full details.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'array', 'items' => array( 'type' => 'object' ), ), 'input_schema' => array( 'type' => 'object', 'properties' => array( 'limit' => array( 'type' => 'integer', 'default' => 20, ), ), ), 'execute_callback' => array( __CLASS__, 'execute_analyze_errors' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the get-tool-performance ability. */ private static function register_get_tool_performance() { wp_register_ability( 'activity-log-for-mcp/get-tool-performance', array( 'label' => __( 'Get Tool Performance', 'activity-log-for-mcp' ), 'description' => __( 'Per-tool metrics: call count, success/error counts, error rate, and unique users. Optionally filter to a single tool.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'array', 'items' => array( 'type' => 'object', 'properties' => array( 'tool_name' => array( 'type' => 'string' ), 'total_calls' => array( 'type' => 'integer' ), 'success_count' => array( 'type' => 'integer' ), 'error_count' => array( 'type' => 'integer' ), 'error_rate' => array( 'type' => 'number' ), 'unique_users' => array( 'type' => 'integer' ), ), ), ), 'input_schema' => array( 'type' => 'object', 'properties' => array( 'tool_name' => array( 'type' => 'string', 'description' => 'Optional tool name to filter metrics for a single tool.', ), ), ), 'execute_callback' => array( __CLASS__, 'execute_get_tool_performance' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the clear-old-logs ability. */ private static function register_clear_old_logs() { wp_register_ability( 'activity-log-for-mcp/clear-old-logs', array( 'label' => __( 'Clear Old Logs', 'activity-log-for-mcp' ), 'description' => __( 'Delete log entries older than a specified date. Logs from the last 24 hours are protected and cannot be removed with this ability.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'deleted' => array( 'type' => 'integer' ), 'message' => array( 'type' => 'string' ), ), ), 'input_schema' => array( 'type' => 'object', 'required' => array( 'before_date' ), 'properties' => array( 'before_date' => array( 'type' => 'string', 'format' => 'date', 'description' => 'Delete all logs before this date (Y-m-d). Must be at least 24 hours in the past.', ), ), ), 'execute_callback' => array( __CLASS__, 'execute_clear_old_logs' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the get-security-events ability. */ private static function register_get_security_events() { wp_register_ability( 'activity-log-for-mcp/get-security-events', array( 'label' => __( 'Get Security Events', 'activity-log-for-mcp' ), 'description' => __( 'Retrieve security alert events with optional filters for rule name, severity, and date range.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'data' => array( 'type' => 'array' ), 'total' => array( 'type' => 'integer' ), ), ), 'input_schema' => array( 'type' => 'object', 'properties' => array( 'limit' => array( 'type' => 'integer', 'default' => 20, ), 'rule_name' => array( 'type' => 'string', 'description' => 'Filter by rule name: velocity, destructive_tool, or error_storm.', ), 'date_from' => array( 'type' => 'string', 'format' => 'date', ), 'date_to' => array( 'type' => 'string', 'format' => 'date', ), ), ), 'execute_callback' => array( __CLASS__, 'execute_get_security_events' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the get-security-stats ability. */ private static function register_get_security_stats() { wp_register_ability( 'activity-log-for-mcp/get-security-stats', array( 'label' => __( 'Get Security Stats', 'activity-log-for-mcp' ), 'description' => __( 'Get security dashboard stats for the last 7 days: total alerts, active sessions, top triggered rule, and success rate.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'total_alerts' => array( 'type' => 'integer' ), 'active_sessions' => array( 'type' => 'integer' ), 'top_rule' => array( 'type' => array( 'string', 'null' ), 'description' => 'Most frequently triggered rule in the last 7 days, or null.', ), 'success_rate' => array( 'type' => 'number' ), ), ), 'input_schema' => array( 'type' => 'object', 'properties' => new \stdClass(), ), 'execute_callback' => array( __CLASS__, 'execute_get_security_stats' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the acknowledge-event ability. */ private static function register_acknowledge_event() { wp_register_ability( 'activity-log-for-mcp/acknowledge-event', array( 'label' => __( 'Acknowledge Security Event', 'activity-log-for-mcp' ), 'description' => __( 'Mark a security event as acknowledged or unacknowledged.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'success' => array( 'type' => 'boolean' ), 'message' => array( 'type' => 'string' ), ), ), 'input_schema' => array( 'type' => 'object', 'required' => array( 'event_id' ), 'properties' => array( 'event_id' => array( 'type' => 'integer', 'description' => 'The security event ID to acknowledge.', ), 'acknowledged' => array( 'type' => 'boolean', 'default' => true, 'description' => 'True to acknowledge, false to unacknowledge.', ), ), ), 'execute_callback' => array( __CLASS__, 'execute_acknowledge_event' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the test-alert ability. */ private static function register_test_alert() { wp_register_ability( 'activity-log-for-mcp/test-alert', array( 'label' => __( 'Send Test Alert', 'activity-log-for-mcp' ), 'description' => __( 'Send a test alert email to verify email delivery is working.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'success' => array( 'type' => 'boolean' ), 'message' => array( 'type' => 'string' ), ), ), 'input_schema' => array( 'type' => 'object', 'properties' => new \stdClass(), ), 'execute_callback' => array( __CLASS__, 'execute_test_alert' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the clear-all-logs ability. */ private static function register_clear_all_logs() { wp_register_ability( 'activity-log-for-mcp/clear-all-logs', array( 'label' => __( 'Clear All Logs', 'activity-log-for-mcp' ), 'description' => __( 'Delete all MCP request logs. This action cannot be undone. Always confirm with the user before calling this.', 'activity-log-for-mcp' ), 'category' => 'activity-log-for-mcp', 'output_schema' => array( 'type' => 'object', 'properties' => array( 'success' => array( 'type' => 'boolean' ), 'message' => array( 'type' => 'string' ), ), ), 'input_schema' => array( 'type' => 'object', 'required' => array( 'confirm' ), 'properties' => array( 'confirm' => array( 'type' => 'boolean', 'description' => 'Must be true to proceed. This is a destructive action.', ), ), ), 'execute_callback' => array( __CLASS__, 'execute_clear_all_logs' ), 'permission_callback' => array( __CLASS__, 'check_permission' ), ) ); } /** * Register the MCP Server. * * @param object $adapter The MCP Adapter instance. */ public static function register_mcp_server( $adapter ) { $adapter->create_server( 'activity-log-for-mcp-server', 'activity-log-for-mcp', 'mcp', 'Activity Log for MCP Server', 'Exposes Activity Log for MCP history and analytics', '1.0.0', array( \WP\MCP\Transport\HttpTransport::class, ), \WP\MCP\Infrastructure\ErrorHandling\ErrorLogMcpErrorHandler::class, \WP\MCP\Infrastructure\Observability\NullMcpObservabilityHandler::class, self::get_mcp_server_abilities() ); } /** * Abilities exposed as tools on the MCP server. * * The log-deletion abilities are deliberately absent. This same tool set * reads untrusted log content (get-activity, search-activity, * analyze-errors return rows whose bodies an unauthenticated caller can * influence), so instruction text planted in a log entry lands in the * context of an administrator's agent. Pairing that with a one-call wipe of * the audit trail lets planted text destroy the record of its own arrival, * and a `confirm: true` input is a model-level check, not a code-level gate. * * Deletion remains available in the authenticated admin UI, over REST, and * to anything calling the abilities directly. * * @return string[] */ private static function get_mcp_server_abilities() { $abilities = array( 'activity-log-for-mcp/get-activity', 'activity-log-for-mcp/get-stats', 'activity-log-for-mcp/get-activity-by-session', 'activity-log-for-mcp/search-activity', 'activity-log-for-mcp/analyze-errors', 'activity-log-for-mcp/get-tool-performance', 'activity-log-for-mcp/get-security-events', 'activity-log-for-mcp/get-security-stats', 'activity-log-for-mcp/acknowledge-event', 'activity-log-for-mcp/test-alert', ); /** * Filter the abilities exposed as MCP tools. * * Re-adding the deletion abilities gives any agent that reads the log a * route to destroying it. Do so only if the agents connecting to this * site are trusted with that. * * @param string[] $abilities Ability names exposed on the MCP server. */ return apply_filters( 'alfmcp_mcp_server_abilities', $abilities ); } /** * Permission callback. * * @return bool */ public static function check_permission() { return ALFMCP_Helper::current_user_can_manage(); } /** * Maximum per_page value allowed via the abilities API. * * @var int */ const MAX_PER_PAGE = 500; /** * Hours of recent log history that clear-old-logs refuses to delete. * * @var int */ const MIN_RETENTION_HOURS = 24; /** * Clamp a per_page value to a safe range. * * @param mixed $value Raw input value. * @param int $default Default when value is missing. * @return int */ private static function clamp_per_page( $value, $default = 10 ) { $val = isset( $value ) ? absint( $value ) : $default; return min( max( 1, $val ), self::MAX_PER_PAGE ); } /** * Sanitize a date string. Accepts Y-m-d or Y-m-d H:i:s. * * @param mixed $date Raw date input. * @return string|null Sanitized date or null. */ private static function sanitize_date( $date ) { if ( empty( $date ) ) { return null; } $timestamp = strtotime( sanitize_text_field( $date ) ); if ( false === $timestamp ) { return null; } if ( strlen( trim( $date ) ) > 10 ) { return gmdate( 'Y-m-d H:i:s', $timestamp ); } return gmdate( 'Y-m-d', $timestamp ); } /** * Execute get-activity. * * @param array $args Input arguments. * @return array */ public static function execute_get_activity( $args ) { return ALFMCP_DB::get_requests( array( 'page' => isset( $args['page'] ) ? $args['page'] : 1, 'per_page' => self::clamp_per_page( $args['per_page'] ?? null, 10 ), 'tool' => isset( $args['tool'] ) ? $args['tool'] : null, 'user_id' => isset( $args['user_id'] ) ? $args['user_id'] : null, 'date_from' => self::sanitize_date( $args['date_from'] ?? null ), 'date_to' => self::sanitize_date( $args['date_to'] ?? null ), ) ); } /** * Execute get-stats. * * @param array $args Input arguments. * @return array */ public static function execute_get_stats( $args ) { return ALFMCP_DB::get_stats( array( 'date_from' => self::sanitize_date( $args['date_from'] ?? null ), 'date_to' => self::sanitize_date( $args['date_to'] ?? null ), ) ); } /** * Execute get-activity-by-session. * * @param array $args Input arguments. * @return array */ public static function execute_get_activity_by_session( $args ) { if ( empty( $args['session_id'] ) ) { return array( 'data' => array(), 'total' => 0, ); } return ALFMCP_DB::get_by_session( array( 'session_id' => sanitize_text_field( $args['session_id'] ), 'page' => isset( $args['page'] ) ? $args['page'] : 1, 'per_page' => self::clamp_per_page( $args['per_page'] ?? null, 50 ), 'exclude_bodies' => ! empty( $args['exclude_bodies'] ), ) ); } /** * Execute search-activity. * * @param array $args Input arguments. * @return array */ public static function execute_search_activity( $args ) { if ( empty( $args['query'] ) ) { return array( 'data' => array(), 'total' => 0, ); } return ALFMCP_DB::search_requests( array( 'query' => sanitize_text_field( $args['query'] ), 'page' => isset( $args['page'] ) ? $args['page'] : 1, 'per_page' => self::clamp_per_page( $args['per_page'] ?? null, 10 ), ) ); } /** * Execute analyze-errors. * * @param array $args Input arguments. * @return array */ public static function execute_analyze_errors( $args ) { $limit = self::clamp_per_page( $args['limit'] ?? null, 20 ); return ALFMCP_DB::get_errors( $limit ); } /** * Execute get-tool-performance. * * @param array $args Input arguments. * @return array */ public static function execute_get_tool_performance( $args ) { $tool_name = isset( $args['tool_name'] ) ? sanitize_text_field( $args['tool_name'] ) : null; return ALFMCP_DB::get_tool_performance( $tool_name ); } /** * Execute clear-old-logs. * * @param array $args Input arguments. * @return array */ public static function execute_clear_old_logs( $args ) { if ( empty( $args['before_date'] ) ) { return array( 'deleted' => 0, 'message' => __( 'No before_date was supplied.', 'activity-log-for-mcp' ), ); } $date = self::sanitize_date( $args['before_date'] ); if ( null === $date ) { return array( 'deleted' => 0, 'message' => __( 'before_date could not be parsed as a date.', 'activity-log-for-mcp' ), ); } /* * Refuse to delete recent history. * * Without a floor, `before_date: 2099-01-01` empties the table in one * call. Capping the cutoff means no single invocation can erase the * window in which suspicious activity would still be visible. */ $floor = strtotime( '-' . self::MIN_RETENTION_HOURS . ' hours', strtotime( current_time( 'mysql' ) ) ); if ( strtotime( $date ) > $floor ) { return array( 'deleted' => 0, 'message' => sprintf( /* translators: %d: number of hours of log history that cannot be deleted. */ __( 'Refused: logs from the last %d hours cannot be deleted through this ability. Use the admin screen for a full clear.', 'activity-log-for-mcp' ), self::MIN_RETENTION_HOURS ), ); } $result = ALFMCP_DB::delete_before( $date ); return array( 'deleted' => false !== $result ? (int) $result : 0, 'message' => '', ); } /** * Execute get-security-events. * * @param array $args Input arguments. * @return array */ public static function execute_get_security_events( $args ) { return ALFMCP_DB::get_security_events( array( 'per_page' => self::clamp_per_page( $args['limit'] ?? null, 20 ), 'rule_name' => isset( $args['rule_name'] ) ? sanitize_text_field( $args['rule_name'] ) : null, 'date_from' => self::sanitize_date( $args['date_from'] ?? null ), 'date_to' => self::sanitize_date( $args['date_to'] ?? null ), ) ); } /** * Execute get-security-stats. * * @param array $args Input arguments (unused). * @return array */ public static function execute_get_security_stats( $args ) { return ALFMCP_DB::get_security_stats(); } /** * Execute acknowledge-event. * * @param array $args Input arguments. * @return array */ public static function execute_acknowledge_event( $args ) { if ( empty( $args['event_id'] ) ) { return array( 'success' => false, 'message' => 'Missing required parameter: event_id.', ); } $acknowledged = isset( $args['acknowledged'] ) ? (bool) $args['acknowledged'] : true; $result = ALFMCP_DB::acknowledge_security_event( absint( $args['event_id'] ), $acknowledged ); if ( ! $result ) { return array( 'success' => false, 'message' => 'Failed to update event. It may not exist.', ); } $label = $acknowledged ? 'acknowledged' : 'unacknowledged'; return array( 'success' => true, 'message' => "Event {$label}.", ); } /** * Execute test-alert. * * @param array $args Input arguments (unused). * @return array */ public static function execute_test_alert( $args ) { $result = ALFMCP_Security::send_test_alert(); return array( 'success' => $result, 'message' => $result ? 'Test email sent successfully.' : 'Email delivery failed. Check your wp_mail configuration.', ); } /** * Execute clear-all-logs. * * @param array $args Input arguments. * @return array */ public static function execute_clear_all_logs( $args ) { if ( empty( $args['confirm'] ) || true !== $args['confirm'] ) { return array( 'success' => false, 'message' => 'You must pass confirm: true to delete all logs. This action cannot be undone.', ); } $result = ALFMCP_DB::clear_all_requests(); if ( false === $result ) { return array( 'success' => false, 'message' => 'Failed to clear logs.', ); } return array( 'success' => true, 'message' => 'All logs cleared.', ); } }