rosett-ai 1.3.3

data/lib/rosett_ai/mcp/tools/context_query_tool.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'yaml'
+require 'pathname'
+
+module RosettAi
+  module Mcp
+    module Tools
+      # MCP tool: query applicable rules for a given context.
+      #
+      # Answers "What rules apply to this situation?" by matching rules
+      # against a file path, tool name, or action. Returns applicable
+      # rules ranked by priority. Read-only operation.
+      #
+      # @author hugo
+      # @author claude
+      class ContextQueryTool
+        TOOL_NAME = 'rai_context_query'
+        DESCRIPTION = 'Query applicable rules for a file path, tool name, or action'
+
+        ANNOTATIONS = {
+          'readOnlyHint' => true,
+          'destructiveHint' => false,
+          'idempotentHint' => true,
+          'openWorldHint' => false
+        }.freeze
+
+        INPUT_SCHEMA = {
+          type: 'object',
+          properties: {
+            file_path: {
+              type: 'string',
+              description: 'File path to query applicable rules for'
+            },
+            tool_name: {
+              type: 'string',
+              description: 'Tool name to query applicable rules for'
+            },
+            action: {
+              type: 'string',
+              description: 'Action to query applicable rules for'
+            }
+          }
+        }.freeze
+
+        # Queries rules applicable to the given context.
+        #
+        # @param file_path [String, nil] file path context
+        # @param tool_name [String, nil] tool name context (e.g. 'Bash', 'Edit')
+        # @param action [String, nil] action context (e.g. 'write', 'delete')
+        # @return [Hash] applicable rules with metadata
+        def call(file_path: nil, tool_name: nil, action: nil)
+          query = build_query(file_path, tool_name, action)
+          return ResponseHelper.error('At least one query parameter required') if query.empty?
+
+          matches = search_rules(query)
+          matches.sort_by! { |m| -(m[:priority] || 0) }
+
+          {
+            applicable_rules: matches,
+            total: matches.size,
+            query: query
+          }
+        rescue StandardError => e
+          ResponseHelper.error("Context query failed: #{e.message}")
+        end
+
+        private
+
+        # @param file_path [String, nil]
+        # @param tool_name [String, nil]
+        # @param action [String, nil]
+        # @return [Hash]
+        def build_query(file_path, tool_name, action)
+          query = {}
+          query[:file_path] = file_path if file_path
+          query[:tool_name] = tool_name if tool_name
+          query[:action] = action if action
+          query
+        end
+
+        # @param query [Hash]
+        # @return [Array<Hash>]
+        def search_rules(query)
+          matches = []
+          each_behaviour do |data|
+            match_rules(data, query, matches)
+          end
+          matches
+        end
+
+        # @param data [Hash]
+        # @param query [Hash]
+        # @param matches [Array<Hash>]
+        def match_rules(data, query, matches)
+          rules = data['rules']
+          return unless rules.is_a?(Array)
+
+          behaviour_name = data['name']
+          rules.each do |rule|
+            next unless rule.is_a?(Hash) && rule.fetch('enabled', true)
+            next unless rule_matches_query?(rule, query)
+
+            matches << format_match(behaviour_name, rule)
+          end
+        end
+
+        # @param rule [Hash]
+        # @param query [Hash]
+        # @return [Boolean]
+        def rule_matches_query?(rule, query)
+          description = rule['description'].to_s.downcase
+
+          query.any? do |_key, value|
+            description.include?(value.to_s.downcase)
+          end
+        end
+
+        # @param behaviour_name [String]
+        # @param rule [Hash]
+        # @return [Hash]
+        def format_match(behaviour_name, rule)
+          {
+            rule_id: rule['id'],
+            behaviour: behaviour_name,
+            priority: rule['priority'] || 0,
+            description: rule['description'].to_s.strip[0, 200]
+          }
+        end
+
+        # @yield [Hash] parsed behaviour data
+        def each_behaviour
+          behaviour_dirs.each do |dir|
+            next unless dir.directory?
+
+            dir.glob('*.yml').each do |path|
+              data = YAML.safe_load_file(path, permitted_classes: [Symbol])
+              yield data if data.is_a?(Hash)
+            end
+          end
+        end
+
+        # @return [Array<Pathname>]
+        def behaviour_dirs
+          dirs = [RosettAi.root.join('conf', 'behaviour')]
+          xdg = RosettAi.paths.rai_conf_dir.join('behaviour')
+          dirs << xdg if xdg.directory?
+          dirs
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/tools/design_list_tool.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    module Tools
+      # MCP tool: list rai design documents.
+      #
+      # Returns a structured list of all design documents with
+      # metadata (name, status, priority, domain).
+      #
+      # @author hugo
+      # @author claude
+      class DesignListTool
+        TOOL_NAME = 'rai_design_list'
+        DESCRIPTION = 'List all rai design documents'
+
+        ANNOTATIONS = {
+          'readOnlyHint' => true,
+          'destructiveHint' => false,
+          'idempotentHint' => true,
+          'openWorldHint' => false
+        }.freeze
+
+        # Executes the listing.
+        #
+        # @return [Hash] result with :designs array
+        def call
+          dir = RosettAi.root.join('conf', 'design')
+          return { designs: [] } unless dir.directory?
+
+          designs = dir.glob('*.yml').filter_map { |path| load_design(path) }
+          { designs: designs }
+        end
+
+        private
+
+        def load_design(path)
+          data = YAML.safe_load_file(path, permitted_classes: [Symbol])
+          return nil unless data.is_a?(Hash)
+
+          {
+            name: data['name'],
+            status: data['status'],
+            priority: data['priority'],
+            domain: data['domain'],
+            file: path.basename.to_s
+          }
+        rescue Psych::SyntaxError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/tools/design_show_tool.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    module Tools
+      # MCP tool: show a specific design document.
+      #
+      # Returns the full content and metadata of a named design document.
+      # Read-only operation.
+      #
+      # @author hugo
+      # @author claude
+      class DesignShowTool
+        TOOL_NAME = 'rai_design_show'
+        DESCRIPTION = 'Show details of a specific rai design document'
+
+        ANNOTATIONS = {
+          'readOnlyHint' => true,
+          'destructiveHint' => false,
+          'idempotentHint' => true,
+          'openWorldHint' => false
+        }.freeze
+
+        INPUT_SCHEMA = {
+          type: 'object',
+          properties: {
+            name: {
+              type: 'string',
+              description: 'Design document name'
+            },
+            full: {
+              type: 'boolean',
+              description: 'Include full content (default: false)'
+            }
+          },
+          required: ['name']
+        }.freeze
+
+        # Executes the show operation.
+        #
+        # @param name [String] design document name (without .yml)
+        # @param full [Boolean] include acceptance criteria
+        # @return [Hash] design data or error
+        def call(name:, full: false)
+          path = RosettAi.root.join('conf', 'design', "#{name}.yml")
+          return ResponseHelper.error("Design document not found: #{name}") unless path.exist?
+
+          data = YAML.safe_load_file(path, permitted_classes: [Symbol])
+          result = {
+            name: data['name'],
+            description: data['description'],
+            status: data['status'],
+            priority: data['priority'],
+            domain: data['domain'],
+            version: data['version'],
+            file: path.basename.to_s
+          }
+          result[:acceptance_criteria] = Array(data['acceptance_criteria']) if full
+          result
+        rescue Psych::SyntaxError => e
+          ResponseHelper.error("YAML parse error in #{name}: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/tools/doctor_tool.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    module Tools
+      # MCP tool: run rosett-ai diagnostics.
+      #
+      # Executes system diagnostic checks and reports status.
+      # Read-only operation.
+      #
+      # @author hugo
+      # @author claude
+      class DoctorTool
+        TOOL_NAME = 'rai_doctor'
+        DESCRIPTION = 'Run rosett-ai diagnostic checks'
+
+        ANNOTATIONS = {
+          'readOnlyHint' => true,
+          'destructiveHint' => false,
+          'idempotentHint' => true,
+          'openWorldHint' => false
+        }.freeze
+
+        INPUT_SCHEMA = {
+          type: 'object',
+          properties: {
+            check: {
+              type: 'string',
+              description: 'Run a specific diagnostic check (default: all)'
+            },
+            format: {
+              type: 'string',
+              enum: ['json', 'text'],
+              description: 'Output format (default: json)'
+            }
+          }
+        }.freeze
+
+        # Executes diagnostic checks.
+        #
+        # @param check [String, nil] specific check to run
+        # @param format [String] output format ('json' or 'text')
+        # @return [Hash] diagnostic results
+        def call(check: nil, format: 'json')
+          results = RosettAi::Doctor.run_all(only: check)
+          failures = results.select { |r| r[:status] == 'fail' }
+          {
+            healthy: failures.empty?,
+            checks: results,
+            failures: failures,
+            format: format
+          }
+        rescue StandardError => e
+          ResponseHelper.error("Doctor check failed: #{e.message}")
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/tools/documentation_status_tool.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    module Tools
+      # MCP tool: show documentation status.
+      #
+      # Returns the current state of project documentation.
+      # Read-only operation.
+      #
+      # @author hugo
+      # @author claude
+      class DocumentationStatusTool
+        TOOL_NAME = 'rai_documentation_status'
+        DESCRIPTION = 'Show rai documentation status'
+
+        ANNOTATIONS = {
+          'readOnlyHint' => true,
+          'destructiveHint' => false,
+          'idempotentHint' => true,
+          'openWorldHint' => false
+        }.freeze
+
+        # Executes the documentation status check.
+        #
+        # @return [Hash] documentation status
+        def call
+          root = RosettAi.root
+          doc_dir = root.join('doc')
+          man_dir = root.join('doc', 'man')
+          {
+            doc_files: doc_dir.directory? ? doc_dir.glob('*.md').size : 0,
+            man_pages: man_dir.directory? ? man_dir.glob('*.ronn').size : 0,
+            changelog_exists: root.join('CHANGELOG.md').exist?,
+            readme_exists: root.join('README.md').exist?,
+            install_guide_exists: root.join('INSTALL.md').exist?
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/tools/engines_tool.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+module RosettAi
+  module Mcp
+    module Tools
+      # MCP tool: manage and query rai engines.
+      #
+      # Lists, detects, and shows status of installed engines.
+      # Read-only operation.
+      #
+      # @author hugo
+      # @author claude
+      class EnginesTool
+        TOOL_NAME = 'rosett_ai_engines'
+        DESCRIPTION = 'List, detect, or show status of rai engines'
+
+        ANNOTATIONS = {
+          'readOnlyHint' => true,
+          'destructiveHint' => false,
+          'idempotentHint' => true,
+          'openWorldHint' => false
+        }.freeze
+
+        VALID_ACTIONS = ['list', 'detect', 'status'].freeze
+
+        INPUT_SCHEMA = {
+          type: 'object',
+          properties: {
+            action: {
+              type: 'string',
+              enum: ['list', 'detect', 'status'],
+              description: 'Engine action (default: list)'
+            }
+          }
+        }.freeze
+
+        # Executes the engine query.
+        #
+        # @param action [String] one of 'list', 'detect', 'status'
+        # @return [Hash] engine information
+        def call(action: 'list')
+          return ResponseHelper.error("Invalid action: #{action}") unless VALID_ACTIONS.include?(action)
+
+          case action
+          when 'list' then action_list
+          when 'detect' then action_detect
+          when 'status' then action_status
+          end
+        rescue StandardError => e
+          ResponseHelper.error("Engine #{action} failed: #{e.message}")
+        end
+
+        private
+
+        def action_list
+          engines = RosettAi::Plugins::Registry.available(:engine)
+          { engines: engines.map { |name| { name: name } } }
+        end
+
+        def action_detect
+          RosettAi::Plugins::Registry.discover!
+          detected = RosettAi::Plugins::Registry.available(:engine)
+          { detected: detected }
+        end
+
+        def action_status
+          default = resolve_default_engine
+          installed = RosettAi::Plugins::Registry.available(:engine)
+          { default_engine: default, installed: installed.map { |name| { name: name } } }
+        end
+
+        # @return [String] default engine name
+        def resolve_default_engine
+          RosettAi.rai_config.default_engine
+        rescue StandardError => e
+          "unknown (#{e.message})"
+        end
+      end
+    end
+  end
+end

data/lib/rosett_ai/mcp/tools/hook_install_tool.rb

@@ -0,0 +1,190 @@
+# frozen_string_literal: true
+
+# SPDX-License-Identifier: GPL-3.0-only
+# Copyright (C) 2026 Hugo Antonio Sepulveda Manriquez / NeatNerds
+
+require 'json'
+require 'fileutils'
+require 'time'
+
+module RosettAi
+  module Mcp
+    module Tools
+      # MCP tool: install enforcement hook + register in settings.json.
+      #
+      # MUTATION tool — writes hook script to disk and updates Claude Code
+      # settings.json. Auto-backs up affected files before writing.
+      # Confirmation is required by default.
+      #
+      # @author hugo
+      # @author claude
+      class HookInstallTool
+        TOOL_NAME = 'rai_hook_install'
+        DESCRIPTION = 'Install enforcement hook: generate script, write to disk, register in settings'
+
+        ANNOTATIONS = {
+          'readOnlyHint' => false,
+          'destructiveHint' => true,
+          'idempotentHint' => true,
+          'openWorldHint' => false
+        }.freeze
+
+        INPUT_SCHEMA = {
+          type: 'object',
+          properties: {
+            behaviour_name: {
+              type: 'string',
+              description: 'Behaviour to generate hook for (default: all enforceable)'
+            },
+            rule_id: {
+              type: 'string',
+              description: 'Specific rule ID to generate hook for'
+            },
+            scope: {
+              type: 'string',
+              enum: ['global', 'local'],
+              description: 'Installation scope (default: global)'
+            },
+            confirm: {
+              type: 'boolean',
+              description: 'Must be true to actually install — safety gate (default: false)'
+            }
+          }
+        }.freeze
+
+        HOOK_DIR_NAME = 'hooks'
+        HOOK_FILENAME = 'rai-enforce.rb'
+        BACKUP_SUFFIX = '.rai-backup'
+
+        # Installs the enforcement hook.
+        #
+        # @param behaviour_name [String, nil] specific behaviour
+        # @param rule_id [String, nil] specific rule
+        # @param scope [String] installation scope ('global' or 'project')
+        # @param confirm [Boolean] must be true to proceed (default false)
+        # @return [Hash] installation result with paths and backup info
+        def call(behaviour_name: nil, rule_id: nil, scope: 'global', confirm: false)
+          return confirmation_required_response unless confirm
+
+          preview = HookPreviewTool.new.call(
+            behaviour_name: behaviour_name, rule_id: rule_id, scope: scope
+          )
+          return preview if preview[:error]
+
+          hook_path = resolve_hook_path(scope)
+          backup_path = backup_existing(hook_path)
+          write_hook(hook_path, preview[:script])
+          settings_diff = register_in_settings(hook_path, scope)
+
+          {
+            installed: true,
+            hook_path: hook_path.to_s,
+            backup_path: backup_path&.to_s,
+            rules_count: preview[:rules_count],
+            behaviours: preview[:behaviours],
+            scope: scope,
+            settings_updated: settings_diff[:updated],
+            message: "Hook installed at #{hook_path} with #{preview[:rules_count]} rule(s)"
+          }
+        rescue StandardError => e
+          ResponseHelper.error("Hook install failed: #{e.message}")
+        end
+
+        private
+
+        # @return [Hash] response requiring confirmation
+        def confirmation_required_response
+          {
+            error: true,
+            confirmation_required: true,
+            message: 'Hook installation requires confirm: true. ' \
+                     'Use rai_hook_preview first to review the script.'
+          }
+        end
+
+        # @param scope [String]
+        # @return [Pathname]
+        def resolve_hook_path(scope)
+          base = scope == 'project' ? project_hooks_dir : global_hooks_dir
+          FileUtils.mkdir_p(base)
+          base.join(HOOK_FILENAME)
+        end
+
+        # @return [Pathname]
+        def global_hooks_dir
+          RosettAi.paths.global_dir.join(HOOK_DIR_NAME)
+        end
+
+        # @return [Pathname]
+        def project_hooks_dir
+          RosettAi.context.project_root.join('.claude', HOOK_DIR_NAME)
+        end
+
+        # Backs up existing hook file before overwriting.
+        #
+        # @param hook_path [Pathname]
+        # @return [Pathname, nil] backup path or nil if no backup needed
+        def backup_existing(hook_path)
+          return nil unless hook_path.exist?
+
+          timestamp = Time.now.utc.strftime('%Y%m%d%H%M%S')
+          backup = Pathname.new("#{hook_path}#{BACKUP_SUFFIX}.#{timestamp}")
+          FileUtils.cp(hook_path, backup)
+          backup
+        end
+
+        # @param hook_path [Pathname]
+        # @param content [String]
+        def write_hook(hook_path, content)
+          FileUtils.mkdir_p(hook_path.dirname)
+          File.write(hook_path, content)
+          FileUtils.chmod(0o755, hook_path)
+        end
+
+        # Registers the hook in settings.json if not already present.
+        #
+        # @param hook_path [Pathname]
+        # @param scope [String]
+        # @return [Hash] diff info
+        def register_in_settings(hook_path, scope)
+          settings_path = resolve_settings_path(scope)
+          return { updated: false, reason: 'settings file not found' } unless settings_path.exist?
+
+          settings = JSON.parse(settings_path.read)
+          hooks = settings['hooks'] ||= {}
+          pre_tool = hooks['PreToolUse'] ||= []
+
+          hook_entry = build_hook_entry(hook_path)
+
+          if pre_tool.any? { |h| h['command'] == hook_entry['command'] }
+            return { updated: false, reason: 'hook already registered' }
+          end
+
+          pre_tool << hook_entry
+          File.write(settings_path, JSON.pretty_generate(settings))
+          { updated: true, settings_path: settings_path.to_s }
+        end
+
+        # @param scope [String]
+        # @return [Pathname]
+        def resolve_settings_path(scope)
+          if scope == 'project'
+            RosettAi.context.project_root.join('.claude', 'settings.json')
+          else
+            RosettAi.paths.global_dir.join('settings.json')
+          end
+        end
+
+        # @param hook_path [Pathname]
+        # @return [Hash]
+        def build_hook_entry(hook_path)
+          {
+            'type' => 'command',
+            'command' => "ruby #{hook_path}",
+            'description' => 'Rosett-AI enforcement hook'
+          }
+        end
+      end
+    end
+  end
+end