@giantswarm-io/pro 1.3.1 → 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 +9 -3
- package/package.json +2 -2
- package/src/lib/items.js +26 -2
- package/src/lib/mcp/tools.js +345 -9
- package/src/lib/project.js +77 -1
- package/src/lib/rest-api.js +77 -3
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
|
|
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,18 @@ 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
|
|
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
|
+
- **`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
|
+
|
|
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.
|
|
222
|
+
|
|
217
223
|
## MCP Resources
|
|
218
224
|
|
|
219
225
|
Resources are provided per board. Read the schema resource before querying to understand the available fields and their valid option values.
|
|
@@ -230,7 +236,7 @@ Resources are provided per board. Read the schema resource before querying to un
|
|
|
230
236
|
- `giantswarm/roadmap` is public. Use it only for sanitized, public-safe issue content.
|
|
231
237
|
- `giantswarm/giantswarm` is internal/private. Use it for internal and customer-specific operational details.
|
|
232
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.
|
|
233
|
-
- 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.
|
|
234
240
|
|
|
235
241
|
## Example Conversations
|
|
236
242
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@giantswarm-io/pro",
|
|
3
|
-
"version": "1.
|
|
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": {
|
|
@@ -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",
|
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
|
|
package/src/lib/mcp/tools.js
CHANGED
|
@@ -1,18 +1,22 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* MCP Tools Implementation
|
|
3
3
|
*
|
|
4
|
-
* Exposes
|
|
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
|
|
13
|
+
* - update_issue_labels: Add and/or remove labels on an issue
|
|
11
14
|
*/
|
|
12
15
|
|
|
13
16
|
import { listItems, getItemByID, updateItemField } from '../items.js';
|
|
14
17
|
import { findFieldByName, findMatchingOption, findMatchingIteration } from '../fields.js';
|
|
15
18
|
import { graphQLWithAuth } from '../api.js';
|
|
19
|
+
import { findMissingLabels, addLabelsToIssue, removeLabelFromIssue } from '../rest-api.js';
|
|
16
20
|
import {
|
|
17
21
|
resolveBoardId,
|
|
18
22
|
DEFAULT_BOARD,
|
|
@@ -23,7 +27,11 @@ import {
|
|
|
23
27
|
ARCHIVE_ITEM_MUTATION,
|
|
24
28
|
ISSUE_NODE_ID_QUERY,
|
|
25
29
|
UPDATE_ITEM_FIELD_MUTATION,
|
|
26
|
-
USER_ID_QUERY
|
|
30
|
+
USER_ID_QUERY,
|
|
31
|
+
ITEM_ISSUE_ID_QUERY,
|
|
32
|
+
CLOSE_ISSUE_MUTATION,
|
|
33
|
+
REOPEN_ISSUE_MUTATION,
|
|
34
|
+
ADD_COMMENT_MUTATION
|
|
27
35
|
} from '../project.js';
|
|
28
36
|
import { logger } from '../logger.js';
|
|
29
37
|
import { subIssueTools, subIssueToolHandlers } from './sub-issues.js';
|
|
@@ -40,13 +48,29 @@ function extractToken(extra) {
|
|
|
40
48
|
return extra?.authInfo?.token;
|
|
41
49
|
}
|
|
42
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
|
+
|
|
43
67
|
// ---------------------------------------------------------------------------
|
|
44
68
|
// Tool: list_issues
|
|
45
69
|
// ---------------------------------------------------------------------------
|
|
46
70
|
|
|
47
71
|
export const listIssuesTool = {
|
|
48
72
|
name: 'list_issues',
|
|
49
|
-
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}.',
|
|
50
74
|
inputSchema: {
|
|
51
75
|
type: 'object',
|
|
52
76
|
properties: {
|
|
@@ -90,6 +114,14 @@ export const listIssuesTool = {
|
|
|
90
114
|
type: 'string',
|
|
91
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).'
|
|
92
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
|
+
},
|
|
93
125
|
reason: {
|
|
94
126
|
type: 'string',
|
|
95
127
|
enum: ['completed', 'not planned', 'reopened'],
|
|
@@ -99,9 +131,9 @@ export const listIssuesTool = {
|
|
|
99
131
|
}
|
|
100
132
|
};
|
|
101
133
|
|
|
102
|
-
const KNOWN_LIST_PARAMS = new Set([
|
|
134
|
+
export const KNOWN_LIST_PARAMS = new Set([
|
|
103
135
|
'board', 'project', 'repository', 'filters', 'emptyFields',
|
|
104
|
-
'assignee', 'label', 'state', 'keyword', 'updated', 'reason'
|
|
136
|
+
'assignee', 'label', 'state', 'keyword', 'updated', 'created', 'closed', 'reason'
|
|
105
137
|
]);
|
|
106
138
|
|
|
107
139
|
// Board field names are single words (Team, Kind, Status), so simple
|
|
@@ -128,7 +160,8 @@ export async function handleListIssues(args, extra) {
|
|
|
128
160
|
board, repository: args.repository, filters,
|
|
129
161
|
emptyFields: args.emptyFields, assignee: args.assignee,
|
|
130
162
|
label: args.label, state: args.state, keyword: args.keyword,
|
|
131
|
-
updated: args.updated,
|
|
163
|
+
updated: args.updated, created: args.created, closed: args.closed,
|
|
164
|
+
reason: args.reason
|
|
132
165
|
});
|
|
133
166
|
|
|
134
167
|
const result = await listItems({
|
|
@@ -141,6 +174,8 @@ export async function handleListIssues(args, extra) {
|
|
|
141
174
|
state: args.state || null,
|
|
142
175
|
keyword: args.keyword || null,
|
|
143
176
|
updated: args.updated || null,
|
|
177
|
+
created: args.created || null,
|
|
178
|
+
closed: args.closed || null,
|
|
144
179
|
reason: args.reason || null,
|
|
145
180
|
token
|
|
146
181
|
});
|
|
@@ -311,7 +346,7 @@ export async function handleUpdateIssueField(args, extra) {
|
|
|
311
346
|
|
|
312
347
|
export const createIssueInProjectTool = {
|
|
313
348
|
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
|
|
349
|
+
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
350
|
inputSchema: {
|
|
316
351
|
type: 'object',
|
|
317
352
|
properties: {
|
|
@@ -332,6 +367,11 @@ export const createIssueInProjectTool = {
|
|
|
332
367
|
description: 'Optional GitHub usernames to assign to the new issue',
|
|
333
368
|
items: { type: 'string' }
|
|
334
369
|
},
|
|
370
|
+
labels: {
|
|
371
|
+
type: 'array',
|
|
372
|
+
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.',
|
|
373
|
+
items: { type: 'string' }
|
|
374
|
+
},
|
|
335
375
|
confirmPublicSafe: {
|
|
336
376
|
type: 'boolean',
|
|
337
377
|
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 +412,30 @@ export async function handleCreateIssueInProject(args, extra) {
|
|
|
372
412
|
};
|
|
373
413
|
}
|
|
374
414
|
|
|
375
|
-
|
|
415
|
+
const labels = Array.isArray(args.labels)
|
|
416
|
+
? args.labels.map(l => String(l || '').trim()).filter(l => l !== '')
|
|
417
|
+
: [];
|
|
418
|
+
|
|
419
|
+
// Get repository node ID. Checked before label validation so a typo'd
|
|
420
|
+
// repository name yields "Repository not found" rather than a
|
|
421
|
+
// confusing label error.
|
|
376
422
|
const repoResult = await graphQLWithAuth(REPO_ID_QUERY, { owner, repo }, token);
|
|
377
423
|
if (!repoResult?.repository?.id) {
|
|
378
424
|
return { error: `Repository '${owner}/${repo}' not found` };
|
|
379
425
|
}
|
|
380
426
|
const repositoryId = repoResult.repository.id;
|
|
381
427
|
|
|
428
|
+
// Validate labels BEFORE creating the issue so a bad label name never
|
|
429
|
+
// leaves an orphan issue behind.
|
|
430
|
+
if (labels.length > 0) {
|
|
431
|
+
const missing = await findMissingLabels(owner, repo, labels, token);
|
|
432
|
+
if (missing.length > 0) {
|
|
433
|
+
return {
|
|
434
|
+
error: `Label(s) not found in ${owner}/${repo}: ${missing.join(', ')}. Create the label first or fix the name -- labels are not auto-created.`
|
|
435
|
+
};
|
|
436
|
+
}
|
|
437
|
+
}
|
|
438
|
+
|
|
382
439
|
const assigneeLogins = Array.isArray(args.assignees)
|
|
383
440
|
? args.assignees
|
|
384
441
|
.map(login => String(login || '').trim())
|
|
@@ -412,6 +469,25 @@ export async function handleCreateIssueInProject(args, extra) {
|
|
|
412
469
|
|
|
413
470
|
const projectItemId = addResult.addProjectV2ItemById.item.id;
|
|
414
471
|
|
|
472
|
+
// Apply labels (already validated above to exist in the repository).
|
|
473
|
+
// The issue and its board membership are already committed at this point,
|
|
474
|
+
// so a failure here is best-effort: log it and surface a warning rather
|
|
475
|
+
// than failing the whole call, since a caller retrying on failure would
|
|
476
|
+
// otherwise create a duplicate issue.
|
|
477
|
+
let labelWarning;
|
|
478
|
+
let labelsApplied = false;
|
|
479
|
+
if (labels.length > 0) {
|
|
480
|
+
try {
|
|
481
|
+
await addLabelsToIssue(owner, repo, issue.number, labels, token);
|
|
482
|
+
labelsApplied = true;
|
|
483
|
+
} catch (error) {
|
|
484
|
+
logger.error('MCP: Failed to apply labels after issue creation', {
|
|
485
|
+
issueUrl: issue.url, labels, error: error.message
|
|
486
|
+
});
|
|
487
|
+
labelWarning = `Issue was created and added to the board, but applying labels failed: ${error.message}`;
|
|
488
|
+
}
|
|
489
|
+
}
|
|
490
|
+
|
|
415
491
|
// Set initial status if provided
|
|
416
492
|
if (args.initialStatus) {
|
|
417
493
|
const statusField = await findFieldByName('status', boardId, token);
|
|
@@ -435,7 +511,9 @@ export async function handleCreateIssueInProject(args, extra) {
|
|
|
435
511
|
success: true,
|
|
436
512
|
issueUrl: issue.url,
|
|
437
513
|
issueNumber: issue.number,
|
|
438
|
-
projectItemId
|
|
514
|
+
projectItemId,
|
|
515
|
+
labels: labelsApplied ? labels : undefined,
|
|
516
|
+
warning: labelWarning
|
|
439
517
|
})
|
|
440
518
|
}]
|
|
441
519
|
};
|
|
@@ -576,6 +654,258 @@ export async function handleArchiveItem(args, extra) {
|
|
|
576
654
|
}
|
|
577
655
|
}
|
|
578
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
|
+
|
|
804
|
+
// ---------------------------------------------------------------------------
|
|
805
|
+
// Tool: update_issue_labels
|
|
806
|
+
// ---------------------------------------------------------------------------
|
|
807
|
+
|
|
808
|
+
export const updateIssueLabelsTool = {
|
|
809
|
+
name: 'update_issue_labels',
|
|
810
|
+
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.',
|
|
811
|
+
inputSchema: {
|
|
812
|
+
type: 'object',
|
|
813
|
+
properties: {
|
|
814
|
+
itemId: {
|
|
815
|
+
type: 'string',
|
|
816
|
+
description: 'The ID of the project item whose underlying issue should be updated'
|
|
817
|
+
},
|
|
818
|
+
addLabels: {
|
|
819
|
+
type: 'array',
|
|
820
|
+
description: 'Label names to add to the issue. Must already exist in the repository.',
|
|
821
|
+
items: { type: 'string' }
|
|
822
|
+
},
|
|
823
|
+
removeLabels: {
|
|
824
|
+
type: 'array',
|
|
825
|
+
description: 'Label names to remove from the issue.',
|
|
826
|
+
items: { type: 'string' }
|
|
827
|
+
}
|
|
828
|
+
},
|
|
829
|
+
required: ['itemId']
|
|
830
|
+
}
|
|
831
|
+
};
|
|
832
|
+
|
|
833
|
+
export async function handleUpdateIssueLabels(args, extra) {
|
|
834
|
+
try {
|
|
835
|
+
const addLabels = Array.isArray(args.addLabels)
|
|
836
|
+
? args.addLabels.map(l => String(l || '').trim()).filter(l => l !== '')
|
|
837
|
+
: [];
|
|
838
|
+
const removeLabels = Array.isArray(args.removeLabels)
|
|
839
|
+
? args.removeLabels.map(l => String(l || '').trim()).filter(l => l !== '')
|
|
840
|
+
: [];
|
|
841
|
+
|
|
842
|
+
if (addLabels.length === 0 && removeLabels.length === 0) {
|
|
843
|
+
return { error: 'At least one of addLabels or removeLabels must be provided.' };
|
|
844
|
+
}
|
|
845
|
+
|
|
846
|
+
const token = extractToken(extra);
|
|
847
|
+
logger.info('MCP: Updating issue labels', { itemId: args.itemId, addLabels, removeLabels });
|
|
848
|
+
|
|
849
|
+
const item = await getItemByID(args.itemId, token);
|
|
850
|
+
if (!item.repository?.nameWithOwner || !item.number) {
|
|
851
|
+
return { error: `Could not resolve the underlying issue for item '${args.itemId}'.` };
|
|
852
|
+
}
|
|
853
|
+
const [owner, repo] = item.repository.nameWithOwner.split('/');
|
|
854
|
+
const issueNumber = item.number;
|
|
855
|
+
|
|
856
|
+
// Snapshot of labels currently on the issue, used below to report which
|
|
857
|
+
// requested removals actually changed anything (removeLabelFromIssue
|
|
858
|
+
// swallows a 404 whether the label was never applied or never existed,
|
|
859
|
+
// so this is the only way to distinguish an effective removal from a
|
|
860
|
+
// no-op).
|
|
861
|
+
const currentLabels = new Set((item.labels || []).map(l => l.toLowerCase()));
|
|
862
|
+
|
|
863
|
+
// Validate additions exist in the repo BEFORE mutating anything -- GitHub's
|
|
864
|
+
// add-labels endpoint would otherwise silently create missing labels.
|
|
865
|
+
if (addLabels.length > 0) {
|
|
866
|
+
const missing = await findMissingLabels(owner, repo, addLabels, token);
|
|
867
|
+
if (missing.length > 0) {
|
|
868
|
+
return {
|
|
869
|
+
error: `Label(s) not found in ${owner}/${repo}: ${missing.join(', ')}. Create the label first or fix the name -- labels are not auto-created.`
|
|
870
|
+
};
|
|
871
|
+
}
|
|
872
|
+
}
|
|
873
|
+
|
|
874
|
+
if (addLabels.length > 0) {
|
|
875
|
+
await addLabelsToIssue(owner, repo, issueNumber, addLabels, token);
|
|
876
|
+
}
|
|
877
|
+
|
|
878
|
+
// Only report additions that actually changed something -- labels already
|
|
879
|
+
// present pre-call are a no-op, mirroring how `removed` below is computed.
|
|
880
|
+
const added = addLabels.filter(name => !currentLabels.has(name.toLowerCase()));
|
|
881
|
+
|
|
882
|
+
const removed = [];
|
|
883
|
+
for (const name of removeLabels) {
|
|
884
|
+
await removeLabelFromIssue(owner, repo, issueNumber, name, token);
|
|
885
|
+
if (currentLabels.has(name.toLowerCase())) {
|
|
886
|
+
removed.push(name);
|
|
887
|
+
}
|
|
888
|
+
}
|
|
889
|
+
|
|
890
|
+
return {
|
|
891
|
+
content: [{
|
|
892
|
+
type: 'text',
|
|
893
|
+
text: JSON.stringify({
|
|
894
|
+
success: true,
|
|
895
|
+
itemId: args.itemId,
|
|
896
|
+
repository: `${owner}/${repo}`,
|
|
897
|
+
issueNumber,
|
|
898
|
+
added,
|
|
899
|
+
removed
|
|
900
|
+
})
|
|
901
|
+
}]
|
|
902
|
+
};
|
|
903
|
+
} catch (error) {
|
|
904
|
+
logger.error('MCP: Error updating issue labels', { error: error.message });
|
|
905
|
+
return { error: error.message };
|
|
906
|
+
}
|
|
907
|
+
}
|
|
908
|
+
|
|
579
909
|
// ---------------------------------------------------------------------------
|
|
580
910
|
// Exports
|
|
581
911
|
// ---------------------------------------------------------------------------
|
|
@@ -587,6 +917,9 @@ export const tools = [
|
|
|
587
917
|
createIssueInProjectTool,
|
|
588
918
|
addExistingIssueTool,
|
|
589
919
|
archiveItemTool,
|
|
920
|
+
closeIssueTool,
|
|
921
|
+
reopenIssueTool,
|
|
922
|
+
updateIssueLabelsTool,
|
|
590
923
|
...subIssueTools
|
|
591
924
|
];
|
|
592
925
|
|
|
@@ -597,5 +930,8 @@ export const toolHandlers = {
|
|
|
597
930
|
create_issue_in_project: handleCreateIssueInProject,
|
|
598
931
|
add_existing_issue: handleAddExistingIssue,
|
|
599
932
|
archive_item: handleArchiveItem,
|
|
933
|
+
close_issue: handleCloseIssue,
|
|
934
|
+
reopen_issue: handleReopenIssue,
|
|
935
|
+
update_issue_labels: handleUpdateIssueLabels,
|
|
600
936
|
...subIssueToolHandlers
|
|
601
937
|
};
|
package/src/lib/project.js
CHANGED
|
@@ -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
|
};
|
package/src/lib/rest-api.js
CHANGED
|
@@ -1,9 +1,10 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* GitHub REST API Client
|
|
3
3
|
*
|
|
4
|
-
* Provides an authenticated Octokit REST client for
|
|
5
|
-
*
|
|
6
|
-
* references
|
|
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
|
+
}
|