@giantswarm-io/pro 1.6.0 → 1.7.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
+ - **`list_issue_comments`** -- Fetch comments for multiple board items in a single call. Board-independent (queries by item ID). Resolves each item to its underlying issue and returns comment author/timestamps/body, with an optional `since` cutoff. Each comment includes `createdAt`, plus `updatedAt` when it differs from `createdAt` (i.e. the comment was edited). Bounded response: max 25 `itemIds` per call, newest 20 comments per issue by default (override with `maxPerIssue`), and long comment bodies are truncated with an explicit indicator. Without `since`, "newest" means newest by creation time, and per-issue REST pagination is capped (surfaced via a `truncatedPages` flag if more comments exist); with `since`, "newest" means newest by last-updated time, so a recently-edited older comment isn't dropped in favor of an untouched newer one, and its `updatedAt` shows why. The response's `itemCount` counts result items (including error entries), not comments.
208
+
207
209
  - **`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
210
 
209
211
  ### Write Tools
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.6.0",
3
+ "version": "1.7.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": {
package/src/index.js CHANGED
@@ -44,6 +44,13 @@ export {
44
44
  reprioritizeSubIssue
45
45
  } from './lib/sub-issues.js';
46
46
 
47
+ // Bulk issue comment fetching (board items -> underlying issue comments)
48
+ export {
49
+ listIssueCommentsForItems,
50
+ resolveItemIssueRefs,
51
+ fetchIssueComments
52
+ } from './lib/comments.js';
53
+
47
54
  // Low-level GitHub clients for anything not covered above
48
55
  export { graphQLWithAuth, fetchPaginated } from './lib/api.js';
49
56
  export { getOctokit, parseIssueRef, resolveIssueId } from './lib/rest-api.js';
@@ -0,0 +1,218 @@
1
+ /**
2
+ * Bulk Issue Comments Module
3
+ *
4
+ * Resolves GitHub Projects V2 items to their underlying issues (via a single
5
+ * batched GraphQL `nodes(ids:)` lookup) and fetches each issue's comments via
6
+ * the REST API, which supports `since` filtering natively. Bounds response
7
+ * size by capping the number of items per call, the number of REST pages
8
+ * fetched per issue (when `since` is absent), the number of comments kept
9
+ * per issue, and truncating long comment bodies.
10
+ *
11
+ * Ordering semantics for the kept comments differ by mode:
12
+ * - Without `since`: newest by creation order (the REST endpoint's natural
13
+ * oldest-first order, sliced from the end).
14
+ * - With `since`: newest by `updated_at`, so a recently-edited older
15
+ * comment is kept over an untouched newer-created one.
16
+ *
17
+ * Each comment always exposes `createdAt`; `updatedAt` is included only when
18
+ * it differs from `createdAt` (i.e. the comment was edited), so the `since`
19
+ * mode's updated_at-driven retention is observable without bloating the
20
+ * common (unedited) case.
21
+ */
22
+
23
+ import { graphQLWithAuth } from './api.js';
24
+ import { getOctokit } from './rest-api.js';
25
+ import { ITEM_ISSUE_REFS_QUERY } from './project.js';
26
+ import { logger } from './logger.js';
27
+
28
+ /** Maximum number of itemIds accepted in a single list_issue_comments call. */
29
+ export const MAX_ITEMS_PER_CALL = 25;
30
+
31
+ /** Default number of newest comments kept per issue when maxPerIssue isn't given. */
32
+ export const DEFAULT_MAX_PER_ISSUE = 20;
33
+
34
+ /** Comment bodies longer than this are truncated with an explicit indicator. */
35
+ export const MAX_COMMENT_BODY_LENGTH = 2000;
36
+
37
+ /**
38
+ * Hard cap on REST pages fetched per issue when `since` is absent. Bounds a
39
+ * single list_issue_comments call to at most MAX_PAGES * 100 REST requests'
40
+ * worth of comments per issue, rather than fetching every page unconditionally.
41
+ * When `since` is supplied this cap does not apply (see fetchIssueComments).
42
+ */
43
+ export const MAX_PAGES = 5;
44
+
45
+ /**
46
+ * Truncate an overly long comment body, appending an explicit indicator of
47
+ * how much was cut so callers can tell the body isn't complete.
48
+ * @param {string} body
49
+ * @returns {string}
50
+ */
51
+ function truncateBody(body) {
52
+ if (typeof body !== 'string') return '';
53
+ if (body.length <= MAX_COMMENT_BODY_LENGTH) return body;
54
+ const cut = body.length - MAX_COMMENT_BODY_LENGTH;
55
+ return `${body.slice(0, MAX_COMMENT_BODY_LENGTH)}\n\n[... truncated ${cut} characters ...]`;
56
+ }
57
+
58
+ /**
59
+ * Resolve a batch of project item IDs to their underlying issue's
60
+ * owner/repo/number in a single batched GraphQL request.
61
+ * @param {string[]} itemIds - Project item (PVTI) IDs
62
+ * @param {string} [token] - Optional per-request GitHub token
63
+ * @returns {Promise<Map<string, {owner: string, repo: string, number: number}|null>>}
64
+ * Map from itemId to its issue ref, or null when the item doesn't resolve
65
+ * to an accessible Issue.
66
+ */
67
+ export async function resolveItemIssueRefs(itemIds, token) {
68
+ const result = await graphQLWithAuth(ITEM_ISSUE_REFS_QUERY, { ids: itemIds }, token);
69
+ const nodes = result?.nodes || [];
70
+ const refs = new Map();
71
+
72
+ itemIds.forEach((itemId, i) => {
73
+ const node = nodes[i];
74
+ const nameWithOwner = node?.content?.repository?.nameWithOwner;
75
+ const number = node?.content?.number;
76
+ if (!node || !nameWithOwner || !number) {
77
+ refs.set(itemId, null);
78
+ return;
79
+ }
80
+ const [owner, repo] = nameWithOwner.split('/');
81
+ refs.set(itemId, { owner, repo, number });
82
+ });
83
+
84
+ return refs;
85
+ }
86
+
87
+ /**
88
+ * Fetch comments for a single issue via REST. `since` is applied server-side
89
+ * (native GitHub support). The per-issue comments endpoint only returns
90
+ * results oldest-first with no server-side reverse option.
91
+ *
92
+ * When `since` is absent, page fan-out is bounded by MAX_PAGES -- an issue
93
+ * with far more comments than maxPerIssue would otherwise fetch every page
94
+ * just to keep the newest few. When stopping short, `truncatedPages: true`
95
+ * is returned so callers know more comments exist beyond what was fetched.
96
+ * When `since` is supplied, all matching pages are fetched (uncapped, same
97
+ * as before) and the newest-by-`updated_at` comments are kept, so a
98
+ * recently-edited older comment isn't dropped in favor of an untouched
99
+ * newer-created one.
100
+ * @param {{owner: string, repo: string, number: number}} ref
101
+ * @param {{since?: string, maxPerIssue: number, token?: string}} options
102
+ * @returns {Promise<{comments: Array<{author: string, createdAt: string, updatedAt?: string, body: string}>, totalFetched: number, truncatedPages: boolean}>}
103
+ */
104
+ export async function fetchIssueComments({ owner, repo, number }, { since, maxPerIssue, token }) {
105
+ const client = getOctokit(token);
106
+ const params = { owner, repo, issue_number: number, per_page: 100 };
107
+ if (since) params.since = since;
108
+
109
+ let all = [];
110
+ let truncatedPages = false;
111
+
112
+ if (since) {
113
+ all = await client.paginate(
114
+ 'GET /repos/{owner}/{repo}/issues/{issue_number}/comments',
115
+ params
116
+ );
117
+ } else {
118
+ let pages = 0;
119
+ const iterator = client.paginate.iterator(
120
+ 'GET /repos/{owner}/{repo}/issues/{issue_number}/comments',
121
+ params
122
+ );
123
+ for await (const { data } of iterator) {
124
+ all.push(...data);
125
+ pages += 1;
126
+ if (pages >= MAX_PAGES) {
127
+ truncatedPages = true;
128
+ break;
129
+ }
130
+ }
131
+ }
132
+
133
+ let kept = all;
134
+ if (maxPerIssue > 0) {
135
+ kept = since
136
+ ? [...all].sort((a, b) => (a.updated_at || '').localeCompare(b.updated_at || '')).slice(-maxPerIssue)
137
+ : all.slice(-maxPerIssue);
138
+ }
139
+
140
+ return {
141
+ comments: kept.map(c => {
142
+ const comment = {
143
+ author: c.user?.login || '',
144
+ createdAt: c.created_at,
145
+ body: truncateBody(c.body || '')
146
+ };
147
+ // Only surface updatedAt when it differs from createdAt (i.e. the
148
+ // comment was edited) -- keeps the common unedited case compact while
149
+ // making the since-mode retention semantics (governed by updated_at)
150
+ // observable when they actually diverge from createdAt.
151
+ if (c.updated_at && c.updated_at !== c.created_at) {
152
+ comment.updatedAt = c.updated_at;
153
+ }
154
+ return comment;
155
+ }),
156
+ totalFetched: all.length,
157
+ truncatedPages
158
+ };
159
+ }
160
+
161
+ /**
162
+ * List comments across multiple board items in one call. Without `since`,
163
+ * kept comments are the newest by creation; with `since`, the newest by
164
+ * `updated_at` (see fetchIssueComments).
165
+ * @param {Object} options
166
+ * @param {string[]} options.itemIds - Project item (PVTI) IDs, max MAX_ITEMS_PER_CALL
167
+ * @param {string} [options.since] - ISO 8601 timestamp; only comments at/after this time
168
+ * @param {number} [options.maxPerIssue] - Newest comments to keep per issue (default DEFAULT_MAX_PER_ISSUE)
169
+ * @param {string} [options.token] - Optional per-request GitHub token
170
+ * @returns {Promise<Array>} - One entry per itemId, in input order
171
+ */
172
+ export async function listIssueCommentsForItems({ itemIds, since, maxPerIssue, token } = {}) {
173
+ if (!Array.isArray(itemIds) || itemIds.length === 0) {
174
+ throw new Error('itemIds must be a non-empty array of project item IDs.');
175
+ }
176
+ if (itemIds.length > MAX_ITEMS_PER_CALL) {
177
+ throw new Error(
178
+ `Too many itemIds (${itemIds.length}). Max ${MAX_ITEMS_PER_CALL} per call -- split into multiple calls.`
179
+ );
180
+ }
181
+
182
+ const effectiveMaxPerIssue = Number.isFinite(maxPerIssue) && maxPerIssue > 0
183
+ ? Math.floor(maxPerIssue)
184
+ : DEFAULT_MAX_PER_ISSUE;
185
+
186
+ const refs = await resolveItemIssueRefs(itemIds, token);
187
+
188
+ const results = [];
189
+ for (const itemId of itemIds) {
190
+ const ref = refs.get(itemId);
191
+ if (!ref) {
192
+ results.push({ itemId, error: 'Item not found or is not an issue' });
193
+ continue;
194
+ }
195
+
196
+ try {
197
+ const { comments, totalFetched, truncatedPages } = await fetchIssueComments(ref, {
198
+ since,
199
+ maxPerIssue: effectiveMaxPerIssue,
200
+ token
201
+ });
202
+ results.push({
203
+ itemId,
204
+ repository: `${ref.owner}/${ref.repo}`,
205
+ issueNumber: ref.number,
206
+ commentCount: comments.length,
207
+ totalCommentsFetched: totalFetched,
208
+ truncatedPages,
209
+ comments
210
+ });
211
+ } catch (err) {
212
+ logger.error('Error fetching comments for issue', { itemId, error: err.message });
213
+ results.push({ itemId, error: err.message });
214
+ }
215
+ }
216
+
217
+ return results;
218
+ }
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * MCP Tools Implementation
3
3
  *
4
- * Exposes 9 tools for managing Giant Swarm project boards:
4
+ * Exposes 10 tools for managing Giant Swarm project boards:
5
5
  * - list_issues: Filter and list project items with generic field filters
6
6
  * - get_issue_details: Get full details for a specific item
7
7
  * - update_issue_field: Update a single-select field value
@@ -11,6 +11,7 @@
11
11
  * - close_issue: Close the issue underlying a project item
12
12
  * - reopen_issue: Reopen the issue underlying a project item
13
13
  * - update_issue_labels: Add and/or remove labels on an issue
14
+ * - list_issue_comments: Fetch comments across multiple board items in one call
14
15
  */
15
16
 
16
17
  import { listItems, getItemByID, updateItemField } from '../items.js';
@@ -36,6 +37,11 @@ import {
36
37
  import { logger } from '../logger.js';
37
38
  import { subIssueTools, subIssueToolHandlers } from './sub-issues.js';
38
39
  import { timelineTools, timelineToolHandlers } from './timeline.js';
40
+ import {
41
+ listIssueCommentsForItems,
42
+ MAX_ITEMS_PER_CALL,
43
+ DEFAULT_MAX_PER_ISSUE
44
+ } from '../comments.js';
39
45
 
40
46
  const BOARD_NAMES = Object.keys(BOARDS);
41
47
 
@@ -907,6 +913,67 @@ export async function handleUpdateIssueLabels(args, extra) {
907
913
  }
908
914
  }
909
915
 
916
+ // ---------------------------------------------------------------------------
917
+ // Tool: list_issue_comments
918
+ // ---------------------------------------------------------------------------
919
+
920
+ export const listIssueCommentsTool = {
921
+ name: 'list_issue_comments',
922
+ description: `Fetch comments for multiple board items in a single call. Board-independent (queries by item ID). Resolves each item to its underlying GitHub issue and returns the comment author, timestamps, and body for each. Bounded response: max ${MAX_ITEMS_PER_CALL} itemIds per call, and only the newest ${DEFAULT_MAX_PER_ISSUE} comments per issue by default (override with maxPerIssue); long comment bodies are truncated with an explicit truncation indicator. Each comment includes \`createdAt\`, plus \`updatedAt\` when it differs from \`createdAt\` (i.e. the comment was edited). Ordering differs by mode: without \`since\`, the newest comments by creation time are kept; with \`since\`, the newest comments by last-updated time are kept (so a recently-edited older comment survives ahead of an untouched newer one, and its \`updatedAt\` shows why). The response's \`itemCount\` counts result items (including error entries), not comments.`,
923
+ inputSchema: {
924
+ type: 'object',
925
+ properties: {
926
+ itemIds: {
927
+ type: 'array',
928
+ items: { type: 'string' },
929
+ description: `The project item IDs to fetch comments for. Max ${MAX_ITEMS_PER_CALL} per call.`
930
+ },
931
+ since: {
932
+ type: 'string',
933
+ description: 'Only return comments created/updated at or after this ISO 8601 timestamp (e.g. "2026-06-01T00:00:00Z"). Changes which comments are kept when maxPerIssue trims the results -- see the tool description.'
934
+ },
935
+ maxPerIssue: {
936
+ type: 'number',
937
+ description: `Maximum number of comments to return per issue, keeping the newest ones. Defaults to ${DEFAULT_MAX_PER_ISSUE}.`
938
+ }
939
+ },
940
+ required: ['itemIds']
941
+ }
942
+ };
943
+
944
+ export async function handleListIssueComments(args, extra) {
945
+ try {
946
+ const token = extractToken(extra);
947
+ const itemIds = args.itemIds;
948
+
949
+ logger.info('MCP: Listing issue comments', {
950
+ itemCount: Array.isArray(itemIds) ? itemIds.length : 0,
951
+ since: args.since,
952
+ maxPerIssue: args.maxPerIssue
953
+ });
954
+
955
+ const results = await listIssueCommentsForItems({
956
+ itemIds,
957
+ since: args.since || null,
958
+ maxPerIssue: args.maxPerIssue,
959
+ token
960
+ });
961
+
962
+ return {
963
+ content: [{
964
+ type: 'text',
965
+ text: JSON.stringify({
966
+ itemCount: results.length,
967
+ items: results
968
+ })
969
+ }]
970
+ };
971
+ } catch (error) {
972
+ logger.error('MCP: Error listing issue comments', { error: error.message });
973
+ return { error: error.message };
974
+ }
975
+ }
976
+
910
977
  // ---------------------------------------------------------------------------
