@giantswarm-io/pro 1.11.2 → 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 CHANGED
@@ -98,6 +98,7 @@ each call.
98
98
 
99
99
  - `GITHUB_API_TOKEN` (required for stdio and the env-token HTTP mode): GitHub PAT with `project:write` and `repo:write` scopes.
100
100
  - `OAUTH_BEARER_ONLY` (optional, HTTP transport): `true` selects the bearer-only mode described above.
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.
101
102
  - `HTTP_PORT` (optional): Port for HTTP transport (default: 8080).
102
103
  - `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`.
103
104
 
@@ -221,23 +222,30 @@ The `board` parameter defaults to `"roadmap"` on every board-scoped tool for bac
221
222
  ### Read Tools
222
223
 
223
224
  - **`get_board_schema`** -- Describe a board's fields for a UI: name, type (`singleSelect`, `iteration`, `date`, `text`, `other`), the options of single-select fields and the iterations of iteration fields. The `{board}://schema` resource as a tool result.
224
- - **`get_item_by_issue`** -- Find the board item of one GitHub issue (URL, `owner/repo#N`, or owner/repo/number) without scanning the board; `item: null` when the issue is not on the board.
225
- - **`list_issues`** -- List and filter issues from a project board using generic field filters. Specify `board` to choose the board (`"roadmap"` or `"customer"`). Use `filters` (a field name-to-value map) to filter by any single-select field. Use `emptyFields` to find items missing specific field values. Read the board's schema resource first to discover available fields and valid options. Next to `count`, the result carries `hidden` (matching items left out because their content could not be read, e.g. issues in private repos the server's GitHub identity cannot access) and `totalCount` (GitHub's count for the server-side query, including unreadable items, draft issues and pull requests).
225
+ - **`get_item_by_issue`** -- Find the board item of one GitHub issue or pull request of any repository on the board (URL, `owner/repo#N`, or owner/repo/number) without scanning the board; `item: null` with a `reason` when the issue is not on the board, does not resolve, or is no issue.
226
+ - **`list_issues`** -- List and filter issues from a project board using generic field filters. Specify `board` to choose the board (`"roadmap"` or `"customer"`). Use `filters` (a field name-to-value map) to filter by any field: single-select options (comma-separated for OR), iteration titles or `@current`/`@next`/`@previous`, date and number comparisons (`">2026-01-01"`, `"1..3"`), exact text; it is the only place for a field filter, and any other top-level argument the tool does not declare is refused with an error naming it, like every other tool's. `exclude` takes the same keys (plus the issue filter names `repository`, `assignee`, `label`, `milestone`, `type`, `parentIssue`, `updated`, `created`, `closed`, `reason`) and leaves matching items out. `milestone`, `type` (issue type) and `parentIssue` filter on those issue attributes. Use `emptyFields` to find items missing specific field values, `nonEmptyFields` for items that have them. Read the board's schema resource first to discover available fields and valid options.
227
+ An item with open dependencies carries their counts as `openBlockedBy` and `openBlocking`. The counts come in a request of their own: an issue whose counts cannot be read just carries none, and when the request fails the list stays and `dependencyCountsError` names why.
228
+ Migration: earlier releases took an unknown top-level string argument as a field filter (so a misspelled argument silently became one). A call like `list_issues(board="roadmap", Team="Honey Badger")` is now `list_issues(board="roadmap", filters={"Team": "Honey Badger"})`; the refusal says so for a capitalized field name. The undeclared `project` alias of `board` is gone as well. Returns at most `limit` items (default 50; `0` for every matching item), reading the board only as far as the limit needs. Next to `count`, the result carries `hidden` (matching items left out because their content could not be read, e.g. issues in private repos the server's GitHub identity cannot access) and `totalCount` (GitHub's count for the server-side query, including unreadable items, draft issues and pull requests); a cut result says so with `truncated: true` and a `nextCursor`, which the next call passes as `cursor` with the same filters to continue.
226
229
 
227
- - **`get_issue_details`** -- Get full details for a specific item: repository metadata, title, body text, comments with timestamps, assignees, labels, dates, and all field values. Board-independent (queries by item ID).
230
+ - **`get_issue_details`** -- Get full details for a specific item: repository metadata, title, body text, comments with timestamps, assignees, labels, dates, all field values, and the issue's relations (`blockedBy`, `blocking`, `relatesTo`: the first 50 of each with their state; `hidden` counts the related issues the caller cannot read, and a list with more than were read says `truncated: true` and its `totalCount`). The relations come in a request of their own: when it fails, the rest of the details stay and `relationsError` names why; a pull request or draft carries neither. Board-independent (queries by item ID).
231
+
232
+ - **`list_issue_relations`** -- List the issues that block an issue (`blockedBy`), that it blocks (`blocking`) and that it relates to (`relatesTo`), with their state; the first 100 of each (`hidden` counts the related issues the caller cannot read; a list with more than were read says `truncated: true` and its `totalCount`). Takes any issue as `issueUrl` (URL or `owner/repo#N`), on a board or not. Parent/child links stay with `list_sub_issues` and `get_parent_issue`.
228
233
 
229
234
  - **`list_issue_comments`** -- Fetch comments for multiple board items in a single call. Board-independent (queries by item ID). Resolves each item to its underlying issue and returns comment author/timestamps/body, with an optional `since` cutoff. Each comment includes `createdAt`, plus `updatedAt` when it differs from `createdAt` (i.e. the comment was edited). Bounded response: max 25 `itemIds` per call, newest 20 comments per issue by default (override with `maxPerIssue`), and long comment bodies are truncated with an explicit indicator. Without `since`, "newest" means newest by creation time, and per-issue REST pagination is capped (surfaced via a `truncatedPages` flag if more comments exist); with `since`, "newest" means newest by last-updated time, so a recently-edited older comment isn't dropped in favor of an untouched newer one, and its `updatedAt` shows why. The response's `itemCount` counts result items (including error entries), not comments.
230
235
 
236
+ - **`get_server_version`** -- The running server's name, version (the release tag, as in the MCP `serverInfo`) and `isDevBuild`.
231
237
  - **`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.
232
238
 
233
239
  ### Write Tools
234
240
 
235
- - **`update_issue_field`** -- Update a single-select field value. Provide human-readable field and option names; the server resolves them to GitHub node IDs. Specify `board` to target the correct board.
241
+ - **`update_issue_field`** -- Update a single-select, iteration or date field value. Name the item by `itemId` or by the issue as `issueUrl` (URL or `owner/repo#N`); provide human-readable field and option names; the server resolves them to GitHub node IDs. Specify `board` to target the correct board.
236
242
 
237
243
  - **`create_issue_in_project`** -- Create a new GitHub Issue in a repository and add it to a board. Optionally set initial status, assignees, and labels. Public issues in `giantswarm/roadmap` require `confirmPublicSafe=true`. Labels must already exist in the repository -- non-existent labels are rejected before the issue is created rather than being auto-created. If applying labels fails *after* the issue has already been created and added to the board, the issue is not rolled back -- the response reports `success: true` with a `warning` explaining that labels were not applied.
238
244
 
239
245
  - **`add_existing_issue`** -- Add an existing GitHub issue to a board by URL or node ID.
240
246
 
247
+ - **`add_issue_relation`** / **`remove_issue_relation`** -- Set or remove a relation between two issues of any repository: `issueUrl`, `relation` (`"blocked_by"`: `relatedIssueUrl` blocks `issueUrl`; `"blocking"`: `issueUrl` blocks `relatedIssueUrl`; `"relates_to"`) and `relatedIssueUrl`. A dependency set this way shows on both issues in GitHub, unlike a "Blocked by" line in an issue body.
248
+
241
249
  - **`archive_item`** -- Archive a project item from the active board view.
242
250
 
243
251
  - **`close_issue`** -- Close the GitHub issue underlying a single project item. Board-independent (queries by item ID). Accepts an optional `stateReason` (`"completed"` or `"not_planned"`, defaults to `"completed"`; any other value returns an error) and an optional `comment` posted before closing. Comments on issues in public repos require `confirmPublicSafe=true`. One item per call -- no bulk close. Closing the issue does not update the board's Status field; unless the board has GitHub's built-in "item closed -> set Status" workflow enabled, pair this with `update_issue_field` if the board Status should reflect the closure.
@@ -336,7 +344,15 @@ The `Publish package` workflow runs on every GitHub Release (created automatical
336
344
 
337
345
  ## Development
338
346
 
347
+ Install the npm dependencies first: a fresh clone or git worktree has no `node_modules`, and every test fails until `npm ci` ran. `make test` does it for you when `node_modules` is missing.
348
+
339
349
  ```bash
350
+ # Install the dependencies (once per clone or worktree)
351
+ npm ci
352
+
353
+ # Run the tests
354
+ make test
355
+
340
356
  # Start the MCP server locally (stdio)
341
357
  node bin/index.js
342
358
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.11.2",
3
+ "version": "1.15.0-rc.2",
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/index.js CHANGED
@@ -46,6 +46,14 @@ export {
46
46
  reprioritizeSubIssue
47
47
  } from './lib/sub-issues.js';
48
48
 
49
+ // Issue relations (GraphQL): blocked by / blocking dependencies, relates to links
50
+ export {
51
+ RELATION_TYPES,
52
+ listIssueRelations,
53
+ addIssueRelation,
54
+ removeIssueRelation
55
+ } from './lib/relations.js';
56
+
49
57
  // Bulk issue comment fetching (board items -> underlying issue comments)
50
58
  export {
51
59
  listIssueCommentsForItems,
@@ -60,5 +68,5 @@ export {
60
68
  } from './lib/timeline.js';
61
69
 
62
70
  // Low-level GitHub clients for anything not covered above
63
- export { graphQLWithAuth, fetchPaginated } from './lib/api.js';
71
+ export { graphQLWithAuth, fetchPaginated, fetchBounded } from './lib/api.js';
64
72
  export { getOctokit, parseIssueRef, resolveIssueId } from './lib/rest-api.js';
package/src/lib/api.js CHANGED
@@ -53,6 +53,23 @@ export async function graphQLWithAuth(query, variables = {}, token) {
53
53
  return await client(query, variables);
54
54
  }
55
55
 
56
+ /**
57
+ * Await a GraphQL request whose response may carry errors next to its data.
58
+ * @octokit/graphql throws on any `errors` entry, partial data attached; when
59
+ * every error passes `tolerate`, this answers that partial data instead.
60
+ * @param {Promise<Object>} request - The graphQLWithAuth call
61
+ * @param {(error: Object) => boolean} tolerate - Whether one GraphQL error is acceptable
62
+ * @returns {Promise<{ data: Object, errors: Array }>}
63
+ */
64
+ export async function withPartialData(request, tolerate) {
65
+ try {
66
+ return { data: await request, errors: [] };
67
+ } catch (error) {
68
+ if (!error.data || !error.errors?.length || !error.errors.every(tolerate)) throw error;
69
+ return { data: error.data, errors: error.errors };
70
+ }
71
+ }
72
+
56
73
  /**
57
74
  * Fetch paginated results.
58
75
  * @param {string} query - GraphQL query
@@ -62,26 +79,52 @@ export async function graphQLWithAuth(query, variables = {}, token) {
62
79
  * @returns {Promise<Array>} - All results
63
80
  */
64
81
  export async function fetchPaginated(query, variables, getNextPage, token) {
65
- const allItems = [];
82
+ const { nodes } = await fetchBounded(query, variables, getNextPage, token);
83
+ return nodes;
84
+ }
85
+
86
+ /**
87
+ * Fetch a cursor-paginated connection page by page, keeping the nodes `keep`
88
+ * accepts, until `limit` nodes are kept (0: every page) or the pages run out.
89
+ * Each page asks GitHub for no more nodes than are still missing, capped at
90
+ * `variables.first`, so a small limit costs one small request. A page that
91
+ * announces a next page without a cursor ends the fetch instead of repeating.
92
+ * @param {string} query - GraphQL query taking $first and $after
93
+ * @param {Object} variables - Query variables; `first` caps the page size
94
+ * @param {Function} getNextPage - Function to extract { nodes, pageInfo } from a result
95
+ * @param {string} [token] - Optional per-request token (falls back to GITHUB_API_TOKEN)
96
+ * @param {Object} [options]
97
+ * @param {string|null} [options.after] - Cursor to continue from (an earlier endCursor)
98
+ * @param {number} [options.limit] - Nodes to keep before stopping; 0 keeps every node
99
+ * @param {Function} [options.keep] - Node predicate; a rejected node does not count
100
+ * @returns {Promise<{nodes: Array, hasNextPage: boolean, endCursor: string|null}>}
101
+ * `hasNextPage` is true when the fetch stopped at the limit with pages
102
+ * left; `endCursor` continues from there.
103
+ */
104
+ export async function fetchBounded(query, variables, getNextPage, token, { after = null, limit = 0, keep = () => true } = {}) {
105
+ const nodes = [];
66
106
  let hasNextPage = true;
67
- let after = null;
107
+ let endCursor = after;
68
108
 
69
- while (hasNextPage) {
109
+ while (hasNextPage && (limit === 0 || nodes.length < limit)) {
70
110
  const queryVars = { ...variables };
71
- if (after) {
72
- queryVars.after = after;
111
+ if (endCursor) {
112
+ queryVars.after = endCursor;
113
+ }
114
+ if (limit > 0) {
115
+ queryVars.first = Math.min(variables.first ?? limit, limit - nodes.length);
73
116
  }
74
117
 
75
118
  const result = await graphQLWithAuth(query, queryVars, token);
76
- const pageInfo = getNextPage(result);
119
+ const page = getNextPage(result);
77
120
 
78
- if (pageInfo.nodes && Array.isArray(pageInfo.nodes)) {
79
- allItems.push(...pageInfo.nodes);
121
+ if (Array.isArray(page.nodes)) {
122
+ nodes.push(...page.nodes.filter(keep));
80
123
  }
81
124
 
82
- hasNextPage = pageInfo.pageInfo && pageInfo.pageInfo.hasNextPage;
83
- after = pageInfo.pageInfo && pageInfo.pageInfo.endCursor;
125
+ endCursor = page.pageInfo?.endCursor || null;
126
+ hasNextPage = Boolean(page.pageInfo?.hasNextPage && endCursor);
84
127
  }
85
128
 
86
- return allItems;
129
+ return { nodes, hasNextPage, endCursor };
87
130
  }
@@ -121,9 +121,17 @@ export function isCimdUrl(clientId) {
121
121
  * Used by the OAuth provider (tokens this server issued) and by the
122
122
  * bearer-only mode (tokens a client such as muster obtained from GitHub).
123
123
  *
124
+ * With `appSlug` (bearer-only mode, `GITHUB_APP_SLUG`) only a user access
125
+ * token of that GitHub App is accepted: a `ghu_` token whose installations,
126
+ * as GitHub lists them for a user token (`GET /user/installations`, only the
127
+ * issuing App's), are all the App's. Every write is then the person's own,
128
+ * capped by that App's permissions on the repository at hand; a token of any
129
+ * other App, OAuth App or PAT is refused with 401.
130
+ *
131
+ * @param {{ appSlug?: string }} [options]
124
132
  * @returns {{ verifyAccessToken(token: string): Promise<object>, sweep(now?: number): void }}
125
133
  */
126
- export function createGitHubTokenVerifier() {
134
+ export function createGitHubTokenVerifier({ appSlug } = {}) {
127
135
  // token → { authInfo, expiresAt }
128
136
  const tokenCache = new Map();
129
137
 
@@ -164,6 +172,10 @@ export function createGitHubTokenVerifier() {
164
172
 
165
173
  const user = await res.json();
166
174
 
175
+ if (appSlug) {
176
+ await requireAppUserToken(token, appSlug);
177
+ }
178
+
167
179
  const authInfo = {
168
180
  token,
169
181
  clientId: user.login,
@@ -188,6 +200,32 @@ export function createGitHubTokenVerifier() {
188
200
  return { verifyAccessToken, sweep };
189
201
  }
190
202
 
203
+ /**
204
+ * Refuse a token that is not a user access token of the GitHub App `appSlug`.
205
+ * @param {string} token
206
+ * @param {string} appSlug
207
+ */
208
+ async function requireAppUserToken(token, appSlug) {
209
+ const refusal = `GitHub token is not a user access token of the GitHub App ${appSlug}`;
210
+ if (!token.startsWith('ghu_')) {
211
+ throw new InvalidTokenError(refusal);
212
+ }
213
+ const res = await fetch('https://api.github.com/user/installations?per_page=100', {
214
+ headers: {
215
+ Authorization: `Bearer ${token}`,
216
+ Accept: 'application/vnd.github+json',
217
+ 'User-Agent': 'giantswarm-pro-mcp'
218
+ }
219
+ });
220
+ if (!res.ok) {
221
+ throw new InvalidTokenError(`GitHub App installation lookup failed: ${res.status}`);
222
+ }
223
+ const { installations = [] } = await res.json();
224
+ if (installations.length === 0 || installations.some(i => i.app_slug !== appSlug)) {
225
+ throw new InvalidTokenError(refusal);
226
+ }
227
+ }
228
+
191
229
  /**
192
230
  * Create the GitHub OAuth provider.
193
231
  *
package/src/lib/fields.js CHANGED
@@ -54,10 +54,12 @@ const UPDATABLE_FIELD_TYPES = new Set([
54
54
  * @returns {Promise<Object|null>} - The field object or null if not found
55
55
  */
56
56
  export async function findFieldByName(fieldName, boardId, token) {
57
+ if (typeof fieldName !== 'string') return null;
57
58
  const allFields = await listFields(boardId, token);
58
59
 
60
+ const wanted = fieldName.toLowerCase();
59
61
  const field = allFields.find(field => {
60
- if (field.name.toLowerCase() !== fieldName.toLowerCase()) return false;
62
+ if (field?.name?.toLowerCase() !== wanted) return false;
61
63
  if (UPDATABLE_FIELD_TYPES.has(field.__typename)) return true;
62
64
  // ProjectV2Field with dataType DATE
63
65
  if (field.__typename === 'ProjectV2Field' && field.dataType === 'DATE') return true;
@@ -74,20 +76,30 @@ export async function findFieldByName(fieldName, boardId, token) {
74
76
  * @returns {Object|null} - Matching option or null
75
77
  */
76
78
  export function findMatchingOption(options, optionName) {
77
- if (!optionName) return null;
79
+ if (!optionName || !Array.isArray(options)) return null;
78
80
 
79
- // Try direct match first
80
- const exactMatch = options.find(option => option.name === optionName);
81
+ // Try direct match first, ignoring surrounding whitespace and emoji
82
+ // variation selectors ("✅️" is "✅")
83
+ const exact = exactForm(optionName);
84
+ const exactMatch = options.find(option => exactForm(option.name) === exact);
81
85
  if (exactMatch) return exactMatch;
82
86
 
83
87
  // Try case-insensitive match with normalization
88
+ // A value of only punctuation or emoji normalizes to nothing, like an
89
+ // option named only so: it matches no option but by its exact name.
84
90
  const normalizedName = normalizeFieldValue(optionName);
91
+ if (!normalizedName) return null;
85
92
  return options.find(option => {
86
93
  const normalizedOption = normalizeFieldValue(option.name);
87
94
  return normalizedOption === normalizedName;
88
95
  });
89
96
  }
90
97
 
98
+ /** A name as compared exactly: trimmed, without emoji variation selectors. */
99
+ function exactForm(name) {
100
+ return String(name).replace(/[\uFE0E\uFE0F]/g, '').trim();
101
+ }
102
+
91
103
  /**
92
104
  * Find a matching iteration in a field's iteration configuration
93
105
  * @param {Object} field - An iteration field with configuration.iterations[]
@@ -99,11 +111,12 @@ export function findMatchingIteration(field, value) {
99
111
  if (!iterations?.length || !value) return null;
100
112
 
101
113
  // Try direct match first
102
- const exactMatch = iterations.find(iter => iter.title === value);
114
+ const exactMatch = iterations.find(iter => exactForm(iter.title) === exactForm(value));
103
115
  if (exactMatch) return exactMatch;
104
116
 
105
117
  // Try case-insensitive match with normalization
106
118
  const normalizedValue = normalizeFieldValue(value);
119
+ if (!normalizedValue) return null;
107
120
  return iterations.find(iter => {
108
121
  const normalizedTitle = normalizeFieldValue(iter.title);
109
122
  return normalizedTitle === normalizedValue;