@giantswarm-io/pro 1.9.0 → 1.10.1
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 +7 -3
- package/package.json +1 -1
- package/src/lib/auth/provider.js +22 -9
- package/src/lib/mcp/board.js +194 -0
- package/src/lib/mcp/tools.js +5 -2
package/README.md
CHANGED
|
@@ -88,9 +88,11 @@ With `--transport=streamable-http` the server picks one of three modes:
|
|
|
88
88
|
|
|
89
89
|
In the OAuth and bearer-only modes GitHub calls run as the caller, so board
|
|
90
90
|
changes are attributed to the person. Scoped tokens (classic OAuth, classic
|
|
91
|
-
PAT) must cover `repo`, `project` and `read:org
|
|
92
|
-
|
|
93
|
-
|
|
91
|
+
PAT) must cover `repo`, `project` and `read:org` (a wider scope counts:
|
|
92
|
+
`admin:org` or `write:org` for `read:org`); GitHub App user-to-server tokens
|
|
93
|
+
and fine-grained PATs have no scopes -- GitHub reports an empty scope list for
|
|
94
|
+
them -- and are accepted as they are, GitHub enforcing their permissions on
|
|
95
|
+
each call.
|
|
94
96
|
|
|
95
97
|
### Environment Variables
|
|
96
98
|
|
|
@@ -217,6 +219,8 @@ The `board` parameter defaults to `"roadmap"` on every board-scoped tool for bac
|
|
|
217
219
|
|
|
218
220
|
### Read Tools
|
|
219
221
|
|
|
222
|
+
- **`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.
|
|
223
|
+
- **`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
224
|
- **`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
225
|
|
|
222
226
|
- **`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
package/src/lib/auth/provider.js
CHANGED
|
@@ -48,8 +48,15 @@ const AUTH_SESSION_TTL_MS = 10 * 60 * 1000;
|
|
|
48
48
|
const TOKEN_CACHE_TTL_MS = 5 * 60 * 1000;
|
|
49
49
|
// Maximum number of registered MCP clients kept in memory
|
|
50
50
|
const MAX_CLIENTS = 1000;
|
|
51
|
-
// GitHub OAuth scopes required by PRO's tools
|
|
51
|
+
// GitHub OAuth scopes required by PRO's tools, each with the scopes that
|
|
52
|
+
// satisfy it: GitHub's classic scopes nest (admin:org > write:org > read:org),
|
|
53
|
+
// and a token announcing the wider scope has the narrower one.
|
|
52
54
|
const REQUIRED_GITHUB_SCOPES = ['repo', 'project', 'read:org'];
|
|
55
|
+
const SCOPE_SATISFIED_BY = {
|
|
56
|
+
repo: ['repo'],
|
|
57
|
+
project: ['project'],
|
|
58
|
+
'read:org': ['read:org', 'write:org', 'admin:org']
|
|
59
|
+
};
|
|
53
60
|
// GitHub's OAuth authorization server, as the hosted GitHub MCP server names it
|
|
54
61
|
// in its protected resource metadata. Used when this server runs as a plain
|
|
55
62
|
// resource server (OAUTH_BEARER_ONLY) whose tokens come from GitHub directly.
|
|
@@ -103,11 +110,13 @@ export function isCimdUrl(clientId) {
|
|
|
103
110
|
*
|
|
104
111
|
* A token is valid when GitHub's /user endpoint accepts it. Classic OAuth and
|
|
105
112
|
* PAT tokens announce their scopes in `x-oauth-scopes`; those must cover the
|
|
106
|
-
* scopes the board tools need
|
|
107
|
-
*
|
|
108
|
-
*
|
|
109
|
-
*
|
|
110
|
-
*
|
|
113
|
+
* scopes the board tools need (a wider scope such as `admin:org` counts for
|
|
114
|
+
* `read:org`), so a token that cannot write is refused up front. GitHub App
|
|
115
|
+
* user-to-server tokens and fine-grained PATs have no scopes -- GitHub sends
|
|
116
|
+
* the header empty or not at all; their permissions are enforced by GitHub
|
|
117
|
+
* per request -- and are accepted; a missing permission surfaces as a 403
|
|
118
|
+
* from the call that needs it. Verified tokens are cached briefly; `sweep`
|
|
119
|
+
* drops expired entries.
|
|
111
120
|
*
|
|
112
121
|
* Used by the OAuth provider (tokens this server issued) and by the
|
|
113
122
|
* bearer-only mode (tokens a client such as muster obtained from GitHub).
|
|
@@ -139,11 +148,15 @@ export function createGitHubTokenVerifier() {
|
|
|
139
148
|
}
|
|
140
149
|
|
|
141
150
|
// Scoped tokens (classic OAuth, classic PAT) announce their scopes; a
|
|
142
|
-
// token
|
|
151
|
+
// token announcing none -- header absent or empty, as for GitHub App
|
|
152
|
+
// user-to-server tokens and fine-grained PATs -- is permission-based and
|
|
153
|
+
// checked per call.
|
|
143
154
|
const scopeHeader = res.headers.get('x-oauth-scopes');
|
|
144
155
|
const grantedScopes = (scopeHeader || '').split(',').map(s => s.trim()).filter(Boolean);
|
|
145
|
-
if (
|
|
146
|
-
const missingScopes = REQUIRED_GITHUB_SCOPES.filter(
|
|
156
|
+
if (grantedScopes.length > 0) {
|
|
157
|
+
const missingScopes = REQUIRED_GITHUB_SCOPES.filter(
|
|
158
|
+
required => !SCOPE_SATISFIED_BY[required].some(scope => grantedScopes.includes(scope))
|
|
159
|
+
);
|
|
147
160
|
if (missingScopes.length > 0) {
|
|
148
161
|
throw new InsufficientScopeError(`GitHub token is missing required scopes: ${missingScopes.join(', ')}`);
|
|
149
162
|
}
|
|
@@ -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
|
+
};
|
package/src/lib/mcp/tools.js
CHANGED
|
@@ -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
|
};
|