911
978
  // Exports
912
979
  // ---------------------------------------------------------------------------
@@ -921,6 +988,7 @@ export const tools = [
921
988
  closeIssueTool,
922
989
  reopenIssueTool,
923
990
  updateIssueLabelsTool,
991
+ listIssueCommentsTool,
924
992
  ...subIssueTools,
925
993
  ...timelineTools
926
994
  ];
@@ -935,6 +1003,7 @@ export const toolHandlers = {
935
1003
  close_issue: handleCloseIssue,
936
1004
  reopen_issue: handleReopenIssue,
937
1005
  update_issue_labels: handleUpdateIssueLabels,
1006
+ list_issue_comments: handleListIssueComments,
938
1007
  ...subIssueToolHandlers,
939
1008
  ...timelineToolHandlers
940
1009
  };
@@ -395,6 +395,29 @@ const USER_ID_QUERY = `
395
395
  }
396
396
  `;
397
397
 
398
+ // Batched lookup: resolve a list of ProjectV2Item IDs to their underlying
399
+ // issue's repository + number in a single round trip, using GitHub's
400
+ // root-level `nodes(ids:)` query. The response array is in the same order
401
+ // as the requested `ids` (entries are null for items that don't resolve to
402
+ // an Issue, e.g. deleted or inaccessible content).
403
+ const ITEM_ISSUE_REFS_QUERY = `
404
+ query GetItemIssueRefs($ids: [ID!]!) {
405
+ nodes(ids: $ids) {
406
+ ... on ProjectV2Item {
407
+ id
408
+ content {
409
+ ... on Issue {
410
+ number
411
+ repository {
412
+ nameWithOwner
413
+ }
414
+ }
415
+ }
416
+ }
417
+ }
418
+ }
419
+ `;
420
+
398
421
  // Query to resolve the underlying issue node ID for a project item, including
399
422
  // the repository's visibility so callers can gate free-text writes (e.g. comments)
400
423
  // to public repos behind an explicit confirmation.
@@ -475,6 +498,7 @@ export {
475
498
  ARCHIVE_ITEM_MUTATION,
476
499
  ISSUE_NODE_ID_QUERY,
477
500
  USER_ID_QUERY,
501
+ ITEM_ISSUE_REFS_QUERY,
478
502
  ITEM_ISSUE_ID_QUERY,
479
503
  CLOSE_ISSUE_MUTATION,
480
504
  REOPEN_ISSUE_MUTATION,