@giantswarm-io/pro 1.3.1 → 1.4.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
@@ -194,7 +194,7 @@ The container defaults to `--transport=streamable-http`.
194
194
  | `roadmap` | [#273](https://github.com/orgs/giantswarm/projects/273) | Company quarterly goals, team/SIG/WG issues |
195
195
  | `customer` | [#345](https://github.com/orgs/giantswarm/projects/345) | Customer activities and requests from private repos |
196
196
 
197
- The `board` parameter defaults to `"roadmap"` on all tools for backward compatibility.
197
+ The `board` parameter defaults to `"roadmap"` on every board-scoped tool for backward compatibility. Tools that resolve purely by item ID (e.g. `get_issue_details`, `update_issue_labels`) don't take a `board` parameter at all.
198
198
 
199
199
  ## MCP Tools
200
200
 
@@ -208,12 +208,14 @@ The `board` parameter defaults to `"roadmap"` on all tools for backward compatib
208
208
 
209
209
  - **`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.
210
210
 
211
- - **`create_issue_in_project`** -- Create a new GitHub Issue in a repository and add it to a board. Optionally set initial status and assignees. Public issues in `giantswarm/roadmap` require `confirmPublicSafe=true`.
211
+ - **`create_issue_in_project`** -- Create a new GitHub Issue in a repository and add it to a board. Optionally set initial status, assignees, and labels. Public issues in `giantswarm/roadmap` require `confirmPublicSafe=true`. Labels must already exist in the repository -- non-existent labels are rejected before the issue is created rather than being auto-created. If applying labels fails *after* the issue has already been created and added to the board, the issue is not rolled back -- the response reports `success: true` with a `warning` explaining that labels were not applied.
212
212
 
213
213
  - **`add_existing_issue`** -- Add an existing GitHub issue to a board by URL or node ID.
214
214
 
215
215
  - **`archive_item`** -- Archive a project item from the active board view.
216
216
 
217
+ - **`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
+
217
219
  ## MCP Resources
218
220
 
219
221
  Resources are provided per board. Read the schema resource before querying to understand the available fields and their valid option values.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.3.1",
3
+ "version": "1.4.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": {
@@ -28,7 +28,7 @@
28
28
  "start": "node bin/index.js",
29
29
  "start:http": "node bin/index.js --transport=streamable-http",
30
30
  "self-update": "node bin/index.js --self-update",
31
- "test": "node --test"
31
+ "test": "node --experimental-test-module-mocks --test"
32
32
  },
33
33
  "dependencies": {
34
34
  "@modelcontextprotocol/sdk": "^1.24.3",
@@ -1,18 +1,20 @@
1
1
  /**
2
2
  * MCP Tools Implementation
3
3
  *
4
- * Exposes 6 tools for managing Giant Swarm project boards:
4
+ * Exposes 7 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
+ * - update_issue_labels: Add and/or remove labels on an issue
11
12
  */
12
13
 
13
14
  import { listItems, getItemByID, updateItemField } from '../items.js';
14
15
  import { findFieldByName, findMatchingOption, findMatchingIteration } from '../fields.js';
15
16
  import { graphQLWithAuth } from '../api.js';
17
+ import { findMissingLabels, addLabelsToIssue, removeLabelFromIssue } from '../rest-api.js';
16
18
  import {
17
19
  resolveBoardId,
18
20
  DEFAULT_BOARD,
@@ -311,7 +313,7 @@ export async function handleUpdateIssueField(args, extra) {
311
313
 
312
314
  export const createIssueInProjectTool = {
313
315
  name: 'create_issue_in_project',
314
- description: 'Create a new GitHub Issue in a specified repository and add it to a project board. Supports optional initial status and assignees. For public repos, only create sanitized, non-customer-specific content.',
316
+ description: 'Create a new GitHub Issue in a specified repository and add it to a project board. Supports optional initial status, assignees, and labels. For public repos, only create sanitized, non-customer-specific content. If applying labels fails after the issue has already been created and added to the board, the issue is NOT rolled back -- the response reports success with a `warning` explaining that labels were not applied.',
315
317
  inputSchema: {
316
318
  type: 'object',
317
319
  properties: {
@@ -332,6 +334,11 @@ export const createIssueInProjectTool = {
332
334
  description: 'Optional GitHub usernames to assign to the new issue',
333
335
  items: { type: 'string' }
334
336
  },
337
+ labels: {
338
+ type: 'array',
339
+ description: 'Optional label names to apply to the new issue. Every label must already exist in the repository -- non-existent labels cause the request to fail (with no issue created) rather than being auto-created.',
340
+ items: { type: 'string' }
341
+ },
335
342
  confirmPublicSafe: {
336
343
  type: 'boolean',
337
344
  description: 'Required when repository resolves to giantswarm/roadmap. Must be true to confirm the title/body are sanitized and safe for public visibility.'
@@ -372,13 +379,30 @@ export async function handleCreateIssueInProject(args, extra) {
372
379
  };
373
380
  }
374
381
 
375
- // Get repository node ID
382
+ const labels = Array.isArray(args.labels)
383
+ ? args.labels.map(l => String(l || '').trim()).filter(l => l !== '')
384
+ : [];
385
+
386
+ // Get repository node ID. Checked before label validation so a typo'd
387
+ // repository name yields "Repository not found" rather than a
388
+ // confusing label error.
376
389
  const repoResult = await graphQLWithAuth(REPO_ID_QUERY, { owner, repo }, token);
377
390
  if (!repoResult?.repository?.id) {
378
391
  return { error: `Repository '${owner}/${repo}' not found` };
379
392
  }
380
393
  const repositoryId = repoResult.repository.id;
381
394
 
395
+ // Validate labels BEFORE creating the issue so a bad label name never
396
+ // leaves an orphan issue behind.
397
+ if (labels.length > 0) {
398
+ const missing = await findMissingLabels(owner, repo, labels, token);
399
+ if (missing.length > 0) {
400
+ return {
401
+ error: `Label(s) not found in ${owner}/${repo}: ${missing.join(', ')}. Create the label first or fix the name -- labels are not auto-created.`
402
+ };
403
+ }
404
+ }
405
+
382
406
  const assigneeLogins = Array.isArray(args.assignees)
383
407
  ? args.assignees
384
408
  .map(login => String(login || '').trim())
@@ -412,6 +436,25 @@ export async function handleCreateIssueInProject(args, extra) {
412
436
 
413
437
  const projectItemId = addResult.addProjectV2ItemById.item.id;
414
438
 
439
+ // Apply labels (already validated above to exist in the repository).
440
+ // The issue and its board membership are already committed at this point,
441
+ // so a failure here is best-effort: log it and surface a warning rather
442
+ // than failing the whole call, since a caller retrying on failure would
443
+ // otherwise create a duplicate issue.
444
+ let labelWarning;
445
+ let labelsApplied = false;
446
+ if (labels.length > 0) {
447
+ try {
448
+ await addLabelsToIssue(owner, repo, issue.number, labels, token);
449
+ labelsApplied = true;
450
+ } catch (error) {
451
+ logger.error('MCP: Failed to apply labels after issue creation', {
452
+ issueUrl: issue.url, labels, error: error.message
453
+ });
454
+ labelWarning = `Issue was created and added to the board, but applying labels failed: ${error.message}`;
455
+ }
456
+ }
457
+
415
458
  // Set initial status if provided
416
459
  if (args.initialStatus) {
417
460
  const statusField = await findFieldByName('status', boardId, token);
@@ -435,7 +478,9 @@ export async function handleCreateIssueInProject(args, extra) {
435
478
  success: true,
436
479
  issueUrl: issue.url,
437
480
  issueNumber: issue.number,
438
- projectItemId
481
+ projectItemId,
482
+ labels: labelsApplied ? labels : undefined,
483
+ warning: labelWarning
439
484
  })
440
485
  }]
441
486
  };
@@ -576,6 +621,111 @@ export async function handleArchiveItem(args, extra) {
576
621
  }
577
622
  }
578
623
 
624
+ // ---------------------------------------------------------------------------
625
+ // Tool: update_issue_labels
626
+ // ---------------------------------------------------------------------------
627
+
628
+ export const updateIssueLabelsTool = {
629
+ name: 'update_issue_labels',
630
+ description: 'Add and/or remove labels on the issue underlying a project board item. At least one of addLabels or removeLabels must be provided. Labels being added must already exist in the repository -- non-existent labels are rejected with an error listing them, rather than being auto-created.',
631
+ inputSchema: {
632
+ type: 'object',
633
+ properties: {
634
+ itemId: {
635
+ type: 'string',
636
+ description: 'The ID of the project item whose underlying issue should be updated'
637
+ },
638
+ addLabels: {
639
+ type: 'array',
640
+ description: 'Label names to add to the issue. Must already exist in the repository.',
641
+ items: { type: 'string' }
642
+ },
643
+ removeLabels: {
644
+ type: 'array',
645
+ description: 'Label names to remove from the issue.',
646
+ items: { type: 'string' }
647
+ }
648
+ },
649
+ required: ['itemId']
650
+ }
651
+ };
652
+
653
+ export async function handleUpdateIssueLabels(args, extra) {
654
+ try {
655
+ const addLabels = Array.isArray(args.addLabels)
656
+ ? args.addLabels.map(l => String(l || '').trim()).filter(l => l !== '')
657
+ : [];
658
+ const removeLabels = Array.isArray(args.removeLabels)
659
+ ? args.removeLabels.map(l => String(l || '').trim()).filter(l => l !== '')
660
+ : [];
661
+
662
+ if (addLabels.length === 0 && removeLabels.length === 0) {
663
+ return { error: 'At least one of addLabels or removeLabels must be provided.' };
664
+ }
665
+
666
+ const token = extractToken(extra);
667
+ logger.info('MCP: Updating issue labels', { itemId: args.itemId, addLabels, removeLabels });
668
+
669
+ const item = await getItemByID(args.itemId, token);
670
+ if (!item.repository?.nameWithOwner || !item.number) {
671
+ return { error: `Could not resolve the underlying issue for item '${args.itemId}'.` };
672
+ }
673
+ const [owner, repo] = item.repository.nameWithOwner.split('/');
674
+ const issueNumber = item.number;
675
+
676
+ // Snapshot of labels currently on the issue, used below to report which
677
+ // requested removals actually changed anything (removeLabelFromIssue
678
+ // swallows a 404 whether the label was never applied or never existed,
679
+ // so this is the only way to distinguish an effective removal from a
680
+ // no-op).
681
+ const currentLabels = new Set((item.labels || []).map(l => l.toLowerCase()));
682
+
683
+ // Validate additions exist in the repo BEFORE mutating anything -- GitHub's
684
+ // add-labels endpoint would otherwise silently create missing labels.
685
+ if (addLabels.length > 0) {
686
+ const missing = await findMissingLabels(owner, repo, addLabels, token);
687
+ if (missing.length > 0) {
688
+ return {
689
+ error: `Label(s) not found in ${owner}/${repo}: ${missing.join(', ')}. Create the label first or fix the name -- labels are not auto-created.`
690
+ };
691
+ }
692
+ }
693
+
694
+ if (addLabels.length > 0) {
695
+ await addLabelsToIssue(owner, repo, issueNumber, addLabels, token);
696
+ }
697
+
698
+ // Only report additions that actually changed something -- labels already
699
+ // present pre-call are a no-op, mirroring how `removed` below is computed.
700
+ const added = addLabels.filter(name => !currentLabels.has(name.toLowerCase()));
701
+
702
+ const removed = [];
703
+ for (const name of removeLabels) {
704
+ await removeLabelFromIssue(owner, repo, issueNumber, name, token);
705
+ if (currentLabels.has(name.toLowerCase())) {
706
+ removed.push(name);
707
+ }
708
+ }
709
+
710
+ return {
711
+ content: [{
712
+ type: 'text',
713
+ text: JSON.stringify({
714
+ success: true,
715
+ itemId: args.itemId,
716
+ repository: `${owner}/${repo}`,
717
+ issueNumber,
718
+ added,
719
+ removed
720
+ })
721
+ }]
722
+ };
723
+ } catch (error) {
724
+ logger.error('MCP: Error updating issue labels', { error: error.message });
725
+ return { error: error.message };
726
+ }
727
+ }
728
+
579
729
  // ---------------------------------------------------------------------------
580
730
  // Exports
581
731
  // ---------------------------------------------------------------------------
@@ -587,6 +737,7 @@ export const tools = [
587
737
  createIssueInProjectTool,
588
738
  addExistingIssueTool,
589
739
  archiveItemTool,
740
+ updateIssueLabelsTool,
590
741
  ...subIssueTools
591
742
  ];
592
743
 
@@ -597,5 +748,6 @@ export const toolHandlers = {
597
748
  create_issue_in_project: handleCreateIssueInProject,
598
749
  add_existing_issue: handleAddExistingIssue,
599
750
  archive_item: handleArchiveItem,
751
+ update_issue_labels: handleUpdateIssueLabels,
600
752
  ...subIssueToolHandlers
601
753
  };
@@ -1,9 +1,10 @@
1
1
  /**
2
2
  * GitHub REST API Client
3
3
  *
4
- * Provides an authenticated Octokit REST client for the GitHub sub-issues API
5
- * (REST-only, not available via GraphQL). Includes utilities for parsing issue
6
- * references and resolving them to integer IDs required by the sub-issues endpoints.
4
+ * Provides an authenticated Octokit REST client for GitHub REST-only endpoints
5
+ * not available via GraphQL: sub-issues and issue labels. Includes utilities
6
+ * for parsing issue references, resolving them to integer IDs, and managing
7
+ * labels (validation, add, remove).
7
8
  *
8
9
  * Supports per-request tokens (for OAuth/HTTP transport) with fallback
9
10
  * to the GITHUB_API_TOKEN environment variable (for stdio transport).
@@ -139,3 +140,76 @@ export async function resolveIssueId(ownerOrRef, repo, issue_number, options) {
139
140
  repository: `${owner}/${repo}`
140
141
  };
141
142
  }
143
+
144
+ /**
145
+ * Check which of the given label names do not exist in a repository.
146
+ *
147
+ * GitHub's "add labels to issue" REST endpoint silently auto-creates any
148
+ * label name that doesn't already exist, which would let a typo create
149
+ * clutter labels instead of failing loudly. Callers should call this first
150
+ * and reject the request if it returns any missing names.
151
+ *
152
+ * @param {string} owner - Repository owner
153
+ * @param {string} repo - Repository name
154
+ * @param {string[]} labels - Label names to check
155
+ * @param {string} [token] - Optional per-request GitHub token
156
+ * @returns {Promise<string[]>} - Names that do not exist in the repository
157
+ */
158
+ export async function findMissingLabels(owner, repo, labels, token) {
159
+ const client = getOctokit(token);
160
+ const missing = [];
161
+ for (const name of labels) {
162
+ try {
163
+ await client.rest.issues.getLabel({ owner, repo, name });
164
+ } catch (err) {
165
+ if (err.status === 404) {
166
+ missing.push(name);
167
+ } else {
168
+ throw err;
169
+ }
170
+ }
171
+ }
172
+ return missing;
173
+ }
174
+
175
+ /**
176
+ * Add labels to an issue via REST.
177
+ * Callers should validate labels with findMissingLabels first to avoid
178
+ * GitHub's auto-create-on-add behavior.
179
+ *
180
+ * @param {string} owner - Repository owner
181
+ * @param {string} repo - Repository name
182
+ * @param {number} issue_number - Issue number
183
+ * @param {string[]} labels - Label names to add
184
+ * @param {string} [token] - Optional per-request GitHub token
185
+ * @returns {Promise<Array>} - The issue's full label list after the update
186
+ */
187
+ export async function addLabelsToIssue(owner, repo, issue_number, labels, token) {
188
+ const client = getOctokit(token);
189
+ const { data } = await client.rest.issues.addLabels({ owner, repo, issue_number, labels });
190
+ return data;
191
+ }
192
+
193
+ /**
194
+ * Remove a single label from an issue via REST.
195
+ * Treats a 404 (label not currently applied to the issue) as a no-op rather
196
+ * than an error, since removal is naturally idempotent.
197
+ *
198
+ * @param {string} owner - Repository owner
199
+ * @param {string} repo - Repository name
200
+ * @param {number} issue_number - Issue number
201
+ * @param {string} name - Label name to remove
202
+ * @param {string} [token] - Optional per-request GitHub token
203
+ * @returns {Promise<void>}
204
+ */
205
+ export async function removeLabelFromIssue(owner, repo, issue_number, name, token) {
206
+ const client = getOctokit(token);
207
+ try {
208
+ await client.rest.issues.removeLabel({ owner, repo, issue_number, name });
209
+ } catch (err) {
210
+ if (err.status !== 404) {
211
+ throw err;
212
+ }
213
+ logger.debug('removeLabelFromIssue: label already absent from issue', { owner, repo, issue_number, name });
214
+ }
215
+ }