jirametrics 2.26.1 → 2.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 960ce78e94ec2c7e87875bd0dc6db2c16b11cee0e4c4dd5a22d8bf3bab1c893d
-  data.tar.gz: f5b2d9aac4d9059654ad7a569d477b0b689c8d22f30760867aec9e13b3f1db61
+  metadata.gz: d93d43ce61e0fcec89c5ee737044cff4007b1f0079be2c6be774c56cb15130e8
+  data.tar.gz: ffbe1b15fc8aa08f928e7c322cf53dc5a1646b9da01b7b9e81e8b5bd2c44650d
 SHA512:
-  metadata.gz: 727e2f5b3e57e937eacd05d868ff1f7a75e16210f0e46e75117a88e56287fb765238753710289d9fb2f09b38d6e940f47d0ae2689be313b1282238727ddae0eb
-  data.tar.gz: d60771157926c74a7ac45d12ea023eef1808b4ea027f8edd6fba6108a79b2f0df8bdb054bf58049cc8a3f3de44e4926dd0af0a40b95b25fb07ed1391d829418b
+  metadata.gz: 66d0c9c0db9b11c4278935a8342cae5f9b6b4e34fffc46d1bad6b719b6ca779374191f05f4139caf28995e8014ab77cfea79945df9abe546405abf9e381e4311
+  data.tar.gz: 3f10707f9b44c14dd8dae67ce73cd208cb7554cee147d502f3b99315b49cb524aa6f12662c1624720f204e814a5686e37393f907da8ec43f1befc88398a79cc7

data/bin/jirametrics-mcp

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'jirametrics'
+JiraMetrics.start(['mcp'] + ARGV)

data/lib/jirametrics/chart_base.rb

@@ -377,7 +377,7 @@ class ChartBase
   end
 
   def seam_start type = 'chart'
-    "\n<!-- seam-start | chart#{@@chart_counter} | #{self.class} | #{header_text} | #{type} -->"
+    "\n<!-- seam-start | chart#{@@chart_counter} | #{self.class} | #{header_text} | #{type} -->\n"
   end
 
   def seam_end type = 'chart'

data/lib/jirametrics/cumulative_flow_diagram.rb

@@ -69,6 +69,9 @@ class CumulativeFlowDiagram < ChartBase
         When the cursor is near the right edge and that point falls outside the visible date range,
         CT and TP cannot be calculated and are hidden; only WIP is shown.
       </div>
+      <div class="p">
+        See also: This article on <a href="https://blog.mikebowler.ca/2026/03/27/cumulative-flow-diagram/">how to read a CFD</a>.
+      </div>      
     HTML
     instance_eval(&block)
   end

data/lib/jirametrics/daily_view.rb

@@ -87,13 +87,14 @@ class DailyView < ChartBase
       lines << ["#{marker} Blocked by flag"] if blocked_stalled.flag
       lines << ["#{marker} Blocked by status: #{blocked_stalled.status}"] if blocked_stalled.blocked_by_status?
       blocked_stalled.blocking_issue_keys&.each do |key|
-        blocking_issue = issues.find { |i| i.key == key }
+        blocking_issue = issues.find_by_key key: key, include_hidden: true
         if blocking_issue
-          lines << "<section><div class=\"foldable startFolded\">#{marker} Blocked by issue: #{key}</div>"
+          lines << "<section><div class=\"foldable startFolded\">#{marker} Blocked by issue: " \
+            "#{make_issue_label issue: blocking_issue, done: blocking_issue.done?}</div>"
           lines << blocking_issue
           lines << '</section>'
         else
-          lines << ["#{marker} Blocked by issue: #{key}"]
+          lines << ["#{marker} Blocked by issue: #{key} (no description found)"]
         end
       end
     elsif blocked_stalled.stalled_by_status?

data/lib/jirametrics/downloader_for_cloud.rb

@@ -108,11 +108,24 @@ class DownloaderForCloud < Downloader
       }
       issue = Issue.new(raw: issue_json, board: board)
       data = issue_datas.find { |d| d.key == issue.key }
+      unless data
+        log "  Skipping #{issue.key}: returned by Jira but key not in request (issue may have been moved)"
+        next
+      end
       data.up_to_date = true
       data.last_modified = issue.updated
       data.issue = issue
     end
 
+    # Mark any unmatched requests as up_to_date to prevent infinite re-fetching.
+    # This happens when Jira returns a different key (moved issue) leaving the original unmatched.
+    issue_datas.each do |data|
+      next if data.up_to_date
+
+      log "  Skipping #{data.key}: not returned by Jira (issue may have been deleted or moved)"
+      data.up_to_date = true
+    end
+
     issue_datas
   end
 
@@ -168,15 +181,20 @@ class DownloaderForCloud < Downloader
 
     issue_data_hash = search_for_issues jql: jql, board_id: board.id, path: path
 
+    checked_for_related = Set.new
+    in_related_phase = false
+
     loop do
       related_issue_keys = Set.new
       stale = issue_data_hash.values.reject { |data| data.up_to_date }
       unless stale.empty?
-        log_start '  Downloading more issues '
+        log_start '  Downloading more issues ' unless in_related_phase
         stale.each_slice(100) do |slice|
           slice = bulk_fetch_issues(issue_datas: slice, board: board, in_initial_query: true)
           progress_dot
           slice.each do |data|
