@giantswarm-io/pro 1.10.4 → 1.10.5

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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giantswarm-io/pro",
3
- "version": "1.10.4",
3
+ "version": "1.10.5",
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,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
+ }
@@ -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',
@@ -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',
@@ -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',