@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 +1 -0
- package/package.json +1 -1
- package/src/lib/mcp/timeline.js +102 -4
- package/src/lib/timeline.js +160 -0
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
package/src/lib/mcp/timeline.js
CHANGED
|
@@ -1,13 +1,22 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* MCP Issue Timeline Tool
|
|
3
3
|
*
|
|
4
|
-
* Exposes
|
|
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 {
|
|
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
|
};
|
package/src/lib/timeline.js
CHANGED
|
@@ -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
|
+
}
|