@giantswarm-io/pro 1.5.0 → 1.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -204,6 +204,8 @@ The `board` parameter defaults to `"roadmap"` on every board-scoped tool for bac
204
204
 
205
205
  - **`get_issue_details`** -- Get full details for a specific item: repository metadata, title, body text, comments with timestamps, assignees, labels, dates, and all field values. Board-independent (queries by item ID).
206
206
 
207
+ - **`get_issue_timeline`** -- Get the compact activity timeline for a board item's underlying issue: label changes, assignments, milestones, renames, cross-references, and close reasons. Board-independent (queries by item ID). Optional `since`/`until`/`eventTypes` filters (applied client-side; malformed `since`/`until` values return an error). When more than 200 events qualify, only the most recent 200 are returned, with a `truncated` flag.
208
+
207
209
  ### Write Tools
208
210
 
209
211
  - **`update_issue_field`** -- Update a single-select field value. Provide human-readable field and option names; the server resolves them to GitHub node IDs. Specify `board` to target the correct board.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.5.0",
3
+ "version": "1.6.0",
4
4
  "description": "Core library and MCP server for managing Giant Swarm's roadmap and customer project boards",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -0,0 +1,110 @@
1
+ /**
2
+ * MCP Issue Timeline Tool
3
+ *
4
+ * Exposes 1 tool for reading an issue's activity timeline:
5
+ * - get_issue_timeline: List label/assignment/milestone/rename/cross-reference
6
+ * events for the issue underlying a project board item.
7
+ */
8
+
9
+ import { getItemByID } from '../items.js';
10
+ import { getIssueTimeline, MAX_TIMELINE_EVENTS } from '../timeline.js';
11
+ import { logger } from '../logger.js';
12
+
13
+ /**
14
+ * Extract the GitHub token from MCP request extra context.
15
+ * @param {Object} [extra] - MCP request extra context
16
+ * @returns {string|undefined}
17
+ */
18
+ function extractToken(extra) {
19
+ return extra?.authInfo?.token;
20
+ }
21
+
22
+ // ---------------------------------------------------------------------------
23
+ // Tool: get_issue_timeline
24
+ // ---------------------------------------------------------------------------
25
+
26
+ export const getIssueTimelineTool = {
27
+ name: 'get_issue_timeline',
28
+ description: `Get the activity timeline for a project board item's underlying issue: label changes, assignments, milestones, renames, cross-references, and close reasons. Returns compact events ordered chronologically (oldest first); when more than ${MAX_TIMELINE_EVENTS} events qualify, only the most recent ${MAX_TIMELINE_EVENTS} are returned (see \`truncated\` in the response). No server-side date/type filters exist on this endpoint, so \`since\`/\`until\`/\`eventTypes\` are applied client-side -- pass full ISO 8601 timestamps (not just a date) for precise since/until cutoffs.`,
29
+ inputSchema: {
30
+ type: 'object',
31
+ properties: {
32
+ itemId: {
33
+ type: 'string',
34
+ description: 'The ID of the project item to retrieve the timeline for. Board-independent (queries by item ID).'
35
+ },
36
+ since: {
37
+ type: 'string',
38
+ description: 'Only include events at or after this ISO 8601 date/time (e.g. "2026-01-01T00:00:00Z").'
39
+ },
40
+ until: {
41
+ type: 'string',
42
+ description: 'Only include events at or before this ISO 8601 date/time.'
43
+ },
44
+ eventTypes: {
45
+ type: 'array',
46
+ items: { type: 'string' },
47
+ description: 'Only include events of these raw timeline types (e.g. ["labeled", "closed", "cross-referenced", "assigned", "renamed", "referenced"]). Omit to include all types.'
48
+ }
49
+ },
50
+ required: ['itemId']
51
+ }
52
+ };
53
+
54
+ export async function handleGetIssueTimeline(args, extra) {
55
+ try {
56
+ const token = extractToken(extra);
57
+ logger.info('MCP: Getting issue timeline', {
58
+ itemId: args.itemId, since: args.since, until: args.until, eventTypes: args.eventTypes
59
+ });
60
+
61
+ const item = await getItemByID(args.itemId, token);
62
+ if (!item.repository?.nameWithOwner || !item.number) {
63
+ return { error: `Could not resolve item '${args.itemId}' to an underlying issue.` };
64
+ }
65
+ const [owner, repo] = item.repository.nameWithOwner.split('/');
66
+
67
+ const result = await getIssueTimeline(
68
+ {
69
+ owner,
70
+ repo,
71
+ issue_number: item.number,
72
+ since: args.since || null,
73
+ until: args.until || null,
74
+ eventTypes: args.eventTypes || null
75
+ },
76
+ token
77
+ );
78
+
79
+ if (result.error) {
80
+ return { error: result.error };
81
+ }
82
+ const { events, truncated } = result;
83
+
84
+ return {
85
+ content: [{
86
+ type: 'text',
87
+ text: JSON.stringify({
88
+ count: events.length,
89
+ truncated,
90
+ events
91
+ })
92
+ }]
93
+ };
94
+ } catch (error) {
95
+ logger.error('MCP: Error getting issue timeline', { error: error.message });
96
+ return { error: error.message };
97
+ }
98
+ }
99
+
100
+ // ---------------------------------------------------------------------------
101
+ // Exports
102
+ // ---------------------------------------------------------------------------
103
+
104
+ export const timelineTools = [
105
+ getIssueTimelineTool
106
+ ];
107
+
108
+ export const timelineToolHandlers = {
109
+ get_issue_timeline: handleGetIssueTimeline
110
+ };
@@ -35,6 +35,7 @@ import {
35
35
  } from '../project.js';
