@giantswarm-io/pro 1.11.1 → 1.15.0-rc.2
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 +20 -4
- package/package.json +1 -1
- package/src/index.js +9 -1
- package/src/lib/api.js +54 -11
- package/src/lib/auth/provider.js +39 -1
- package/src/lib/fields.js +18 -5
- package/src/lib/items.js +473 -157
- package/src/lib/mcp/board.js +147 -67
- package/src/lib/mcp/http.js +2 -2
- package/src/lib/mcp/relations.js +174 -0
- package/src/lib/mcp/resources.js +24 -1
- package/src/lib/mcp/server.js +11 -1
- package/src/lib/mcp/tools.js +180 -46
- package/src/lib/mcp/validate.js +157 -0
- package/src/lib/project.js +264 -82
- package/src/lib/relations.js +269 -0
package/src/lib/mcp/tools.js
CHANGED
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
* - list_issue_comments: Fetch comments across multiple board items in one call
|
|
15
15
|
*/
|
|
16
16
|
|
|
17
|
-
import { listItems, getItemByID, resolveItemIssues, updateItemField, clearItemField } from '../items.js';
|
|
17
|
+
import { listItems, getItemByID, resolveItemIssues, resolveBoardItem, updateItemField, clearItemField } from '../items.js';
|
|
18
18
|
import { findFieldByName, findMatchingOption, findMatchingIteration } from '../fields.js';
|
|
19
19
|
import { graphQLWithAuth } from '../api.js';
|
|
20
20
|
import { findMissingLabels, listIssueLabels, addLabelsToIssue, removeLabelFromIssue } from '../rest-api.js';
|
|
@@ -31,12 +31,15 @@ import {
|
|
|
31
31
|
USER_ID_QUERY,
|
|
32
32
|
CLOSE_ISSUE_MUTATION,
|
|
33
33
|
REOPEN_ISSUE_MUTATION,
|
|
34
|
-
ADD_COMMENT_MUTATION
|
|
34
|
+
ADD_COMMENT_MUTATION,
|
|
35
|
+
DETAIL_RELATIONS_PAGE
|
|
35
36
|
} from '../project.js';
|
|
36
37
|
import { logger } from '../logger.js';
|
|
38
|
+
import { name as serverName, version, isDevBuild } from '../version.js';
|
|
37
39
|
import { subIssueTools, subIssueToolHandlers } from './sub-issues.js';
|
|
38
40
|
import { timelineTools, timelineToolHandlers } from './timeline.js';
|
|
39
|
-
import { boardTools, boardToolHandlers } from './board.js';
|
|
41
|
+
import { boardTools, boardToolHandlers, findBoardItemByIssue } from './board.js';
|
|
42
|
+
import { relationTools, relationToolHandlers } from './relations.js';
|
|
40
43
|
import {
|
|
41
44
|
listIssueCommentsForItems,
|
|
42
45
|
MAX_ITEMS_PER_CALL,
|
|
@@ -76,10 +79,13 @@ async function resolveSingleItemIssue(itemId, token) {
|
|
|
76
79
|
// Tool: list_issues
|
|
77
80
|
// ---------------------------------------------------------------------------
|
|
78
81
|
|
|
82
|
+
/** Items list_issues returns when the call names no `limit`. */
|
|
83
|
+
export const DEFAULT_LIST_LIMIT = 50;
|
|
84
|
+
|
|
79
85
|
export const listIssuesTool = {
|
|
80
86
|
name: 'list_issues',
|
|
81
87
|
annotations: READ_ONLY,
|
|
82
|
-
description:
|
|
88
|
+
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. Field filters go under \`filters\` only (e.g. \`filters: {"Team": "Honey Badger", "Status": "Backlog", "Quarter": "@current"}\`), and \`exclude\` leaves matching items out (e.g. \`exclude: {"Status": "Done"}\`); any other top-level argument that is not listed here is refused with an error naming it. Earlier releases took an unknown top-level string argument as a field filter: a call with \`Team: "X"\` becomes \`filters: {"Team": "X"}\`. Returns at most \`limit\` items (default ${DEFAULT_LIST_LIMIT}; 0 for every matching item, which on a large board takes seconds per hundred items: narrow it with \`closed\` or \`updated\`) as compact entries 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}. Next to \`count\` (items returned), \`hidden\` is the number of matching items left out because their content could not be read (typically issues in private repos the server's GitHub identity cannot access), and \`totalCount\` is GitHub's count of items matching the server-side query (unreadable items, draft issues and pull requests included). \`hidden > 0\` means the result is incomplete. \`truncated: true\` means the limit cut the list with items left: pass \`nextCursor\` as \`cursor\` with the same filters to continue. An issue with open dependencies carries their counts as \`openBlockedBy\` / \`openBlocking\`; when they cannot be read, \`dependencyCountsError\` says why.`,
|
|
83
89
|
inputSchema: {
|
|
84
90
|
type: 'object',
|
|
85
91
|
properties: {
|
|
@@ -88,19 +94,50 @@ export const listIssuesTool = {
|
|
|
88
94
|
enum: BOARD_NAMES,
|
|
89
95
|
description: 'Which board to query. Defaults to "roadmap".'
|
|
90
96
|
},
|
|
97
|
+
limit: {
|
|
98
|
+
type: 'integer',
|
|
99
|
+
minimum: 0,
|
|
100
|
+
description: `Maximum number of items to return. Defaults to ${DEFAULT_LIST_LIMIT}; 0 returns every matching item (slow on a large board). A cut result says so with \`truncated: true\` and \`nextCursor\`.`
|
|
101
|
+
},
|
|
102
|
+
cursor: {
|
|
103
|
+
type: 'string',
|
|
104
|
+
description: 'Continue a cut result: the `nextCursor` of the previous call, with the same filters.'
|
|
105
|
+
},
|
|
91
106
|
repository: {
|
|
92
107
|
type: 'string',
|
|
93
108
|
description: 'Filter by repository. Accepts short name (e.g. "myrepo") which resolves to "giantswarm/myrepo", or full "owner/name" format. On the customer board each customer has their own repo (e.g. "giantswarm/<customer-name>"). On the roadmap board the repos are "giantswarm/roadmap" (public) and "giantswarm/giantswarm" (internal).'
|
|
94
109
|
},
|
|
95
110
|
filters: {
|
|
96
111
|
type: 'object',
|
|
97
|
-
description: 'Field filter map: keys are field names (e.g. "Status", "Team", "
|
|
112
|
+
description: 'Field filter map: keys are field names (e.g. "Status", "Team", "Quarter", "Target Date"), values what to match. Read the board schema resource first to discover available fields and valid options. Single-select: an option name, comma-separated for OR ("Backlog,Up Next"). Iteration: an iteration title ("Q4/2026") or "@current", "@next", "@previous". Date and number: GitHub comparison syntax (">2026-01-01", "2026-01-01..2026-03-31", "@today", ">1"). Text: the exact text. Fields standing for issue attributes (Assignees, Labels, Repository, Milestone, Parent issue) match like the issue filters. The only place for a field filter: a field name given as a top-level argument is refused.',
|
|
113
|
+
additionalProperties: { type: 'string' }
|
|
114
|
+
},
|
|
115
|
+
exclude: {
|
|
116
|
+
type: 'object',
|
|
117
|
+
description: 'Leave out the items matching any entry: the same keys and values as `filters`, plus the issue filter names repository, assignee, label, milestone, type, parentIssue, updated, created, closed and reason (e.g. {"Status": "Done", "label": "wontfix,duplicate"}).',
|
|
98
118
|
additionalProperties: { type: 'string' }
|
|
99
119
|
},
|
|
100
120
|
emptyFields: {
|
|
101
121
|
type: 'array',
|
|
102
122
|
items: { type: 'string' },
|
|
103
|
-
description: 'Return only items where these fields have no value set. Works for single-select, text, date, and iteration fields (e.g. ["Team", "Kind"]).'
|
|
123
|
+
description: 'Return only items where these fields have no value set. Works for single-select, text, date, number and iteration fields and for Assignees, Labels and Milestone (e.g. ["Team", "Kind"]).'
|
|
124
|
+
},
|
|
125
|
+
nonEmptyFields: {
|
|
126
|
+
type: 'array',
|
|
127
|
+
items: { type: 'string' },
|
|
128
|
+
description: 'Return only items where these fields have a value set: the opposite of emptyFields (e.g. ["Quarter", "Assignees"]).'
|
|
129
|
+
},
|
|
130
|
+
milestone: {
|
|
131
|
+
type: 'string',
|
|
132
|
+
description: 'Filter by milestone title. Comma-separated for OR matching.'
|
|
133
|
+
},
|
|
134
|
+
type: {
|
|
135
|
+
type: 'string',
|
|
136
|
+
description: 'Filter by issue type (e.g. "Bug", "Task"). Comma-separated for OR matching.'
|
|
137
|
+
},
|
|
138
|
+
parentIssue: {
|
|
139
|
+
type: 'string',
|
|
140
|
+
description: 'Return only the sub-issues of this parent issue: its URL or "owner/repo#number".'
|
|
104
141
|
},
|
|
105
142
|
assignee: {
|
|
106
143
|
type: 'string',
|
|
@@ -140,52 +177,52 @@ export const listIssuesTool = {
|
|
|
140
177
|
}
|
|
141
178
|
};
|
|
142
179
|
|
|
143
|
-
export const KNOWN_LIST_PARAMS = new Set([
|
|
144
|
-
'board', 'project', 'repository', 'filters', 'emptyFields',
|
|
145
|
-
'assignee', 'label', 'state', 'keyword', 'updated', 'created', 'closed', 'reason'
|
|
146
|
-
]);
|
|
147
|
-
|
|
148
|
-
// Board field names are single words (Team, Kind, Status), so simple
|
|
149
|
-
// word-boundary capitalization is sufficient here.
|
|
150
|
-
function titleCase(str) {
|
|
151
|
-
return str.replace(/\b\w/g, c => c.toUpperCase());
|
|
152
|
-
}
|
|
153
|
-
|
|
154
180
|
export async function handleListIssues(args, extra) {
|
|
155
181
|
try {
|
|
156
182
|
const token = extractToken(extra);
|
|
157
|
-
const board = args.board ||
|
|
183
|
+
const board = args.board || DEFAULT_BOARD;
|
|
158
184
|
const boardId = resolveBoardId(board);
|
|
159
185
|
|
|
160
|
-
const
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
186
|
+
const limit = args.limit ?? DEFAULT_LIST_LIMIT;
|
|
187
|
+
if (!Number.isInteger(limit) || limit < 0) {
|
|
188
|
+
return { error: `limit must be a whole number of items (default ${DEFAULT_LIST_LIMIT}; 0 for every matching item), got ${JSON.stringify(args.limit)}.` };
|
|
189
|
+
}
|
|
190
|
+
if (args.cursor !== undefined && (typeof args.cursor !== 'string' || args.cursor.trim() === '')) {
|
|
191
|
+
return { error: `cursor must be the nextCursor string of a previous list_issues call, got ${JSON.stringify(args.cursor)}.` };
|
|
166
192
|
}
|
|
167
193
|
|
|
194
|
+
const filters = args.filters || {};
|
|
195
|
+
|
|
168
196
|
logger.info('MCP: Listing issues', {
|
|
169
197
|
board, repository: args.repository, filters,
|
|
170
|
-
|
|
198
|
+
exclude: args.exclude, emptyFields: args.emptyFields,
|
|
199
|
+
nonEmptyFields: args.nonEmptyFields, assignee: args.assignee,
|
|
171
200
|
label: args.label, state: args.state, keyword: args.keyword,
|
|
201
|
+
milestone: args.milestone, type: args.type, parentIssue: args.parentIssue,
|
|
172
202
|
updated: args.updated, created: args.created, closed: args.closed,
|
|
173
|
-
reason: args.reason
|
|
203
|
+
reason: args.reason, limit, cursor: args.cursor
|
|
174
204
|
});
|
|
175
205
|
|
|
176
206
|
const result = await listItems({
|
|
177
207
|
boardId,
|
|
178
208
|
repository: args.repository || null,
|
|
179
209
|
filters,
|
|
210
|
+
exclude: args.exclude || {},
|
|
180
211
|
emptyFields: args.emptyFields || [],
|
|
212
|
+
nonEmptyFields: args.nonEmptyFields || [],
|
|
181
213
|
assignee: args.assignee || null,
|
|
182
214
|
label: args.label || null,
|
|
183
215
|
state: args.state || null,
|
|
184
216
|
keyword: args.keyword || null,
|
|
217
|
+
milestone: args.milestone || null,
|
|
218
|
+
type: args.type || null,
|
|
219
|
+
parentIssue: args.parentIssue || null,
|
|
185
220
|
updated: args.updated || null,
|
|
186
221
|
created: args.created || null,
|
|
187
222
|
closed: args.closed || null,
|
|
188
223
|
reason: args.reason || null,
|
|
224
|
+
limit,
|
|
225
|
+
after: args.cursor || null,
|
|
189
226
|
token
|
|
190
227
|
});
|
|
191
228
|
|
|
@@ -200,6 +237,9 @@ export async function handleListIssues(args, extra) {
|
|
|
200
237
|
count: result.data.length,
|
|
201
238
|
hidden: result.hidden ?? 0,
|
|
202
239
|
...(typeof result.totalCount === 'number' ? { totalCount: result.totalCount } : {}),
|
|
240
|
+
truncated: result.truncated === true,
|
|
241
|
+
...(result.truncated === true && result.nextCursor ? { nextCursor: result.nextCursor } : {}),
|
|
242
|
+
...(result.dependencyCountsError ? { dependencyCountsError: result.dependencyCountsError } : {}),
|
|
203
243
|
issues: result.data
|
|
204
244
|
})
|
|
205
245
|
}]
|
|
@@ -217,7 +257,7 @@ export async function handleListIssues(args, extra) {
|
|
|
217
257
|
export const getIssueDetailsTool = {
|
|
218
258
|
name: 'get_issue_details',
|
|
219
259
|
annotations: READ_ONLY,
|
|
220
|
-
description:
|
|
260
|
+
description: `Get detailed information about a specific issue including repository metadata, title, description, comments, assignees, labels, field values, and its relations: the issues that block it (blockedBy), that it blocks (blocking) and that it relates to (relatesTo), the first ${DETAIL_RELATIONS_PAGE} of each with their state. Relations that cannot be read leave the rest in place and are named in relationsError; a pull request or draft has none.`,
|
|
221
261
|
inputSchema: {
|
|
222
262
|
type: 'object',
|
|
223
263
|
properties: {
|
|
@@ -255,13 +295,17 @@ export async function handleGetIssueDetails(args, extra) {
|
|
|
255
295
|
export const updateIssueFieldTool = {
|
|
256
296
|
name: 'update_issue_field',
|
|
257
297
|
annotations: destructiveWrite(),
|
|
258
|
-
description: 'Update a field value for an issue on a project board. Supports single-select fields (Status, Kind, Team, etc.) and iteration fields (Quarter). Also supports date fields (Start Date, Target Date) when a specific date is known. The server resolves field and option names to internal IDs automatically. To clear/unset a field instead of setting it, pass `clear: true` (and omit `value`) -- this works for single-select, iteration, and date fields.',
|
|
298
|
+
description: 'Update a field value for an issue on a project board. Name the item by itemId, or by issueUrl (the issue\'s URL or owner/repo#N, resolved to its item on the board). Supports single-select fields (Status, Kind, Team, etc.) and iteration fields (Quarter). Also supports date fields (Start Date, Target Date) when a specific date is known. The server resolves field and option names to internal IDs automatically. To clear/unset a field instead of setting it, pass `clear: true` (and omit `value`) -- this works for single-select, iteration, and date fields.',
|
|
259
299
|
inputSchema: {
|
|
260
300
|
type: 'object',
|
|
261
301
|
properties: {
|
|
262
302
|
itemId: {
|
|
263
303
|
type: 'string',
|
|
264
|
-
description: 'The ID of the project item to update'
|
|
304
|
+
description: 'The ID of the project item to update. Pass this or issueUrl.'
|
|
305
|
+
},
|
|
306
|
+
issueUrl: {
|
|
307
|
+
type: 'string',
|
|
308
|
+
description: 'The issue (or pull request) whose board item to update, as a URL or owner/repo#N. Pass this or itemId.'
|
|
265
309
|
},
|
|
266
310
|
fieldName: {
|
|
267
311
|
type: 'string',
|
|
@@ -281,35 +325,70 @@ export const updateIssueFieldTool = {
|
|
|
281
325
|
description: 'Which board the item belongs to. Defaults to "roadmap".'
|
|
282
326
|
}
|
|
283
327
|
},
|
|
284
|
-
required: ['
|
|
328
|
+
required: ['fieldName']
|
|
285
329
|
}
|
|
286
330
|
};
|
|
287
331
|
|
|
332
|
+
/**
|
|
333
|
+
* The project item ID a call names: its itemId, or the board item of its
|
|
334
|
+
* issueUrl. Returns {itemId, onBoard} (onBoard: found on the board itself) or
|
|
335
|
+
* {error} naming what is missing or wrong.
|
|
336
|
+
*/
|
|
337
|
+
async function resolveItemArg(args, board, boardName, token) {
|
|
338
|
+
const hasItemId = typeof args.itemId === 'string' && args.itemId.trim() !== '';
|
|
339
|
+
const hasIssueUrl = typeof args.issueUrl === 'string' && args.issueUrl.trim() !== '';
|
|
340
|
+
if (hasItemId && hasIssueUrl) {
|
|
341
|
+
return { error: `Pass itemId or issueUrl, not both: they name the same board item.` };
|
|
342
|
+
}
|
|
343
|
+
if (hasItemId) return { itemId: args.itemId };
|
|
344
|
+
if (!hasIssueUrl) {
|
|
345
|
+
return { error: `itemId or issueUrl is required: the project item ID of the issue on ${boardName}, or the issue's URL (owner/repo#N).` };
|
|
346
|
+
}
|
|
347
|
+
const found = await findBoardItemByIssue({ issueUrl: args.issueUrl }, board, token);
|
|
348
|
+
if (!found.item) {
|
|
349
|
+
return { error: `No item for ${args.issueUrl} on ${boardName}: ${found.reason} Add it with add_existing_issue.` };
|
|
350
|
+
}
|
|
351
|
+
return { itemId: found.item.id, onBoard: true };
|
|
352
|
+
}
|
|
353
|
+
|
|
288
354
|
export async function handleUpdateIssueField(args, extra) {
|
|
289
355
|
try {
|
|
290
356
|
const token = extractToken(extra);
|
|
291
|
-
const board = args.board || DEFAULT_BOARD;
|
|
357
|
+
const board = (args.board || DEFAULT_BOARD).toLowerCase();
|
|
292
358
|
const boardId = resolveBoardId(board);
|
|
359
|
+
const boardName = `the ${board} board (#${BOARDS[board].number})`;
|
|
293
360
|
logger.info('MCP: Updating issue field', { ...args, board });
|
|
294
361
|
|
|
362
|
+
if (typeof args.fieldName !== 'string' || args.fieldName.trim() === '') {
|
|
363
|
+
return { error: `fieldName is required: the name of a field on ${boardName} (e.g. Status). Read the board schema resource for the fields.` };
|
|
364
|
+
}
|
|
365
|
+
|
|
366
|
+
const resolved = await resolveItemArg(args, board, boardName, token);
|
|
367
|
+
if (resolved.error) return { error: resolved.error };
|
|
368
|
+
const { itemId, onBoard } = resolved;
|
|
369
|
+
|
|
295
370
|
const field = await findFieldByName(args.fieldName, boardId, token);
|
|
296
371
|
if (!field) {
|
|
297
372
|
return {
|
|
298
|
-
error: `Field '${args.fieldName}' not
|
|
373
|
+
error: `Field '${args.fieldName}' not on ${boardName}. Only single-select, iteration, and date fields can be updated.`
|
|
299
374
|
};
|
|
300
375
|
}
|
|
301
376
|
|
|
377
|
+
// The item is resolved by its project item ID before any write, so a
|
|
378
|
+
// wrong or misplaced ID is named instead of failing inside the mutation.
|
|
379
|
+
if (!onBoard) await resolveBoardItem(itemId, board, token);
|
|
380
|
+
|
|
302
381
|
// Clear path -- clearProjectV2ItemFieldValue takes only the field ID and
|
|
303
382
|
// works uniformly across single-select, iteration, and date fields, so it
|
|
304
383
|
// short-circuits before the per-type value resolution below.
|
|
305
384
|
if (args.clear === true) {
|
|
306
|
-
await clearItemField(
|
|
385
|
+
await clearItemField(itemId, field.id, boardId, token);
|
|
307
386
|
return {
|
|
308
387
|
content: [{
|
|
309
388
|
type: 'text',
|
|
310
389
|
text: JSON.stringify({
|
|
311
390
|
success: true,
|
|
312
|
-
itemId:
|
|
391
|
+
itemId: itemId,
|
|
313
392
|
field: args.fieldName,
|
|
314
393
|
cleared: true
|
|
315
394
|
})
|
|
@@ -330,7 +409,7 @@ export async function handleUpdateIssueField(args, extra) {
|
|
|
330
409
|
const option = findMatchingOption(field.options, args.value);
|
|
331
410
|
if (!option) {
|
|
332
411
|
return {
|
|
333
|
-
error: `Value '${args.value}' not found in ${args.fieldName} options. Available: ${field.options.map(o => o.name).join(', ')}`
|
|
412
|
+
error: `Value '${args.value}' not found in ${args.fieldName} options. Available: ${(field.options || []).map(o => o.name).join(', ')}`
|
|
334
413
|
};
|
|
335
414
|
}
|
|
336
415
|
value = { singleSelectOptionId: option.id };
|
|
@@ -362,14 +441,14 @@ export async function handleUpdateIssueField(args, extra) {
|
|
|
362
441
|
};
|
|
363
442
|
}
|
|
364
443
|
|
|
365
|
-
await updateItemField(
|
|
444
|
+
await updateItemField(itemId, field.id, value, boardId, token);
|
|
366
445
|
|
|
367
446
|
return {
|
|
368
447
|
content: [{
|
|
369
448
|
type: 'text',
|
|
370
449
|
text: JSON.stringify({
|
|
371
450
|
success: true,
|
|
372
|
-
itemId:
|
|
451
|
+
itemId: itemId,
|
|
373
452
|
field: args.fieldName,
|
|
374
453
|
value: resolvedName
|
|
375
454
|
})
|
|
@@ -388,7 +467,7 @@ export async function handleUpdateIssueField(args, extra) {
|
|
|
388
467
|
export const createIssueInProjectTool = {
|
|
389
468
|
name: 'create_issue_in_project',
|
|
390
469
|
annotations: additiveWrite(),
|
|
391
|
-
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.',
|
|
470
|
+
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. If GitHub refuses the creation (the person or the GitHub App of the token lacks issues:write on the repository), the error names the repository and the missing permission and no issue is created.',
|
|
392
471
|
inputSchema: {
|
|
393
472
|
type: 'object',
|
|
394
473
|
properties: {
|
|
@@ -432,6 +511,31 @@ export const createIssueInProjectTool = {
|
|
|
432
511
|
}
|
|
433
512
|
};
|
|
434
513
|
|
|
514
|
+
/**
|
|
515
|
+
* Whether a GitHub API error is a permission refusal: GraphQL reports it as a
|
|
516
|
+
* FORBIDDEN error ("Resource not accessible by integration" for a GitHub App
|
|
517
|
+
* user token where the person or the App lacks the permission), REST as 403.
|
|
518
|
+
* @param {Error} error
|
|
519
|
+
* @returns {boolean}
|
|
520
|
+
*/
|
|
521
|
+
export function isPermissionRefusal(error) {
|
|
522
|
+
return error?.status === 403 ||
|
|
523
|
+
(Array.isArray(error?.errors) && error.errors.some(e => e?.type === 'FORBIDDEN')) ||
|
|
524
|
+
/Resource not accessible by integration/i.test(error?.message || '');
|
|
525
|
+
}
|
|
526
|
+
|
|
527
|
+
/**
|
|
528
|
+
* The error returned when GitHub refuses to create an issue in a repository.
|
|
529
|
+
* @param {string} owner
|
|
530
|
+
* @param {string} repo
|
|
531
|
+
* @returns {string}
|
|
532
|
+
*/
|
|
533
|
+
export function issueCreationRefusedMessage(owner, repo) {
|
|
534
|
+
return `No issue was created: GitHub refused to create an issue in ${owner}/${repo} because the token lacks the issues:write permission there. ` +
|
|
535
|
+
'A GitHub App user token writes only where the person may write and the App is installed: ' +
|
|
536
|
+
`ask for write access to ${owner}/${repo}, or create the issue elsewhere and use add_existing_issue.`;
|
|
537
|
+
}
|
|
538
|
+
|
|
435
539
|
export async function handleCreateIssueInProject(args, extra) {
|
|
436
540
|
try {
|
|
437
541
|
const token = extractToken(extra);
|
|
@@ -494,12 +598,21 @@ export async function handleCreateIssueInProject(args, extra) {
|
|
|
494
598
|
}
|
|
495
599
|
|
|
496
600
|
// Create the issue
|
|
497
|
-
|
|
498
|
-
|
|
499
|
-
|
|
500
|
-
|
|
501
|
-
|
|
502
|
-
|
|
601
|
+
let createResult;
|
|
602
|
+
try {
|
|
603
|
+
createResult = await graphQLWithAuth(CREATE_ISSUE_MUTATION, {
|
|
604
|
+
repositoryId,
|
|
605
|
+
title: args.title,
|
|
606
|
+
body: args.body || '',
|
|
607
|
+
assigneeIds: assigneeIds.length > 0 ? assigneeIds : undefined
|
|
608
|
+
}, token);
|
|
609
|
+
} catch (error) {
|
|
610
|
+
if (isPermissionRefusal(error)) {
|
|
611
|
+
logger.error('MCP: Issue creation refused', { repository: `${owner}/${repo}`, error: error.message });
|
|
612
|
+
return { error: issueCreationRefusedMessage(owner, repo) };
|
|
613
|
+
}
|
|
614
|
+
throw error;
|
|
615
|
+
}
|
|
503
616
|
|
|
504
617
|
const issue = createResult.createIssue.issue;
|
|
505
618
|
|
|
@@ -677,6 +790,8 @@ export async function handleArchiveItem(args, extra) {
|
|
|
677
790
|
const boardId = resolveBoardId(board);
|
|
678
791
|
logger.info('MCP: Archiving item', { itemId: args.itemId, board });
|
|
679
792
|
|
|
793
|
+
await resolveBoardItem(args.itemId, board, token);
|
|
794
|
+
|
|
680
795
|
await graphQLWithAuth(ARCHIVE_ITEM_MUTATION, {
|
|
681
796
|
projectId: boardId,
|
|
682
797
|
itemId: args.itemId
|
|
@@ -1019,6 +1134,21 @@ export async function handleListIssueComments(args, extra) {
|
|
|
1019
1134
|
// Exports
|
|
1020
1135
|
// ---------------------------------------------------------------------------
|
|
1021
1136
|
|
|
1137
|
+
// ---------------------------------------------------------------------------
|
|
1138
|
+
// Tool: get_server_version
|
|
1139
|
+
// ---------------------------------------------------------------------------
|
|
1140
|
+
|
|
1141
|
+
export const getServerVersionTool = {
|
|
1142
|
+
name: 'get_server_version',
|
|
1143
|
+
annotations: READ_ONLY,
|
|
1144
|
+
description: 'The running pro server\'s name and version: the release tag it was built from (as in the MCP serverInfo), and isDevBuild: true for a checkout that runs no release.',
|
|
1145
|
+
inputSchema: { type: 'object', properties: {} }
|
|
1146
|
+
};
|
|
1147
|
+
|
|
1148
|
+
export async function handleGetServerVersion() {
|
|
1149
|
+
return { content: [{ type: 'text', text: JSON.stringify({ name: serverName, version, isDevBuild }) }] };
|
|
1150
|
+
}
|
|
1151
|
+
|
|
1022
1152
|
export const tools = [
|
|
1023
1153
|
listIssuesTool,
|
|
1024
1154
|
getIssueDetailsTool,
|
|
@@ -1030,9 +1160,11 @@ export const tools = [
|
|
|
1030
1160
|
reopenIssueTool,
|
|
1031
1161
|
updateIssueLabelsTool,
|
|
1032
1162
|
listIssueCommentsTool,
|
|
1163
|
+
getServerVersionTool,
|
|
1033
1164
|
...subIssueTools,
|
|
1034
1165
|
...timelineTools,
|
|
1035
|
-
...boardTools
|
|
1166
|
+
...boardTools,
|
|
1167
|
+
...relationTools
|
|
1036
1168
|
];
|
|
1037
1169
|
|
|
1038
1170
|
export const toolHandlers = {
|
|
@@ -1046,7 +1178,9 @@ export const toolHandlers = {
|
|
|
1046
1178
|
reopen_issue: handleReopenIssue,
|
|
1047
1179
|
update_issue_labels: handleUpdateIssueLabels,
|
|
1048
1180
|
list_issue_comments: handleListIssueComments,
|
|
1181
|
+
get_server_version: handleGetServerVersion,
|
|
1049
1182
|
...subIssueToolHandlers,
|
|
1050
1183
|
...timelineToolHandlers,
|
|
1051
|
-
...boardToolHandlers
|
|
1184
|
+
...boardToolHandlers,
|
|
1185
|
+
...relationToolHandlers
|
|
1052
1186
|
};
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool argument validation
|
|
3
|
+
*
|
|
4
|
+
* WHY:
|
|
5
|
+
* - A tool called with a wrong argument name or type used to reach its
|
|
6
|
+
* handler with undefined inputs and fail with an internal error
|
|
7
|
+
* ("Cannot read properties of undefined", a GraphQL variable error) that
|
|
8
|
+
* does not say which argument is at fault
|
|
9
|
+
*
|
|
10
|
+
* HOW:
|
|
11
|
+
* - Every call is checked against the inputSchema the tool declares, before
|
|
12
|
+
* the handler runs: missing required arguments, unknown top-level arguments
|
|
13
|
+
* and wrong types are all named in one refusal, together with the arguments
|
|
14
|
+
* the tool accepts. A top-level argument is one the schema lists: a free-form
|
|
15
|
+
* map is a declared object property (list_issues' filters), never the top
|
|
16
|
+
* level, so a misspelled argument can never pass as something else
|
|
17
|
+
* - A string that spells a number or a boolean exactly is taken as that value
|
|
18
|
+
* for a number, integer or boolean argument, as handlers always did; null
|
|
19
|
+
* for an optional argument means the argument is left out
|
|
20
|
+
*/
|
|
21
|
+
|
|
22
|
+
const JSON_TYPES = {
|
|
23
|
+
string: v => typeof v === 'string',
|
|
24
|
+
number: v => typeof v === 'number' && Number.isFinite(v),
|
|
25
|
+
integer: v => Number.isInteger(v),
|
|
26
|
+
boolean: v => typeof v === 'boolean',
|
|
27
|
+
array: v => Array.isArray(v),
|
|
28
|
+
object: v => typeof v === 'object' && v !== null && !Array.isArray(v)
|
|
29
|
+
};
|
|
30
|
+
|
|
31
|
+
const NUMERIC = /^-?\d+(\.\d+)?$/;
|
|
32
|
+
|
|
33
|
+
function coerce(value, type) {
|
|
34
|
+
if (typeof value !== 'string') return value;
|
|
35
|
+
if ((type === 'number' || type === 'integer') && NUMERIC.test(value.trim())) return Number(value);
|
|
36
|
+
if (type === 'boolean' && (value === 'true' || value === 'false')) return value === 'true';
|
|
37
|
+
return value;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function describeValue(value) {
|
|
41
|
+
if (value === null) return 'null';
|
|
42
|
+
if (Array.isArray(value)) return 'array';
|
|
43
|
+
return `${typeof value} ${JSON.stringify(value)}`;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
function describeType(schema) {
|
|
47
|
+
if (schema.enum) return schema.enum.map(v => JSON.stringify(v)).join(' | ');
|
|
48
|
+
if (schema.type === 'array' && schema.items?.type) return `array of ${schema.items.type}`;
|
|
49
|
+
return schema.type || 'any';
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
/** Check one value against a property schema; returns a problem or null. */
|
|
53
|
+
function checkValue(path, value, schema) {
|
|
54
|
+
if (schema.type && !JSON_TYPES[schema.type]?.(value)) {
|
|
55
|
+
return `${path} must be ${describeType(schema)}, got ${describeValue(value)}`;
|
|
56
|
+
}
|
|
57
|
+
if (schema.enum && !schema.enum.includes(value)) {
|
|
58
|
+
return `${path} must be one of ${describeType(schema)}, got ${describeValue(value)}`;
|
|
59
|
+
}
|
|
60
|
+
if (typeof schema.minimum === 'number' && typeof value === 'number' && value < schema.minimum) {
|
|
61
|
+
return `${path} must be at least ${schema.minimum}, got ${value}`;
|
|
62
|
+
}
|
|
63
|
+
if (schema.type === 'array' && schema.items) {
|
|
64
|
+
for (const [i, item] of value.entries()) {
|
|
65
|
+
const problem = checkValue(`${path}[${i}]`, item, schema.items);
|
|
66
|
+
if (problem) return problem;
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
if (schema.type === 'object' && typeof schema.additionalProperties === 'object') {
|
|
70
|
+
for (const [key, item] of Object.entries(value)) {
|
|
71
|
+
const problem = checkValue(`${path}.${key}`, item, schema.additionalProperties);
|
|
72
|
+
if (problem) return problem;
|
|
73
|
+
}
|
|
74
|
+
}
|
|
75
|
+
return null;
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/** "itemId (string, required), board ("roadmap" | "customer")" */
|
|
79
|
+
export function describeArguments(inputSchema) {
|
|
80
|
+
const properties = inputSchema.properties || {};
|
|
81
|
+
const required = new Set(inputSchema.required || []);
|
|
82
|
+
const names = Object.keys(properties);
|
|
83
|
+
if (names.length === 0) return 'none';
|
|
84
|
+
return names
|
|
85
|
+
.map(name => `${name} (${describeType(properties[name])}${required.has(name) ? ', required' : ''})`)
|
|
86
|
+
.join(', ');
|
|
87
|
+
}
|
|
88
|
+
|
|
89
|
+
/**
|
|
90
|
+
* A hint for an unknown argument: a name that differs only in case or
|
|
91
|
+
* underscores (field_name for fieldName), field for fieldName, how to get
|
|
92
|
+
* an itemId, or where a board field (capitalized, like Team or Status; every
|
|
93
|
+
* argument is camelCase) goes on a tool that takes a filters map.
|
|
94
|
+
*/
|
|
95
|
+
function hintFor(name, properties, toolName) {
|
|
96
|
+
const bare = n => n.toLowerCase().replace(/_/g, '');
|
|
97
|
+
const sameName = Object.keys(properties).find(p => bare(p) === bare(name));
|
|
98
|
+
if (sameName) return ` (did you mean ${sameName}?)`;
|
|
99
|
+
if (properties.fieldName && bare(name) === 'field') return ' (did you mean fieldName?)';
|
|
100
|
+
if (properties.itemId && /^issue(Url|_number|NodeId)$|^(owner|repo)$/.test(name)) {
|
|
101
|
+
return properties.issueUrl
|
|
102
|
+
? ` (${toolName} takes the itemId of the board item, or the issue as issueUrl: "owner/repo#N")`
|
|
103
|
+
: ` (${toolName} takes the itemId of the board item: get_item_by_issue returns it for an issue URL)`;
|
|
104
|
+
}
|
|
105
|
+
if (properties.filters?.type === 'object' && /^[A-Z]/.test(name)) {
|
|
106
|
+
return ` (a field filter goes under filters: {${JSON.stringify(name)}: "..."})`;
|
|
107
|
+
}
|
|
108
|
+
return '';
|
|
109
|
+
}
|
|
110
|
+
|
|
111
|
+
/**
|
|
112
|
+
* Validate a tool call's arguments against the tool's inputSchema.
|
|
113
|
+
* @param {{name: string, inputSchema: object}} tool - The tool definition
|
|
114
|
+
* @param {object} [args] - The call's arguments
|
|
115
|
+
* @returns {{args: object} | {error: string}} - The arguments to hand to the
|
|
116
|
+
* handler (with string spellings of numbers and booleans converted and null
|
|
117
|
+
* optionals dropped), or the refusal naming every problem
|
|
118
|
+
*/
|
|
119
|
+
export function validateToolArguments(tool, args) {
|
|
120
|
+
const schema = tool.inputSchema || {};
|
|
121
|
+
const properties = schema.properties || {};
|
|
122
|
+
const required = schema.required || [];
|
|
123
|
+
const problems = [];
|
|
124
|
+
|
|
125
|
+
if (args !== undefined && args !== null && !JSON_TYPES.object(args)) {
|
|
126
|
+
return { error: `${tool.name}: the arguments must be an object, got ${describeValue(args)}. Accepted arguments: ${describeArguments(schema)}.` };
|
|
127
|
+
}
|
|
128
|
+
const given = args || {};
|
|
129
|
+
const result = {};
|
|
130
|
+
|
|
131
|
+
const missing = required.filter(name => given[name] === undefined || given[name] === null);
|
|
132
|
+
for (const name of missing) {
|
|
133
|
+
problems.push(`missing required argument: ${name}`);
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
for (const [name, raw] of Object.entries(given)) {
|
|
137
|
+
if (raw === undefined || (raw === null && !required.includes(name))) continue;
|
|
138
|
+
const propSchema = properties[name];
|
|
139
|
+
if (!propSchema) {
|
|
140
|
+
problems.push(`unknown argument: ${name}${hintFor(name, properties, tool.name)}`);
|
|
141
|
+
continue;
|
|
142
|
+
}
|
|
143
|
+
if (raw === null) continue; // a null required argument is already named as missing
|
|
144
|
+
const value = coerce(raw, propSchema.type);
|
|
145
|
+
const problem = checkValue(name, value, propSchema);
|
|
146
|
+
if (problem) {
|
|
147
|
+
problems.push(problem);
|
|
148
|
+
continue;
|
|
149
|
+
}
|
|
150
|
+
result[name] = value;
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
if (problems.length > 0) {
|
|
154
|
+
return { error: `${tool.name}: ${problems.join('; ')}. Accepted arguments: ${describeArguments(schema)}.` };
|
|
155
|
+
}
|
|
156
|
+
return { args: result };
|
|
157
|
+
}
|