jirametrics 2.27 → 2.28pre2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c87212eebf4e22145b8e66741174658bffc3cb1e47bd45bfe3f7590586a42200
-  data.tar.gz: 00fb6c4375e7e6858359fa754af42c697028198dedd2ae8100c98d0564f59db8
+  metadata.gz: '0409b8154ccd9182692080f022a6abc0112fb737034eb214f29a0af09a0cb3c5'
+  data.tar.gz: d3a8d6080925d02572e0f0010c02dfef139e4b4b99234f3675c6ffae6898a08d
 SHA512:
-  metadata.gz: aad3747a78dcf530df02244720c676632816a30688045d95c9a701ba946a5573f81a2e3955c5035e745fb197f5c6cff58491a63d35db68b3abf35817c78dc0b8
-  data.tar.gz: fcf17a8c2a4c91e4de45ff15150d1de9147c890d9e80354b490bec2b27fb17ef2b20e7bc6073c503e88fd0ad188c414002d8312500b22dd5207b043d3c253be7
+  metadata.gz: a2ecb538d8ffc5f23f784966f809bb3643349d3f9799bd589b601d54370182b3f8b78a688c61a6e5d3cdfa12dd7614480353f58808070ee6987dcd2629100e3a
+  data.tar.gz: 310bf1b0b51a14ab393060e4fc782cb413eeb64f473012f17337b0fc36500243105ac6277705f4c8ff76c6faf2ccc981046934ea5639d53cdcd99023c08b5811

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/mcp_server.rb

@@ -4,17 +4,27 @@ require 'mcp'
 require 'mcp/server/transports/stdio_transport'
 
 class McpServer
-  def initialize projects:, timezone_offset: '+00:00'
+  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: [AgingWorkTool, CompletedWorkTool, NotYetStartedTool],
-      server_context: { projects: @projects, timezone_offset: @timezone_offset }
+      tools: canonical_tools + alias_tools,
+      server_context: { projects: @projects, aggregates: @aggregates, timezone_offset: @timezone_offset }
     )
 
     transport = MCP::Server::Transports::StdioTransport.new(server)
@@ -51,6 +61,80 @@ class McpServer
     }
   }.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
@@ -79,6 +163,31 @@ class McpServer
     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), ' \
@@ -95,22 +204,33 @@ class McpServer
           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,
+    def self.call(server_context:, min_age_days: nil, project: 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)
+                  currently_blocked: nil, currently_stalled: nil, **)
       rows = []
+      allowed_projects = McpServer.resolve_projects(server_context, project)
 
       server_context[:projects].each do |project_name, project_data|
-        next if project && project_name != project
+        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
@@ -206,11 +326,12 @@ class McpServer
     def self.call(server_context:, days_back: nil, project: 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)
+                  currently_blocked: nil, currently_stalled: nil, **)
       rows = []
+      allowed_projects = McpServer.resolve_projects(server_context, project)
 
       server_context[:projects].each do |project_name, project_data|
-        next if project && project_name != project
+        next if allowed_projects && !allowed_projects.include?(project_name)
 
         today = project_data[:today]
         cutoff = today - days_back if days_back
@@ -256,21 +377,32 @@ class McpServer
           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,
+    def self.call(server_context:, project: 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)
+                  currently_blocked: nil, currently_stalled: nil, **)
       rows = []
+      allowed_projects = McpServer.resolve_projects(server_context, project)
 
       server_context[:projects].each do |project_name, project_data|
-        next if project && project_name != project
+        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)
@@ -302,4 +434,90 @@ class McpServer
       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, issue_state: 'all', group_by: 'status', **)
+      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.rb

@@ -56,12 +56,19 @@ class JiraMetrics < Thor
   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
@@ -71,13 +78,19 @@ class JiraMetrics < Thor
         end_time: project.time_range.end
       }
     rescue StandardError => e
-      next if e.message.start_with? 'This is an aggregated project'
+      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
 
-    McpServer.new(projects: projects, timezone_offset: Exporter.instance.timezone_offset).run
+    $stdout.reopen(original_stdout)
+    original_stdout.close
+    McpServer.new(projects: projects, aggregates: aggregates, timezone_offset: Exporter.instance.timezone_offset).run
   end
 
   option :config

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jirametrics
 version: !ruby/object:Gem::Version
-  version: '2.27'
+  version: 2.28pre2
 platform: ruby
 authors:
 - Mike Bowler
@@ -83,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