@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 +2 -0
- package/package.json +1 -1
- package/src/lib/mcp/timeline.js +110 -0
- package/src/lib/mcp/tools.js +5 -2
- package/src/lib/timeline.js +181 -0
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
|
@@ -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
|
+
};
|
package/src/lib/mcp/tools.js
CHANGED
|
@@ -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
|
+
}
|