+            next unless data.issue
+
             @file_system.save_json(
               json: data.issue.raw, filename: data.cache_path
             )
@@ -184,22 +202,25 @@ class DownloaderForCloud < Downloader
             # to parse the file just to find the timestamp
             @file_system.utime time: data.issue.updated, file: data.cache_path
 
-            issue = data.issue
-            next unless issue
-
-            parent_key = issue.parent_key(project_config: @download_config.project_config)
-            related_issue_keys << parent_key if parent_key
-
-            # Sub-tasks
-            issue.raw['fields']['subtasks']&.each do |raw_subtask|
-              related_issue_keys << raw_subtask['key']
-            end
+            collect_related_issue_keys issue: data.issue, related_issue_keys: related_issue_keys
+            checked_for_related << data.key
           end
         end
-        end_progress
+        end_progress unless in_related_phase
       end
 
-      # Remove all the ones we already downloaded
+      # Also scan up-to-date cached issues we haven't checked yet — they may reference
+      # related issues that are not in the primary query result.
+      issue_data_hash.each_value do |data|
+        next if checked_for_related.include?(data.key)
+        next unless @file_system.file_exist?(data.cache_path)
+
+        checked_for_related << data.key
+        raw = @file_system.load_json(data.cache_path)
+        collect_related_issue_keys issue: Issue.new(raw: raw, board: board), related_issue_keys: related_issue_keys
+      end
+
+      # Remove all the ones we already have
       related_issue_keys.reject! { |key| issue_data_hash[key] }
 
       related_issue_keys.each do |key|
@@ -211,9 +232,15 @@ class DownloaderForCloud < Downloader
       end
       break if related_issue_keys.empty?
 
-      log "  Downloading linked issues for board #{board.id}", both: true
+      unless in_related_phase
+        in_related_phase = true
+        log "  Identifying related issues (parents, subtasks, links) for board #{board.id}", both: true
+        log_start '  Downloading more issues '
+      end
     end
 
+    end_progress if in_related_phase
+
     delete_issues_from_cache_that_are_not_in_server(
       issue_data_hash: issue_data_hash, path: path
     )
@@ -238,6 +265,22 @@ class DownloaderForCloud < Downloader
     end
   end
 
+  def collect_related_issue_keys issue:, related_issue_keys:
+    parent_key = issue.parent_key(project_config: @download_config.project_config)
+    related_issue_keys << parent_key if parent_key
+
+    issue.raw['fields']['subtasks']&.each do |raw_subtask|
+      related_issue_keys << raw_subtask['key']
+    end
+
+    issue.raw['fields']['issuelinks']&.each do |link|
+      next if link['type']['name'] == 'Cloners'
+
+      linked = link['inwardIssue'] || link['outwardIssue']
+      related_issue_keys << linked['key'] if linked
+    end
+  end
+
   def last_modified filename:
     File.mtime(filename) if File.exist?(filename)
   end

data/lib/jirametrics/examples/aggregated_project.rb

@@ -10,7 +10,7 @@
 class Exporter
   def aggregated_project name:, project_names:, settings: {}
     project name: name do
-      puts name
+      file_system.log name
       file_prefix name
       self.settings.merge! stringify_keys(settings)
 

data/lib/jirametrics/examples/standard_project.rb

@@ -9,7 +9,7 @@ class Exporter
       show_experimental_charts: false, github_repos: nil
     exporter = self
     project name: name do
-      puts name
+      file_system.log name
       file_prefix file_prefix
 
       self.anonymize if anonymize
@@ -35,7 +35,7 @@ class Exporter
       download do
         self.rolling_date_count(rolling_date_count) if rolling_date_count
         self.no_earlier_than(no_earlier_than) if no_earlier_than
-        github_repo github_repos if github_repos
+        github_repo *github_repos if github_repos
       end
 
       issues.reject! do |issue|

data/lib/jirametrics/file_system.rb

@@ -3,13 +3,14 @@
 require 'json'
 
 class FileSystem
-  attr_accessor :logfile, :logfile_name
+  attr_accessor :logfile, :logfile_name, :log_only
 
   def initialize
     # In almost all cases, this will be immediately replaced in the Exporter
     # but if we fail before we get that far, this will at least let a useful
     # error show up on the console.
     @logfile = $stdout
+    @log_only = false
   end
 
   # Effectively the same as File.read except it forces the encoding to UTF-8
@@ -59,7 +60,7 @@ class FileSystem
 
     logfile.puts message
     logfile.puts more if more
-    return unless also_write_to_stderr
+    return if log_only || !also_write_to_stderr
 
     # Obscure edge-case where we're trying to log something before logging is even
     # set up. Quick escape here so that we don't dump the error twice.
@@ -70,23 +71,29 @@ class FileSystem
 
   def log_start message
     logfile.puts message
-    return if logfile == $stdout
+    return if log_only || logfile == $stdout
 
     $stderr.print message
     $stderr.flush
   end
 
   def start_progress
+    return if log_only
+
     $stderr.print '  '
     $stderr.flush
   end
 
   def progress_dot
+    return if log_only
+
     $stderr.print '.'
     $stderr.flush
   end
 
   def end_progress
+    return if log_only
+
     $stderr.puts '' # rubocop:disable Style/StderrPuts
   end
 

