@giantswarm-io/pro 1.9.0 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -217,6 +217,8 @@ The `board` parameter defaults to `"roadmap"` on every board-scoped tool for bac
217
217
 
218
218
  ### Read Tools
219
219
 
220
+ - **`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.
221
+ - **`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.
220
222
  - **`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.
221
223
 
222
224
  - **`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).
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.9.0",
3
+ "version": "1.10.0",
4
4
  "description": "Core library and MCP server for managing Giant Swarm's roadmap and customer project boards",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -0,0 +1,194 @@
1
+ /**
2
+ * Board tools for UIs: the field schema as a tool result and the board item of
3
+ * a given issue. Both exist because a UI (the Dev Portal's roadmap page) needs
4
+ * them as tools it can call through an MCP aggregator on behalf of the person,
5
+ * where the schema resource and a board scan would not do.
6
+ */
7
+
8
+ import { listFields } from '../fields.js';
9
+ import { graphQLWithAuth } from '../api.js';
10
+ import { resolveBoardId, DEFAULT_BOARD } from '../project.js';
11
+ import { parseIssueRef } from '../rest-api.js';
12
+ import { logger } from '../logger.js';
13
+
14
+ function extractToken(extra) {
15
+ return extra?.authInfo?.token;
16
+ }
17
+
18
+ /**
19
+ * The field description a UI works with: name, a coarse type, and the values
20
+ * a single-select or iteration field accepts. Internal ids stay out.
21
+ */
22
+ export function describeField(field) {
23
+ let type = 'other';
24
+ if (field.__typename === 'ProjectV2SingleSelectField') {
25
+ type = 'singleSelect';
26
+ } else if (field.__typename === 'ProjectV2IterationField') {
27
+ type = 'iteration';
28
+ } else if (field.__typename === 'ProjectV2Field') {
29
+ type = field.dataType === 'DATE' ? 'date' : 'text';
30
+ }
31
+ const described = { name: field.name, type };
32
+ if (field.options) {
33
+ described.options = field.options.map(option => option.name);
34
+ }
35
+ if (field.configuration?.iterations) {
36
+ described.iterations = field.configuration.iterations.map(iteration => iteration.title);
37
+ }
38
+ return described;
39
+ }
40
+
41
+ export const getBoardSchemaTool = {
42
+ name: 'get_board_schema',
43
+ 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.',
44
+ inputSchema: {
45
+ type: 'object',
46
+ properties: {
47
+ board: {
48
+ type: 'string',
49
+ enum: ['roadmap', 'customer'],
50
+ description: 'Which board to describe. Defaults to "roadmap".'
51
+ }
52
+ }
53
+ }
54
+ };
55
+
56
+ export async function handleGetBoardSchema(args, extra) {
57
+ try {
58
+ const token = extractToken(extra);
59
+ const board = (args.board || DEFAULT_BOARD).toLowerCase();
60
+ const boardId = resolveBoardId(board);
61
+ logger.info('MCP: Describing board schema', { board });
62
+
63
+ const fields = await listFields(boardId, token);
64
+
65
+ return {
66
+ content: [{
67
+ type: 'text',
68
+ text: JSON.stringify({ board, fields: fields.map(describeField) })
69
+ }]
70
+ };
71
+ } catch (error) {
72
+ logger.error('MCP: Error describing board schema', { error: error.message });
73
+ return { error: error.message };
74
+ }
75
+ }
76
+
77
+ const ISSUE_PROJECT_ITEM_QUERY = `
78
+ query IssueProjectItem($owner: String!, $repo: String!, $number: Int!) {
79
+ repository(owner: $owner, name: $repo) {
80
+ issue(number: $number) {
81
+ title
82
+ url
83
+ state
84
+ projectItems(first: 20, includeArchived: false) {
85
+ nodes {
86
+ id
87
+ project { id }
88
+ fieldValues(first: 30) {
89
+ nodes {
90
+ ... on ProjectV2ItemFieldSingleSelectValue {
91
+ name
92
+ field { ... on ProjectV2FieldCommon { name } }
93
+ }
94
+ ... on ProjectV2ItemFieldIterationValue {
95
+ title
96
+ field { ... on ProjectV2FieldCommon { name } }
97
+ }
98
+ ... on ProjectV2ItemFieldDateValue {
99
+ date
100
+ field { ... on ProjectV2FieldCommon { name } }
101
+ }
102
+ }
103
+ }
104
+ }
105
+ }
106
+ }
107
+ }
108
+ }
109
+ `;
110
+
111
+ export const getItemByIssueTool = {
112
+ name: 'get_item_by_issue',
113
+ description: 'Find the project board item of one GitHub issue -- given as a URL, a short ref ("owner/repo#N") or owner/repo/issue_number -- without scanning the board. Returns the item id, title, url, state and field values, or item: null when the issue is not on the board.',
114
+ inputSchema: {
115
+ type: 'object',
116
+ properties: {
117
+ issueUrl: { type: 'string', description: 'Issue URL or short ref (owner/repo#num)' },
118
+ owner: { type: 'string', description: 'Repository owner' },
119
+ repo: { type: 'string', description: 'Repository name' },
120
+ issue_number: { type: 'number', description: 'Issue number' },
121
+ board: {
122
+ type: 'string',
123
+ enum: ['roadmap', 'customer'],
124
+ description: 'Which board to look on. Defaults to "roadmap".'
125
+ }
126
+ }
127
+ }
128
+ };
129
+
130
+ function resolveIssueArgs(args) {
131
+ if (args.issueUrl) {
132
+ return parseIssueRef(args.issueUrl);
133
+ }
134
+ if (args.owner && args.repo && args.issue_number) {
135
+ return { owner: args.owner, repo: args.repo, issue_number: Number(args.issue_number) };
136
+ }
137
+ throw new Error("Provide either 'issueUrl' (URL or owner/repo#num) or 'owner', 'repo', and 'issue_number'.");
138
+ }
139
+
140
+ export async function handleGetItemByIssue(args, extra) {
141
+ try {
142
+ const token = extractToken(extra);
143
+ const board = (args.board || DEFAULT_BOARD).toLowerCase();
144
+ const boardId = resolveBoardId(board);
145
+ const { owner, repo, issue_number } = resolveIssueArgs(args);
146
+ logger.info('MCP: Looking up board item by issue', { board, owner, repo, issue_number });
147
+
148
+ const result = await graphQLWithAuth(
149
+ ISSUE_PROJECT_ITEM_QUERY,
150
+ { owner, repo, number: issue_number },
151
+ token
152
+ );
153
+ const issue = result?.repository?.issue;
154
+ const node = issue?.projectItems?.nodes?.find(item => item?.project?.id === boardId);
155
+ if (!issue || !node) {
156
+ return { content: [{ type: 'text', text: JSON.stringify({ item: null }) }] };
157
+ }
158
+
159
+ const fields = {};
160
+ for (const fieldValue of node.fieldValues?.nodes || []) {
161
+ const value = fieldValue?.name ?? fieldValue?.title ?? fieldValue?.date;
162
+ if (fieldValue?.field?.name && value) {
163
+ fields[fieldValue.field.name] = value;
164
+ }
165
+ }
166
+
167
+ return {
168
+ content: [{
169
+ type: 'text',
170
+ text: JSON.stringify({
171
+ item: {
172
+ id: node.id,
173
+ title: issue.title,
174
+ number: issue_number,
175
+ url: issue.url,
176
+ repo: `${owner}/${repo}`,
177
+ state: issue.state,
178
+ fields
179
+ }
180
+ })
181
+ }]
182
+ };
183
+ } catch (error) {
184
+ logger.error('MCP: Error looking up board item by issue', { error: error.message });
185
+ return { error: error.message };
186
+ }
187
+ }
188
+
189
+ export const boardTools = [getBoardSchemaTool, getItemByIssueTool];
190
+
191
+ export const boardToolHandlers = {
192
+ get_board_schema: handleGetBoardSchema,
193
+ get_item_by_issue: handleGetItemByIssue
194
+ };
@@ -36,6 +36,7 @@ import {
36
36
  import { logger } from '../logger.js';
37
37
  import { subIssueTools, subIssueToolHandlers } from './sub-issues.js';
38
38
  import { timelineTools, timelineToolHandlers } from './timeline.js';
39
+ import { boardTools, boardToolHandlers } from './board.js';
39
40
  import {
40
41
  listIssueCommentsForItems,
41
42
  MAX_ITEMS_PER_CALL,
@@ -1017,7 +1018,8 @@ export const tools = [
1017
1018
  updateIssueLabelsTool,
1018
1019
  listIssueCommentsTool,
1019
1020
  ...subIssueTools,
1020
- ...timelineTools
1021
+ ...timelineTools,
1022
+ ...boardTools
1021
1023
  ];
1022
1024
 
1023
1025
  export const toolHandlers = {
@@ -1032,5 +1034,6 @@ export const toolHandlers = {
1032
1034
  update_issue_labels: handleUpdateIssueLabels,
1033
1035
  list_issue_comments: handleListIssueComments,
1034
1036
  ...subIssueToolHandlers,
1035
- ...timelineToolHandlers
1037
+ ...timelineToolHandlers,
1038
+ ...boardToolHandlers
1036
1039
  };