@giantswarm-io/pro 1.16.0-rc.3 → 1.16.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
@@ -238,6 +238,7 @@ The `board` parameter defaults to `"roadmap"` on every board-scoped tool for bac
238
238
 
239
239
  - **`get_server_version`** -- The running server's name, version (the release tag, as in the MCP `serverInfo`) and `isDevBuild`.
240
240
  - **`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.
241
+ - **`list_status_changes`** -- List the board Status changes of one repository's issues in one call: per change the issue, the board (`board`, or `null` with `projectNumber` for a project pro does not serve), `from` and `to` (the option names GitHub recorded at the time), `actor` and `createdAt`, oldest first, with optional `since`/`until`/`board` filters. A Status change does not bump an issue's `updatedAt`, so this is how to see board movement since a date. Scans the open issues (newest first, at most `maxIssues`, default 300; `0` for all), or with `state: "closed"` the closed issues updated since `since`; `truncated` says more issues exist, `timelineTruncated` names issues with more than 50 Status changes whose older ones in the window were not read. Needs one GraphQL request per 50 issues.
241
242
 
242
243
  ### Write Tools
243
244
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.16.0-rc.3",
3
+ "version": "1.16.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": {
@@ -1,13 +1,22 @@
1
1
  /**
2
2
  * MCP Issue Timeline Tool
3
3
  *
4
- * Exposes 1 tool for reading an issue's activity timeline:
4
+ * Exposes 2 tools for reading issue activity:
5
5
  * - get_issue_timeline: List label/assignment/milestone/rename/cross-reference
6
6
  * events for the issue underlying a project board item.
7
+ * - list_status_changes: List the board Status changes (from, to, board) of
8
+ * the issues of one repository in one call.
7
9
  */
8
10
 
9
11
  import { resolveItemIssues } from '../items.js';
10
- import { getIssueTimeline, MAX_TIMELINE_EVENTS } from '../timeline.js';
12
+ import {
13
+ getIssueTimeline,
14
+ listStatusChanges,
15
+ MAX_TIMELINE_EVENTS,
16
+ STATUS_CHANGES_PER_ISSUE,
17
+ DEFAULT_STATUS_CHANGES_MAX_ISSUES
18
+ } from '../timeline.js';
19
+ import { BOARD_NAMES } from '../project.js';
11
20
  import { logger } from '../logger.js';
12
21
  import { READ_ONLY } from './annotations.js';
13
22
 
@@ -98,14 +107,103 @@ export async function handleGetIssueTimeline(args, extra) {
98
107
  }
99
108
  }
100
109
 
110
+ // ---------------------------------------------------------------------------
111
+ // Tool: list_status_changes
112
+ // ---------------------------------------------------------------------------
113
+
114
+ export const listStatusChangesTool = {
115
+ name: 'list_status_changes',
116
+ annotations: READ_ONLY,
117
+ description: `List the board Status changes of the issues of one repository in one call: for each change the issue (number, title, url, state), the board it happened on (\`board\`, or null for a project pro does not serve, with \`projectNumber\`), \`from\` and \`to\` (the Status option names as GitHub recorded them at the time; \`from\` is empty when the item was just added), \`actor\` and \`createdAt\`, oldest first. A Status change does not bump an issue's updatedAt, so this is the way to see board movement since a date. Scans the repository's open issues (newest first, at most \`maxIssues\`), or with state "closed" the closed issues updated since \`since\`. \`truncated: true\`: more issues exist than were scanned. \`timelineTruncated\` lists issues with more than ${STATUS_CHANGES_PER_ISSUE} Status changes whose older ones inside the window were not read.`,
118
+ inputSchema: {
119
+ type: 'object',
120
+ properties: {
121
+ repository: {
122
+ type: 'string',
123
+ description: 'The repository: short name (e.g. "myrepo", resolved to "giantswarm/myrepo") or "owner/name".'
124
+ },
125
+ since: {
126
+ type: 'string',
127
+ description: 'Only changes at or after this ISO 8601 date/time (e.g. "2026-01-01T00:00:00Z").'
128
+ },
129
+ until: {
130
+ type: 'string',
131
+ description: 'Only changes at or before this ISO 8601 date/time.'
132
+ },
133
+ board: {
134
+ type: 'string',
135
+ enum: BOARD_NAMES,
136
+ description: 'Only changes on this board. Omit for every board.'
137
+ },
138
+ state: {
139
+ type: 'string',
140
+ enum: ['open', 'closed'],
141
+ description: 'Which issues to scan: "open" (default) or "closed" (those updated since `since`).'
142
+ },
143
+ maxIssues: {
144
+ type: 'integer',
145
+ minimum: 0,
146
+ description: `Issues to scan at most, newest first. Default ${DEFAULT_STATUS_CHANGES_MAX_ISSUES}; 0 scans every issue of the state.`
147
+ }
148
+ },
149
+ required: ['repository']
150
+ }
151
+ };
152
+
153
+ /**
154
+ * Split a repository argument into owner and name; a short name is in giantswarm.
155
+ * @param {string} repository
156
+ * @returns {{ owner: string, repo: string }|null}
157
+ */
158
+ export function parseRepository(repository) {
159
+ const parts = String(repository || '').trim().split('/').filter(Boolean);
160
+ if (parts.length === 1) return { owner: 'giantswarm', repo: parts[0] };
161
+ if (parts.length === 2) return { owner: parts[0], repo: parts[1] };
162
+ return null;
163
+ }
164
+
165
+ export async function handleListStatusChanges(args, extra) {
166
+ try {
167
+ const token = extractToken(extra);
168
+ const parsed = parseRepository(args.repository);
169
+ if (!parsed) {
170
+ return { error: `Invalid repository '${args.repository}': give "name" or "owner/name".` };
171
+ }
172
+ logger.info('MCP: Listing status changes', {
173
+ repository: `${parsed.owner}/${parsed.repo}`, since: args.since, until: args.until, board: args.board, state: args.state
174
+ });
175
+
176
+ const result = await listStatusChanges(
177
+ {
178
+ ...parsed,
179
+ since: args.since || null,
180
+ until: args.until || null,
181
+ board: args.board || null,
182
+ state: args.state || 'open',
183
+ maxIssues: args.maxIssues ?? DEFAULT_STATUS_CHANGES_MAX_ISSUES
184
+ },
185
+ token
186
+ );
187
+ if (result.error) {
188
+ return { error: result.error };
189
+ }
190
+ return { content: [{ type: 'text', text: JSON.stringify(result) }] };
191
+ } catch (error) {
192
+ logger.error('MCP: Error listing status changes', { error: error.message });
193
+ return { error: error.message };
194
+ }
195
+ }
196
+
101
197
  // ---------------------------------------------------------------------------
