@giantswarm-io/pro 1.4.0 → 1.5.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
@@ -214,6 +214,10 @@ The `board` parameter defaults to `"roadmap"` on every board-scoped tool for bac
214
214
 
215
215
  - **`archive_item`** -- Archive a project item from the active board view.
216
216
 
217
+ - **`close_issue`** -- Close the GitHub issue underlying a single project item. Board-independent (queries by item ID). Accepts an optional `stateReason` (`"completed"` or `"not_planned"`, defaults to `"completed"`; any other value returns an error) and an optional `comment` posted before closing. Comments on issues in public repos require `confirmPublicSafe=true`. One item per call -- no bulk close. Closing the issue does not update the board's Status field; unless the board has GitHub's built-in "item closed -> set Status" workflow enabled, pair this with `update_issue_field` if the board Status should reflect the closure.
218
+
219
+ - **`reopen_issue`** -- Reopen the GitHub issue underlying a single project item. Board-independent (queries by item ID). Accepts an optional `comment` posted before reopening. Comments on issues in public repos require `confirmPublicSafe=true`. One item per call -- no bulk reopen. Reopening the issue does not update the board's Status field; unless the board has GitHub's built-in "item closed -> set Status" workflow enabled, pair this with `update_issue_field` if the board Status should reflect the reopening.
220
+
217
221
  - **`update_issue_labels`** -- Add and/or remove labels on the issue underlying a project item. Board-independent (queries by item ID). At least one of `addLabels`/`removeLabels` is required. Labels being added must already exist in the repository -- non-existent labels are rejected with a clear error instead of being auto-created. `added` and `removed` in the response both reflect effective changes only -- labels not already present pre-call for `added`, labels that were actually present pre-call for `removed` -- rather than echoing the requested sets.
218
222
 
219
223
  ## MCP Resources
@@ -232,7 +236,7 @@ Resources are provided per board. Read the schema resource before querying to un
232
236
  - `giantswarm/roadmap` is public. Use it only for sanitized, public-safe issue content.
233
237
  - `giantswarm/giantswarm` is internal/private. Use it for internal and customer-specific operational details.
234
238
  - Customer board issues live in private customer repositories (e.g. `giantswarm/<customer>`). The board itself is a public GitHub project, but issue content is only visible to users with repository access.
235
- - The server enforces an explicit confirmation (`confirmPublicSafe=true`) before creating issues in `giantswarm/roadmap`.
239
+ - The server enforces an explicit confirmation (`confirmPublicSafe=true`) before creating issues in `giantswarm/roadmap`, and before posting a comment via `close_issue`/`reopen_issue` on an issue in any public repository.
236
240
 
237
241
  ## Example Conversations