36
36
  import { logger } from '../logger.js';
37
37
  import { subIssueTools, subIssueToolHandlers } from './sub-issues.js';
38
+ import { timelineTools, timelineToolHandlers } from './timeline.js';
38
39
 
39
40
  const BOARD_NAMES = Object.keys(BOARDS);
40
41
 
@@ -920,7 +921,8 @@ export const tools = [
920
921
  closeIssueTool,
921
922
  reopenIssueTool,
922
923
  updateIssueLabelsTool,
923
- ...subIssueTools
924
+ ...subIssueTools,
925
+ ...timelineTools
924
926
  ];
925
927
 
926
928
  export const toolHandlers = {
@@ -933,5 +935,6 @@ export const toolHandlers = {
933
935
  close_issue: handleCloseIssue,
934
936
  reopen_issue: handleReopenIssue,
935
937
  update_issue_labels: handleUpdateIssueLabels,
936
- ...subIssueToolHandlers
938
+ ...subIssueToolHandlers,
939
+ ...timelineToolHandlers
937
940
  };
@@ -0,0 +1,181 @@
1
+ /**
2
+ * Issue Timeline Module
3
+ *
4
+ * Provides access to the GitHub Issue Timeline REST API (not available via
5
+ * GraphQL, same reasoning as sub-issues.js). Maps raw timeline events to a
6
+ * compact shape and supports client-side since/until/eventTypes filtering,
7
+ * with an early pagination stop once `until` is exceeded, since the timeline
8
+ * is returned in chronological (oldest-first) order. When more than
9
+ * MAX_TIMELINE_EVENTS qualifying events exist, the most recent ones are kept
10
+ * and `truncated: true` is set.
11
+ */
12
+
13
+ import { getOctokit } from './rest-api.js';
14
+ import { logger } from './logger.js';
15
+
16
+ const DEFAULT_PAGE_SIZE = 100;
17
+
18
+ /**
19
+ * Maximum number of (post-filter) events returned by getIssueTimeline.
20
+ * When more qualifying events exist, the result is truncated and
21
+ * `truncated: true` is set on the return value.
22
+ */
23
+ export const MAX_TIMELINE_EVENTS = 200;
24
+
25
+ /**
26
+ * Extract a GitHub login (or best-effort name) from an actor-like object.
27
+ * @param {Object} [obj]
28
+ * @returns {string|undefined}
29
+ */
30
+ function actorLogin(obj) {
31
+ return obj?.login || obj?.name || undefined;
32
+ }
33
+
34
+ /**
35
+ * Best-effort timestamp for a raw timeline event, used both for since/until
36
+ * filtering and as the compact event's createdAt.
37
+ * @param {Object} event
38
+ * @returns {string|null}
39
+ */
40
+ function eventTimestamp(event) {
41
+ return event.created_at || event.submitted_at || event.author?.date || event.committer?.date || null;
42
+ }
43
+
44
+ /**
45
+ * Map a single raw timeline event to a compact { type, actor, createdAt, detail } shape.
46
+ * `detail` is only populated for event types where it carries meaningful signal;
47
+ * all other payload fields (bodies, diffs, node IDs, etc.) are dropped.
48
+ * @param {Object} event - Raw event from GET /repos/{owner}/{repo}/issues/{issue_number}/timeline
49
+ * @returns {{ type: string, actor?: string, createdAt: string|null, detail?: Object }|null}
50
+ */
51
+ export function compactTimelineEvent(event) {
52
+ const type = event?.event;
53
+ if (!type) return null;
54
+
55
+ const base = {
56
+ type,
57
+ actor: actorLogin(event.actor) || actorLogin(event.user) || actorLogin(event.author),
58
+ createdAt: eventTimestamp(event)
59
+ };
60
+
61
+ switch (type) {
62
+ case 'labeled':
63
+ case 'unlabeled':
64
+ return { ...base, detail: { label: event.label?.name } };
65
+
66
+ case 'closed':
67
+ return event.state_reason
68
+ ? { ...base, detail: { stateReason: event.state_reason } }
69
+ : base;
70
+
71
+ case 'cross-referenced': {
72
+ const src = event.source?.issue;
73
+ return {
74
+ ...base,
75
+ actor: actorLogin(event.actor) || actorLogin(src?.user),
76
+ createdAt: event.created_at || src?.created_at || base.createdAt,
77
+ detail: src
78
+ ? {
79
+ ref: `${src.repository?.full_name || ''}#${src.number}`,
80
+ title: src.title,
81
+ isPullRequest: Boolean(src.pull_request)
82
+ }
83
+ : undefined
84
+ };
85
+ }
86
+
87
+ case 'assigned':
88
+ case 'unassigned':
89
+ return { ...base, detail: { assignee: actorLogin(event.assignee) } };
90
+
91
+ case 'milestoned':
92
+ case 'demilestoned':
93
+ return { ...base, detail: { milestone: event.milestone?.title } };
94
+
95
+ case 'renamed':
96
+ return { ...base, detail: { from: event.rename?.from, to: event.rename?.to } };
97
+
98
+ case 'referenced':
99
+ return { ...base, detail: { commit: event.commit_id } };
100
+
101
+ default:
102
+ return base;
103
+ }
104
+ }
105
+
106
+ /**
107
+ * Fetch and compact the activity timeline for a GitHub issue, paginating
108
+ * via Octokit and filtering client-side (the timeline endpoint has no
109
+ * server-side date/type filters). Stops paginating early once `until` is
110
+ * exceeded, since events are returned in chronological (oldest-first) order.
111
+ * When more than MAX_TIMELINE_EVENTS qualifying events are found, only the
112
+ * most recent MAX_TIMELINE_EVENTS are kept (oldest-first order preserved
113
+ * within that tail) and `truncated: true` is set.
114
+ *
115
+ * @param {Object} params
116
+ * @param {string} params.owner
117
+ * @param {string} params.repo
118
+ * @param {number} params.issue_number
119
+ * @param {string} [params.since] - ISO 8601 date/time; only include events at or after this instant
120
+ * @param {string} [params.until] - ISO 8601 date/time; only include events at or before this instant
121
+ * @param {string[]} [params.eventTypes] - Only include events whose raw `type` is in this list
122
+ * @param {string} [token] - Optional per-request GitHub token
123
+ * @returns {Promise<{ events: Array, truncated: boolean } | { error: string }>}
124
+ */
125
+ export async function getIssueTimeline({ owner, repo, issue_number, since, until, eventTypes }, token) {
126
+ const sinceDate = since ? new Date(since) : null;
127
+ const untilDate = until ? new Date(until) : null;
128
+
129
+ if (sinceDate && Number.isNaN(sinceDate.getTime())) {
130
+ return { error: `Invalid 'since' date/time: '${since}'` };
131
+ }
132
+ if (untilDate && Number.isNaN(untilDate.getTime())) {
133
+ return { error: `Invalid 'until' date/time: '${until}'` };
134
+ }
135
+
136
+ const client = getOctokit(token);
137
+ const typeFilter = Array.isArray(eventTypes) && eventTypes.length > 0 ? new Set(eventTypes) : null;
138
+
139
+ logger.debug('Fetching issue timeline', { owner, repo, issue_number, since, until, eventTypes });
140
+
141
+ const events = [];
142
+ let page = 1;
143
+
144
+ outer:
145
+ while (true) {
146
+ const { data } = await client.request(
147
+ 'GET /repos/{owner}/{repo}/issues/{issue_number}/timeline',
148
+ { owner, repo, issue_number, per_page: DEFAULT_PAGE_SIZE, page }
149
+ );
150
+
151
+ if (!Array.isArray(data) || data.length === 0) break;
152
+
153
+ for (const raw of data) {
154
+ const ts = eventTimestamp(raw);
155
+ const tsDate = ts ? new Date(ts) : null;
156
+
157
+ // Chronological (oldest-first) order means once we're past `until`,
158
+ // nothing later in the timeline can be in range either.
159
+ if (untilDate && tsDate && tsDate > untilDate) {
160
+ break outer;
161
+ }
162
+ if (sinceDate && tsDate && tsDate < sinceDate) {
163
+ continue;
164
+ }
165
+
166
+ const compact = compactTimelineEvent(raw);
167
+ if (!compact) continue;
168
+ if (typeFilter && !typeFilter.has(compact.type)) continue;
169
+
170
+ events.push(compact);
171
+ }
172
+
173
+ if (data.length < DEFAULT_PAGE_SIZE) break;
174
+ page += 1;
175
+ }
176
+
177
+ const truncated = events.length > MAX_TIMELINE_EVENTS;
178
+ const kept = truncated ? events.slice(events.length - MAX_TIMELINE_EVENTS) : events;
179
+
180
+ return { events: kept, truncated };
181
+ }