@giantswarm-io/pro 1.16.0-rc.2 → 1.16.0-rc.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -100,6 +100,7 @@ each call.
100
100
  - `OAUTH_BEARER_ONLY` (optional, HTTP transport): `true` selects the bearer-only mode described above.
101
101
  - `GITHUB_APP_SLUG` (optional, bearer-only mode): the slug of the GitHub App whose user access tokens alone are accepted (`giantswarm-pro`, pro's own App, installed on every repository of the organization). Every write is then the person's own, capped by that App's permissions on the repository at hand; a token of another App, an OAuth App or a PAT is answered 401.
102
102
  - `HTTP_PORT` (optional): Port for HTTP transport (default: 8080).
103
+ - `PRO_EXTRA_BOARDS` (optional): JSON object of further boards to serve next to the built-in ones; see [Extra boards](docs/extra-boards.md).
103
104
  - `PRO_VERSION` (set by the Helm chart): the version the server reports in its startup log and MCP `serverInfo`, the image tag the chart deploys. Unset, the server reports the `package.json` version, which the npm package carries from its release tag; a checkout reports `0.0.0-dev`.
104
105
 
105
106
  ## Transport Modes
@@ -215,6 +216,8 @@ The container defaults to `--transport=streamable-http`.
215
216
  | `roadmap` | [#273](https://github.com/orgs/giantswarm/projects/273) | Company quarterly goals, team/SIG/WG issues |
216
217
  | `customer` | [#345](https://github.com/orgs/giantswarm/projects/345) | Customer activities and requests from private repos |
217
218
 
219
+ An installation can add boards of its own, such as a team's or a person's board, with `PRO_EXTRA_BOARDS`: see [Extra boards](docs/extra-boards.md).
220
+
218
221
  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.
219
222
 
220
223
  ## MCP Tools
@@ -235,6 +238,7 @@ The `board` parameter defaults to `"roadmap"` on every board-scoped tool for bac
235
238
 
236
239
  - **`get_server_version`** -- The running server's name, version (the release tag, as in the MCP `serverInfo`) and `isDevBuild`.
237
240
  - **`get_issue_timeline`** -- Get the compact activity timeline for a board item's underlying issue: label changes, assignments, milestones, renames, cross-references, and close reasons. Board-independent (queries by item ID). Optional `since`/`until`/`eventTypes` filters (applied client-side; malformed `since`/`until` values return an error). When more than 200 events qualify, only the most recent 200 are returned, with a `truncated` flag.
241
+ - **`list_status_changes`** -- List the board Status changes of one repository's issues in one call: per change the issue, the board (`board`, or `null` with `projectNumber` for a project pro does not serve), `from` and `to` (the option names GitHub recorded at the time), `actor` and `createdAt`, oldest first, with optional `since`/`until`/`board` filters. A Status change does not bump an issue's `updatedAt`, so this is how to see board movement since a date. Scans the open issues (newest first, at most `maxIssues`, default 300; `0` for all), or with `state: "closed"` the closed issues updated since `since`; `truncated` says more issues exist, `timelineTruncated` names issues with more than 50 Status changes whose older ones in the window were not read. Needs one GraphQL request per 50 issues.
238
242
 
239
243
  ### Write Tools
240
244
 
package/bin/index.js CHANGED
@@ -12,6 +12,7 @@
12
12
  *
13
13
  * Optional environment variables:
14
14
  * - HTTP_PORT: Port for HTTP transport (default: 8080)
15
+ * - PRO_EXTRA_BOARDS: JSON object of further boards to serve (docs/extra-boards.md)
15
16
  */
16
17
 
17
18
  import { startMCPServer } from '../src/lib/mcp/server.js';
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.16.0-rc.2",
3
+ "version": "1.16.0-rc.4",
4
4
  "description": "Core library and MCP server for managing Giant Swarm's roadmap and customer project boards",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
package/src/lib/items.js CHANGED
@@ -17,7 +17,9 @@ import {
17
17
  ITEM_ISSUE_REFS_QUERY,
18
18
  BOARD_ITEM_QUERY,
19
19
  BOARDS,
20
+ BOARD_NAMES,
20
21
  DEFAULT_BOARD,
22
+ resolveBoardOwner,
21
23
  UPDATE_ITEM_FIELD_MUTATION,
22
24
  CLEAR_ITEM_FIELD_MUTATION
23
25
  } from './project.js';
@@ -185,7 +187,7 @@ export async function resolveBoardItem(itemId, boardKey, token) {
185
187
  const key = (boardKey || DEFAULT_BOARD).toLowerCase();
186
188
  const board = BOARDS[key];
187
189
  if (!board) {
188
- throw new Error(`Unknown board '${boardKey}'. Valid boards: ${Object.keys(BOARDS).join(', ')}`);
190
+ throw new Error(`Unknown board '${boardKey}'. Valid boards: ${BOARD_NAMES.join(', ')}`);
189
191
  }
190
192
  const boardName = `the ${key} board (#${board.number})`;
191
193
 
@@ -233,17 +235,18 @@ function fieldNameToQueryKey(fieldName) {
233
235
 
234
236
  /**
235
237
  * Resolve a short or full repository name to "owner/name" format.
236
- * Accepts "myrepo" -> "giantswarm/myrepo" or "giantswarm/myrepo" -> "giantswarm/myrepo".
238
+ * Accepts "myrepo" -> "<owner>/myrepo"; a full "owner/name" stays as given.
237
239
  *
238
240
  * @param {string} repository - Short name or full "owner/name" format
241
+ * @param {string} owner - The board's owner, which a short name resolves to
239
242
  * @returns {string} - Full "owner/name" format
240
243
  */
241
- function resolveRepositoryName(repository) {
244
+ function resolveRepositoryName(repository, owner) {
242
245
  const trimmed = repository.trim();
243
246
  if (trimmed.includes('/')) {
244
247
  return trimmed;
245
248
  }
246
- return `giantswarm/${trimmed}`;
249
+ return `${owner}/${trimmed}`;
247
250
  }
248
251
 
249
252
  /**
@@ -310,10 +313,13 @@ function comparisonValue(value) {
310
313
  /**
311
314
  * The query term for an issue-level qualifier.
312
315
  * Dates (created, updated, closed) keep GitHub's comparison and range syntax.
316
+ * @param {string} qualifier - The query qualifier
317
+ * @param {string} value - Requested value, trimmed
318
+ * @param {string} owner - The board's owner, for short repository names
313
319
  * @returns {string|null} - The term, or null for a list without values
314
320
  * @throws {Error} When a parent issue is not a URL or owner/repo#number
315
321
  */
316
- function qualifierTerm(qualifier, value) {
322
+ function qualifierTerm(qualifier, value, owner) {
317
323
  switch (qualifier) {
318
324
  case 'created':
319
325
  case 'updated':
@@ -322,7 +328,7 @@ function qualifierTerm(qualifier, value) {
322
328
  case 'reason':
323
329
  return `reason:${queryValue(value)}`;
324
330
  case 'repo': {
325
- const list = queryValueList(value, resolveRepositoryName);
331
+ const list = queryValueList(value, part => resolveRepositoryName(part, owner));
326
332
  return list ? `repo:${list}` : null;
327
333
  }
328
334
  case 'parent-issue': {
@@ -358,16 +364,17 @@ function qualifierTerm(qualifier, value) {
358
364
  * @param {string} value - Requested value, trimmed
359
365
  * @param {Object[]} allFields - The board's fields
360
366
  * @param {boolean} issueFilters - Whether issue filter names are accepted
367
+ * @param {string} owner - The board's owner, for short repository names
361
368
  * @returns {string|null} - The query term, or null for a list without values
362
369
  * @throws {Error} Naming the unknown field or value and what is available
363
370
  */
364
- function fieldTerm(param, name, value, allFields, issueFilters) {
371
+ function fieldTerm(param, name, value, allFields, issueFilters, owner) {
365
372
  const field = allFields.find(f => f?.name?.toLowerCase() === name.toLowerCase());
366
373
  if (!field) {
367
374
  const filterName = issueFilters &&
368
375
  Object.keys(ISSUE_FILTER_QUALIFIERS).find(key => key.toLowerCase() === name.toLowerCase());
369
376
  if (filterName) {
370
- return qualifierTerm(ISSUE_FILTER_QUALIFIERS[filterName], value);
377
+ return qualifierTerm(ISSUE_FILTER_QUALIFIERS[filterName], value, owner);
371
378
  }
372
379
  const available = allFields.map(f => f?.name).filter(Boolean);
373
380
  const extra = issueFilters ? `; or one of ${Object.keys(ISSUE_FILTER_QUALIFIERS).join(', ')}` : '';
@@ -413,7 +420,7 @@ function fieldTerm(param, name, value, allFields, issueFilters) {
413
420
 
414
421
  const qualifier = QUALIFIER_BY_DATA_TYPE[field.dataType];
415
422
  if (qualifier) {
416
- return qualifierTerm(qualifier, value);
423
+ return qualifierTerm(qualifier, value, owner);
417
424
  }
418
425
 
419
426
  if (field.dataType === 'TEXT') {
@@ -546,6 +553,7 @@ export async function listItems(options) {
546
553
 
547
554
  // Build server-side filter query
548
555
  const queryTerms = [];
556
+ const owner = resolveBoardOwner(boardId);
549
557
 
550
558
  // Issue filters, each in GitHub Projects query syntax. List values are
551
559
  // comma-separated for OR matching; a value with spaces is quoted on its
@@ -575,7 +583,7 @@ export async function listItems(options) {
575
583
  queryTerms.push(`is:${lower}`);
576
584
  }
577
585
  } else {
578
- const term = qualifierTerm(qualifier, trimmed);
586
+ const term = qualifierTerm(qualifier, trimmed, owner);
579
587
  if (term) queryTerms.push(term);
580
588
  }
581
589
  }
@@ -622,11 +630,11 @@ export async function listItems(options) {
622
630
 
623
631
  try {
624
632
  for (const [fieldName, value] of filterEntries) {
625
- const term = fieldTerm('filters', fieldName, value, allFields, false);
633
+ const term = fieldTerm('filters', fieldName, value, allFields, false, owner);
626
634
  if (term) queryTerms.push(term);
627
635
  }
628
636
  for (const [fieldName, value] of excludeEntries) {
629
- const term = fieldTerm('exclude', fieldName, value, allFields, true);
637
+ const term = fieldTerm('exclude', fieldName, value, allFields, true, owner);
630
638
  if (term) queryTerms.push(`-${term}`);
631
639
  }
632
640
  } catch (error) {
@@ -7,7 +7,7 @@
7
7
 
8
8
  import { listFields } from '../fields.js';
9
9
  import { graphQLWithAuth, withPartialData } from '../api.js';
10
- import { resolveBoardId, BOARDS, DEFAULT_BOARD } from '../project.js';
10
+ import { resolveBoardId, BOARDS, BOARD_NAMES, BOARD_NAMES_TEXT, DEFAULT_BOARD } from '../project.js';
11
11
  import { parseIssueRef } from '../rest-api.js';
12
12
  import { logger } from '../logger.js';
13
13
  import { READ_ONLY } from './annotations.js';
@@ -42,13 +42,13 @@ export function describeField(field) {
42
42
  export const getBoardSchemaTool = {
43
43
  name: 'get_board_schema',
44
44
  annotations: READ_ONLY,
45
- description: 'Describe the fields of a project board (roadmap or customer) the way a UI needs them: name, type (singleSelect, iteration, date, text, other), the options a single-select field accepts and the iterations of an iteration field. The same information as the {board}://schema resource, as a tool result.',
45
+ description: `Describe the fields of a project board (${BOARD_NAMES_TEXT}) the way a UI needs them: name, type (singleSelect, iteration, date, text, other), the options a single-select field accepts and the iterations of an iteration field. The same information as the {board}://schema resource, as a tool result.`,
46
46
  inputSchema: {
47
47
  type: 'object',
48
48
  properties: {
49
49
  board: {
50
50
  type: 'string',
51
- enum: ['roadmap', 'customer'],
51
+ enum: BOARD_NAMES,
52
52
  description: 'Which board to describe. Defaults to "roadmap".'
53
53
  }
54
54
  }
@@ -162,7 +162,7 @@ export const getItemByIssueTool = {
162
162
  issue_number: { type: 'number', description: 'Issue number' },
163
163
  board: {
164
164
  type: 'string',
165
- enum: ['roadmap', 'customer'],
165
+ enum: BOARD_NAMES,
166
166
  description: 'Which board to look on. Defaults to "roadmap".'
167
167
  }
168
168
  }
@@ -5,12 +5,13 @@
5
5
  * - {board}://schema: Compact field schema with valid option values, repository guidance, and content policy
6
6
  * - {board}://overview: Board-level stats (issue counts, status and repository distribution)
7
7
  *
8
- * Supported boards: roadmap, customer
8
+ * One pair per board of the registry: the built-in roadmap and customer
9
+ * boards and the ones PRO_EXTRA_BOARDS adds.
9
10
  */
10
11
 
11
12
  import { listFields } from '../fields.js';
12
13
  import { fetchPaginated } from '../api.js';
13
- import { BOARDS, LIST_ITEMS_OVERVIEW_QUERY } from '../project.js';
14
+ import { BOARDS, BOARD_NAMES, LIST_ITEMS_OVERVIEW_QUERY } from '../project.js';
14
15
  import { logger } from '../logger.js';
15
16
 
16
17
  /**
@@ -68,7 +69,7 @@ const SKIP_DATA_TYPES = new Set([
68
69
  async function getSchemaResource(boardKey, token) {
69
70
  const board = BOARDS[boardKey];
70
71
  if (!board) {
71
- throw new Error(`Unknown board '${boardKey}'. Valid boards: ${Object.keys(BOARDS).join(', ')}`);
72
+ throw new Error(`Unknown board '${boardKey}'. Valid boards: ${BOARD_NAMES.join(', ')}`);
72
73
  }
73
74
  try {
74
75
  logger.info(`MCP: Generating schema resource for ${boardKey} board`);
@@ -164,6 +165,9 @@ async function getSchemaResource(boardKey, token) {
164
165
  if (repoInfo.policy?.length) {
165
166
  schema.policy = repoInfo.policy.join(' ');
166
167
  }
168
+ } else {
169
+ // A board added by PRO_EXTRA_BOARDS: only its owner is known
170
+ schema.repoPattern = `${board.owner}/<repository>`;
167
171
  }
168
172
 
169
173
  return {
@@ -194,7 +198,7 @@ async function getSchemaResource(boardKey, token) {
194
198
  async function getOverviewResource(boardKey, token) {
195
199
  const board = BOARDS[boardKey];
196
200
  if (!board) {
197
- throw new Error(`Unknown board '${boardKey}'. Valid boards: ${Object.keys(BOARDS).join(', ')}`);
201
+ throw new Error(`Unknown board '${boardKey}'. Valid boards: ${BOARD_NAMES.join(', ')}`);
198
202
  }
199
203
  try {
200
204
  logger.info(`MCP: Generating overview resource for ${boardKey} board`);
@@ -308,7 +312,7 @@ export async function readResource(uri, extra) {
308
312
  const [, boardKey, resourceType] = match;
309
313
 
310
314
  if (!BOARDS[boardKey]) {
311
- throw new Error(`Unknown board '${boardKey}' in resource URI: ${uri}. Valid boards: ${Object.keys(BOARDS).join(', ')}`);
315
+ throw new Error(`Unknown board '${boardKey}' in resource URI: ${uri}. Valid boards: ${BOARD_NAMES.join(', ')}`);
312
316
  }
313
317
 
314
318
  if (resourceType === 'schema') {
@@ -1,13 +1,22 @@
1
1
  /**
2
2
  * MCP Issue Timeline Tool
3
3
  *
4
- * Exposes 1 tool for reading an issue's activity timeline:
4
+ * Exposes 2 tools for reading issue activity:
5
5
  * - get_issue_timeline: List label/assignment/milestone/rename/cross-reference
6
6
  * events for the issue underlying a project board item.
7
+ * - list_status_changes: List the board Status changes (from, to, board) of
8
+ * the issues of one repository in one call.
7
9
  */
8
10
 
9
11
  import { resolveItemIssues } from '../items.js';
10
- import { getIssueTimeline, MAX_TIMELINE_EVENTS } from '../timeline.js';
12
+ import {
13
+ getIssueTimeline,
14
+ listStatusChanges,
15
+ MAX_TIMELINE_EVENTS,
16
+ STATUS_CHANGES_PER_ISSUE,
17
+ DEFAULT_STATUS_CHANGES_MAX_ISSUES
18
+ } from '../timeline.js';
19
+ import { BOARD_NAMES } from '../project.js';
11
20
  import { logger } from '../logger.js';
12
21
  import { READ_ONLY } from './annotations.js';
13
22
 
@@ -98,14 +107,103 @@ export async function handleGetIssueTimeline(args, extra) {
98
107
  }
99
108
  }
100
109
 
110
+ // ---------------------------------------------------------------------------
111
+ // Tool: list_status_changes
112
+ // ---------------------------------------------------------------------------
113
+
114
+ export const listStatusChangesTool = {
115
+ name: 'list_status_changes',
116
+ annotations: READ_ONLY,
117
+ description: `List the board Status changes of the issues of one repository in one call: for each change the issue (number, title, url, state), the board it happened on (\`board\`, or null for a project pro does not serve, with \`projectNumber\`), \`from\` and \`to\` (the Status option names as GitHub recorded them at the time; \`from\` is empty when the item was just added), \`actor\` and \`createdAt\`, oldest first. A Status change does not bump an issue's updatedAt, so this is the way to see board movement since a date. Scans the repository's open issues (newest first, at most \`maxIssues\`), or with state "closed" the closed issues updated since \`since\`. \`truncated: true\`: more issues exist than were scanned. \`timelineTruncated\` lists issues with more than ${STATUS_CHANGES_PER_ISSUE} Status changes whose older ones inside the window were not read.`,
118
+ inputSchema: {
119
+ type: 'object',
120
+ properties: {
121
+ repository: {
122
+ type: 'string',
123
+ description: 'The repository: short name (e.g. "myrepo", resolved to "giantswarm/myrepo") or "owner/name".'
124
+ },
125
+ since: {
126
+ type: 'string',
127
+ description: 'Only changes at or after this ISO 8601 date/time (e.g. "2026-01-01T00:00:00Z").'
128
+ },
129
+ until: {
130
+ type: 'string',
131
+ description: 'Only changes at or before this ISO 8601 date/time.'
132
+ },
133
+ board: {
134
+ type: 'string',
135
+ enum: BOARD_NAMES,
136
+ description: 'Only changes on this board. Omit for every board.'
137
+ },
138
+ state: {
139
+ type: 'string',
140
+ enum: ['open', 'closed'],
141
+ description: 'Which issues to scan: "open" (default) or "closed" (those updated since `since`).'
142
+ },
143
+ maxIssues: {
144
+ type: 'integer',
145
+ minimum: 0,
146
+ description: `Issues to scan at most, newest first. Default ${DEFAULT_STATUS_CHANGES_MAX_ISSUES}; 0 scans every issue of the state.`
147
+ }
148
+ },
149
+ required: ['repository']
150
+ }
151
+ };
152
+
153
+ /**
154
+ * Split a repository argument into owner and name; a short name is in giantswarm.
155
+ * @param {string} repository
156
+ * @returns {{ owner: string, repo: string }|null}
157
+ */
158
+ export function parseRepository(repository) {
159
+ const parts = String(repository || '').trim().split('/').filter(Boolean);
160
+ if (parts.length === 1) return { owner: 'giantswarm', repo: parts[0] };
161
+ if (parts.length === 2) return { owner: parts[0], repo: parts[1] };
162
+ return null;
163
+ }
164
+
165
+ export async function handleListStatusChanges(args, extra) {
166
+ try {
167
+ const token = extractToken(extra);
168
+ const parsed = parseRepository(args.repository);
169
+ if (!parsed) {
170
+ return { error: `Invalid repository '${args.repository}': give "name" or "owner/name".` };
171
+ }
172
+ logger.info('MCP: Listing status changes', {
173
+ repository: `${parsed.owner}/${parsed.repo}`, since: args.since, until: args.until, board: args.board, state: args.state
174
+ });
175
+
176
+ const result = await listStatusChanges(
177
+ {
178
+ ...parsed,
179
+ since: args.since || null,
180
+ until: args.until || null,
181
+ board: args.board || null,
182
+ state: args.state || 'open',
183
+ maxIssues: args.maxIssues ?? DEFAULT_STATUS_CHANGES_MAX_ISSUES
184
+ },
185
+ token
186
+ );
187
+ if (result.error) {
188
+ return { error: result.error };
189
+ }
190
+ return { content: [{ type: 'text', text: JSON.stringify(result) }] };
191
+ } catch (error) {
192
+ logger.error('MCP: Error listing status changes', { error: error.message });
193
+ return { error: error.message };
194
+ }
195
+ }
196
+
101
197
  // ---------------------------------------------------------------------------
102
198
  // Exports
103
199
  // ---------------------------------------------------------------------------
104
200
 
105
201
  export const timelineTools = [
106
- getIssueTimelineTool
202
+ getIssueTimelineTool,
203
+ listStatusChangesTool
107
204
  ];
108
205
 
109
206
  export const timelineToolHandlers = {
110
- get_issue_timeline: handleGetIssueTimeline
207
+ get_issue_timeline: handleGetIssueTimeline,
208
+ list_status_changes: handleListStatusChanges
111
209
  };
@@ -22,6 +22,8 @@ import {
22
22
  resolveBoardId,
23
23
  DEFAULT_BOARD,
24
24
  BOARDS,
25
+ BOARD_NAMES,
26
+ BOARD_NAMES_TEXT,
25
27
  REPO_ID_QUERY,
26
28
  CREATE_ISSUE_MUTATION,
27
29
  ADD_ITEM_TO_PROJECT_MUTATION,
@@ -47,8 +49,6 @@ import {
47
49
  } from '../comments.js';
48
50
  import { READ_ONLY, additiveWrite, destructiveWrite } from './annotations.js';
49
51
 
50
- const BOARD_NAMES = Object.keys(BOARDS);
51
-
52
52
  /**
53
53
  * Extract the GitHub token from MCP request extra context.
54
54
  * Returns the OAuth token if present, otherwise undefined (falls back to env var in api.js).
@@ -85,7 +85,7 @@ export const DEFAULT_LIST_LIMIT = 50;
85
85
  export const listIssuesTool = {
86
86
  name: 'list_issues',
87
87
  annotations: READ_ONLY,
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 of single-select, iteration, date and text values (only non-empty ones; the built-in Title is the entry's \`title\`). 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.`,
88
+ description: `List and filter issues from a project board (${BOARD_NAMES_TEXT}). 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 of single-select, iteration, date and text values (only non-empty ones; the built-in Title is the entry's \`title\`). 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.`,
89
89
  inputSchema: {
90
90
  type: 'object',
91
91
  properties: {
@@ -105,7 +105,7 @@ export const listIssuesTool = {
105
105
  },
106
106
  repository: {
107
107
  type: 'string',
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).'
108
+ description: 'Filter by repository. Accepts short name (e.g. "myrepo") which resolves to the board\'s owner ("giantswarm/myrepo" on the roadmap and customer boards), 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).'
109
109
  },
110
110
  filters: {
111
111
  type: 'object',
@@ -473,7 +473,7 @@ export const createIssueInProjectTool = {
473
473
  properties: {
474
474
  repository: {
475
475
  type: 'string',
476
- description: 'Repository name (e.g., "my-app") within the giantswarm org, or full "owner/name" format. Use giantswarm/roadmap for public-safe issues and giantswarm/giantswarm for internal/customer-specific issues.'
476
+ description: 'Repository name (e.g., "my-app") of the board\'s owner (the giantswarm org on the roadmap and customer boards), or full "owner/name" format. Use giantswarm/roadmap for public-safe issues and giantswarm/giantswarm for internal/customer-specific issues.'
477
477
  },
478
478
  title: {
479
479
  type: 'string',
@@ -539,7 +539,7 @@ export function issueCreationRefusedMessage(owner, repo) {
539
539
  export async function handleCreateIssueInProject(args, extra) {
540
540
  try {
541
541
  const token = extractToken(extra);
542
- const board = args.board || DEFAULT_BOARD;
542
+ const board = (args.board || DEFAULT_BOARD).toLowerCase();
543
543
  const boardId = resolveBoardId(board);
544
544
  logger.info('MCP: Creating issue in project', { repository: args.repository, title: args.title, board });
545
545
 
@@ -548,7 +548,7 @@ export async function handleCreateIssueInProject(args, extra) {
548
548
  if (args.repository.includes('/')) {
549
549
  [owner, repo] = args.repository.split('/');
550
550
  } else {
551
- owner = 'giantswarm';
551
+ owner = BOARDS[board].owner;
552
552
  repo = args.repository;
553
553
  }
554
554
 
@@ -28,13 +28,100 @@ const CUSTOMER_BOARD_ID = 'PVT_kwDOAHNM9M4AHBOF';
28
28
  export const DEFAULT_BOARD = 'roadmap';
29
29
 
30
30
  /**
31
- * Board registry mapping human-readable keys to project IDs and metadata.
31
+ * The owner a short repository name ("myrepo") resolves to on the built-in boards.
32
32
  */
33
- export const BOARDS = {
34
- roadmap: { id: ROADMAP_BOARD_ID, number: 273, name: 'Roadmap Board' },
35
- customer: { id: CUSTOMER_BOARD_ID, number: 345, name: 'Customer Board' }
33
+ const DEFAULT_OWNER = 'giantswarm';
34
+
35
+ const BUILT_IN_BOARDS = {
36
+ roadmap: { id: ROADMAP_BOARD_ID, number: 273, name: 'Roadmap Board', owner: DEFAULT_OWNER },
37
+ customer: { id: CUSTOMER_BOARD_ID, number: 345, name: 'Customer Board', owner: DEFAULT_OWNER }
36
38
  };
37
39
 
40
+ // A board key is also the scheme of the board's resource URIs ({key}://schema).
41
+ const BOARD_KEY_RE = /^[a-z][a-z0-9-]*$/;
42
+ const EXTRA_BOARD_PROPERTIES = ['id', 'number', 'owner', 'name'];
43
+
44
+ /**
45
+ * Parse the boards an installation adds to the built-in ones (PRO_EXTRA_BOARDS):
46
+ * a JSON object of board key -> { id, number, owner, name }.
47
+ * - id: the project's node ID ("PVT_...")
48
+ * - number: the project's number, as in its URL
49
+ * - owner: the user or organization a short repository name resolves to
50
+ * - name: display name (optional, defaults to "<Key> Board")
51
+ * A mistake fails the start instead of serving a board half configured.
52
+ * @param {string} [json] - The value of PRO_EXTRA_BOARDS
53
+ * @returns {Object} - Board registry entries, keyed by board key
54
+ * @throws {Error} - Naming the entry and what is wrong with it
55
+ */
56
+ export function parseExtraBoards(json) {
57
+ if (!json?.trim()) return {};
58
+
59
+ const fail = message => { throw new Error(`PRO_EXTRA_BOARDS: ${message}`); };
60
+
61
+ let entries;
62
+ try {
63
+ entries = JSON.parse(json);
64
+ } catch (error) {
65
+ fail(`not valid JSON (${error.message})`);
66
+ }
67
+ const isObject = value => value !== null && typeof value === 'object' && !Array.isArray(value);
68
+ if (!isObject(entries)) {
69
+ fail('expected a JSON object of board key -> { id, number, owner, name }');
70
+ }
71
+
72
+ const boards = {};
73
+ for (const [key, board] of Object.entries(entries)) {
74
+ if (!BOARD_KEY_RE.test(key)) {
75
+ fail(`board key '${key}' must be lowercase letters, digits and hyphens, starting with a letter`);
76
+ }
77
+ if (BUILT_IN_BOARDS[key]) {
78
+ fail(`'${key}' is a built-in board and cannot be redefined`);
79
+ }
80
+ if (!isObject(board)) {
81
+ fail(`board '${key}' must be an object with id, number and owner`);
82
+ }
83
+ const unknown = Object.keys(board).filter(property => !EXTRA_BOARD_PROPERTIES.includes(property));
84
+ if (unknown.length) {
85
+ fail(`board '${key}' has unknown properties: ${unknown.join(', ')}. Accepted: ${EXTRA_BOARD_PROPERTIES.join(', ')}`);
86
+ }
87
+ if (typeof board.id !== 'string' || !board.id.startsWith('PVT_')) {
88
+ fail(`board '${key}' needs "id", the project's node ID (PVT_...)`);
89
+ }
90
+ if (!Number.isInteger(board.number) || board.number < 1) {
91
+ fail(`board '${key}' needs "number", the project's number as in its URL`);
92
+ }
93
+ if (typeof board.owner !== 'string' || !/^[A-Za-z0-9-]+$/.test(board.owner)) {
94
+ fail(`board '${key}' needs "owner", the user or organization a short repository name resolves to`);
95
+ }
96
+ if (board.name !== undefined && (typeof board.name !== 'string' || !board.name.trim())) {
97
+ fail(`board '${key}': "name" must be a non-empty string`);
98
+ }
99
+ boards[key] = {
100
+ id: board.id,
101
+ number: board.number,
102
+ name: board.name?.trim() || `${key[0].toUpperCase()}${key.slice(1)} Board`,
103
+ owner: board.owner
104
+ };
105
+ }
106
+ return boards;
107
+ }
108
+
109
+ /**
110
+ * Board registry mapping human-readable keys to project IDs and metadata:
111
+ * the built-in boards, then the ones PRO_EXTRA_BOARDS adds.
112
+ */
113
+ export const BOARDS = { ...BUILT_IN_BOARDS, ...parseExtraBoards(process.env.PRO_EXTRA_BOARDS) };
114
+
115
+ /**
116
+ * The board keys, for the `board` argument of the tools.
117
+ */
118
+ export const BOARD_NAMES = Object.keys(BOARDS);
119
+
120
+ /**
121
+ * The board keys as prose ("roadmap or customer"), for tool descriptions.
122
+ */
123
+ export const BOARD_NAMES_TEXT = new Intl.ListFormat('en', { type: 'disjunction' }).format(BOARD_NAMES);
124
+
38
125
  /**
39
126
  * Resolve a board key (e.g. "roadmap", "customer") to its GitHub project node ID.
40
127
  * Defaults to DEFAULT_BOARD when boardKey is null/undefined/empty.
@@ -46,11 +133,20 @@ export function resolveBoardId(boardKey) {
46
133
  const key = (boardKey || DEFAULT_BOARD).toLowerCase();
47
134
  const entry = BOARDS[key];
48
135
  if (!entry) {
49
- throw new Error(`Unknown board '${boardKey}'. Valid boards: ${Object.keys(BOARDS).join(', ')}`);
136
+ throw new Error(`Unknown board '${boardKey}'. Valid boards: ${BOARD_NAMES.join(', ')}`);
50
137
  }
51
138
  return entry.id;
52
139
  }
53
140
 
141
+ /**
142
+ * The owner a short repository name resolves to on a board.
143
+ * @param {string} boardId - GitHub project node ID
144
+ * @returns {string} - The board's owner; the built-in one for a project outside the registry
145
+ */
146
+ export function resolveBoardOwner(boardId) {
147
+ return Object.values(BOARDS).find(board => board.id === boardId)?.owner || DEFAULT_OWNER;
148
+ }
149
+
54
150
  // Fetch repository id
55
151
  const REPO_ID_QUERY = `
56
152
  query ($owner: String!, $repo: String!) {
@@ -12,6 +12,8 @@
12
12
 
13
13
  import { getOctokit } from './rest-api.js';
14
14
  import { logger } from './logger.js';
15
+ import { fetchBounded } from './api.js';
16
+ import { BOARDS } from './project.js';
15
17
 
16
18
  const DEFAULT_PAGE_SIZE = 100;
17
19
 
@@ -179,3 +181,161 @@ export async function getIssueTimeline({ owner, repo, issue_number, since, until
179
181
 
180
182
  return { events: kept, truncated };
181
183
  }
184
+
185
+
186
+ // ---------------------------------------------------------------------------
187
+ // Status changes across one repository (GraphQL)
188
+ // ---------------------------------------------------------------------------
189
+
190
+ /** Issues read per GraphQL page by listStatusChanges. */
191
+ const STATUS_CHANGES_PAGE_SIZE = 50;
192
+
193
+ /** Status-change events read per issue (the newest ones). */
194
+ export const STATUS_CHANGES_PER_ISSUE = 50;
195
+
196
+ /** Issues scanned by listStatusChanges unless maxIssues says otherwise. */
197
+ export const DEFAULT_STATUS_CHANGES_MAX_ISSUES = 300;
198
+
199
+ const STATUS_CHANGES_QUERY = `
200
+ query($owner: String!, $repo: String!, $first: Int!, $after: String, $states: [IssueState!], $filterSince: DateTime) {
201
+ repository(owner: $owner, name: $repo) {
202
+ issues(first: $first, after: $after, states: $states, filterBy: { since: $filterSince }, orderBy: { field: CREATED_AT, direction: DESC }) {
203
+ totalCount
204
+ pageInfo { hasNextPage endCursor }
205
+ nodes {
206
+ number
207
+ title
208
+ url
209
+ state
210
+ timelineItems(last: ${STATUS_CHANGES_PER_ISSUE}, itemTypes: [PROJECT_V2_ITEM_STATUS_CHANGED_EVENT]) {
211
+ totalCount
212
+ nodes {
213
+ ... on ProjectV2ItemStatusChangedEvent {
214
+ createdAt
215
+ actor { login }
216
+ previousStatus
217
+ status
218
+ project { number url }
219
+ }
220
+ }
221
+ }
222
+ }
223
+ }
224
+ }
225
+ }
226
+ `;
227
+
228
+ /**
229
+ * The board key of a project, matched on its number and owner (the owner is
230
+ * read from the project URL, https://github.com/orgs/<owner>/projects/<n>).
231
+ * @param {{ number?: number, url?: string }} [project]
232
+ * @returns {string|null}
233
+ */
234
+ export function boardKeyOfProject(project) {
235
+ if (!project) return null;
236
+ const owner = /github\.com\/(?:orgs|users)\/([^/]+)\/projects\//.exec(project.url || '')?.[1];
237
+ const entry = Object.entries(BOARDS).find(([, board]) =>
238
+ board.number === project.number && (!owner || board.owner.toLowerCase() === owner.toLowerCase()));
239
+ return entry ? entry[0] : null;
240
+ }
241
+
242
+ /**
243
+ * List the board Status changes of the issues of one repository: every
244
+ * ProjectV2ItemStatusChangedEvent with its previous and new Status and the
245
+ * board it happened on. Project field changes do not bump an issue's
246
+ * updatedAt, so open issues are all scanned (newest first, up to maxIssues);
247
+ * closed issues are narrowed to those updated since \`since\` (closing an
248
+ * issue bumps it).
249
+ *
250
+ * @param {Object} params
251
+ * @param {string} params.owner
252
+ * @param {string} params.repo
253
+ * @param {string} [params.since] - ISO 8601; only changes at or after this instant
254
+ * @param {string} [params.until] - ISO 8601; only changes at or before this instant
255
+ * @param {string} [params.board] - Only changes on this board key
256
+ * @param {'open'|'closed'} [params.state] - Which issues to scan (default open)
257
+ * @param {number} [params.maxIssues] - Issues to scan at most; 0 = all
258
+ * @param {string} [token] - Optional per-request GitHub token
259
+ * @returns {Promise<Object>}
260
+ */
261
+ export async function listStatusChanges({ owner, repo, since, until, board, state = 'open', maxIssues = DEFAULT_STATUS_CHANGES_MAX_ISSUES }, token) {
262
+ const sinceDate = since ? new Date(since) : null;
263
+ const untilDate = until ? new Date(until) : null;
264
+ if (sinceDate && Number.isNaN(sinceDate.getTime())) {
265
+ return { error: `Invalid 'since' date/time: '${since}'` };
266
+ }
267
+ if (untilDate && Number.isNaN(untilDate.getTime())) {
268
+ return { error: `Invalid 'until' date/time: '${until}'` };
269
+ }
270
+ if (state !== 'open' && state !== 'closed') {
271
+ return { error: `Invalid 'state': '${state}' (open or closed)` };
272
+ }
273
+ if (board && !BOARDS[board]) {
274
+ return { error: `Unknown board '${board}'` };
275
+ }
276
+
277
+ logger.debug('Listing status changes', { owner, repo, since, until, board, state, maxIssues });
278
+
279
+ let totalCount = null;
280
+ const { nodes, hasNextPage } = await fetchBounded(
281
+ STATUS_CHANGES_QUERY,
282
+ {
283
+ owner,
284
+ repo,
285
+ first: STATUS_CHANGES_PAGE_SIZE,
286
+ states: [state === 'closed' ? 'CLOSED' : 'OPEN'],
287
+ filterSince: state === 'closed' && sinceDate ? sinceDate.toISOString() : null
288
+ },
289
+ (result) => {
290
+ const issues = result?.repository?.issues;
291
+ if (totalCount === null && typeof issues?.totalCount === 'number') totalCount = issues.totalCount;
292
+ return issues || { nodes: [], pageInfo: { hasNextPage: false } };
293
+ },
294
+ token,
295
+ { limit: maxIssues > 0 ? maxIssues : 0 }
296
+ );
297
+
298
+ const changes = [];
299
+ const timelineTruncated = [];
300
+ for (const issue of nodes) {
301
+ const events = (issue.timelineItems?.nodes || []).filter(event => event && event.createdAt);
302
+ if ((issue.timelineItems?.totalCount ?? 0) > events.length) {
303
+ const oldestKept = events[0]?.createdAt;
304
+ if (!sinceDate || !oldestKept || new Date(oldestKept) > sinceDate) timelineTruncated.push(issue.number);
305
+ }
306
+ for (const event of events) {
307
+ const at = new Date(event.createdAt);
308
+ if (sinceDate && at < sinceDate) continue;
309
+ if (untilDate && at > untilDate) continue;
310
+ const eventBoard = boardKeyOfProject(event.project);
311
+ if (board && eventBoard !== board) continue;
312
+ changes.push({
313
+ number: issue.number,
314
+ title: issue.title,
315
+ url: issue.url,
316
+ state: issue.state,
317
+ board: eventBoard,
318
+ projectNumber: event.project?.number ?? null,
319
+ from: event.previousStatus ?? '',
320
+ to: event.status ?? '',
321
+ actor: event.actor?.login,
322
+ createdAt: event.createdAt
323
+ });
324
+ }
325
+ }
326
+ changes.sort((a, b) => a.createdAt.localeCompare(b.createdAt));
327
+
328
+ return {
329
+ repository: `${owner}/${repo}`,
330
+ state,
331
+ since: since || null,
332
+ until: until || null,
333
+ board: board || null,
334
+ issuesScanned: nodes.length,
335
+ issuesTotal: totalCount,
336
+ truncated: hasNextPage,
337
+ timelineTruncated,
338
+ count: changes.length,
339
+ changes
340
+ };
341
+ }