238
242
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.4.0",
3
+ "version": "1.5.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/lib/items.js CHANGED
@@ -151,6 +151,8 @@ function resolveRepositoryName(repository) {
151
151
  * @param {string} [options.state] - Filter by issue state: "open" or "closed"
152
152
  * @param {string} [options.keyword] - Free text search matching titles and text fields
153
153
  * @param {string} [options.updated] - Filter by last-updated date (e.g. ">@today-7d")
154
+ * @param {string} [options.created] - Filter by creation date (e.g. ">@today-90d")
155
+ * @param {string} [options.closed] - Filter by closed date (e.g. ">@today-30d")
154
156
  * @param {string} [options.reason] - Filter by close reason: "completed", "not planned", or "reopened"
155
157
  * @param {string} [options.token] - Optional per-request GitHub token
156
158
  * @returns {Promise<Object>} - Result with status and data
@@ -161,7 +163,7 @@ export async function listItems(options) {
161
163
  const {
162
164
  boardId, repository = null, filters = {}, emptyFields = [],
163
165
  assignee = null, label = null, state = null, keyword = null,
164
- updated = null, reason = null, token
166
+ updated = null, created = null, closed = null, reason = null, token
165
167
  } = options;
166
168
 
167
169
  if (!boardId) {
@@ -222,6 +224,24 @@ export async function listItems(options) {
222
224
  }
223
225
  }
224
226
 
227
+ // Created date filter — same GitHub Projects query syntax as `updated`.
228
+ // Examples: ">@today-90d", "<@today-30d", "@today", ">2025-01-01"
229
+ if (created) {
230
+ const trimmed = created.trim();
231
+ if (trimmed) {
232
+ queryTerms.push(`created:${trimmed}`);
233
+ }
234
+ }
235
+
236
+ // Closed date filter — same GitHub Projects query syntax as `updated`.
237
+ // Examples: ">@today-30d", "<@today-7d", "@today", ">2025-01-01"
238
+ if (closed) {
239
+ const trimmed = closed.trim();
240
+ if (trimmed) {
241
+ queryTerms.push(`closed:${trimmed}`);
242
+ }
243
+ }
244
+
225
245
  // Close reason filter
226
246
  if (reason) {
227
247
  const trimmed = reason.trim();
@@ -387,10 +407,14 @@ export async function listItems(options) {
387
407
  url: item.content?.url,
388
408
  repo: item.content?.repository?.nameWithOwner || null,
389
409
  private: item.content?.repository?.isPrivate ?? null,
410
+ state: item.content?.state || null,
411
+ createdAt: item.content?.createdAt || null,
412
+ updatedAt: item.content?.updatedAt || null,
390
413
  fields
391
414
  };
392
415
 
393
- // Only include assignees and labels when non-empty to keep output compact
416
+ // Only include closedAt, assignees, and labels when non-empty to keep output compact
417
+ if (item.content?.closedAt) entry.closedAt = item.content.closedAt;
394
418
  if (assignees.length > 0) entry.assignees = assignees;
395
419
  if (labels.length > 0) entry.labels = labels;
396
420
 
@@ -1,13 +1,15 @@
1
1
  /**
2
2
  * MCP Tools Implementation
3
3
  *
4
- * Exposes 7 tools for managing Giant Swarm project boards:
4
+ * Exposes 9 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
8
8
  * - create_issue_in_project: Create a new issue and add to a board
9
9
  * - add_existing_issue: Add an existing issue to a board
10
10
  * - archive_item: Archive a project item
11
+ * - close_issue: Close the issue underlying a project item
12
+ * - reopen_issue: Reopen the issue underlying a project item
11
13
  * - update_issue_labels: Add and/or remove labels on an issue
12
14
  */
13
15
 
@@ -25,7 +27,11 @@ import {
25
27
  ARCHIVE_ITEM_MUTATION,
26
28
  ISSUE_NODE_ID_QUERY,
27
29
  UPDATE_ITEM_FIELD_MUTATION,
28
- USER_ID_QUERY
30
+ USER_ID_QUERY,
31
+ ITEM_ISSUE_ID_QUERY,
32
+ CLOSE_ISSUE_MUTATION,
33
+ REOPEN_ISSUE_MUTATION,
34
+ ADD_COMMENT_MUTATION
29
35
  } from '../project.js';
30
36
  import { logger } from '../logger.js';
31
37
  import { subIssueTools, subIssueToolHandlers } from './sub-issues.js';
@@ -42,13 +48,29 @@ function extractToken(extra) {
42
48
  return extra?.authInfo?.token;
43
49
  }
44
50
 
51
+ /**
52
+ * Resolve a project item ID to its underlying GitHub issue (id, number, state, url,
53
+ * and repository visibility).
54
+ * @param {string} itemId - The project item ID
55
+ * @param {string} [token] - Optional per-request GitHub token
56
+ * @returns {Promise<{id: string, number: number, state: string, url: string, repository: {isPrivate: boolean, nameWithOwner: string}}>}
57
+ */
58
+ async function resolveItemIssueId(itemId, token) {
59
+ const result = await graphQLWithAuth(ITEM_ISSUE_ID_QUERY, { itemId }, token);
60
+ const issue = result?.node?.content;
61
+ if (!issue?.id) {
62
+ throw new Error(`Could not resolve an underlying issue for item '${itemId}'`);
63
+ }
64
+ return issue;
65
+ }
66
+
45
67
  // ---------------------------------------------------------------------------
46
68
  // Tool: list_issues
47
69
  // ---------------------------------------------------------------------------
48
70
 
49
71
  export const listIssuesTool = {
50
72
  name: 'list_issues',
51
- description: 'List and filter issues from a project board (roadmap or customer). Uses generic field filters -- read the board\'s schema resource first (e.g. roadmap://schema or customer://schema) to discover available fields and valid option values. Returns compact items with `repo` (nameWithOwner), `private` flag, and a `fields` map (only non-empty values). The repo URL is always https://github.com/{repo}.',
73
+ description: 'List and filter issues from a project board (roadmap or customer). Uses generic field filters -- read the board\'s schema resource first (e.g. roadmap://schema or customer://schema) to discover available fields and valid option values. Returns compact items with `repo` (nameWithOwner), `private` flag, `state` (OPEN/CLOSED), `createdAt`/`updatedAt` timestamps, `closedAt` (only present when the item is closed), and a `fields` map (only non-empty values). The repo URL is always https://github.com/{repo}.',
52
74
  inputSchema: {
53
75
  type: 'object',
54
76
  properties: {
@@ -92,6 +114,14 @@ export const listIssuesTool = {
92
114
  type: 'string',
93
115
  description: 'Filter by last-updated date using GitHub Projects syntax. Examples: ">@today-7d" (updated in last 7 days), "<@today-30d" (not updated in last 30 days), "@today" (updated today), ">2025-01-01" (updated after a specific date).'
94
116
  },
117
+ created: {
118
+ type: 'string',
119
+ description: 'Filter by creation date using GitHub Projects syntax. Examples: ">@today-90d" (created in last 90 days), "<@today-365d" (created more than a year ago), ">2025-01-01" (created after a specific date).'
120
+ },
121
+ closed: {
122
+ type: 'string',
123
+ description: 'Filter by closed date using GitHub Projects syntax. Only applies to closed items. Examples: ">@today-30d" (closed in last 30 days), "@today" (closed today), ">2025-01-01" (closed after a specific date).'
124
+ },
95
125
  reason: {
96
126
  type: 'string',
97
127
  enum: ['completed', 'not planned', 'reopened'],
@@ -101,9 +131,9 @@ export const listIssuesTool = {
101
131
  }
102
132
  };
103
133
 
104
- const KNOWN_LIST_PARAMS = new Set([
134
+ export const KNOWN_LIST_PARAMS = new Set([
105
135
  'board', 'project', 'repository', 'filters', 'emptyFields',
106
- 'assignee', 'label', 'state', 'keyword', 'updated', 'reason'
136
+ 'assignee', 'label', 'state', 'keyword', 'updated', 'created', 'closed', 'reason'
107
137
  ]);
108
138
 
109
139
  // Board field names are single words (Team, Kind, Status), so simple
@@ -130,7 +160,8 @@ export async function handleListIssues(args, extra) {
130
160
  board, repository: args.repository, filters,
131
161
  emptyFields: args.emptyFields, assignee: args.assignee,
132
162
  label: args.label, state: args.state, keyword: args.keyword,
133
- updated: args.updated, reason: args.reason
163
+ updated: args.updated, created: args.created, closed: args.closed,
164
+ reason: args.reason
134
165
  });
135
166
 
136
167
  const result = await listItems({
@@ -143,6 +174,8 @@ export async function handleListIssues(args, extra) {
143
174
  state: args.state || null,
144
175
  keyword: args.keyword || null,
145
176
  updated: args.updated || null,
177
+ created: args.created || null,
178
+ closed: args.closed || null,
146
179
  reason: args.reason || null,
147
180
  token
148
181
  });
@@ -621,6 +654,153 @@ export async function handleArchiveItem(args, extra) {
621
654
  }
622
655
  }
623
656
 
657
+ // ---------------------------------------------------------------------------
658
+ // Tool: close_issue
659
+ // ---------------------------------------------------------------------------
660
+
661
+ export const closeIssueTool = {
662
+ name: 'close_issue',
663
+ description: 'Close the GitHub issue underlying a single project board item. Board-independent (queries by item ID). Optionally posts a comment before closing. Operates on exactly one item per call -- there is no bulk close. Comments on issues in public repos require confirmPublicSafe=true. This does not change the board\'s Status field -- unless the board has GitHub\'s built-in "item closed -> set Status" workflow enabled, pair this call with update_issue_field if the board Status should reflect the closure.',
664
+ inputSchema: {
665
+ type: 'object',
666
+ properties: {
667
+ itemId: {
668
+ type: 'string',
669
+ description: 'The project item ID whose underlying issue should be closed'
670
+ },
671
+ stateReason: {
672
+ type: 'string',
673
+ enum: ['completed', 'not_planned'],
674
+ description: 'Why the issue is being closed. Defaults to "completed".'
675
+ },
676
+ comment: {
677
+ type: 'string',
678
+ description: 'Optional comment to post on the issue before closing it'
679
+ },
680
+ confirmPublicSafe: {
681
+ type: 'boolean',
682
+ description: 'Required when comment is provided and the underlying issue is in a public repository. Must be true to confirm the comment is sanitized and safe for public visibility.'
683
+ }
684
+ },
685
+ required: ['itemId']
686
+ }
687
+ };
688
+
689
+ export async function handleCloseIssue(args, extra) {
690
+ try {
691
+ const token = extractToken(extra);
692
+ logger.info('MCP: Closing issue', { itemId: args.itemId, stateReason: args.stateReason });
693
+
694
+ // Validate stateReason before any network calls -- an invalid value must not
695
+ // have side effects (e.g. posting a comment) before the error is returned.
696
+ let stateReason;
697
+ if (!args.stateReason) {
698
+ stateReason = 'COMPLETED';
699
+ } else if (args.stateReason === 'completed') {
700
+ stateReason = 'COMPLETED';
701
+ } else if (args.stateReason === 'not_planned') {
702
+ stateReason = 'NOT_PLANNED';
703
+ } else {
704
+ return { error: `Invalid stateReason '${args.stateReason}'. Must be "completed" or "not_planned".` };
705
+ }
706
+
707
+ const issue = await resolveItemIssueId(args.itemId, token);
708
+
709
+ if (args.comment) {
710
+ if (issue.repository?.isPrivate === false && args.confirmPublicSafe !== true) {
711
+ return {
712
+ error: `Posting a comment to ${issue.repository.nameWithOwner} (public) requires confirmPublicSafe=true to reduce accidental disclosure of internal or customer-specific information.`
713
+ };
714
+ }
715
+ await graphQLWithAuth(ADD_COMMENT_MUTATION, { subjectId: issue.id, body: args.comment }, token);
716
+ }
717
+
718
+ const result = await graphQLWithAuth(CLOSE_ISSUE_MUTATION, { issueId: issue.id, stateReason }, token);
719
+ const closed = result.closeIssue.issue;
720
+
721
+ return {
722
+ content: [{
723
+ type: 'text',
724
+ text: JSON.stringify({
725
+ success: true,
726
+ itemId: args.itemId,
727
+ issueUrl: closed.url,
728
+ state: closed.state,
729
+ stateReason: closed.stateReason,
730
+ commentPosted: Boolean(args.comment)
731
+ })
732
+ }]
733
+ };
734
+ } catch (error) {
735
+ logger.error('MCP: Error closing issue', { error: error.message });
736
+ return { error: error.message };
737
+ }
738
+ }
739
+
740
+ // ---------------------------------------------------------------------------
741
+ // Tool: reopen_issue
742
+ // ---------------------------------------------------------------------------
743
+
744
+ export const reopenIssueTool = {
745
+ name: 'reopen_issue',
746
+ description: 'Reopen the GitHub issue underlying a single project board item. Board-independent (queries by item ID). Optionally posts a comment before reopening. Operates on exactly one item per call -- there is no bulk reopen. Comments on issues in public repos require confirmPublicSafe=true. This does not change the board\'s Status field -- unless the board has GitHub\'s built-in "item closed -> set Status" workflow enabled, pair this call with update_issue_field if the board Status should reflect the reopening.',
747
+ inputSchema: {
748
+ type: 'object',
749
+ properties: {
750
+ itemId: {
751
+ type: 'string',
752
+ description: 'The project item ID whose underlying issue should be reopened'
753
+ },
754
+ comment: {
755
+ type: 'string',
756
+ description: 'Optional comment to post on the issue before reopening it'
757
+ },
758
+ confirmPublicSafe: {
759
+ type: 'boolean',
760
+ description: 'Required when comment is provided and the underlying issue is in a public repository. Must be true to confirm the comment is sanitized and safe for public visibility.'
761
+ }
762
+ },
763
+ required: ['itemId']
764
+ }
765
+ };
766
+
767
+ export async function handleReopenIssue(args, extra) {
768
+ try {
769
+ const token = extractToken(extra);
770
+ logger.info('MCP: Reopening issue', { itemId: args.itemId });
771
+
772
+ const issue = await resolveItemIssueId(args.itemId, token);
773
+
774
+ if (args.comment) {
775
+ if (issue.repository?.isPrivate === false && args.confirmPublicSafe !== true) {
776
+ return {
777
+ error: `Posting a comment to ${issue.repository.nameWithOwner} (public) requires confirmPublicSafe=true to reduce accidental disclosure of internal or customer-specific information.`
778
+ };
779
+ }
780
+ await graphQLWithAuth(ADD_COMMENT_MUTATION, { subjectId: issue.id, body: args.comment }, token);
781
+ }
782
+
783
+ const result = await graphQLWithAuth(REOPEN_ISSUE_MUTATION, { issueId: issue.id }, token);
784
+ const reopened = result.reopenIssue.issue;
785
+
786
+ return {
787
+ content: [{
788
+ type: 'text',
789
+ text: JSON.stringify({
790
+ success: true,
791
+ itemId: args.itemId,
792
+ issueUrl: reopened.url,
793
+ state: reopened.state,
794
+ commentPosted: Boolean(args.comment)
795
+ })
796
+ }]
797
+ };
798
+ } catch (error) {
799
+ logger.error('MCP: Error reopening issue', { error: error.message });
800
+ return { error: error.message };
801
+ }
802
+ }
803
+
624
804
  // ---------------------------------------------------------------------------
625
805
  // Tool: update_issue_labels
626
806
  // ---------------------------------------------------------------------------
@@ -737,6 +917,8 @@ export const tools = [
737
917
  createIssueInProjectTool,
738
918
  addExistingIssueTool,
739
919
  archiveItemTool,
920
+ closeIssueTool,
921
+ reopenIssueTool,
740
922
  updateIssueLabelsTool,
741
923
  ...subIssueTools
742
924
  ];
@@ -748,6 +930,8 @@ export const toolHandlers = {
748
930
  create_issue_in_project: handleCreateIssueInProject,
749
931
  add_existing_issue: handleAddExistingIssue,
750
932
  archive_item: handleArchiveItem,
933
+ close_issue: handleCloseIssue,
934
+ reopen_issue: handleReopenIssue,
751
935
  update_issue_labels: handleUpdateIssueLabels,
752
936
  ...subIssueToolHandlers
753
937
  };
@@ -171,6 +171,10 @@ const LIST_ITEMS_QUERY = `
171
171
  title
172
172
  number
173
173
  url
174
+ state
175
+ createdAt
176
+ updatedAt
177
+ closedAt
174
178
  repository {
175
179
  nameWithOwner
176
180
  isPrivate
@@ -391,6 +395,74 @@ const USER_ID_QUERY = `
391
395
  }
392
396
  `;
393
397
 
398
+ // Query to resolve the underlying issue node ID for a project item, including
399
+ // the repository's visibility so callers can gate free-text writes (e.g. comments)
400
+ // to public repos behind an explicit confirmation.
401
+ const ITEM_ISSUE_ID_QUERY = `
402
+ query GetItemIssueId($itemId: ID!) {
403
+ node(id: $itemId) {
404
+ ... on ProjectV2Item {
405
+ content {
406
+ ... on Issue {
407
+ id
408
+ number
409
+ state
410
+ url
411
+ repository {
412
+ isPrivate
413
+ nameWithOwner
414
+ }
415
+ }
416
+ }
417
+ }
418
+ }
419
+ }
420
+ `;
421
+
422
+ // Mutation to close an issue
423
+ const CLOSE_ISSUE_MUTATION = `
424
+ mutation CloseIssue($issueId: ID!, $stateReason: IssueClosedStateReason) {
425
+ closeIssue(input: { issueId: $issueId, stateReason: $stateReason }) {
426
+ issue {
427
+ id
428
+ number
429
+ state
430
+ stateReason
431
+ url
432
+ }
433
+ }
434
+ }
435
+ `;
436
+
437
+ // Mutation to reopen an issue
438
+ const REOPEN_ISSUE_MUTATION = `
439
+ mutation ReopenIssue($issueId: ID!) {
440
+ reopenIssue(input: { issueId: $issueId }) {
441
+ issue {
442
+ id
443
+ number
444
+ state
445
+ url
446
+ }
447
+ }
448
+ }
449
+ `;
450
+
451
+ // Mutation to add a comment to an issue (used to post a comment before
452
+ // closing/reopening when the caller supplies one)
453
+ const ADD_COMMENT_MUTATION = `
454
+ mutation AddComment($subjectId: ID!, $body: String!) {
455
+ addComment(input: { subjectId: $subjectId, body: $body }) {
456
+ commentEdge {
457
+ node {
458
+ id
459
+ url
460
+ }
461
+ }
462
+ }
463
+ }
464
+ `;
465
+
394
466
  export {
395
467
  REPO_ID_QUERY,
396
468
  LIST_ITEMS_QUERY,
@@ -402,5 +474,9 @@ export {
402
474
  ADD_ITEM_TO_PROJECT_MUTATION,
403
475
  ARCHIVE_ITEM_MUTATION,
404
476
  ISSUE_NODE_ID_QUERY,
405
- USER_ID_QUERY
477
+ USER_ID_QUERY,
478
+ ITEM_ISSUE_ID_QUERY,
479
+ CLOSE_ISSUE_MUTATION,
480
+ REOPEN_ISSUE_MUTATION,
481
+ ADD_COMMENT_MUTATION
406
482
  };