data/lib/jirametrics/github_gateway.rb

@@ -64,9 +64,10 @@ class GithubGateway
       raw_pr['body']
     ]
 
-    sources.compact
-           .flat_map { |s| s.scan(@issue_key_pattern) }
-           .uniq
+    keys = sources.compact.flat_map { |s| s.scan(@issue_key_pattern) }.uniq
+    return keys unless keys.empty?
+
+    commit_messages_for(raw_pr['number']).flat_map { |msg| msg.scan(@issue_key_pattern) }.uniq
   end
 
   def extract_reviews raw_reviews
@@ -83,11 +84,19 @@ class GithubGateway
 
   private
 
+  def commit_messages_for pr_number
+    args = ['pr', 'view', pr_number.to_s, '--json', 'commits', '--repo', @repo]
+    result = run_command(args)
+    (result['commits'] || []).flat_map do |commit|
+      [commit['messageHeadline'], commit['messageBody']].compact
+    end
+  end
+
   def build_issue_key_pattern
     return nil if @project_keys.empty?
 
     keys_pattern = @project_keys.map { |k| Regexp.escape(k) }.join('|')
-    Regexp.new("\\b(?:#{keys_pattern})-\\d+\\b")
+    Regexp.new("\\b(?:#{keys_pattern})-\\d+(?![A-Za-z0-9])")
   end
 
   def run_command args

data/lib/jirametrics/html/index.js

