@giantswarm-io/pro 1.10.4 → 1.10.6
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/package.json
CHANGED
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint) for the
|
|
3
|
+
* pro tools. Every tool declares its class here so a client -- or an
|
|
4
|
+
* aggregator's read-only toolset such as muster's `preset:read-only`, which is
|
|
5
|
+
* an annotation predicate -- can tell the reads from the writes. A tool
|
|
6
|
+
* without annotations is treated as a destructive write by the MCP defaults.
|
|
7
|
+
*
|
|
8
|
+
* openWorldHint is left to the MCP default (true): every tool talks to
|
|
9
|
+
* GitHub's API.
|
|
10
|
+
*/
|
|
11
|
+
|
|
12
|
+
/** A tool that reads GitHub and changes nothing. */
|
|
13
|
+
export const READ_ONLY = Object.freeze({
|
|
14
|
+
readOnlyHint: true,
|
|
15
|
+
destructiveHint: false,
|
|
16
|
+
idempotentHint: true
|
|
17
|
+
});
|
|
18
|
+
|
|
19
|
+
/** A write that only adds (create, add to a board): repeating it adds again unless noted. */
|
|
20
|
+
export function additiveWrite({ idempotent = false } = {}) {
|
|
21
|
+
return Object.freeze({
|
|
22
|
+
readOnlyHint: false,
|
|
23
|
+
destructiveHint: false,
|
|
24
|
+
idempotentHint: idempotent
|
|
25
|
+
});
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
/** A write that changes or removes what exists (set a field, close, archive, remove). */
|
|
29
|
+
export function destructiveWrite({ idempotent = true } = {}) {
|
|
30
|
+
return Object.freeze({
|
|
31
|
+
readOnlyHint: false,
|
|
32
|
+
destructiveHint: true,
|
|
33
|
+
idempotentHint: idempotent
|
|
34
|
+
});
|
|
35
|
+
}
|
package/src/lib/mcp/board.js
CHANGED
|
@@ -10,6 +10,7 @@ import { graphQLWithAuth } from '../api.js';
|
|
|
10
10
|
import { resolveBoardId, DEFAULT_BOARD } from '../project.js';
|
|
11
11
|
import { parseIssueRef } from '../rest-api.js';
|
|
12
12
|
import { logger } from '../logger.js';
|
|
13
|
+
import { READ_ONLY } from './annotations.js';
|
|
13
14
|
|
|
14
15
|
function extractToken(extra) {
|
|
15
16
|
return extra?.authInfo?.token;
|
|
@@ -40,6 +41,7 @@ export function describeField(field) {
|
|
|
40
41
|
|
|
41
42
|
export const getBoardSchemaTool = {
|
|
42
43
|
name: 'get_board_schema',
|
|
44
|
+
annotations: READ_ONLY,
|
|
43
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.',
|
|
44
46
|
inputSchema: {
|
|
45
47
|
type: 'object',
|
|
@@ -110,6 +112,7 @@ const ISSUE_PROJECT_ITEM_QUERY = `
|
|
|
110
112
|
|
|
111
113
|
export const getItemByIssueTool = {
|
|
112
114
|
name: 'get_item_by_issue',
|
|
115
|
+
annotations: READ_ONLY,
|
|
113
116
|
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
117
|
inputSchema: {
|
|
115
118
|
type: 'object',
|
|
@@ -19,6 +19,7 @@ import {
|
|
|
19
19
|
reprioritizeSubIssue
|
|
20
20
|
} from '../sub-issues.js';
|
|
21
21
|
import { logger } from '../logger.js';
|
|
22
|
+
import { READ_ONLY, additiveWrite, destructiveWrite } from './annotations.js';
|
|
22
23
|
|
|
23
24
|
/**
|
|
24
25
|
* Extract the GitHub token from MCP request extra context.
|
|
@@ -62,6 +63,7 @@ function compactIssue(issue) {
|
|
|
62
63
|
|
|
63
64
|
export const listSubIssuesTool = {
|
|
64
65
|
name: 'list_sub_issues',
|
|
66
|
+
annotations: READ_ONLY,
|
|
65
67
|
description: 'List the sub-issues of a GitHub issue. Provide the parent issue as a URL (e.g. "https://github.com/owner/repo/issues/1"), short ref ("owner/repo#1"), or explicit owner/repo/issue_number.',
|
|
66
68
|
inputSchema: {
|
|
67
69
|
type: 'object',
|
|
@@ -123,6 +125,7 @@ export async function handleListSubIssues(args, extra) {
|
|
|
123
125
|
|
|
124
126
|
export const addSubIssueTool = {
|
|
125
127
|
name: 'add_sub_issue',
|
|
128
|
+
annotations: additiveWrite({ idempotent: true }),
|
|
126
129
|
description: 'Add a sub-issue to a parent issue. Provide the parent issue and the child issue to add. The child can be specified as a URL/ref (subIssueUrl) or integer ID (subIssueId).',
|
|
127
130
|
inputSchema: {
|
|
128
131
|
type: 'object',
|
|
@@ -197,6 +200,7 @@ export async function handleAddSubIssue(args, extra) {
|
|
|
197
200
|
|
|
198
201
|
export const removeSubIssueTool = {
|
|
199
202
|
name: 'remove_sub_issue',
|
|
203
|
+
annotations: destructiveWrite(),
|
|
200
204
|
description: 'Remove a sub-issue from a parent issue. Provide the parent issue and the child issue to remove.',
|
|
201
205
|
inputSchema: {
|
|
202
206
|
type: 'object',
|
|
@@ -255,6 +259,7 @@ export async function handleRemoveSubIssue(args, extra) {
|
|
|
255
259
|
|
|
256
260
|
export const getParentIssueTool = {
|
|
257
261
|
name: 'get_parent_issue',
|
|
262
|
+
annotations: READ_ONLY,
|
|
258
263
|
description: 'Get the parent issue of a given issue. Returns null if the issue has no parent.',
|
|
259
264
|
inputSchema: {
|
|
260
265
|
type: 'object',
|
|
@@ -296,6 +301,7 @@ export async function handleGetParentIssue(args, extra) {
|
|
|
296
301
|
|
|
297
302
|
export const reprioritizeSubIssueTool = {
|
|
298
303
|
name: 'reprioritize_sub_issue',
|
|
304
|
+
annotations: destructiveWrite(),
|
|
299
305
|
description: 'Reorder a sub-issue within its parent\'s sub-issue list. Specify either afterUrl/afterId (place after that issue) or beforeUrl/beforeId (place before that issue).',
|
|
300
306
|
inputSchema: {
|
|
301
307
|
type: 'object',
|
|
@@ -462,6 +468,7 @@ export function extractIssueRef(text, fallbackOwner, fallbackRepo) {
|
|
|
462
468
|
|
|
463
469
|
export const migrateTaskListTool = {
|
|
464
470
|
name: 'migrate_task_list_to_sub_issues',
|
|
471
|
+
annotations: destructiveWrite({ idempotent: false }),
|
|
465
472
|
description: 'Convert markdown task-list items in an issue body into sub-issues. Parses lines like "- [ ] https://github.com/o/r/issues/1", "- [x] owner/repo#1", or "- [ ] #1" (same-repo). Optionally removes converted lines from the issue body.',
|
|
466
473
|
inputSchema: {
|
|
467
474
|
type: 'object',
|
package/src/lib/mcp/timeline.js
CHANGED
|
@@ -9,6 +9,7 @@
|
|
|
9
9
|
import { resolveItemIssues } from '../items.js';
|
|
10
10
|
import { getIssueTimeline, MAX_TIMELINE_EVENTS } from '../timeline.js';
|
|
11
11
|
import { logger } from '../logger.js';
|
|
12
|
+
import { READ_ONLY } from './annotations.js';
|
|
12
13
|
|
|
13
14
|
/**
|
|
14
15
|
* Extract the GitHub token from MCP request extra context.
|
|
@@ -25,6 +26,7 @@ function extractToken(extra) {
|
|
|
25
26
|
|
|
26
27
|
export const getIssueTimelineTool = {
|
|
27
28
|
name: 'get_issue_timeline',
|
|
29
|
+
annotations: READ_ONLY,
|
|
28
30
|
description: `Get the activity timeline for a project board item's underlying issue: label changes, assignments, milestones, renames, cross-references, and close reasons. Returns compact events ordered chronologically (oldest first); when more than ${MAX_TIMELINE_EVENTS} events qualify, only the most recent ${MAX_TIMELINE_EVENTS} are returned (see \`truncated\` in the response). No server-side date/type filters exist on this endpoint, so \`since\`/\`until\`/\`eventTypes\` are applied client-side -- pass full ISO 8601 timestamps (not just a date) for precise since/until cutoffs.`,
|
|
29
31
|
inputSchema: {
|
|
30
32
|
type: 'object',
|
package/src/lib/mcp/tools.js
CHANGED
|
@@ -42,6 +42,7 @@ import {
|
|
|
42
42
|
MAX_ITEMS_PER_CALL,
|
|
43
43
|
DEFAULT_MAX_PER_ISSUE
|
|
44
44
|
} from '../comments.js';
|
|
45
|
+
import { READ_ONLY, additiveWrite, destructiveWrite } from './annotations.js';
|
|
45
46
|
|
|
46
47
|
const BOARD_NAMES = Object.keys(BOARDS);
|
|
47
48
|
|
|
@@ -77,6 +78,7 @@ async function resolveSingleItemIssue(itemId, token) {
|
|
|
77
78
|
|
|
78
79
|
export const listIssuesTool = {
|
|
79
80
|
name: 'list_issues',
|
|
81
|
+
annotations: READ_ONLY,
|
|
80
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}.',
|
|
81
83
|
inputSchema: {
|
|
82
84
|
type: 'object',
|
|
@@ -212,6 +214,7 @@ export async function handleListIssues(args, extra) {
|
|
|
212
214
|
|
|
213
215
|
export const getIssueDetailsTool = {
|
|
214
216
|
name: 'get_issue_details',
|
|
217
|
+
annotations: READ_ONLY,
|
|
215
218
|
description: 'Get detailed information about a specific issue including repository metadata, title, description, comments, assignees, labels, and field values.',
|
|
216
219
|
inputSchema: {
|
|
217
220
|
type: 'object',
|
|
@@ -249,6 +252,7 @@ export async function handleGetIssueDetails(args, extra) {
|
|
|
249
252
|
|
|
250
253
|
export const updateIssueFieldTool = {
|
|
251
254
|
name: 'update_issue_field',
|
|
255
|
+
annotations: destructiveWrite(),
|
|
252
256
|
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.',
|
|
253
257
|
inputSchema: {
|
|
254
258
|
type: 'object',
|
|
@@ -381,6 +385,7 @@ export async function handleUpdateIssueField(args, extra) {
|
|
|
381
385
|
|
|
382
386
|
export const createIssueInProjectTool = {
|
|
383
387
|
name: 'create_issue_in_project',
|
|
388
|
+
annotations: additiveWrite(),
|
|
384
389
|
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.',
|
|
385
390
|
inputSchema: {
|
|
386
391
|
type: 'object',
|
|
@@ -564,6 +569,7 @@ export async function handleCreateIssueInProject(args, extra) {
|
|
|
564
569
|
|
|
565
570
|
export const addExistingIssueTool = {
|
|
566
571
|
name: 'add_existing_issue',
|
|
572
|
+
annotations: additiveWrite({ idempotent: true }),
|
|
567
573
|
description: 'Add an existing GitHub issue to a project board. At least one of issueUrl or issueNodeId must be provided.',
|
|
568
574
|
inputSchema: {
|
|
569
575
|
type: 'object',
|
|
@@ -643,6 +649,7 @@ export async function handleAddExistingIssue(args, extra) {
|
|
|
643
649
|
|
|
644
650
|
export const archiveItemTool = {
|
|
645
651
|
name: 'archive_item',
|
|
652
|
+
annotations: destructiveWrite(),
|
|
646
653
|
description: 'Archive a project item, removing it from the active board view without deleting the underlying issue.',
|
|
647
654
|
inputSchema: {
|
|
648
655
|
type: 'object',
|
|
@@ -695,6 +702,7 @@ export async function handleArchiveItem(args, extra) {
|
|
|
695
702
|
|
|
696
703
|
export const closeIssueTool = {
|
|
697
704
|
name: 'close_issue',
|
|
705
|
+
annotations: destructiveWrite(),
|
|
698
706
|
description: 'Close the GitHub issue underlying a single project board item. Board-independent (queries by item ID). Optionally posts a comment before closing. Operates on exactly one item per call -- there is no bulk close. Comments on issues in public repos require confirmPublicSafe=true. This does not change the board\'s Status field -- unless the board has GitHub\'s built-in "item closed -> set Status" workflow enabled, pair this call with update_issue_field if the board Status should reflect the closure.',
|
|
699
707
|
inputSchema: {
|
|
700
708
|
type: 'object',
|
|
@@ -778,6 +786,7 @@ export async function handleCloseIssue(args, extra) {
|
|
|
778
786
|
|
|
779
787
|
export const reopenIssueTool = {
|
|
780
788
|
name: 'reopen_issue',
|
|
789
|
+
annotations: destructiveWrite(),
|
|
781
790
|
description: 'Reopen the GitHub issue underlying a single project board item. Board-independent (queries by item ID). Optionally posts a comment before reopening. Operates on exactly one item per call -- there is no bulk reopen. Comments on issues in public repos require confirmPublicSafe=true. This does not change the board\'s Status field -- unless the board has GitHub\'s built-in "item closed -> set Status" workflow enabled, pair this call with update_issue_field if the board Status should reflect the reopening.',
|
|
782
791
|
inputSchema: {
|
|
783
792
|
type: 'object',
|
|
@@ -842,6 +851,7 @@ export async function handleReopenIssue(args, extra) {
|
|
|
842
851
|
|
|
843
852
|
export const updateIssueLabelsTool = {
|
|
844
853
|
name: 'update_issue_labels',
|
|
854
|
+
annotations: destructiveWrite(),
|
|
845
855
|
description: 'Add and/or remove labels on the issue underlying a project board item. At least one of addLabels or removeLabels must be provided. Labels being added must already exist in the repository -- non-existent labels are rejected with an error listing them, rather than being auto-created.',
|
|
846
856
|
inputSchema: {
|
|
847
857
|
type: 'object',
|
|
@@ -947,6 +957,7 @@ export async function handleUpdateIssueLabels(args, extra) {
|
|
|
947
957
|
|
|
948
958
|
export const listIssueCommentsTool = {
|
|
949
959
|
name: 'list_issue_comments',
|
|
960
|
+
annotations: READ_ONLY,
|
|
950
961
|
description: `Fetch comments for multiple board items in a single call. Board-independent (queries by item ID). Resolves each item to its underlying GitHub issue and returns the comment author, timestamps, and body for each. Bounded response: max ${MAX_ITEMS_PER_CALL} itemIds per call, and only the newest ${DEFAULT_MAX_PER_ISSUE} comments per issue by default (override with maxPerIssue); long comment bodies are truncated with an explicit truncation indicator. Each comment includes \`createdAt\`, plus \`updatedAt\` when it differs from \`createdAt\` (i.e. the comment was edited). Ordering differs by mode: without \`since\`, the newest comments by creation time are kept; with \`since\`, the newest comments by last-updated time are kept (so a recently-edited older comment survives ahead of an untouched newer one, and its \`updatedAt\` shows why). The response's \`itemCount\` counts result items (including error entries), not comments.`,
|
|
951
962
|
inputSchema: {
|
|
952
963
|
type: 'object',
|