102
198
  // Exports
103
199
  // ---------------------------------------------------------------------------
104
200
 
105
201
  export const timelineTools = [
106
- getIssueTimelineTool
202
+ getIssueTimelineTool,
203
+ listStatusChangesTool
107
204
  ];
108
205
 
109
206
  export const timelineToolHandlers = {
110
- get_issue_timeline: handleGetIssueTimeline
207
+ get_issue_timeline: handleGetIssueTimeline,
208
+ list_status_changes: handleListStatusChanges
111
209
  };
@@ -12,6 +12,8 @@
12
12
 
13
13
  import { getOctokit } from './rest-api.js';
14
14
  import { logger } from './logger.js';
15
+ import { fetchBounded } from './api.js';
16
+ import { BOARDS } from './project.js';
15
17
 
16
18
  const DEFAULT_PAGE_SIZE = 100;
17
19
 
@@ -179,3 +181,161 @@ export async function getIssueTimeline({ owner, repo, issue_number, since, until
179
181
 
180
182
  return { events: kept, truncated };
181
183
  }
184
+
185
+
186
+ // ---------------------------------------------------------------------------
187
+ // Status changes across one repository (GraphQL)
188
+ // ---------------------------------------------------------------------------
189
+
190
+ /** Issues read per GraphQL page by listStatusChanges. */
191
+ const STATUS_CHANGES_PAGE_SIZE = 50;
192
+
193
+ /** Status-change events read per issue (the newest ones). */
194
+ export const STATUS_CHANGES_PER_ISSUE = 50;
195
+
196
+ /** Issues scanned by listStatusChanges unless maxIssues says otherwise. */
197
+ export const DEFAULT_STATUS_CHANGES_MAX_ISSUES = 300;
198
+
199
+ const STATUS_CHANGES_QUERY = `
200
+ query($owner: String!, $repo: String!, $first: Int!, $after: String, $states: [IssueState!], $filterSince: DateTime) {
201
+ repository(owner: $owner, name: $repo) {
202
+ issues(first: $first, after: $after, states: $states, filterBy: { since: $filterSince }, orderBy: { field: CREATED_AT, direction: DESC }) {
203
+ totalCount
204
+ pageInfo { hasNextPage endCursor }
205
+ nodes {
206
+ number
207
+ title
208
+ url
209
+ state
210
+ timelineItems(last: ${STATUS_CHANGES_PER_ISSUE}, itemTypes: [PROJECT_V2_ITEM_STATUS_CHANGED_EVENT]) {
211
+ totalCount
212
+ nodes {
213
+ ... on ProjectV2ItemStatusChangedEvent {
214
+ createdAt
215
+ actor { login }
216
+ previousStatus
217
+ status
218
+ project { number url }
219
+ }
220
+ }
221
+ }
222
+ }
223
+ }
224
+ }
225
+ }
226
+ `;
227
+
228
+ /**
229
+ * The board key of a project, matched on its number and owner (the owner is
230
+ * read from the project URL, https://github.com/orgs/<owner>/projects/<n>).
231
+ * @param {{ number?: number, url?: string }} [project]
232
+ * @returns {string|null}
233
+ */
234
+ export function boardKeyOfProject(project) {
235
+ if (!project) return null;
236
+ const owner = /github\.com\/(?:orgs|users)\/([^/]+)\/projects\//.exec(project.url || '')?.[1];
237
+ const entry = Object.entries(BOARDS).find(([, board]) =>
238
+ board.number === project.number && (!owner || board.owner.toLowerCase() === owner.toLowerCase()));
239
+ return entry ? entry[0] : null;
240
+ }
241
+
242
+ /**
243
+ * List the board Status changes of the issues of one repository: every
244
+ * ProjectV2ItemStatusChangedEvent with its previous and new Status and the
245
+ * board it happened on. Project field changes do not bump an issue's
246
+ * updatedAt, so open issues are all scanned (newest first, up to maxIssues);
247
+ * closed issues are narrowed to those updated since \`since\` (closing an
248
+ * issue bumps it).
249
+ *
250
+ * @param {Object} params
251
+ * @param {string} params.owner
252
+ * @param {string} params.repo
253
+ * @param {string} [params.since] - ISO 8601; only changes at or after this instant
254
+ * @param {string} [params.until] - ISO 8601; only changes at or before this instant
255
+ * @param {string} [params.board] - Only changes on this board key
256
+ * @param {'open'|'closed'} [params.state] - Which issues to scan (default open)
257
+ * @param {number} [params.maxIssues] - Issues to scan at most; 0 = all
258
+ * @param {string} [token] - Optional per-request GitHub token
259
+ * @returns {Promise<Object>}
260
+ */
261
+ export async function listStatusChanges({ owner, repo, since, until, board, state = 'open', maxIssues = DEFAULT_STATUS_CHANGES_MAX_ISSUES }, token) {
262
+ const sinceDate = since ? new Date(since) : null;
263
+ const untilDate = until ? new Date(until) : null;
264
+ if (sinceDate && Number.isNaN(sinceDate.getTime())) {
265
+ return { error: `Invalid 'since' date/time: '${since}'` };
266
+ }
267
+ if (untilDate && Number.isNaN(untilDate.getTime())) {
268
+ return { error: `Invalid 'until' date/time: '${until}'` };
269
+ }
270
+ if (state !== 'open' && state !== 'closed') {
271
+ return { error: `Invalid 'state': '${state}' (open or closed)` };
272
+ }
273
+ if (board && !BOARDS[board]) {
274
+ return { error: `Unknown board '${board}'` };
275
+ }
276
+
277
+ logger.debug('Listing status changes', { owner, repo, since, until, board, state, maxIssues });
278
+
279
+ let totalCount = null;
280
+ const { nodes, hasNextPage } = await fetchBounded(
281
+ STATUS_CHANGES_QUERY,
282
+ {
283
+ owner,
284
+ repo,
285
+ first: STATUS_CHANGES_PAGE_SIZE,
286
+ states: [state === 'closed' ? 'CLOSED' : 'OPEN'],
287
+ filterSince: state === 'closed' && sinceDate ? sinceDate.toISOString() : null
288
+ },
289
+ (result) => {
290
+ const issues = result?.repository?.issues;
291
+ if (totalCount === null && typeof issues?.totalCount === 'number') totalCount = issues.totalCount;
292
+ return issues || { nodes: [], pageInfo: { hasNextPage: false } };
293
+ },
294
+ token,
295
+ { limit: maxIssues > 0 ? maxIssues : 0 }
296
+ );
297
+
298
+ const changes = [];
299
+ const timelineTruncated = [];
300
+ for (const issue of nodes) {
301
+ const events = (issue.timelineItems?.nodes || []).filter(event => event && event.createdAt);
302
+ if ((issue.timelineItems?.totalCount ?? 0) > events.length) {
303
+ const oldestKept = events[0]?.createdAt;
304
+ if (!sinceDate || !oldestKept || new Date(oldestKept) > sinceDate) timelineTruncated.push(issue.number);
305
+ }
306
+ for (const event of events) {
307
+ const at = new Date(event.createdAt);
308
+ if (sinceDate && at < sinceDate) continue;
309
+ if (untilDate && at > untilDate) continue;
310
+ const eventBoard = boardKeyOfProject(event.project);
311
+ if (board && eventBoard !== board) continue;
312
+ changes.push({
313
+ number: issue.number,
314
+ title: issue.title,
315
+ url: issue.url,
316
+ state: issue.state,
317
+ board: eventBoard,
318
+ projectNumber: event.project?.number ?? null,
319
+ from: event.previousStatus ?? '',
320
+ to: event.status ?? '',
321
+ actor: event.actor?.login,
322
+ createdAt: event.createdAt
323
+ });
324
+ }
325
+ }
326
+ changes.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
327
+
328
+ return {
329
+ repository: `${owner}/${repo}`,
330
+ state,
331
+ since: since || null,
332
+ until: until || null,
333
+ board: board || null,
334
+ issuesScanned: nodes.length,
335
+ issuesTotal: totalCount,
336
+ truncated: hasNextPage,
337
+ timelineTruncated,
338
+ count: changes.length,
339
+ changes
340
+ };
341
+ }