@@ -35,7 +35,7 @@ function makeFoldable() {
     const toggleButton = document.createElement(element.tagName); //'button');
     toggleButton.id = toggleId;
     toggleButton.className = 'foldable-toggle-btn';
-    toggleButton.innerHTML = '▼ ' + element.textContent;
+    toggleButton.innerHTML = '▼ ' + element.innerHTML;
     
     // Create a content container
     const contentContainer = document.createElement('div');

data/lib/jirametrics/html/time_based_scatterplot.erb

@@ -28,15 +28,20 @@ new Chart(document.getElementById('<%= chart_id %>').getContext('2d'), {
         max: "<%= (date_range.end + 1).to_s %>"
       },
       y: {
+        min: 0,
+        max: <%= (@highest_y_value * 1.1).ceil %>,
         scaleLabel: {
-          display: true,
-          min: 0,
-          max: <%= @highest_y_value %>
+          display: true
         },
         <%= render_axis_title :y %>
         grid: {
           color: <%= CssVariable['--grid-line-color'].to_json %>
         },
+        ticks: {
+          callback: function(value, index, ticks) {
+            return index === ticks.length - 1 ? null : value;
+          }
+        }
       }
     },
     plugins: {

data/lib/jirametrics/issue.rb

@@ -210,7 +210,25 @@ class Issue
   end
 
   def first_time_visible_on_board
-    first_time_in_status(*board.visible_columns.collect(&:status_ids).flatten)
+    visible_status_ids = board.visible_columns.collect(&:status_ids).flatten
+    return first_time_in_status(*visible_status_ids) unless board.scrum?
+
+    # For scrum boards, an issue is only visible when BOTH conditions are true simultaneously:
+    # 1. Its status is in a visible column
+    # 2. It is in an active sprint
+    # At each moment one condition becomes true, check if the other is already true.
+    candidates = []
+
+    status_changes.each do |change|
+      next unless visible_status_ids.include?(change.value_id)
+      candidates << change if in_active_sprint_at?(change.time)
+    end
+
+    sprint_entry_events.each do |effective_time, representative_change|
+      candidates << representative_change if in_visible_status_at?(effective_time, visible_status_ids)
+    end
+
+    candidates.min_by(&:time)
   end
 
   def reasons_not_visible_on_board
@@ -815,6 +833,72 @@ class Issue
 
   private
 
+  # Returns [[effective_time, change_item]] for each moment the issue entered an active sprint.
+  # Skips sprints that were removed before they activated.
+  def sprint_entry_events
+    data_clazz = Struct.new(:sprint_id, :sprint_start, :add_time, :change)
+    events = []
+    in_sprint = []
+
+    @changes.each do |change|
+      next unless change.sprint?
+
+      (change.value_id - change.old_value_id).each do |sprint_id|
+        sprint_start, = find_sprint_start_end(sprint_id: sprint_id, change: change)
+        in_sprint << data_clazz.new(sprint_id, sprint_start, change.time, change) if sprint_start
+      end
+
+      (change.old_value_id - change.value_id).each do |sprint_id|
+        data = in_sprint.find { |d| d.sprint_id == sprint_id }
+        next unless data
+
+        in_sprint.delete(data)
+        next if data.sprint_start >= change.time # sprint hadn't activated before removal
+
+        effective_time = [data.add_time, data.sprint_start].max
+        events << [effective_time, sprint_change_at(effective_time, data.change)]
+      end
+    end
+
+    in_sprint.each do |data|
+      effective_time = [data.add_time, data.sprint_start].max
+      events << [effective_time, sprint_change_at(effective_time, data.change)]
+    end
+
+    events
+  end
+
+  def sprint_change_at effective_time, change
+    return change if effective_time == change.time
+
+    ChangeItem.new(
+      raw: { 'field' => 'Sprint', 'toString' => 'Sprint activated', 'to' => '0', 'from' => nil, 'fromString' => nil },
+      author_raw: nil,
+      time: effective_time,
+      artificial: true
+    )
+  end
+
+  def in_active_sprint_at? time
+    active_ids = []
+    @changes.each do |change|
+      break if change.time > time
+      next unless change.sprint?
+
+      (change.value_id - change.old_value_id).each do |sprint_id|
+        sprint_start, = find_sprint_start_end(sprint_id: sprint_id, change: change)
+        active_ids << sprint_id if sprint_start && sprint_start <= time
+      end
+      (change.old_value_id - change.value_id).each { |id| active_ids.delete(id) }
+    end
+    active_ids.any?
+  end
+
+  def in_visible_status_at? time, visible_status_ids
+    last = status_changes.reverse.find { |c| c.time <= time }
+    last && visible_status_ids.include?(last.value_id)
+  end
+
   def load_history_into_changes
     @raw['changelog']['histories']&.each do |history|
       created = parse_time(history['created'])

data/lib/jirametrics/mcp_server.rb

@@ -0,0 +1,531 @@
+# frozen_string_literal: true
+
+require 'mcp'
+require 'mcp/server/transports/stdio_transport'
+
+class McpServer
+  def initialize projects:, aggregates: {}, timezone_offset: '+00:00'
+    @projects = projects
+    @aggregates = aggregates
+    @timezone_offset = timezone_offset
+  end
+
+  def run
+    canonical_tools = [ListProjectsTool, AgingWorkTool, CompletedWorkTool, NotYetStartedTool, StatusTimeAnalysisTool]
+    alias_tools = ALIASES.map do |alias_name, canonical|
+      schema = canonical.input_schema
+      Class.new(canonical) do
+        tool_name alias_name
+        input_schema schema
+      end
+    end
+
+    server = MCP::Server.new(
+      name: 'jirametrics',
+      version: Gem.loaded_specs['jirametrics']&.version&.to_s || '0.0.0',
+      tools: canonical_tools + alias_tools,
+      server_context: { projects: @projects, aggregates: @aggregates, timezone_offset: @timezone_offset }
+    )
+
+    transport = MCP::Server::Transports::StdioTransport.new(server)
+    transport.open
+  end
+
+  HISTORY_FILTER_SCHEMA = {
+    history_field: {
+      type: 'string',
+      description: 'When combined with history_value, only return issues where this field ever had that value ' \
+                   '(e.g. "priority", "status"). Both history_field and history_value must be provided together.'
+    },
+    history_value: {
+      type: 'string',
+      description: 'The value to look for in the change history of history_field (e.g. "Highest", "Done").'
+    },
+    ever_blocked: {
+      type: 'boolean',
+      description: 'When true, only return issues that were ever blocked. Blocked includes flagged items, ' \
+                   'issues in blocked statuses, and blocking issue links.'
+    },
+    ever_stalled: {
+      type: 'boolean',
+      description: 'When true, only return issues that were ever stalled. Stalled means the issue sat ' \
+                   'inactive for longer than the stalled threshold, or entered a stalled status.'
+    },
+    currently_blocked: {
+      type: 'boolean',
+      description: 'When true, only return issues that are currently blocked (as of the data end date).'
+    },
+    currently_stalled: {
+      type: 'boolean',
+      description: 'When true, only return issues that are currently stalled (as of the data end date).'
+    }
+  }.freeze
+
+  def self.resolve_projects server_context, project_filter
+    return nil if project_filter.nil?
+
+    aggregates = server_context[:aggregates] || {}
+    aggregates[project_filter] || [project_filter]
+  end
+
+  def self.column_name_for board, status_id
+    board.visible_columns.find { |c| c.status_ids.include?(status_id) }&.name
+  end
+
+  def self.time_per_column issue, end_time
+    changes = issue.status_changes
+    _, stopped = issue.started_stopped_times
+    effective_end = stopped && stopped < end_time ? stopped : end_time
+    board = issue.board
+
+    result = Hash.new(0.0)
+
+    if changes.empty?
+      col = column_name_for(board, issue.status.id) || issue.status.name
+      duration = effective_end - issue.created
+      result[col] += duration if duration.positive?
+      return result
+    end
+
+    first_change = changes.first
+    initial_col = column_name_for(board, first_change.old_value_id) || first_change.old_value
+    initial_duration = first_change.time - issue.created
+    result[initial_col] += initial_duration if initial_duration.positive?
+
+    changes.each_cons(2) do |prev_change, next_change|
+      col = column_name_for(board, prev_change.value_id) || prev_change.value
+      duration = next_change.time - prev_change.time
+      result[col] += duration if duration.positive?
+    end
+
+    last_change = changes.last
+    final_col = column_name_for(board, last_change.value_id) || last_change.value
+    final_duration = effective_end - last_change.time
+    result[final_col] += final_duration if final_duration.positive?
+
+    result
+  end
+
+  def self.time_per_status issue, end_time
+    changes = issue.status_changes
+    _, stopped = issue.started_stopped_times
+    effective_end = stopped && stopped < end_time ? stopped : end_time
+
+    result = Hash.new(0.0)
+
+    if changes.empty?
+      duration = effective_end - issue.created
+      result[issue.status.name] += duration if duration.positive?
+      return result
+    end
+
+    first_change = changes.first
+    initial_duration = first_change.time - issue.created
+    result[first_change.old_value] += initial_duration if initial_duration.positive?
+
+    changes.each_cons(2) do |prev_change, next_change|
+      duration = next_change.time - prev_change.time
+      result[prev_change.value] += duration if duration.positive?
+    end
+
+    last_change = changes.last
+    final_duration = effective_end - last_change.time
+    result[last_change.value] += final_duration if final_duration.positive?
+
+    result
+  end
+
+  def self.flow_efficiency_percent issue, end_time
+    active_time, total_time = issue.flow_efficiency_numbers(end_time: end_time)
+    total_time.positive? ? (active_time / total_time * 100).round(1) : nil
+  end
+
+  def self.matches_blocked_stalled?(bsc, ever_blocked, ever_stalled, currently_blocked, currently_stalled)
+    return false if ever_blocked && bsc.none?(&:blocked?)
+    return false if ever_stalled && bsc.none?(&:stalled?)
+    return false if currently_blocked && !bsc.last&.blocked?
+    return false if currently_stalled && !bsc.last&.stalled?
+
+    true
+  end
+
+  def self.matches_history?(issue, end_time, history_field, history_value,
+                            ever_blocked, ever_stalled, currently_blocked, currently_stalled)
+    return false if history_field && history_value &&
+                    issue.changes.none? { |c| c.field == history_field && c.value == history_value }
+
+    if ever_blocked || ever_stalled || currently_blocked || currently_stalled
+      bsc = issue.blocked_stalled_changes(end_time: end_time)
+      return false unless matches_blocked_stalled?(bsc, ever_blocked, ever_stalled,
+                                                   currently_blocked, currently_stalled)
+    end
+
+    true
+  end
+
+  class ListProjectsTool < MCP::Tool
+    tool_name 'list_projects'
+    description 'Lists all available projects with basic metadata. Call this first when the user asks a ' \
+                'question that could apply to multiple projects, so you can clarify which one they mean.'
+
+    input_schema(type: 'object', properties: {})
+
+    def self.call(server_context:, **)
+      lines = server_context[:projects].map do |project_name, project_data|
+        "#{project_name} | #{project_data[:issues].size} issues | Data through: #{project_data[:today]}"
+      end
+
+      aggregates = server_context[:aggregates] || {}
+      unless aggregates.empty?
+        lines << ''
+        lines << 'Aggregate groups (can be used as a project filter):'
+        aggregates.each do |name, constituent_names|
+          lines << "#{name} | includes: #{constituent_names.join(', ')}"
+        end
+      end
+
+      MCP::Tool::Response.new([{ type: 'text', text: lines.join("\n") }])
+    end
+  end
+
+  class AgingWorkTool < MCP::Tool
+    tool_name 'aging_work'
+    description 'Returns all issues that have been started but not yet completed (work in progress), ' \
+                'sorted from oldest to newest. Age is the number of days since the issue was started.'
+
+    input_schema(
+      type: 'object',
+      properties: {
+        min_age_days: {
+          type: 'integer',
+          description: 'Only return issues at least this many days old. Omit to return all ages.'
+        },
+        project: {
+          type: 'string',
+          description: 'Only return issues from this project name. Omit to return all projects.'
+        },
+        current_status: {
+          type: 'string',
+          description: 'Only return issues currently in this status (e.g. "Review", "In Progress").'
+        },
+        current_column: {
+          type: 'string',
+          description: 'Only return issues whose current status maps to this board column (e.g. "In Progress").'
+        },
+        **HISTORY_FILTER_SCHEMA
+      }
+    )
+
+    def self.call(server_context:, min_age_days: nil, project: nil, project_name: nil,
+                  current_status: nil, current_column: nil,
+                  history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
+                  currently_blocked: nil, currently_stalled: nil, **)
+      project ||= project_name
+      rows = []
+      allowed_projects = McpServer.resolve_projects(server_context, project)
+
+      server_context[:projects].each do |project_name, project_data|
+        next if allowed_projects && !allowed_projects.include?(project_name)
+
+        today = project_data[:today]
+        project_data[:issues].each do |issue|
+          started, stopped = issue.started_stopped_times
+          next unless started && !stopped
+          next if current_status && issue.status.name != current_status
+          next if current_column && McpServer.column_name_for(issue.board, issue.status.id) != current_column
+
+          age = (today - started.to_date).to_i + 1
+          next if min_age_days && age < min_age_days
+          unless McpServer.matches_history?(issue, project_data[:end_time],
+                                            history_field, history_value, ever_blocked, ever_stalled,
+                                            currently_blocked, currently_stalled)
+            next
+          end
+
+          rows << {
+            key: issue.key,
+            summary: issue.summary,
+            status: issue.status.name,
+            type: issue.type,
+            age_days: age,
+            flow_efficiency: McpServer.flow_efficiency_percent(issue, project_data[:end_time]),
+            project: project_name
+          }
+        end
+      end
+
+      rows.sort_by! { |r| -r[:age_days] }
+
+      if rows.empty?
+        text = 'No aging work found.'
+      else
+        lines = rows.map do |r|
+          fe = r[:flow_efficiency] ? " | FE: #{r[:flow_efficiency]}%" : ''
+          "#{r[:key]} | #{r[:project]} | #{r[:type]} | #{r[:status]} | Age: #{r[:age_days]}d#{fe} | #{r[:summary]}"
+        end
+        text = lines.join("\n")
+      end
+
+      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    end
+  end
+
+  class CompletedWorkTool < MCP::Tool
+    tool_name 'completed_work'
+    description 'Returns issues that have been completed, sorted most recently completed first. ' \
+                'Includes cycle time (days from start to completion).'
+
+    input_schema(
+      type: 'object',
+      properties: {
+        days_back: {
+          type: 'integer',
+          description: 'Only return issues completed within this many days of the data end date. Omit to return all.'
+        },
+        project: {
+          type: 'string',
+          description: 'Only return issues from this project name. Omit to return all projects.'
+        },
+        completed_status: {
+          type: 'string',
+          description: 'Only return issues whose status at completion matches this value (e.g. "Cancelled", "Done").'
+        },
+        completed_resolution: {
+          type: 'string',
+          description: 'Only return issues whose resolution at completion matches this value (e.g. "Won\'t Do").'
+        },
+        **HISTORY_FILTER_SCHEMA
+      }
+    )
+
+    def self.build_row issue, project_name, started, stopped, cutoff, completed_status, completed_resolution,
+                       end_time, history_field, history_value, ever_blocked, ever_stalled,
+                       currently_blocked, currently_stalled
+      completed_date = stopped.to_date
+      return nil if cutoff && completed_date < cutoff
+
+      status_at_done, resolution_at_done = issue.status_resolution_at_done
+      return nil if completed_status && status_at_done&.name != completed_status
+      return nil if completed_resolution && completed_resolution != resolution_at_done
+      return nil unless McpServer.matches_history?(issue, end_time,
+                                                   history_field, history_value, ever_blocked, ever_stalled,
+                                                   currently_blocked, currently_stalled)
+
+      cycle_time = started ? (completed_date - started.to_date).to_i + 1 : nil
+      {
+        key: issue.key,
+        summary: issue.summary,
+        type: issue.type,
+        completed_date: completed_date,
+        cycle_time_days: cycle_time,
+        flow_efficiency: McpServer.flow_efficiency_percent(issue, stopped),
+        status_at_done: status_at_done&.name,
+        resolution_at_done: resolution_at_done,
+        project: project_name
+      }
+    end
+
+    def self.call(server_context:, days_back: nil, project: nil, project_name: nil,
+                  completed_status: nil, completed_resolution: nil,
+                  history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
+                  currently_blocked: nil, currently_stalled: nil, **)
+      project ||= project_name
+      rows = []
+      allowed_projects = McpServer.resolve_projects(server_context, project)
+
+      server_context[:projects].each do |project_name, project_data|
+        next if allowed_projects && !allowed_projects.include?(project_name)
+
+        today = project_data[:today]
+        cutoff = today - days_back if days_back
+
+        project_data[:issues].each do |issue|
+          started, stopped = issue.started_stopped_times
+          next unless stopped
+
+          row = build_row(issue, project_name, started, stopped, cutoff, completed_status, completed_resolution,
+                          project_data[:end_time], history_field, history_value, ever_blocked, ever_stalled,
+                          currently_blocked, currently_stalled)
+          rows << row if row
+        end
+      end
+
+      rows.sort_by! { |r| -r[:completed_date].to_time.to_i }
+
+      if rows.empty?
+        text = 'No completed work found.'
+      else
+        lines = rows.map do |r|
+          ct = r[:cycle_time_days] ? "#{r[:cycle_time_days]}d" : 'unknown'
+          fe = r[:flow_efficiency] ? " | FE: #{r[:flow_efficiency]}%" : ''
+          completion = [r[:status_at_done], r[:resolution_at_done]].compact.join(' / ')
+          "#{r[:key]} | #{r[:project]} | #{r[:type]} | #{r[:completed_date]} | " \
+            "Cycle time: #{ct}#{fe} | #{completion} | #{r[:summary]}"
+        end
+        text = lines.join("\n")
+      end
+
+      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    end
+  end
+
+  class NotYetStartedTool < MCP::Tool
+    tool_name 'not_yet_started'
+    description 'Returns issues that have not yet been started (backlog items), sorted by creation date oldest first.'
+
+    input_schema(
+      type: 'object',
+      properties: {
+        project: {
+          type: 'string',
+          description: 'Only return issues from this project name. Omit to return all projects.'
+        },
+        current_status: {
+          type: 'string',
+          description: 'Only return issues currently in this status (e.g. "To Do", "Backlog").'
+        },
+        current_column: {
+          type: 'string',
+          description: 'Only return issues whose current status maps to this board column.'
+        },
+        **HISTORY_FILTER_SCHEMA
+      }
+    )
+
+    def self.call(server_context:, project: nil, project_name: nil, current_status: nil, current_column: nil,
+                  history_field: nil, history_value: nil, ever_blocked: nil, ever_stalled: nil,
+                  currently_blocked: nil, currently_stalled: nil, **)
+      project ||= project_name
+      rows = []
+      allowed_projects = McpServer.resolve_projects(server_context, project)
+
+      server_context[:projects].each do |project_name, project_data|
+        next if allowed_projects && !allowed_projects.include?(project_name)
+
+        project_data[:issues].each do |issue|
+          started, stopped = issue.started_stopped_times
+          next if started || stopped
+          next if current_status && issue.status.name != current_status
+          next if current_column && McpServer.column_name_for(issue.board, issue.status.id) != current_column
+          unless McpServer.matches_history?(issue, project_data[:end_time],
+                                            history_field, history_value, ever_blocked, ever_stalled,
+                                            currently_blocked, currently_stalled)
+            next
+          end
+
+          rows << {
+            key: issue.key,
+            summary: issue.summary,
+            status: issue.status.name,
+            type: issue.type,
+            created: issue.created.to_date,
+            project: project_name
+          }
+        end
+      end
+
+      rows.sort_by! { |r| r[:created] }
+
+      if rows.empty?
+        text = 'No unstarted work found.'
+      else
+        lines = rows.map do |r|
+          "#{r[:key]} | #{r[:project]} | #{r[:type]} | #{r[:status]} | Created: #{r[:created]} | #{r[:summary]}"
+        end
+        text = lines.join("\n")
+      end
+
+      MCP::Tool::Response.new([{ type: 'text', text: text }])
+    end
+  end
+
+  class StatusTimeAnalysisTool < MCP::Tool
+    tool_name 'status_time_analysis'
+    description 'Aggregates the time issues spend in each status or column, ranked by average days. ' \
+                'Useful for identifying bottlenecks. Before calling this tool, always ask the user ' \
+                'which issues they want to include: aging (in progress), completed, not yet started, ' \
+                'or all. Do not assume — the answer changes the result significantly.'
+
+    input_schema(
+      type: 'object',
+      properties: {
+        project: {
+          type: 'string',
+          description: 'Only include issues from this project name. Omit to include all projects.'
+        },
+        issue_state: {
+          type: 'string',
+          enum: %w[all aging completed not_started],
+          description: 'Which issues to include: "aging" (in progress), "completed", ' \
+                       '"not_started" (backlog), or "all" (default).'
+        },
+        group_by: {
+          type: 'string',
+          enum: %w[status column],
+          description: 'Whether to group results by status name (default) or board column.'
+        }
+      }
+    )
+
+    def self.select_issues issue, issue_state
+      started, stopped = issue.started_stopped_times
+      case issue_state
+      when 'aging' then started && !stopped
+      when 'completed' then !!stopped
+      when 'not_started' then !started && !stopped
+      else true
+      end
+    end
+
+    def self.call(server_context:, project: nil, project_name: nil, issue_state: 'all', group_by: 'status',
+                  column: nil, **)
+      project ||= project_name
+      group_by = 'column' if column
+
+      totals = Hash.new { |h, k| h[k] = { total_seconds: 0.0, visit_count: 0 } }
+      allowed_projects = McpServer.resolve_projects(server_context, project)
+
+      server_context[:projects].each do |project_name, project_data|
+        next if allowed_projects && !allowed_projects.include?(project_name)
+
+        project_data[:issues].each do |issue|
+          next unless select_issues(issue, issue_state)
+
+          time_map = if group_by == 'column'
+                       McpServer.time_per_column(issue, project_data[:end_time])
+                     else
+                       McpServer.time_per_status(issue, project_data[:end_time])
+                     end
+
+          time_map.each do |name, seconds|
+            totals[name][:total_seconds] += seconds
+            totals[name][:visit_count] += 1
+          end
+        end
+      end
+
+      return MCP::Tool::Response.new([{ type: 'text', text: 'No data found.' }]) if totals.empty?
+
+      rows = totals.map do |name, data|
+        total_days = (data[:total_seconds] / 86_400.0).round(1)
+        avg_days = (data[:total_seconds] / data[:visit_count] / 86_400.0).round(1)
+        { name: name, total_days: total_days, avg_days: avg_days, visit_count: data[:visit_count] }
+      end
+      rows.sort_by! { |r| -r[:avg_days] }
+
+      label = group_by == 'column' ? 'Column' : 'Status'
+      lines = rows.map do |r|
+        "#{label}: #{r[:name]} | Avg: #{r[:avg_days]}d | Total: #{r[:total_days]}d | Issues: #{r[:visit_count]}"
+      end
+      MCP::Tool::Response.new([{ type: 'text', text: lines.join("\n") }])
+    end
+  end
+
+  # Alternative tool names used by AI agents other than Claude.
+  # Each entry maps an alias name to the canonical tool class it delegates to.
+  # The alias inherits the canonical tool's schema and call behaviour automatically.
+  # To add a new alias, append one line: 'alias_name' => CanonicalToolClass
+  ALIASES = {
+    'board_list' => ListProjectsTool
+  }.freeze
+end

data/lib/jirametrics/project_config.rb

@@ -98,6 +98,12 @@ class ProjectConfig
     !!@aggregate_config
   end
 
+  def aggregate_project_names
+    return [] unless aggregated_project?
+
+    @aggregate_config.included_projects.filter_map(&:name)
+  end
+
   def download &block
     raise 'Not allowed to have multiple download blocks in one project' if @download_config
     raise 'Not allowed to have both an aggregate and a download section. Pick only one.' if @aggregate_config

data/lib/jirametrics/pull_request_cycle_time_histogram.rb

@@ -19,8 +19,8 @@ class PullRequestCycleTimeHistogram < TimeBasedHistogram
     HTML
 
     init_configuration_block(block) do
-      grouping_rules do |pull_request, _rule|
-        rules.label = pull_request.repo
+      grouping_rules do |pull_request, rule|
+        rule.label = pull_request.repo
       end
     end
   end

data/lib/jirametrics/pull_request_cycle_time_scatterplot.rb

@@ -18,8 +18,8 @@ class PullRequestCycleTimeScatterplot < TimeBasedScatterplot
     HTML
 
     init_configuration_block(block) do
-      grouping_rules do |pull_request, _rule|
-        rules.label = pull_request.repo
+      grouping_rules do |pull_request, rule|
+        rule.label = pull_request.repo
       end
     end
   end
@@ -48,8 +48,15 @@ class PullRequestCycleTimeScatterplot < TimeBasedScatterplot
   end
 
   def y_value pull_request
-    divisor = { minutes: 60, hours: 3600, days: 86_400 }[@cycletime_unit]
-    ((pull_request.closed_at - pull_request.opened_at) / divisor).round
+    if @cycletime_unit == :days
+      tz = timezone_offset || '+00:00'
+      opened = pull_request.opened_at.getlocal(tz).to_date
+      closed = pull_request.closed_at.getlocal(tz).to_date
+      (closed - opened).to_i + 1
+    else
+      divisor = { minutes: 60, hours: 3600 }[@cycletime_unit]
+      ((pull_request.closed_at - pull_request.opened_at) / divisor).round
+    end
   end
 
   def label_cycletime value
@@ -62,7 +69,8 @@ class PullRequestCycleTimeScatterplot < TimeBasedScatterplot
 
   def title_value pull_request, rules: nil
     age_label = label_cycletime y_value(pull_request)
-    "#{pull_request.title} | #{rules.label} | Age:#{age_label}#{lines_changed_text(pull_request)}"
+    keys = pull_request.issue_keys.join(', ')
+    "#{keys} | #{pull_request.title} | #{rules.label} | Age:#{age_label}#{lines_changed_text(pull_request)}"
   end
 
   def lines_changed_text pull_request

data/lib/jirametrics/stitcher.rb

@@ -60,6 +60,11 @@ class Stitcher < HtmlGenerator
         if matches[:seam] == 'start'
           content = +''
         else
+          if content.nil? || content.strip.empty?
+            file_system.warning "Seam found with no content in #{filename.inspect}: " \
+              "id=#{matches[:id].strip.inspect}, class=#{matches[:clazz].strip.inspect}, " \
+              "title=#{matches[:title].strip.inspect}"
+          end
           @all_stitches << Stitcher::StitchContent.new(
             file: filename, title: matches[:title], type: matches[:type], content: content
           )

data/lib/jirametrics.rb

@@ -52,6 +52,47 @@ class JiraMetrics < Thor
     Exporter.instance.info(key, name_filter: options[:name] || '*')
   end
 
+  option :config
+  option :name
+  desc 'mcp', 'Start in MCP (Model Context Protocol) server mode'
+  def mcp
+    # Redirect stdout to stderr for the entire startup phase so that any
+    # incidental output (from config files, gem loading, etc.) does not
+    # corrupt the JSON-RPC channel before the MCP transport takes over.
+    original_stdout = $stdout.dup
+    $stdout.reopen($stderr)
+
+    load_config options[:config]
+    require 'jirametrics/mcp_server'
+
+    Exporter.instance.file_system.log_only = true
+
+    projects = {}
+    aggregates = {}
+    Exporter.instance.each_project_config(name_filter: options[:name] || '*') do |project|
+      project.evaluate_next_level
+      project.run load_only: true
+      projects[project.name || 'default'] = {
+        issues: project.issues,
+        today: project.time_range.end.to_date,
+        end_time: project.time_range.end
+      }
+    rescue StandardError => e
+      if e.message.start_with? 'This is an aggregated project'
+        names = project.aggregate_project_names
+        aggregates[project.name] = names if names.any?
+        next
+      end
+      next if e.message.start_with? 'No data found'
+
+      raise
+    end
+
+    $stdout.reopen(original_stdout)
+    original_stdout.close
+    McpServer.new(projects: projects, aggregates: aggregates, timezone_offset: Exporter.instance.timezone_offset).run
+  end
+
   option :config
   desc 'stitch', 'Dump information about one issue'
   def stitch stitch_file = 'stitcher.erb'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: 2.26.1
+  version: '2.28'
 platform: ruby
 authors:
 - Mike Bowler
@@ -9,6 +9,34 @@ bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: mutant-rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: random-word
   requirement: !ruby/object:Gem::Requirement
@@ -55,10 +83,12 @@ description: Extract metrics from Jira and export to either a report or to CSV f
 email: mbowler@gargoylesoftware.com
 executables:
 - jirametrics
+- jirametrics-mcp
 extensions: []
 extra_rdoc_files: []
 files:
 - bin/jirametrics
+- bin/jirametrics-mcp
 - lib/jirametrics.rb
 - lib/jirametrics/aggregate_config.rb
 - lib/jirametrics/aging_work_bar_chart.rb
@@ -131,6 +161,7 @@ files:
 - lib/jirametrics/issue_link.rb
 - lib/jirametrics/issue_printer.rb
 - lib/jirametrics/jira_gateway.rb
+- lib/jirametrics/mcp_server.rb
 - lib/jirametrics/project_config.rb
 - lib/jirametrics/pull_request.rb
 - lib/jirametrics/pull_request_cycle_time_histogram.rb