@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.
@@ -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: '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}. 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.',
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", "Kind"), values are the desired option value. Read the board schema resource first to discover available fields and valid options.',
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 || args.project || DEFAULT_BOARD;
183
+ const board = args.board || DEFAULT_BOARD;
158
184
  const boardId = resolveBoardId(board);
159
185
 
160
- const filters = { ...(args.filters || {}) };
161
- for (const [key, value] of Object.entries(args)) {
162
- if (KNOWN_LIST_PARAMS.has(key) || typeof value !== 'string') continue;
163
- const fieldName = titleCase(key);
164
- logger.warn(`MCP: list_issues auto-forwarding top-level param "${key}" to filters["${fieldName}"]`);
165
- filters[fieldName] = value;
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
- emptyFields: args.emptyFields, assignee: args.assignee,
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: 'Get detailed information about a specific issue including repository metadata, title, description, comments, assignees, labels, and field values.',
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: ['itemId', 'fieldName']
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 found on the ${board} board. Only single-select, iteration, and date fields can be updated.`
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(args.itemId, field.id, boardId, token);
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: args.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(args.itemId, field.id, value, boardId, token);
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: args.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
- const createResult = await graphQLWithAuth(CREATE_ISSUE_MUTATION, {
498
- repositoryId,
499
- title: args.title,
500
- body: args.body || '',
501
- assigneeIds: assigneeIds.length > 0 ? assigneeIds : undefined
502
- }, token);
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
+ }