@flowrelay/mcp-server 1.0.29 → 1.8.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 +34 -3
- package/dist/api.d.ts +368 -1
- package/dist/api.js +118 -0
- package/dist/server.js +583 -4
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ It connects to Flow Relay API v1 using an API key and supports:
|
|
|
11
11
|
## Package
|
|
12
12
|
|
|
13
13
|
- Name: @flowrelay/mcp-server
|
|
14
|
-
- Version: 1.0
|
|
14
|
+
- Version: 1.8.0
|
|
15
15
|
|
|
16
16
|
## Supported Sources (52 Integrations)
|
|
17
17
|
|
|
@@ -32,10 +32,10 @@ Flow Relay MCP Server supports 52 integration sources across the entire engineer
|
|
|
32
32
|
|
|
33
33
|
## What Is Included
|
|
34
34
|
|
|
35
|
-
The server currently exposes
|
|
35
|
+
The server currently exposes 40 tools, 3 prompts and 1 resource template. Every tool carries the four MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`): the `list_*` and `get_*` tools are read-only and idempotent, the `generate_*` tools (including `generate_plan_review`), `ask_project`, `create_work_item`, `create_raid_entry`, `resolve_suggestion`, `decide_approval`, `request_change` and `discord_send_message` are non-idempotent (each call spends credits, creates an item or an entry, files a request, decides one or posts a message), `update_work_item` and `link_evidence` write but are idempotent (the same values twice leave the item unchanged) and `delete_work_item` is the one destructive tool (`destructiveHint: true`, so clients can ask before it runs; the deletion can be restored from the change history).
|
|
36
36
|
|
|
37
37
|
- `get_workspace_context`: Show current Flow Relay context (account mode, organizations count, accessible projects count, active project scope and caller role).
|
|
38
|
-
- `list_projects`: List every accessible project (personal and organization) with id, scope and
|
|
38
|
+
- `list_projects`: List every accessible project (personal and organization) with id, scope, role and the prefix of its work item keys.
|
|
39
39
|
- `set_active_project`: Set or clear the active project for subsequent tool calls so `project_id` can be omitted.
|
|
40
40
|
- `list_filter_options`: List selectable resources (projects/repos/channels/boards), branches, event types and priorities per source for a project. Call this before generating so handoff and insight filters use real values instead of guesses. Also reports whether Figma visual context is selectable (requires Global processing region).
|
|
41
41
|
- `list_handoffs`: List handoffs for the active project or across accessible projects. Filter by status (`active`, `archived` or `all`). Outputs server-rendered Markdown.
|
|
@@ -52,6 +52,37 @@ The server currently exposes 18 tools. Every tool carries the four MCP annotatio
|
|
|
52
52
|
- `list_untracked_resources`: List event-producing resources not scoped to any project (useful for discovering unassigned activity).
|
|
53
53
|
- `discord_list_channels`: List text channels in connected Discord servers.
|
|
54
54
|
- `discord_send_message`: Send a Discord message – plain text, or attach a rendered Markdown artifact (`last_handoff`, `last_correlation`, `last_onboarding`, `last_architecture` or `last_release_notes`) as a `.md` file.
|
|
55
|
+
- `list_my_work`: List the work items assigned to you across every accessible project (open items plus those finished in the last 7 days) with status, progress and dates.
|
|
56
|
+
- `list_work_items`: List the tasks and milestones of a project plan with key, status, progress, dates and assignees. Filter by status or to your own items (`mine`); paginate with `cursor`.
|
|
57
|
+
- `get_work_item`: Read one work item by key (such as `FR-12`) or id: description, dates, assignees, dependencies, linked evidence and comment count.
|
|
58
|
+
- `create_work_item`: Create a task or milestone, optionally nested under a parent, with a duration (`3d`, `2w`, `4h`), a deadline and `assign_to_me`.
|
|
59
|
+
- `update_work_item`: Change status, progress, title, description, priority, the blocked flag, duration or deadline of an item.
|
|
60
|
+
- `list_suggestions`: List the pending suggestions of a project you can act on: status changes proposed from linked activity (an opened or merged pull request, a deploy), new items from meeting action items, dependencies from tracker links and activity suggested as evidence. Suggestions routed to you are marked; nothing changes until someone accepts one in Flow Relay.
|
|
61
|
+
- `link_evidence`: Attach an https link (pull request, commit, build, deploy, incident, document) to an item as evidence, with an optional title, kind and time.
|
|
62
|
+
- `list_raid`: Read the RAID register of a project: risks, assumptions, issues, decisions and dependencies with their score (probability times impact) and response. Filter by type and status; entries that are not closed by default.
|
|
63
|
+
- `get_earned_value`: Read the cost picture of a project plan at its status date – planned and actual cost, planned value, earned value, variances, SPI, CPI, TCPI and the estimates at completion – against a baseline. Project managers only, on plans that include costs.
|
|
64
|
+
- `get_portfolio`: Read the portfolio of an organization – every project you can open with its progress, forecast finish, next milestone, open risks and health (on track, at risk or off track, computed every night from the plan and the build, deploy and incident signals, or set by hand by a project manager) – to see which projects need attention. Business plan and above.
|
|
65
|
+
- `get_forecast`: Forecast when a project plan finishes by simulating it thousands of times – the finish of the project and of each milestone as the dates by which half, four out of five and nineteen out of twenty of the runs are done, the chance of meeting the target or a deadline and the items most often on the critical path. Business plan and above.
|
|
66
|
+
- `plan_whatif`: Ask a what-if question about a plan in words (for example, what if the payment integration takes three weeks longer?): the model turns it into changes to the work and the scheduler computes the new finish dates. Nothing is saved. Costs 5 credits per question.
|
|
67
|
+
- `list_automations`: List the automation rules of a plan as sentences, with how often they ran and how the last run went. Team plan and above.
|
|
68
|
+
- `list_templates`: List the templates saved for a plan, with the id to give to `apply_template`.
|
|
69
|
+
- `apply_template`: Add a saved template to a plan, at the top level or under an item key. Project managers only.
|
|
70
|
+
- `list_approvals`: List the change requests of a plan: what was asked in plain language, who asked, who decided and what they said. Business plan and above, organization projects.
|
|
71
|
+
- `request_change`: Ask for a change to an item (status, progress, priority, blocked flag, duration or deadline) that a second person must approve. It only files the request; approving applies it. Business plan and above, organization projects.
|
|
72
|
+
- `resolve_suggestion`: Accept or dismiss one pending suggestion from `list_suggestions`. Accepting applies it to the plan as the key owner.
|
|
73
|
+
- `create_raid_entry`: Add a risk, assumption, issue, decision or dependency to the register of a plan, with optional probability and impact from 1 to 5, response and due date.
|
|
74
|
+
- `delete_work_item`: Delete a work item and everything under it. One batch in the change history, so a project manager can restore it. Contributors can delete only items they created.
|
|
75
|
+
- `decide_approval`: Approve, reject or withdraw a change request from `list_approvals`. A request needs a second person; only its author can withdraw it.
|
|
76
|
+
- `generate_plan_review`: Write a status report for a project plan (progress, concerns, milestone outlook, suggested register entries, next steps) from numbers the scheduler computed and the last 14 days of linked activity. Returns Markdown. Costs 5 credits per run.
|
|
77
|
+
|
|
78
|
+
Work item tools, `resolve_suggestion`, `create_raid_entry`, `delete_work_item`, `decide_approval`, `list_raid`, `get_earned_value`, `get_portfolio`, `get_forecast`, `list_automations`, `list_templates`, `apply_template`, `list_approvals` and `request_change` cost no credits. Dates are wall-clock times in the plan time zone (`YYYY-MM-DDTHH:mm`), which every reply names. Contributors can create items when the project allows it, assign only themselves and update the items assigned to them or created by them; schedule changes may need a project manager. A commit message, branch name or pull request title that mentions an item key (`FR-12`) is linked to that item as evidence. Items mirrored from Jira, Linear or GitHub Issues also answer to the key the tracker gave them (`PAY-123`, `acme/web#42`).
|
|
79
|
+
|
|
80
|
+
### Prompts and resources
|
|
81
|
+
|
|
82
|
+
- `handoff_for_branch` (argument `branch`): finds the git sources that carry the branch and generates a handoff limited to it.
|
|
83
|
+
- `onboard_me` (arguments `role`, optional `focus`): reads the existing insights first and generates an onboarding brief only when none fits.
|
|
84
|
+
- `weekly_status`: writes a short status update from the plan, the register and the last days of activity.
|
|
85
|
+
- Resource template `flowrelay://projects/{project_id}/handoffs/latest`: the latest active handoff of a project as Markdown.
|
|
55
86
|
|
|
56
87
|
### Filter Dimensions
|
|
57
88
|
|
package/dist/api.d.ts
CHANGED
|
@@ -17,6 +17,7 @@ export interface TenantProject {
|
|
|
17
17
|
id: string;
|
|
18
18
|
name: string;
|
|
19
19
|
slug: string;
|
|
20
|
+
key?: string | null;
|
|
20
21
|
description: string;
|
|
21
22
|
organization_id: string | null;
|
|
22
23
|
organization_name: string | null;
|
|
@@ -136,6 +137,303 @@ export interface FigmaGateInfo {
|
|
|
136
137
|
canManageResidency: boolean;
|
|
137
138
|
residencyHref: string | null;
|
|
138
139
|
}
|
|
140
|
+
export interface WorkItemSummary {
|
|
141
|
+
id: string;
|
|
142
|
+
key: string;
|
|
143
|
+
number: number;
|
|
144
|
+
title: string;
|
|
145
|
+
kind: string;
|
|
146
|
+
status: string;
|
|
147
|
+
blocked: boolean;
|
|
148
|
+
priority: number;
|
|
149
|
+
isSummary: boolean;
|
|
150
|
+
parentId: string | null;
|
|
151
|
+
percentComplete: number;
|
|
152
|
+
start: string | null;
|
|
153
|
+
finish: string | null;
|
|
154
|
+
deadline: string | null;
|
|
155
|
+
durationMinutes: number | null;
|
|
156
|
+
critical: boolean;
|
|
157
|
+
assignees: {
|
|
158
|
+
userId: string | null;
|
|
159
|
+
name: string;
|
|
160
|
+
}[];
|
|
161
|
+
version: number;
|
|
162
|
+
updatedAt: string;
|
|
163
|
+
url: string;
|
|
164
|
+
}
|
|
165
|
+
export interface WorkItemDetail extends WorkItemSummary {
|
|
166
|
+
description: string;
|
|
167
|
+
predecessors: {
|
|
168
|
+
key: string | null;
|
|
169
|
+
type: string;
|
|
170
|
+
lagMinutes: number;
|
|
171
|
+
}[];
|
|
172
|
+
successors: {
|
|
173
|
+
key: string | null;
|
|
174
|
+
type: string;
|
|
175
|
+
lagMinutes: number;
|
|
176
|
+
}[];
|
|
177
|
+
evidence: {
|
|
178
|
+
source: string;
|
|
179
|
+
kind: string;
|
|
180
|
+
title: string | null;
|
|
181
|
+
url: string | null;
|
|
182
|
+
occurredAt: string;
|
|
183
|
+
}[];
|
|
184
|
+
commentCount: number;
|
|
185
|
+
}
|
|
186
|
+
export interface MyWorkEntry {
|
|
187
|
+
id: string;
|
|
188
|
+
key: string;
|
|
189
|
+
title: string;
|
|
190
|
+
status: string;
|
|
191
|
+
blocked: boolean;
|
|
192
|
+
priority: number;
|
|
193
|
+
kind: string;
|
|
194
|
+
percentComplete: number;
|
|
195
|
+
start: string | null;
|
|
196
|
+
finish: string | null;
|
|
197
|
+
deadline: string | null;
|
|
198
|
+
updatedAt: string;
|
|
199
|
+
url: string;
|
|
200
|
+
project: {
|
|
201
|
+
id: string;
|
|
202
|
+
name: string;
|
|
203
|
+
timezone: string;
|
|
204
|
+
};
|
|
205
|
+
}
|
|
206
|
+
export interface WorkItemInput {
|
|
207
|
+
title?: string;
|
|
208
|
+
description?: string;
|
|
209
|
+
parent?: string;
|
|
210
|
+
kind?: 'task' | 'milestone';
|
|
211
|
+
status?: string;
|
|
212
|
+
priority?: number;
|
|
213
|
+
duration?: string;
|
|
214
|
+
deadline?: string | null;
|
|
215
|
+
assignee?: string;
|
|
216
|
+
blocked?: boolean;
|
|
217
|
+
percentComplete?: number;
|
|
218
|
+
}
|
|
219
|
+
export interface WorkSuggestion {
|
|
220
|
+
id: string;
|
|
221
|
+
type: 'status_change' | 'create_item' | 'dependency' | 'evidence';
|
|
222
|
+
item: string | null;
|
|
223
|
+
payload: Record<string, unknown>;
|
|
224
|
+
origin: string;
|
|
225
|
+
forYou: boolean;
|
|
226
|
+
createdAt: string;
|
|
227
|
+
}
|
|
228
|
+
export interface EvidenceLinkInput {
|
|
229
|
+
url: string;
|
|
230
|
+
title?: string;
|
|
231
|
+
kind?: string;
|
|
232
|
+
occurredAt?: string;
|
|
233
|
+
}
|
|
234
|
+
export interface EarnedValueResult {
|
|
235
|
+
currency: string;
|
|
236
|
+
statusDate: string;
|
|
237
|
+
baseline: number | null;
|
|
238
|
+
actualsFrom: 'timesheets' | 'progress';
|
|
239
|
+
plannedCostCents: number | null;
|
|
240
|
+
actualCostCents: number | null;
|
|
241
|
+
budgetCents: number | null;
|
|
242
|
+
earnedValue: {
|
|
243
|
+
budgetAtCompletionCents: number | null;
|
|
244
|
+
plannedValueCents: number | null;
|
|
245
|
+
earnedValueCents: number | null;
|
|
246
|
+
actualCostCents: number | null;
|
|
247
|
+
scheduleVarianceCents: number | null;
|
|
248
|
+
costVarianceCents: number | null;
|
|
249
|
+
spi: number | null;
|
|
250
|
+
cpi: number | null;
|
|
251
|
+
tcpi: number | null;
|
|
252
|
+
estimateAtCompletionCents: {
|
|
253
|
+
cpi: number | null;
|
|
254
|
+
budgetRate: number | null;
|
|
255
|
+
cpiSpi: number | null;
|
|
256
|
+
};
|
|
257
|
+
estimateToCompleteCents: number | null;
|
|
258
|
+
varianceAtCompletionCents: number | null;
|
|
259
|
+
};
|
|
260
|
+
}
|
|
261
|
+
export interface RaidEntry {
|
|
262
|
+
id: string;
|
|
263
|
+
number: number;
|
|
264
|
+
type: 'risk' | 'assumption' | 'issue' | 'decision' | 'dependency';
|
|
265
|
+
title: string;
|
|
266
|
+
description: string;
|
|
267
|
+
status: 'open' | 'monitoring' | 'closed';
|
|
268
|
+
probability: number | null;
|
|
269
|
+
impact: number | null;
|
|
270
|
+
score: number | null;
|
|
271
|
+
response: string;
|
|
272
|
+
dueOn: string | null;
|
|
273
|
+
item: string | null;
|
|
274
|
+
}
|
|
275
|
+
export interface RaidQuery {
|
|
276
|
+
kind?: string;
|
|
277
|
+
status?: string;
|
|
278
|
+
limit?: number;
|
|
279
|
+
}
|
|
280
|
+
export interface RaidInput {
|
|
281
|
+
kind: 'risk' | 'assumption' | 'issue' | 'decision' | 'dependency';
|
|
282
|
+
title: string;
|
|
283
|
+
description?: string;
|
|
284
|
+
status?: 'open' | 'monitoring' | 'closed';
|
|
285
|
+
probability?: number;
|
|
286
|
+
impact?: number;
|
|
287
|
+
response?: string;
|
|
288
|
+
dueOn?: string;
|
|
289
|
+
}
|
|
290
|
+
export interface ScheduleForecast {
|
|
291
|
+
mode: 'schedule';
|
|
292
|
+
uncertainty: string;
|
|
293
|
+
iterations: number;
|
|
294
|
+
project: {
|
|
295
|
+
plan: string | null;
|
|
296
|
+
target: string | null;
|
|
297
|
+
p50: string | null;
|
|
298
|
+
p80: string | null;
|
|
299
|
+
p95: string | null;
|
|
300
|
+
chance: number | null;
|
|
301
|
+
};
|
|
302
|
+
milestones: {
|
|
303
|
+
ref: string;
|
|
304
|
+
title: string;
|
|
305
|
+
plan: string | null;
|
|
306
|
+
deadline: string | null;
|
|
307
|
+
p50: string | null;
|
|
308
|
+
p80: string | null;
|
|
309
|
+
p95: string | null;
|
|
310
|
+
chance: number | null;
|
|
311
|
+
}[];
|
|
312
|
+
critical: {
|
|
313
|
+
ref: string;
|
|
314
|
+
title: string;
|
|
315
|
+
index: number;
|
|
316
|
+
}[];
|
|
317
|
+
}
|
|
318
|
+
export interface ThroughputForecast {
|
|
319
|
+
mode: 'throughput';
|
|
320
|
+
iterations: number;
|
|
321
|
+
available: boolean;
|
|
322
|
+
backlog: number;
|
|
323
|
+
weeksOfHistory: number;
|
|
324
|
+
p50: string | null;
|
|
325
|
+
p80: string | null;
|
|
326
|
+
p95: string | null;
|
|
327
|
+
weeks: {
|
|
328
|
+
p50: number;
|
|
329
|
+
p80: number;
|
|
330
|
+
p95: number;
|
|
331
|
+
} | null;
|
|
332
|
+
chance: number | null;
|
|
333
|
+
capped: boolean;
|
|
334
|
+
}
|
|
335
|
+
export type ForecastResult = ScheduleForecast | ThroughputForecast;
|
|
336
|
+
export interface WhatIfResult {
|
|
337
|
+
explanation: string;
|
|
338
|
+
changes: string[];
|
|
339
|
+
left_out: string[];
|
|
340
|
+
comparison: {
|
|
341
|
+
projectFinish: {
|
|
342
|
+
now: string | null;
|
|
343
|
+
scenario: string | null;
|
|
344
|
+
deltaWorkingDays: number | null;
|
|
345
|
+
};
|
|
346
|
+
milestones: {
|
|
347
|
+
ref: string;
|
|
348
|
+
title: string;
|
|
349
|
+
now: string | null;
|
|
350
|
+
scenario: string | null;
|
|
351
|
+
deltaWorkingDays: number | null;
|
|
352
|
+
}[];
|
|
353
|
+
moved: number;
|
|
354
|
+
criticalBecame: number;
|
|
355
|
+
criticalLeft: number;
|
|
356
|
+
warnings: number;
|
|
357
|
+
} | null;
|
|
358
|
+
errors: string[];
|
|
359
|
+
}
|
|
360
|
+
export interface AutomationSummary {
|
|
361
|
+
id: string;
|
|
362
|
+
name: string;
|
|
363
|
+
enabled: boolean;
|
|
364
|
+
summary: string;
|
|
365
|
+
runCount: number;
|
|
366
|
+
lastRunAt: string | null;
|
|
367
|
+
lastStatus: string | null;
|
|
368
|
+
}
|
|
369
|
+
export interface TemplateSummary {
|
|
370
|
+
id: string;
|
|
371
|
+
kind: 'project' | 'item';
|
|
372
|
+
name: string;
|
|
373
|
+
description: string;
|
|
374
|
+
itemCount: number;
|
|
375
|
+
}
|
|
376
|
+
export interface ApprovalSummary {
|
|
377
|
+
id: string;
|
|
378
|
+
kind: 'scope' | 'baseline';
|
|
379
|
+
title: string;
|
|
380
|
+
note: string;
|
|
381
|
+
summary: string[];
|
|
382
|
+
status: 'pending' | 'approved' | 'rejected' | 'withdrawn' | 'failed';
|
|
383
|
+
requestedBy: string | null;
|
|
384
|
+
decidedBy: string | null;
|
|
385
|
+
decidedAt: string | null;
|
|
386
|
+
decisionNote: string | null;
|
|
387
|
+
createdAt: string;
|
|
388
|
+
}
|
|
389
|
+
export interface RequestChangeInput {
|
|
390
|
+
item: string;
|
|
391
|
+
title: string;
|
|
392
|
+
note?: string;
|
|
393
|
+
changes: Record<string, unknown>;
|
|
394
|
+
}
|
|
395
|
+
export interface PortfolioProject {
|
|
396
|
+
id: string;
|
|
397
|
+
key: string;
|
|
398
|
+
name: string;
|
|
399
|
+
status: string;
|
|
400
|
+
programId: string | null;
|
|
401
|
+
percentComplete: number | null;
|
|
402
|
+
projectStart: string | null;
|
|
403
|
+
scheduledFinish: string | null;
|
|
404
|
+
targetFinish: string | null;
|
|
405
|
+
openRisks: number;
|
|
406
|
+
nextMilestone: {
|
|
407
|
+
ref: string;
|
|
408
|
+
title: string;
|
|
409
|
+
finish: string;
|
|
410
|
+
} | null;
|
|
411
|
+
health: {
|
|
412
|
+
verdict: 'green' | 'amber' | 'red';
|
|
413
|
+
overridden: boolean;
|
|
414
|
+
comment: string | null;
|
|
415
|
+
schedule: 'green' | 'amber' | 'red';
|
|
416
|
+
scope: 'green' | 'amber' | 'red' | null;
|
|
417
|
+
delivery: 'green' | 'amber' | 'red' | null;
|
|
418
|
+
computedOn: string;
|
|
419
|
+
slipWorkingDays: number | null;
|
|
420
|
+
overdueItems: number | null;
|
|
421
|
+
openItems: number | null;
|
|
422
|
+
} | null;
|
|
423
|
+
}
|
|
424
|
+
export interface PortfolioResult {
|
|
425
|
+
organizationId: string;
|
|
426
|
+
projects: PortfolioProject[];
|
|
427
|
+
programs: {
|
|
428
|
+
id: string;
|
|
429
|
+
name: string;
|
|
430
|
+
}[];
|
|
431
|
+
dependencies: {
|
|
432
|
+
from: string;
|
|
433
|
+
to: string;
|
|
434
|
+
count: number;
|
|
435
|
+
}[];
|
|
436
|
+
}
|
|
139
437
|
export declare class FlowRelayAPI {
|
|
140
438
|
private baseUrl;
|
|
141
439
|
private apiKey;
|
|
@@ -169,7 +467,7 @@ export declare class FlowRelayAPI {
|
|
|
169
467
|
answer: string;
|
|
170
468
|
citations: string[];
|
|
171
469
|
}>;
|
|
172
|
-
generateInsight(projectId: string, kind: 'correlation' | 'onboarding' | 'architecture' | 'release_notes', body?: Record<string, unknown>): Promise<GenerateInsightResponse>;
|
|
470
|
+
generateInsight(projectId: string, kind: 'correlation' | 'onboarding' | 'architecture' | 'release_notes' | 'plan_review', body?: Record<string, unknown>): Promise<GenerateInsightResponse>;
|
|
173
471
|
listDigests(projectId: string, limit?: number): Promise<{
|
|
174
472
|
digests: Array<{
|
|
175
473
|
id: string;
|
|
@@ -224,4 +522,73 @@ export declare class FlowRelayAPI {
|
|
|
224
522
|
message_id: string;
|
|
225
523
|
}>;
|
|
226
524
|
listUntrackedResources(): Promise<UntrackedResource[]>;
|
|
525
|
+
listWorkItems(projectId: string, opts?: {
|
|
526
|
+
status?: string[];
|
|
527
|
+
assignee?: 'me';
|
|
528
|
+
limit?: number;
|
|
529
|
+
cursor?: number;
|
|
530
|
+
}): Promise<{
|
|
531
|
+
timezone: string;
|
|
532
|
+
items: WorkItemSummary[];
|
|
533
|
+
nextCursor: number | null;
|
|
534
|
+
}>;
|
|
535
|
+
getWorkItem(projectId: string, ref: string): Promise<{
|
|
536
|
+
timezone: string;
|
|
537
|
+
item: WorkItemDetail;
|
|
538
|
+
}>;
|
|
539
|
+
createWorkItem(projectId: string, input: WorkItemInput): Promise<{
|
|
540
|
+
item: WorkItemDetail;
|
|
541
|
+
}>;
|
|
542
|
+
updateWorkItem(projectId: string, ref: string, input: WorkItemInput): Promise<{
|
|
543
|
+
item: WorkItemDetail;
|
|
544
|
+
}>;
|
|
545
|
+
listMyWork(): Promise<{
|
|
546
|
+
items: MyWorkEntry[];
|
|
547
|
+
}>;
|
|
548
|
+
listSuggestions(projectId: string): Promise<{
|
|
549
|
+
suggestions: WorkSuggestion[];
|
|
550
|
+
}>;
|
|
551
|
+
linkEvidence(projectId: string, ref: string, input: EvidenceLinkInput): Promise<{
|
|
552
|
+
linked: boolean;
|
|
553
|
+
url: string;
|
|
554
|
+
}>;
|
|
555
|
+
getEarnedValue(projectId: string, baseline?: number): Promise<EarnedValueResult>;
|
|
556
|
+
listRaid(projectId: string, query?: RaidQuery): Promise<{
|
|
557
|
+
entries: RaidEntry[];
|
|
558
|
+
}>;
|
|
559
|
+
getPortfolio(organizationId: string): Promise<PortfolioResult>;
|
|
560
|
+
getForecast(projectId: string, query?: {
|
|
561
|
+
mode?: string;
|
|
562
|
+
uncertainty?: string;
|
|
563
|
+
}): Promise<ForecastResult>;
|
|
564
|
+
planWhatIf(projectId: string, question: string): Promise<WhatIfResult>;
|
|
565
|
+
listAutomations(projectId: string): Promise<{
|
|
566
|
+
automations: AutomationSummary[];
|
|
567
|
+
}>;
|
|
568
|
+
listTemplates(projectId: string): Promise<{
|
|
569
|
+
templates: TemplateSummary[];
|
|
570
|
+
}>;
|
|
571
|
+
applyTemplate(projectId: string, templateId: string, parent?: string): Promise<{
|
|
572
|
+
created: number;
|
|
573
|
+
version: number;
|
|
574
|
+
}>;
|
|
575
|
+
listApprovals(projectId: string, pendingOnly: boolean): Promise<{
|
|
576
|
+
approvals: ApprovalSummary[];
|
|
577
|
+
}>;
|
|
578
|
+
requestChange(projectId: string, input: RequestChangeInput): Promise<{
|
|
579
|
+
id: string;
|
|
580
|
+
status: string;
|
|
581
|
+
}>;
|
|
582
|
+
resolveSuggestion(projectId: string, suggestionId: string, action: 'accept' | 'dismiss'): Promise<{
|
|
583
|
+
status?: string;
|
|
584
|
+
}>;
|
|
585
|
+
createRaidEntry(projectId: string, input: RaidInput): Promise<{
|
|
586
|
+
id: string;
|
|
587
|
+
number: number;
|
|
588
|
+
}>;
|
|
589
|
+
deleteWorkItem(projectId: string, ref: string): Promise<void>;
|
|
590
|
+
decideApproval(projectId: string, approvalId: string, decision: 'approve' | 'reject' | 'withdraw', note?: string): Promise<{
|
|
591
|
+
status: string;
|
|
592
|
+
batchId?: string;
|
|
593
|
+
}>;
|
|
227
594
|
}
|
package/dist/api.js
CHANGED
|
@@ -134,4 +134,122 @@ export class FlowRelayAPI {
|
|
|
134
134
|
async listUntrackedResources() {
|
|
135
135
|
return this.request('/integrations/untracked');
|
|
136
136
|
}
|
|
137
|
+
async listWorkItems(projectId, opts = {}) {
|
|
138
|
+
const params = new URLSearchParams();
|
|
139
|
+
if (opts.status?.length)
|
|
140
|
+
params.set('status', opts.status.join(','));
|
|
141
|
+
if (opts.assignee)
|
|
142
|
+
params.set('assignee', opts.assignee);
|
|
143
|
+
if (opts.limit)
|
|
144
|
+
params.set('limit', String(opts.limit));
|
|
145
|
+
if (opts.cursor !== undefined)
|
|
146
|
+
params.set('cursor', String(opts.cursor));
|
|
147
|
+
const suffix = params.toString();
|
|
148
|
+
return this.request(`/projects/${projectId}/work-items${suffix ? `?${suffix}` : ''}`);
|
|
149
|
+
}
|
|
150
|
+
async getWorkItem(projectId, ref) {
|
|
151
|
+
return this.request(`/projects/${projectId}/work-items/${encodeURIComponent(ref)}`);
|
|
152
|
+
}
|
|
153
|
+
async createWorkItem(projectId, input) {
|
|
154
|
+
return this.request(`/projects/${projectId}/work-items`, {
|
|
155
|
+
method: 'POST',
|
|
156
|
+
body: JSON.stringify(input),
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
async updateWorkItem(projectId, ref, input) {
|
|
160
|
+
return this.request(`/projects/${projectId}/work-items/${encodeURIComponent(ref)}`, {
|
|
161
|
+
method: 'PATCH',
|
|
162
|
+
body: JSON.stringify(input),
|
|
163
|
+
});
|
|
164
|
+
}
|
|
165
|
+
async listMyWork() {
|
|
166
|
+
return this.request('/my-work');
|
|
167
|
+
}
|
|
168
|
+
async listSuggestions(projectId) {
|
|
169
|
+
return this.request(`/projects/${projectId}/suggestions`);
|
|
170
|
+
}
|
|
171
|
+
async linkEvidence(projectId, ref, input) {
|
|
172
|
+
return this.request(`/projects/${projectId}/work-items/${encodeURIComponent(ref)}/evidence`, {
|
|
173
|
+
method: 'POST',
|
|
174
|
+
body: JSON.stringify(input),
|
|
175
|
+
});
|
|
176
|
+
}
|
|
177
|
+
async getEarnedValue(projectId, baseline) {
|
|
178
|
+
const params = new URLSearchParams();
|
|
179
|
+
if (baseline !== undefined)
|
|
180
|
+
params.set('baseline', String(baseline));
|
|
181
|
+
const qs = params.toString();
|
|
182
|
+
return this.request(`/projects/${projectId}/evm${qs ? `?${qs}` : ''}`);
|
|
183
|
+
}
|
|
184
|
+
async listRaid(projectId, query = {}) {
|
|
185
|
+
const params = new URLSearchParams();
|
|
186
|
+
if (query.kind)
|
|
187
|
+
params.set('kind', query.kind);
|
|
188
|
+
if (query.status)
|
|
189
|
+
params.set('status', query.status);
|
|
190
|
+
if (query.limit)
|
|
191
|
+
params.set('limit', String(query.limit));
|
|
192
|
+
const qs = params.toString();
|
|
193
|
+
return this.request(`/projects/${projectId}/raid${qs ? `?${qs}` : ''}`);
|
|
194
|
+
}
|
|
195
|
+
async getPortfolio(organizationId) {
|
|
196
|
+
return this.request(`/portfolio?organization_id=${encodeURIComponent(organizationId)}`);
|
|
197
|
+
}
|
|
198
|
+
async getForecast(projectId, query = {}) {
|
|
199
|
+
const params = new URLSearchParams();
|
|
200
|
+
if (query.mode)
|
|
201
|
+
params.set('mode', query.mode);
|
|
202
|
+
if (query.uncertainty)
|
|
203
|
+
params.set('uncertainty', query.uncertainty);
|
|
204
|
+
const qs = params.toString();
|
|
205
|
+
return this.request(`/projects/${projectId}/forecast${qs ? `?${qs}` : ''}`);
|
|
206
|
+
}
|
|
207
|
+
async planWhatIf(projectId, question) {
|
|
208
|
+
return this.request(`/projects/${projectId}/whatif`, {
|
|
209
|
+
method: 'POST',
|
|
210
|
+
body: JSON.stringify({ question }),
|
|
211
|
+
});
|
|
212
|
+
}
|
|
213
|
+
async listAutomations(projectId) {
|
|
214
|
+
return this.request(`/projects/${projectId}/automations`);
|
|
215
|
+
}
|
|
216
|
+
async listTemplates(projectId) {
|
|
217
|
+
return this.request(`/projects/${projectId}/templates`);
|
|
218
|
+
}
|
|
219
|
+
async applyTemplate(projectId, templateId, parent) {
|
|
220
|
+
return this.request(`/projects/${projectId}/templates/${encodeURIComponent(templateId)}/apply`, {
|
|
221
|
+
method: 'POST',
|
|
222
|
+
body: JSON.stringify(parent ? { parent } : {}),
|
|
223
|
+
});
|
|
224
|
+
}
|
|
225
|
+
async listApprovals(projectId, pendingOnly) {
|
|
226
|
+
return this.request(`/projects/${projectId}/approvals${pendingOnly ? '?status=pending' : ''}`);
|
|
227
|
+
}
|
|
228
|
+
async requestChange(projectId, input) {
|
|
229
|
+
return this.request(`/projects/${projectId}/approvals`, {
|
|
230
|
+
method: 'POST',
|
|
231
|
+
body: JSON.stringify(input),
|
|
232
|
+
});
|
|
233
|
+
}
|
|
234
|
+
async resolveSuggestion(projectId, suggestionId, action) {
|
|
235
|
+
return this.request(`/projects/${projectId}/suggestions/${encodeURIComponent(suggestionId)}`, {
|
|
236
|
+
method: 'POST',
|
|
237
|
+
body: JSON.stringify({ action }),
|
|
238
|
+
});
|
|
239
|
+
}
|
|
240
|
+
async createRaidEntry(projectId, input) {
|
|
241
|
+
return this.request(`/projects/${projectId}/raid`, {
|
|
242
|
+
method: 'POST',
|
|
243
|
+
body: JSON.stringify(input),
|
|
244
|
+
});
|
|
245
|
+
}
|
|
246
|
+
async deleteWorkItem(projectId, ref) {
|
|
247
|
+
await this.request(`/projects/${projectId}/work-items/${encodeURIComponent(ref)}`, { method: 'DELETE' });
|
|
248
|
+
}
|
|
249
|
+
async decideApproval(projectId, approvalId, decision, note) {
|
|
250
|
+
return this.request(`/projects/${projectId}/approvals/${encodeURIComponent(approvalId)}`, {
|
|
251
|
+
method: 'PATCH',
|
|
252
|
+
body: JSON.stringify(note ? { decision, note } : { decision }),
|
|
253
|
+
});
|
|
254
|
+
}
|
|
137
255
|
}
|
package/dist/server.js
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
* Copyright (c) 2026 Adriano Sorbello (atrisorb) <https://github.com/atrisorb>
|
|
5
5
|
* Licensed under GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
|
|
6
6
|
*/
|
|
7
|
-
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
7
|
+
import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
8
8
|
import { z } from 'zod';
|
|
9
9
|
import { createRequire } from 'node:module';
|
|
10
10
|
export const PKG_VERSION = createRequire(import.meta.url)('../package.json').version;
|
|
@@ -76,6 +76,8 @@ const FiltersSchema = z.record(z.string(), SourceFilterSchema)
|
|
|
76
76
|
const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
|
|
77
77
|
const MUTATING = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
|
|
78
78
|
const SESSION_STATE = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
|
|
79
|
+
const WRITE_IDEMPOTENT = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true };
|
|
80
|
+
const DESTRUCTIVE = { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true };
|
|
79
81
|
export function normalizeProjectId(value) {
|
|
80
82
|
if (typeof value !== 'string')
|
|
81
83
|
return null;
|
|
@@ -95,6 +97,148 @@ function formatProjectScope(project) {
|
|
|
95
97
|
: 'owner';
|
|
96
98
|
return `Org project: ${project.name} (${project.organization_name ?? 'Unknown org'}, ${role})`;
|
|
97
99
|
}
|
|
100
|
+
function workItemLine(item) {
|
|
101
|
+
const facts = [`${item.percentComplete}%`];
|
|
102
|
+
if (item.finish)
|
|
103
|
+
facts.push(`finish ${item.finish}`);
|
|
104
|
+
if (item.deadline)
|
|
105
|
+
facts.push(`deadline ${item.deadline}`);
|
|
106
|
+
if ('assignees' in item && item.assignees.length > 0)
|
|
107
|
+
facts.push(item.assignees.map((a) => a.name).join(', '));
|
|
108
|
+
return `- ${item.key} [${item.status}${item.blocked ? ', blocked' : ''}] ${item.title} (${facts.join(', ')})`;
|
|
109
|
+
}
|
|
110
|
+
function workItemDetail(item, timezone) {
|
|
111
|
+
const links = (list) => list.map((l) => `${l.key ?? 'unknown'} (${l.type.toUpperCase()})`).join(', ');
|
|
112
|
+
const deadline = item.deadline ? ` · **Deadline:** ${item.deadline}` : '';
|
|
113
|
+
const lines = [
|
|
114
|
+
`# ${item.key} ${item.title}`,
|
|
115
|
+
`**Status:** ${item.status}${item.blocked ? ' (blocked)' : ''} · **Progress:** ${item.percentComplete}% · **Kind:** ${item.kind}`,
|
|
116
|
+
`**Start:** ${item.start ?? 'not scheduled'} · **Finish:** ${item.finish ?? 'not scheduled'}${deadline} (${timezone})`,
|
|
117
|
+
`**Assignees:** ${item.assignees.map((a) => a.name).join(', ') || 'none'}`,
|
|
118
|
+
];
|
|
119
|
+
if (item.predecessors.length > 0)
|
|
120
|
+
lines.push(`**Predecessors:** ${links(item.predecessors)}`);
|
|
121
|
+
if (item.successors.length > 0)
|
|
122
|
+
lines.push(`**Successors:** ${links(item.successors)}`);
|
|
123
|
+
lines.push(`**Comments:** ${item.commentCount} · **Link:** ${item.url}`);
|
|
124
|
+
if (item.description)
|
|
125
|
+
lines.push('', item.description);
|
|
126
|
+
if (item.evidence.length > 0) {
|
|
127
|
+
lines.push('', '## Evidence', ...item.evidence.map((e) => `- [${e.source}/${e.kind}] ${e.title ?? 'Untitled'} (${e.occurredAt.slice(0, 10)})${e.url ? ` ${e.url}` : ''}`));
|
|
128
|
+
}
|
|
129
|
+
return lines.join('\n');
|
|
130
|
+
}
|
|
131
|
+
function suggestionLine(s) {
|
|
132
|
+
const text = (value, fallback) => (typeof value === 'string' && value.length > 0 ? value : fallback);
|
|
133
|
+
const p = s.payload;
|
|
134
|
+
const summary = {
|
|
135
|
+
status_change: () => `${s.item ?? 'An item'}: move to ${text(p.to, 'a new status')}`,
|
|
136
|
+
create_item: () => `New item: ${text(p.title, 'Untitled')}`,
|
|
137
|
+
dependency: () => `${text(p.predecessor, 'An item')} should finish before ${text(p.successor, 'another item')} starts`,
|
|
138
|
+
evidence: () => `${s.item ?? 'An item'}: "${text(p.title, 'Untitled')}" from ${text(p.source, 'activity')} as evidence`,
|
|
139
|
+
}[s.type]();
|
|
140
|
+
const reason = typeof p.reason === 'string' && p.reason.length > 0 ? ` – ${p.reason}` : '';
|
|
141
|
+
return `- ${summary}${reason} (id ${s.id}${s.forYou ? ', for you' : ''})`;
|
|
142
|
+
}
|
|
143
|
+
function moneyText(cents, currency) {
|
|
144
|
+
return cents === null ? 'n/a' : new Intl.NumberFormat('en', { style: 'currency', currency }).format(cents / 100);
|
|
145
|
+
}
|
|
146
|
+
function earnedValueText(name, r) {
|
|
147
|
+
const e = r.earnedValue;
|
|
148
|
+
const m = (v) => moneyText(v, r.currency);
|
|
149
|
+
const index = (v) => (v === null ? 'n/a' : v.toFixed(2));
|
|
150
|
+
return [
|
|
151
|
+
`Earned value of ${name} as of ${r.statusDate}${r.baseline === null ? ' (no baseline with costs yet)' : ` against baseline ${r.baseline}`}. Actual cost comes from ${r.actualsFrom === 'timesheets' ? 'logged hours' : 'progress'}.`,
|
|
152
|
+
`Planned cost ${m(r.plannedCostCents)}, actual cost ${m(r.actualCostCents)}${r.budgetCents === null ? '' : `, budget ${m(r.budgetCents)}`}.`,
|
|
153
|
+
`Budget at completion ${m(e.budgetAtCompletionCents)}, planned value ${m(e.plannedValueCents)}, earned value ${m(e.earnedValueCents)}.`,
|
|
154
|
+
`Schedule variance ${m(e.scheduleVarianceCents)}, cost variance ${m(e.costVarianceCents)}, SPI ${index(e.spi)}, CPI ${index(e.cpi)}, TCPI ${index(e.tcpi)}.`,
|
|
155
|
+
`Estimate at completion: ${m(e.estimateAtCompletionCents.cpi)} at the current cost efficiency, ${m(e.estimateAtCompletionCents.budgetRate)} at the budgeted rate, ${m(e.estimateAtCompletionCents.cpiSpi)} at cost and schedule efficiency. Estimate to complete ${m(e.estimateToCompleteCents)}, variance at completion ${m(e.varianceAtCompletionCents)}.`,
|
|
156
|
+
].join('\n');
|
|
157
|
+
}
|
|
158
|
+
function forecastText(name, f) {
|
|
159
|
+
const date = (v) => (v ? v.slice(0, 10) : 'n/a');
|
|
160
|
+
const pct = (v) => (v === null ? 'n/a' : `${Math.round(v * 100)}%`);
|
|
161
|
+
if (f.mode === 'throughput') {
|
|
162
|
+
if (!f.available)
|
|
163
|
+
return `No throughput forecast for ${name}: it needs at least 4 weeks of history with something finished (${f.weeksOfHistory} so far, ${f.backlog} open items).`;
|
|
164
|
+
return [
|
|
165
|
+
`Throughput forecast of ${name}: ${f.backlog} open items at the pace of the last ${f.weeksOfHistory} weeks (${f.iterations} simulated runs).`,
|
|
166
|
+
`Done by ${date(f.p50)} (${f.weeks.p50} weeks) in half of the runs, by ${date(f.p80)} (${f.weeks.p80} weeks) in four out of five and by ${date(f.p95)} (${f.weeks.p95} weeks) in nineteen out of twenty${f.chance === null ? '' : `; chance of the target finish ${pct(f.chance)}`}.`,
|
|
167
|
+
...(f.capped ? ['Some runs did not finish within ten years: the pace is too low for the backlog.'] : []),
|
|
168
|
+
].join('\n');
|
|
169
|
+
}
|
|
170
|
+
return [
|
|
171
|
+
`Forecast of ${name}: ${f.iterations} simulated runs with ${f.uncertainty} uncertainty on the durations.`,
|
|
172
|
+
`The plan says ${date(f.project.plan)}. The project is done by ${date(f.project.p50)} in half of the runs, by ${date(f.project.p80)} in four out of five and by ${date(f.project.p95)} in nineteen out of twenty${f.project.target ? `; chance of the target finish ${date(f.project.target)}: ${pct(f.project.chance)}` : ''}.`,
|
|
173
|
+
...(f.milestones.length > 0 ? ['Milestones (plan, likely by, chance on its date):', ...f.milestones.map((m) => `- ${m.ref} ${m.title}: plan ${date(m.plan)}, likely by ${date(m.p80)}, ${pct(m.chance)} chance${m.deadline ? ` of the deadline ${date(m.deadline)}` : ''}`)] : []),
|
|
174
|
+
...(f.critical.length > 0 ? ['Most often on the critical path:', ...f.critical.map((c) => `- ${c.ref} ${c.title}: ${Math.round(c.index * 100)}% of runs`)] : []),
|
|
175
|
+
].join('\n');
|
|
176
|
+
}
|
|
177
|
+
function whatIfText(r) {
|
|
178
|
+
const date = (v) => (v ? v.slice(0, 10) : 'n/a');
|
|
179
|
+
const lines = [r.explanation || 'What-if result.'];
|
|
180
|
+
if (r.changes.length === 0)
|
|
181
|
+
lines.push('No change in the plan could express this question, so nothing was compared.');
|
|
182
|
+
else
|
|
183
|
+
lines.push('Changes tried:', ...r.changes.map((c) => `- ${c}`));
|
|
184
|
+
if (r.left_out.length > 0)
|
|
185
|
+
lines.push(`Left out: ${r.left_out.join('; ')}.`);
|
|
186
|
+
if (r.comparison) {
|
|
187
|
+
const c = r.comparison;
|
|
188
|
+
const d = c.projectFinish.deltaWorkingDays;
|
|
189
|
+
lines.push(`The project would finish ${date(c.projectFinish.scenario)} instead of ${date(c.projectFinish.now)} (${d === null ? 'n/a' : d === 0 ? 'no change' : `${d > 0 ? '+' : ''}${d} working days`}); ${c.moved} items move, ${c.criticalBecame} become critical and ${c.criticalLeft} stop being critical.`);
|
|
190
|
+
lines.push(...c.milestones.map((m) => `- ${m.ref} ${m.title}: ${date(m.now)} to ${date(m.scenario)}${m.deltaWorkingDays === null || m.deltaWorkingDays === 0 ? '' : ` (${m.deltaWorkingDays > 0 ? '+' : ''}${m.deltaWorkingDays} working days)`}`));
|
|
191
|
+
}
|
|
192
|
+
if (r.errors.length > 0)
|
|
193
|
+
lines.push(`Could not compare: ${r.errors.join('; ')}.`);
|
|
194
|
+
lines.push('Nothing was saved or changed in the plan.');
|
|
195
|
+
return lines.join('\n');
|
|
196
|
+
}
|
|
197
|
+
function portfolioText(r) {
|
|
198
|
+
if (r.projects.length === 0)
|
|
199
|
+
return 'No project in this portfolio that you can open.';
|
|
200
|
+
const programs = new Map(r.programs.map((p) => [p.id, p.name]));
|
|
201
|
+
const names = new Map(r.projects.map((p) => [p.id, p.name]));
|
|
202
|
+
const verdict = { green: 'on track', amber: 'at risk', red: 'off track' };
|
|
203
|
+
const lines = r.projects.map((p) => {
|
|
204
|
+
const h = p.health;
|
|
205
|
+
const slip = h?.slipWorkingDays ?? null;
|
|
206
|
+
const parts = [
|
|
207
|
+
h ? `${verdict[h.verdict]}${h.overridden ? ' (set by hand)' : ''}` : 'health not computed yet',
|
|
208
|
+
p.percentComplete === null ? null : `${Math.round(p.percentComplete)}% complete`,
|
|
209
|
+
p.scheduledFinish ? `forecast finish ${p.scheduledFinish.slice(0, 10)}` : null,
|
|
210
|
+
p.targetFinish ? `target ${p.targetFinish.slice(0, 10)}` : null,
|
|
211
|
+
slip === null ? null : slip > 0 ? `${slip} working days late` : slip < 0 ? `${-slip} working days ahead` : 'on schedule',
|
|
212
|
+
h?.overdueItems ? `${h.overdueItems} overdue items` : null,
|
|
213
|
+
p.openRisks > 0 ? `${p.openRisks} open risks` : null,
|
|
214
|
+
p.nextMilestone ? `next milestone ${p.nextMilestone.ref} ${p.nextMilestone.title} on ${p.nextMilestone.finish.slice(0, 10)}` : null,
|
|
215
|
+
p.programId ? `program ${programs.get(p.programId) ?? 'unknown'}` : null,
|
|
216
|
+
].filter((part) => part !== null);
|
|
217
|
+
return `- ${p.key} ${p.name}: ${parts.join(', ')}${h?.comment ? ` – ${h.comment}` : ''}`;
|
|
218
|
+
});
|
|
219
|
+
const waits = r.dependencies.map((d) => `- ${names.get(d.to) ?? 'A project'} waits for ${names.get(d.from) ?? 'another project'} (${d.count} ${d.count === 1 ? 'link' : 'links'})`);
|
|
220
|
+
return [`Portfolio, ${r.projects.length} ${r.projects.length === 1 ? 'project' : 'projects'}:`, ...lines, ...(waits.length > 0 ? ['', 'Dependencies between projects:', ...waits] : [])].join('\n');
|
|
221
|
+
}
|
|
222
|
+
function automationLine(a) {
|
|
223
|
+
const ran = a.runCount === 0 ? 'not run yet' : `ran ${a.runCount} time${a.runCount === 1 ? '' : 's'}, last ${a.lastStatus ?? 'ok'}`;
|
|
224
|
+
return `- ${a.name} [${a.enabled ? 'on' : 'off'}, ${ran}]: ${a.summary}`;
|
|
225
|
+
}
|
|
226
|
+
function templateLine(t) {
|
|
227
|
+
return `- ${t.name} (${t.kind === 'project' ? 'whole plan' : 'one item with its subtasks'}, ${t.itemCount} item${t.itemCount === 1 ? '' : 's'}) id ${t.id}${t.description ? ` – ${t.description}` : ''}`;
|
|
228
|
+
}
|
|
229
|
+
function approvalLine(a) {
|
|
230
|
+
const state = a.status === 'pending' ? 'waiting for a decision' : a.status === 'failed' ? 'approved but not applied' : a.status;
|
|
231
|
+
const by = a.requestedBy ? `, asked by ${a.requestedBy}` : '';
|
|
232
|
+
const said = a.decidedBy ? `, ${a.decidedBy}${a.decisionNote ? ` said: ${a.decisionNote}` : ''}` : '';
|
|
233
|
+
return `- ${a.title} [${a.kind === 'scope' ? 'plan change' : 'baseline'}, ${state}${by}${said}]: ${a.summary.join('; ')}`;
|
|
234
|
+
}
|
|
235
|
+
function raidLine(e) {
|
|
236
|
+
const score = e.score === null ? '' : `, score ${e.score} (probability ${e.probability} x impact ${e.impact})`;
|
|
237
|
+
const due = e.dueOn ? `, due ${e.dueOn}` : '';
|
|
238
|
+
const item = e.item ? `, on ${e.item}` : '';
|
|
239
|
+
const response = e.response ? ` – ${e.response}` : '';
|
|
240
|
+
return `- R-${e.number} ${e.type} [${e.status}${score}${due}${item}]: ${e.title}${response}`;
|
|
241
|
+
}
|
|
98
242
|
export function createFlowRelayServer(api, initialProjectId) {
|
|
99
243
|
let activeProjectId = initialProjectId;
|
|
100
244
|
const server = new McpServer({
|
|
@@ -118,6 +262,10 @@ export function createFlowRelayServer(api, initialProjectId) {
|
|
|
118
262
|
'',
|
|
119
263
|
'Cost: every generate_* call consumes credits from the user\'s plan and is charged once on success (architecture is the deepest and most expensive, handoff the cheapest). Do not regenerate an artifact you can retrieve with list_handoffs / list_insights, and confirm intent before generating repeatedly.',
|
|
120
264
|
'',
|
|
265
|
+
'Work items: a project plan holds tasks and milestones addressed by keys such as FR-12. list_my_work shows what is assigned to the caller, list_work_items and get_work_item read a plan, create_work_item and update_work_item change it, list_suggestions shows the changes Flow Relay proposes from linked activity and link_evidence attaches a link to an item, list_raid reads the risk register, get_earned_value reads costs and earned value against a baseline and get_portfolio reads the progress, forecast, risks and health of every project of an organization, get_forecast simulates a plan to say how likely each finish date is and plan_whatif tries a what-if question on a copy of the plan (5 credits). list_automations reads the rules that act on a plan by themselves, list_templates and apply_template add saved structure to a plan, list_approvals reads the change requests of a plan and request_change asks for a change that a second person must approve. resolve_suggestion accepts or dismisses one of those suggestions, create_raid_entry adds an entry to the register, delete_work_item removes an item and everything under it (a project manager can restore it from the change history) and decide_approval approves, rejects or withdraws a change request. Work item tools cost no credits; generate_plan_review writes a status report from the numbers of the plan (5 credits). A commit message, branch name or pull request title that mentions an item key links that work to the item.',
|
|
266
|
+
'',
|
|
267
|
+
'Prompts: handoff_for_branch, onboard_me and weekly_status start the usual flows. The resource flowrelay://projects/{project_id}/handoffs/latest holds the latest handoff of a project as Markdown.',
|
|
268
|
+
'',
|
|
121
269
|
'Scope and access follow the API key\'s tenant role; a tool only ever sees projects the key can access.',
|
|
122
270
|
].join('\n'),
|
|
123
271
|
});
|
|
@@ -181,7 +329,7 @@ export function createFlowRelayServer(api, initialProjectId) {
|
|
|
181
329
|
}
|
|
182
330
|
});
|
|
183
331
|
// ── Tool: list projects ─────────────────────────────────────────────
|
|
184
|
-
server.tool('list_projects', 'List every project the API key can access (personal and organization), each with its id, scope and the caller\'s role. The id returned here is what you pass as project_id to the generate_* and list tools – start here whenever you need one.', {}, READ_ONLY, async () => {
|
|
332
|
+
server.tool('list_projects', 'List every project the API key can access (personal and organization), each with its id, scope, the prefix of its work item keys and the caller\'s role. The id returned here is what you pass as project_id to the generate_* and list tools – start here whenever you need one.', {}, READ_ONLY, async () => {
|
|
185
333
|
try {
|
|
186
334
|
const context = await getTenantContext();
|
|
187
335
|
if (context.projects.length === 0) {
|
|
@@ -197,7 +345,9 @@ export function createFlowRelayServer(api, initialProjectId) {
|
|
|
197
345
|
const scope = project.project_type === 'personal'
|
|
198
346
|
? 'personal'
|
|
199
347
|
: `org:${project.organization_name ?? 'unknown'}`;
|
|
200
|
-
|
|
348
|
+
const key = project.key ? `, keys=${project.key}-n` : '';
|
|
349
|
+
const org = project.organization_id ? `, organization_id=${project.organization_id}` : '';
|
|
350
|
+
return `- ${project.name} (${scope}, role=${project.access_role}${key}${org})\n id: ${project.id}${active}`;
|
|
201
351
|
});
|
|
202
352
|
return {
|
|
203
353
|
content: [{
|
|
@@ -557,7 +707,7 @@ export function createFlowRelayServer(api, initialProjectId) {
|
|
|
557
707
|
});
|
|
558
708
|
server.tool('list_insights', 'List existing insights for a project (newest first) with their content. Use this to read what has already been generated before spending credits on a new generate_*_insight. Each row\'s id can be sent to Discord via discord_send_message.', {
|
|
559
709
|
project_id: z.string().describe('Project id from list_projects to list insights for.'),
|
|
560
|
-
kind: z.enum(['onboarding_brief', 'cross_source_correlation', 'architecture_insight', 'release_notes']).optional().describe('Restrict to one kind. Omit for all kinds.'),
|
|
710
|
+
kind: z.enum(['onboarding_brief', 'cross_source_correlation', 'architecture_insight', 'release_notes', 'plan_review']).optional().describe('Restrict to one kind. Omit for all kinds.'),
|
|
561
711
|
status: z.enum(['active', 'archived', 'all']).default('active').describe('active = current, archived = superseded, all = both.'),
|
|
562
712
|
limit: z.number().int().min(1).max(50).default(20).describe('Max insights to return (1-50, default 20).'),
|
|
563
713
|
}, READ_ONLY, async ({ project_id, kind, status, limit }) => {
|
|
@@ -629,5 +779,434 @@ export function createFlowRelayServer(api, initialProjectId) {
|
|
|
629
779
|
return { content: [{ type: 'text', text: `Could not load filter options: ${err.message}` }] };
|
|
630
780
|
}
|
|
631
781
|
});
|
|
782
|
+
server.tool('list_work_items', 'List the work items (tasks and milestones) of a project plan with key, status, progress, dates and assignees, ordered by item number. Filter by status or to your own assignments. Dates are wall-clock times in the plan time zone. When the reply ends with a cursor, pass it back as cursor to read the next page. Free: no credits.', {
|
|
783
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
784
|
+
status: z.array(z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled'])).optional().describe('Only items in these statuses. Omit for every status.'),
|
|
785
|
+
mine: z.boolean().default(false).describe('Only items assigned to you.'),
|
|
786
|
+
limit: z.number().int().min(1).max(200).default(50).describe('Max items to return (1-200, default 50).'),
|
|
787
|
+
cursor: z.number().int().min(0).optional().describe('The cursor printed at the end of a previous page.'),
|
|
788
|
+
}, READ_ONLY, async ({ project_id, status, mine, limit, cursor }) => {
|
|
789
|
+
try {
|
|
790
|
+
const resolved = await requireProject(project_id);
|
|
791
|
+
const page = await api.listWorkItems(resolved.projectId, { status, assignee: mine ? 'me' : undefined, limit, cursor });
|
|
792
|
+
if (page.items.length === 0) {
|
|
793
|
+
return { content: [{ type: 'text', text: `No work items found in ${resolved.project.name}.` }] };
|
|
794
|
+
}
|
|
795
|
+
const more = page.nextCursor !== null ? `\n\nMore items: call again with cursor=${page.nextCursor}` : '';
|
|
796
|
+
const text = `Work items in ${resolved.project.name} (times in ${page.timezone}):\n${page.items.map(workItemLine).join('\n')}${more}`;
|
|
797
|
+
return { content: [{ type: 'text', text }] };
|
|
798
|
+
}
|
|
799
|
+
catch (err) {
|
|
800
|
+
return { content: [{ type: 'text', text: `Could not list work items: ${err.message}` }] };
|
|
801
|
+
}
|
|
802
|
+
});
|
|
803
|
+
server.tool('get_work_item', 'Read one work item by key (such as FR-12) or id: description, progress, dates, assignees, dependencies, linked evidence (commits, pull requests, deploys, messages) and the comment count. Free: no credits.', {
|
|
804
|
+
ref: z.string().min(1).max(100).describe('Item key such as FR-12, or the item id.'),
|
|
805
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
806
|
+
}, READ_ONLY, async ({ ref, project_id }) => {
|
|
807
|
+
try {
|
|
808
|
+
const resolved = await requireProject(project_id);
|
|
809
|
+
const { timezone, item } = await api.getWorkItem(resolved.projectId, ref);
|
|
810
|
+
return { content: [{ type: 'text', text: workItemDetail(item, timezone) }] };
|
|
811
|
+
}
|
|
812
|
+
catch (err) {
|
|
813
|
+
return { content: [{ type: 'text', text: `Could not read work item: ${err.message}` }] };
|
|
814
|
+
}
|
|
815
|
+
});
|
|
816
|
+
server.tool('list_my_work', 'List the work items assigned to you across every accessible project: open items plus the ones finished in the last 7 days, with status, progress and dates. A good first call for "what should I work on next". Free: no credits.', {}, READ_ONLY, async () => {
|
|
817
|
+
try {
|
|
818
|
+
const { items } = await api.listMyWork();
|
|
819
|
+
if (items.length === 0) {
|
|
820
|
+
return { content: [{ type: 'text', text: 'Nothing is assigned to you right now.' }] };
|
|
821
|
+
}
|
|
822
|
+
const text = `Your work:\n${items.map((item) => `${workItemLine(item)} – ${item.project.name}`).join('\n')}`;
|
|
823
|
+
return { content: [{ type: 'text', text }] };
|
|
824
|
+
}
|
|
825
|
+
catch (err) {
|
|
826
|
+
return { content: [{ type: 'text', text: `Could not list your work: ${err.message}` }] };
|
|
827
|
+
}
|
|
828
|
+
});
|
|
829
|
+
server.tool('create_work_item', 'Create a work item (task or milestone) in a project plan and return it with its key. Dates are wall-clock times in the plan time zone. Contributors can create items when the project allows it and can assign only themselves. Free: no credits. Not idempotent: calling it twice creates two items.', {
|
|
830
|
+
title: z.string().min(1).max(500).describe('Item title, 1-500 characters.'),
|
|
831
|
+
description: z.string().max(50000).optional().describe('Description in plain text or Markdown.'),
|
|
832
|
+
parent: z.string().optional().describe('Key or id of the parent item (such as FR-3) to nest the new item under. Omit for a top-level item.'),
|
|
833
|
+
kind: z.enum(['task', 'milestone']).optional().describe('task (default) or milestone.'),
|
|
834
|
+
status: z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled']).optional().describe('Initial status (default todo).'),
|
|
835
|
+
priority: z.number().int().min(0).max(4).optional().describe('0 lowest, 1 low, 2 medium (default), 3 high, 4 urgent.'),
|
|
836
|
+
duration: z.string().optional().describe('Duration such as "4h", "3d", "2w", "3ed" (elapsed days) or "2d?" (an estimate).'),
|
|
837
|
+
deadline: z.string().optional().describe('Deadline as YYYY-MM-DD or YYYY-MM-DDTHH:mm in the plan time zone.'),
|
|
838
|
+
assign_to_me: z.boolean().default(false).describe('Assign the new item to yourself.'),
|
|
839
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
840
|
+
}, MUTATING, async ({ title, description, parent, kind, status, priority, duration, deadline, assign_to_me, project_id }) => {
|
|
841
|
+
try {
|
|
842
|
+
const resolved = await requireProject(project_id);
|
|
843
|
+
const { item } = await api.createWorkItem(resolved.projectId, {
|
|
844
|
+
title,
|
|
845
|
+
description,
|
|
846
|
+
parent,
|
|
847
|
+
kind,
|
|
848
|
+
status,
|
|
849
|
+
priority,
|
|
850
|
+
duration,
|
|
851
|
+
deadline,
|
|
852
|
+
assignee: assign_to_me ? 'me' : undefined,
|
|
853
|
+
});
|
|
854
|
+
return { content: [{ type: 'text', text: `Created ${item.key}: ${item.title}\n${item.url}` }] };
|
|
855
|
+
}
|
|
856
|
+
catch (err) {
|
|
857
|
+
return { content: [{ type: 'text', text: `Could not create work item: ${err.message}` }] };
|
|
858
|
+
}
|
|
859
|
+
});
|
|
860
|
+
server.tool('update_work_item', 'Update a work item by key or id: status, progress, title, description, priority, the blocked flag, duration or deadline. Sending the same values again leaves the item unchanged. Contributors can update items assigned to them or created by them; changing dates or durations may need a project manager. Free: no credits.', {
|
|
861
|
+
ref: z.string().min(1).max(100).describe('Item key such as FR-12, or the item id.'),
|
|
862
|
+
status: z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled']).optional().describe('New status.'),
|
|
863
|
+
percent_complete: z.number().int().min(0).max(100).optional().describe('Progress 0-100. 100 marks the item done.'),
|
|
864
|
+
title: z.string().min(1).max(500).optional().describe('New title, 1-500 characters.'),
|
|
865
|
+
description: z.string().max(50000).optional().describe('New description in plain text or Markdown.'),
|
|
866
|
+
priority: z.number().int().min(0).max(4).optional().describe('0 lowest, 1 low, 2 medium, 3 high, 4 urgent.'),
|
|
867
|
+
blocked: z.boolean().optional().describe('Flag or unflag the item as blocked. A flag, not a status.'),
|
|
868
|
+
duration: z.string().optional().describe('Duration such as "4h", "3d", "2w", "3ed" (elapsed days) or "2d?" (an estimate).'),
|
|
869
|
+
deadline: z.string().nullable().optional().describe('Deadline as YYYY-MM-DD or YYYY-MM-DDTHH:mm in the plan time zone, or null to clear it.'),
|
|
870
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
871
|
+
}, WRITE_IDEMPOTENT, async ({ ref, status, percent_complete, title, description, priority, blocked, duration, deadline, project_id }) => {
|
|
872
|
+
try {
|
|
873
|
+
const resolved = await requireProject(project_id);
|
|
874
|
+
const { item } = await api.updateWorkItem(resolved.projectId, ref, {
|
|
875
|
+
status,
|
|
876
|
+
percentComplete: percent_complete,
|
|
877
|
+
title,
|
|
878
|
+
description,
|
|
879
|
+
priority,
|
|
880
|
+
blocked,
|
|
881
|
+
duration,
|
|
882
|
+
deadline,
|
|
883
|
+
});
|
|
884
|
+
return { content: [{ type: 'text', text: `Updated ${item.key} [${item.status}] ${item.percentComplete}%: ${item.title}\n${item.url}` }] };
|
|
885
|
+
}
|
|
886
|
+
catch (err) {
|
|
887
|
+
return { content: [{ type: 'text', text: `Could not update work item: ${err.message}` }] };
|
|
888
|
+
}
|
|
889
|
+
});
|
|
890
|
+
server.tool('list_suggestions', 'List the pending suggestions in a project plan that you can act on: status changes proposed from linked activity (an opened or merged pull request, a deploy), new items from meeting action items, dependencies from tracker links and activity suggested as evidence for an item. Nothing changes until someone accepts a suggestion in Flow Relay. Free: no credits.', {
|
|
891
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
892
|
+
}, READ_ONLY, async ({ project_id }) => {
|
|
893
|
+
try {
|
|
894
|
+
const resolved = await requireProject(project_id);
|
|
895
|
+
const { suggestions } = await api.listSuggestions(resolved.projectId);
|
|
896
|
+
if (suggestions.length === 0) {
|
|
897
|
+
return { content: [{ type: 'text', text: `No pending suggestions in ${resolved.project.name}.` }] };
|
|
898
|
+
}
|
|
899
|
+
return { content: [{ type: 'text', text: `Pending suggestions in ${resolved.project.name}:\n${suggestions.map(suggestionLine).join('\n')}` }] };
|
|
900
|
+
}
|
|
901
|
+
catch (err) {
|
|
902
|
+
return { content: [{ type: 'text', text: `Could not list suggestions: ${err.message}` }] };
|
|
903
|
+
}
|
|
904
|
+
});
|
|
905
|
+
server.tool('link_evidence', 'Link work to a work item as evidence: a pull request, commit, build, deploy, incident, document or any other https link. The link joins the activity trail of the item and counts toward its evidence coverage. Sending the same link again leaves the item unchanged. Viewers cannot link. Free: no credits.', {
|
|
906
|
+
ref: z.string().min(1).max(100).describe('Item key such as FR-12, or the item id.'),
|
|
907
|
+
url: z.string().min(1).max(500).describe('The https link to attach.'),
|
|
908
|
+
title: z.string().min(1).max(300).optional().describe('Short title for the link. Defaults to the link itself.'),
|
|
909
|
+
kind: z.enum(['commit', 'branch', 'pull_request', 'review', 'build', 'deploy', 'incident', 'ticket', 'message', 'meeting', 'document', 'other']).optional().describe('What the link points to (default other).'),
|
|
910
|
+
occurred_at: z.string().optional().describe('When the work happened, as an ISO 8601 date and time. Defaults to now.'),
|
|
911
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
912
|
+
}, WRITE_IDEMPOTENT, async ({ ref, url, title, kind, occurred_at, project_id }) => {
|
|
913
|
+
try {
|
|
914
|
+
const resolved = await requireProject(project_id);
|
|
915
|
+
const linked = await api.linkEvidence(resolved.projectId, ref, { url, title, kind, occurredAt: occurred_at });
|
|
916
|
+
return { content: [{ type: 'text', text: `Linked ${linked.url} to ${ref}.` }] };
|
|
917
|
+
}
|
|
918
|
+
catch (err) {
|
|
919
|
+
return { content: [{ type: 'text', text: `Could not link evidence: ${err.message}` }] };
|
|
920
|
+
}
|
|
921
|
+
});
|
|
922
|
+
server.tool('generate_plan_review', 'Write a status report for a project plan: progress, concerns, the outlook of each upcoming milestone, suggested register entries and next steps. Every date, variance and index comes from the plan itself; the model only writes the narrative from the plan facts and the last 14 days of linked activity. Runs synchronously and returns Markdown. Consumes 5 credits on success. Viewers cannot generate.', {
|
|
923
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
924
|
+
filters: FiltersSchema,
|
|
925
|
+
}, MUTATING, async ({ project_id, filters }) => {
|
|
926
|
+
try {
|
|
927
|
+
const resolved = await requireProject(project_id);
|
|
928
|
+
const res = await api.generateInsight(resolved.projectId, 'plan_review', { filters });
|
|
929
|
+
const { job, result } = await api.waitForJob(res.jobId);
|
|
930
|
+
if (job.status === 'failed' || !result) {
|
|
931
|
+
const reason = job.error ?? 'unknown error';
|
|
932
|
+
return { content: [{ type: 'text', text: `Could not generate the plan review: ${reason}` }] };
|
|
933
|
+
}
|
|
934
|
+
const insight = result;
|
|
935
|
+
return { content: [{ type: 'text', text: insight.markdown ?? `# ${insight.title}\n\n${insight.summary}` }] };
|
|
936
|
+
}
|
|
937
|
+
catch (err) {
|
|
938
|
+
return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
|
|
939
|
+
}
|
|
940
|
+
});
|
|
941
|
+
server.tool('get_earned_value', 'Read the cost picture of a project plan at its status date: planned and actual cost, and the earned value figures (planned value, earned value, variances, SPI, CPI, TCPI and the estimates at completion) measured against a baseline. Amounts are in the currency of the organization. Project managers only, on plans that include costs. Free: no credits.', {
|
|
942
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
943
|
+
baseline: z.number().int().min(0).max(10).optional().describe('Baseline slot to measure against, 0 to 10 (default 0).'),
|
|
944
|
+
}, READ_ONLY, async ({ project_id, baseline }) => {
|
|
945
|
+
try {
|
|
946
|
+
const resolved = await requireProject(project_id);
|
|
947
|
+
const evm = await api.getEarnedValue(resolved.projectId, baseline);
|
|
948
|
+
return { content: [{ type: 'text', text: earnedValueText(resolved.project.name, evm) }] };
|
|
949
|
+
}
|
|
950
|
+
catch (err) {
|
|
951
|
+
return { content: [{ type: 'text', text: `Could not read earned value: ${err.message}` }] };
|
|
952
|
+
}
|
|
953
|
+
});
|
|
954
|
+
server.tool('list_raid', 'List the RAID register of a project plan: risks, assumptions, issues, decisions and dependencies, highest number first, with their score (probability times impact) and response. Entries that are not closed by default. Free: no credits.', {
|
|
955
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
956
|
+
kind: z.enum(['risk', 'assumption', 'issue', 'decision', 'dependency']).optional().describe('Restrict to one type. Omit for all types.'),
|
|
957
|
+
status: z.enum(['open', 'monitoring', 'closed', 'all']).optional().describe('Restrict to one status, or all. Omit for every entry that is not closed.'),
|
|
958
|
+
limit: z.number().int().min(1).max(200).default(50).describe('Max entries to return (1-200, default 50).'),
|
|
959
|
+
}, READ_ONLY, async ({ project_id, kind, status, limit }) => {
|
|
960
|
+
try {
|
|
961
|
+
const resolved = await requireProject(project_id);
|
|
962
|
+
const { entries } = await api.listRaid(resolved.projectId, { kind, status, limit });
|
|
963
|
+
if (entries.length === 0) {
|
|
964
|
+
return { content: [{ type: 'text', text: `No register entries match in ${resolved.project.name}.` }] };
|
|
965
|
+
}
|
|
966
|
+
return { content: [{ type: 'text', text: `RAID register of ${resolved.project.name}:\n${entries.map(raidLine).join('\n')}` }] };
|
|
967
|
+
}
|
|
968
|
+
catch (err) {
|
|
969
|
+
return { content: [{ type: 'text', text: `Could not list the register: ${err.message}` }] };
|
|
970
|
+
}
|
|
971
|
+
});
|
|
972
|
+
server.tool('get_portfolio', 'Read the portfolio of an organization: every project you can open with its progress, forecast finish, next milestone, open risks and health (on track, at risk or off track: computed every night from the plan and the build, deploy and incident signals, or set by hand by a project manager). Use it to see which projects need attention. Business plan and above. Free: no credits.', {
|
|
973
|
+
organization_id: z.string().describe('Organization id: shown as organization_id on the projects of list_projects.'),
|
|
974
|
+
}, READ_ONLY, async ({ organization_id }) => {
|
|
975
|
+
try {
|
|
976
|
+
const portfolio = await api.getPortfolio(organization_id);
|
|
977
|
+
return { content: [{ type: 'text', text: portfolioText(portfolio) }] };
|
|
978
|
+
}
|
|
979
|
+
catch (err) {
|
|
980
|
+
return { content: [{ type: 'text', text: `Could not read the portfolio: ${err.message}` }] };
|
|
981
|
+
}
|
|
982
|
+
});
|
|
983
|
+
server.tool('get_forecast', 'Forecast when a project plan will finish by simulating it thousands of times: the finish of the project and of each milestone as the date by which half, four out of five and nineteen out of twenty of the runs are done, the chance of meeting the target finish or a milestone deadline, and the items most often on the critical path. Mode schedule (default) varies the durations of the plan (uncertainty low, medium or high); mode throughput uses how many items the team finished each week over the last twelve weeks. Business plan and above. Free: no credits.', {
|
|
984
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
985
|
+
mode: z.enum(['schedule', 'throughput']).optional().describe('schedule varies the durations of the plan (default); throughput uses the weekly pace of the team.'),
|
|
986
|
+
uncertainty: z.enum(['low', 'medium', 'high']).optional().describe('How much the durations may vary in schedule mode (default medium).'),
|
|
987
|
+
}, READ_ONLY, async ({ project_id, mode, uncertainty }) => {
|
|
988
|
+
try {
|
|
989
|
+
const resolved = await requireProject(project_id);
|
|
990
|
+
const forecast = await api.getForecast(resolved.projectId, { mode, uncertainty });
|
|
991
|
+
return { content: [{ type: 'text', text: forecastText(resolved.project.name, forecast) }] };
|
|
992
|
+
}
|
|
993
|
+
catch (err) {
|
|
994
|
+
return { content: [{ type: 'text', text: `Could not forecast: ${err.message}` }] };
|
|
995
|
+
}
|
|
996
|
+
});
|
|
997
|
+
server.tool('plan_whatif', 'Ask a what-if question about a project plan, for example: what if the payment integration takes three weeks longer? The model turns the question into changes to the work (a duration, a delay, a cancellation, a link) and the scheduler computes the new finish of the project and of each milestone and how many items move. Nothing is saved and the plan is not changed. Costs 5 credits.', {
|
|
998
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
999
|
+
question: z.string().min(5).max(500).describe('The what-if question, in words, about the work of the plan.'),
|
|
1000
|
+
}, MUTATING, async ({ project_id, question }) => {
|
|
1001
|
+
try {
|
|
1002
|
+
const resolved = await requireProject(project_id);
|
|
1003
|
+
const result = await api.planWhatIf(resolved.projectId, question);
|
|
1004
|
+
return { content: [{ type: 'text', text: whatIfText(result) }] };
|
|
1005
|
+
}
|
|
1006
|
+
catch (err) {
|
|
1007
|
+
return { content: [{ type: 'text', text: `Could not answer the what-if: ${err.message}` }] };
|
|
1008
|
+
}
|
|
1009
|
+
});
|
|
1010
|
+
server.tool('list_automations', 'List the automation rules of a project plan: what starts each one, what it checks and what it does, how many times it ran and how the last run went. Read only, the rules are changed in the app. Free: no credits.', {
|
|
1011
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
1012
|
+
}, READ_ONLY, async ({ project_id }) => {
|
|
1013
|
+
try {
|
|
1014
|
+
const resolved = await requireProject(project_id);
|
|
1015
|
+
const { automations } = await api.listAutomations(resolved.projectId);
|
|
1016
|
+
if (automations.length === 0)
|
|
1017
|
+
return { content: [{ type: 'text', text: `${resolved.project.name} has no automation rules.` }] };
|
|
1018
|
+
return { content: [{ type: 'text', text: `Automation rules of ${resolved.project.name}:\n${automations.map(automationLine).join('\n')}` }] };
|
|
1019
|
+
}
|
|
1020
|
+
catch (err) {
|
|
1021
|
+
return { content: [{ type: 'text', text: `Could not list the automations: ${err.message}` }] };
|
|
1022
|
+
}
|
|
1023
|
+
});
|
|
1024
|
+
server.tool('list_templates', 'List the templates saved for a project plan, either a whole plan or one item with its subtasks, with the id to give to apply_template. A template keeps names, notes, durations and links, never people or dates. Free: no credits.', {
|
|
1025
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
1026
|
+
}, READ_ONLY, async ({ project_id }) => {
|
|
1027
|
+
try {
|
|
1028
|
+
const resolved = await requireProject(project_id);
|
|
1029
|
+
const { templates } = await api.listTemplates(resolved.projectId);
|
|
1030
|
+
if (templates.length === 0)
|
|
1031
|
+
return { content: [{ type: 'text', text: `No templates are saved for ${resolved.project.name}.` }] };
|
|
1032
|
+
return { content: [{ type: 'text', text: `Templates for ${resolved.project.name}:\n${templates.map(templateLine).join('\n')}` }] };
|
|
1033
|
+
}
|
|
1034
|
+
catch (err) {
|
|
1035
|
+
return { content: [{ type: 'text', text: `Could not list the templates: ${err.message}` }] };
|
|
1036
|
+
}
|
|
1037
|
+
});
|
|
1038
|
+
server.tool('apply_template', 'Add the items of a saved template to a project plan, at the top level or under an existing item. Only project managers can do it. Costs no credits but creates items in the plan, which the change history can undo.', {
|
|
1039
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
1040
|
+
template_id: z.string().describe('Template id from list_templates.'),
|
|
1041
|
+
parent: z.string().optional().describe('Item key such as FR-12 or item id to add the template under. Omit for the top level.'),
|
|
1042
|
+
}, MUTATING, async ({ project_id, template_id, parent }) => {
|
|
1043
|
+
try {
|
|
1044
|
+
const resolved = await requireProject(project_id);
|
|
1045
|
+
const result = await api.applyTemplate(resolved.projectId, template_id, parent);
|
|
1046
|
+
return { content: [{ type: 'text', text: `Added ${result.created} item${result.created === 1 ? '' : 's'} from the template to ${resolved.project.name}.` }] };
|
|
1047
|
+
}
|
|
1048
|
+
catch (err) {
|
|
1049
|
+
return { content: [{ type: 'text', text: `Could not apply the template: ${err.message}` }] };
|
|
1050
|
+
}
|
|
1051
|
+
});
|
|
1052
|
+
server.tool('list_approvals', 'List the change requests of a project plan: what was asked in plain language, who asked, who decided and what they said. Change requests need the Business plan and an organization project. Free: no credits.', {
|
|
1053
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
1054
|
+
pending_only: z.boolean().optional().describe('Only the requests waiting for a decision.'),
|
|
1055
|
+
}, READ_ONLY, async ({ project_id, pending_only }) => {
|
|
1056
|
+
try {
|
|
1057
|
+
const resolved = await requireProject(project_id);
|
|
1058
|
+
const { approvals } = await api.listApprovals(resolved.projectId, pending_only === true);
|
|
1059
|
+
if (approvals.length === 0)
|
|
1060
|
+
return { content: [{ type: 'text', text: `${resolved.project.name} has no change requests${pending_only ? ' waiting for a decision' : ''}.` }] };
|
|
1061
|
+
return { content: [{ type: 'text', text: `Change requests of ${resolved.project.name}:\n${approvals.map(approvalLine).join('\n')}` }] };
|
|
1062
|
+
}
|
|
1063
|
+
catch (err) {
|
|
1064
|
+
return { content: [{ type: 'text', text: `Could not list the change requests: ${err.message}` }] };
|
|
1065
|
+
}
|
|
1066
|
+
});
|
|
1067
|
+
server.tool('request_change', 'Ask for a change to a work item that a second person must approve, when you may not make it directly or want it reviewed: status, progress, priority, the blocked flag, duration or deadline. The approvers are notified and approving applies the change. This only creates a request: nothing changes in the plan yet. Organization projects on the Business plan or above only. Free: no credits.', {
|
|
1068
|
+
ref: z.string().min(1).max(100).describe('Item key such as FR-12, or the item id.'),
|
|
1069
|
+
title: z.string().min(1).max(200).describe('What you want changed, in a few words.'),
|
|
1070
|
+
note: z.string().max(2000).optional().describe('Why the change is needed.'),
|
|
1071
|
+
status: z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled']).optional().describe('New status.'),
|
|
1072
|
+
percent_complete: z.number().int().min(0).max(100).optional().describe('Progress 0-100.'),
|
|
1073
|
+
priority: z.number().int().min(0).max(4).optional().describe('0 lowest, 1 low, 2 medium, 3 high, 4 urgent.'),
|
|
1074
|
+
blocked: z.boolean().optional().describe('Flag or unflag the item as blocked.'),
|
|
1075
|
+
duration: z.string().optional().describe('Duration such as "4h", "3d", "2w", "3ed" (elapsed days) or "2d?" (an estimate).'),
|
|
1076
|
+
deadline: z.string().nullable().optional().describe('Deadline as YYYY-MM-DD or YYYY-MM-DDTHH:mm in the plan time zone, or null to clear it.'),
|
|
1077
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
1078
|
+
}, MUTATING, async ({ ref, title, note, status, percent_complete, priority, blocked, duration, deadline, project_id }) => {
|
|
1079
|
+
try {
|
|
1080
|
+
const resolved = await requireProject(project_id);
|
|
1081
|
+
const changes = Object.fromEntries(Object.entries({ status, percentComplete: percent_complete, priority, blocked, duration, deadline }).filter(([, v]) => v !== undefined));
|
|
1082
|
+
if (Object.keys(changes).length === 0)
|
|
1083
|
+
return { content: [{ type: 'text', text: 'Give at least one change to ask for.' }] };
|
|
1084
|
+
await api.requestChange(resolved.projectId, { item: ref, title, note, changes });
|
|
1085
|
+
return { content: [{ type: 'text', text: `Change request sent to the approvers of ${resolved.project.name}: "${title}". Nothing changes in the plan until someone else approves it.` }] };
|
|
1086
|
+
}
|
|
1087
|
+
catch (err) {
|
|
1088
|
+
return { content: [{ type: 'text', text: `Could not send the change request: ${err.message}` }] };
|
|
1089
|
+
}
|
|
1090
|
+
});
|
|
1091
|
+
server.tool('resolve_suggestion', 'Accept or dismiss one pending suggestion from list_suggestions. Accepting applies it to the plan as the key owner: a status change, a new item, a dependency or an evidence link. Dismissing hides it. Accepting changes the plan, so confirm with the user first. Free: no credits.', {
|
|
1092
|
+
suggestion_id: z.string().min(1).describe('Suggestion id from list_suggestions.'),
|
|
1093
|
+
action: z.enum(['accept', 'dismiss']).describe('accept applies the suggestion to the plan, dismiss hides it.'),
|
|
1094
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
1095
|
+
}, MUTATING, async ({ suggestion_id, action, project_id }) => {
|
|
1096
|
+
try {
|
|
1097
|
+
const resolved = await requireProject(project_id);
|
|
1098
|
+
const { status } = await api.resolveSuggestion(resolved.projectId, suggestion_id, action);
|
|
1099
|
+
return { content: [{ type: 'text', text: `Suggestion ${suggestion_id} ${status ?? (action === 'accept' ? 'accepted' : 'dismissed')} in ${resolved.project.name}.` }] };
|
|
1100
|
+
}
|
|
1101
|
+
catch (err) {
|
|
1102
|
+
return { content: [{ type: 'text', text: `Could not resolve the suggestion: ${err.message}` }] };
|
|
1103
|
+
}
|
|
1104
|
+
});
|
|
1105
|
+
server.tool('create_raid_entry', 'Add an entry to the RAID register of a project plan: a risk, assumption, issue, decision or dependency. Probability and impact are scores from 1 to 5 and their product is the score list_raid shows. Viewers cannot add. Free: no credits.', {
|
|
1106
|
+
kind: z.enum(['risk', 'assumption', 'issue', 'decision', 'dependency']).describe('What the entry is.'),
|
|
1107
|
+
title: z.string().min(1).max(300).describe('Short title of the entry.'),
|
|
1108
|
+
description: z.string().max(10000).optional().describe('Details of the entry.'),
|
|
1109
|
+
status: z.enum(['open', 'monitoring', 'closed']).optional().describe('Status (default open).'),
|
|
1110
|
+
probability: z.number().int().min(1).max(5).optional().describe('How likely it is, 1 rare to 5 almost certain.'),
|
|
1111
|
+
impact: z.number().int().min(1).max(5).optional().describe('How much it matters, 1 minor to 5 severe.'),
|
|
1112
|
+
response: z.string().max(5000).optional().describe('The planned response or mitigation.'),
|
|
1113
|
+
due_on: z.string().optional().describe('Due date as YYYY-MM-DD.'),
|
|
1114
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
1115
|
+
}, MUTATING, async ({ kind, title, description, status, probability, impact, response, due_on, project_id }) => {
|
|
1116
|
+
try {
|
|
1117
|
+
const resolved = await requireProject(project_id);
|
|
1118
|
+
const created = await api.createRaidEntry(resolved.projectId, { kind, title, description, status, probability, impact, response, dueOn: due_on });
|
|
1119
|
+
return { content: [{ type: 'text', text: `Added ${kind} #${created.number} to the register of ${resolved.project.name}: ${title}` }] };
|
|
1120
|
+
}
|
|
1121
|
+
catch (err) {
|
|
1122
|
+
return { content: [{ type: 'text', text: `Could not add the register entry: ${err.message}` }] };
|
|
1123
|
+
}
|
|
1124
|
+
});
|
|
1125
|
+
server.tool('delete_work_item', 'Delete a work item and everything under it from a project plan: its sub-items, dependencies and assignments leave the plan and the plan is rescheduled. The deletion is recorded as one batch in the change history, so a project manager can restore it in Flow Relay. Contributors can delete only items they created. Confirm with the user before calling it. Free: no credits.', {
|
|
1126
|
+
ref: z.string().min(1).max(100).describe('Item key such as FR-12, or the item id.'),
|
|
1127
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
1128
|
+
}, DESTRUCTIVE, async ({ ref, project_id }) => {
|
|
1129
|
+
try {
|
|
1130
|
+
const resolved = await requireProject(project_id);
|
|
1131
|
+
await api.deleteWorkItem(resolved.projectId, ref);
|
|
1132
|
+
return { content: [{ type: 'text', text: `Deleted ${ref} from ${resolved.project.name}. A project manager can restore it from the change history.` }] };
|
|
1133
|
+
}
|
|
1134
|
+
catch (err) {
|
|
1135
|
+
return { content: [{ type: 'text', text: `Could not delete the work item: ${err.message}` }] };
|
|
1136
|
+
}
|
|
1137
|
+
});
|
|
1138
|
+
server.tool('decide_approval', 'Approve, reject or withdraw a change request listed by list_approvals. Approving applies the requested change to the plan as the approver. A request needs a second person: you cannot approve or reject a request you made, and only its author can withdraw it. Confirm with the user before approving. Free: no credits.', {
|
|
1139
|
+
approval_id: z.string().min(1).describe('Change request id from list_approvals.'),
|
|
1140
|
+
decision: z.enum(['approve', 'reject', 'withdraw']).describe('approve applies the change, reject refuses it, withdraw cancels your own request.'),
|
|
1141
|
+
note: z.string().max(1000).optional().describe('Why, shown to the other person.'),
|
|
1142
|
+
project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
|
|
1143
|
+
}, MUTATING, async ({ approval_id, decision, note, project_id }) => {
|
|
1144
|
+
try {
|
|
1145
|
+
const resolved = await requireProject(project_id);
|
|
1146
|
+
const { status } = await api.decideApproval(resolved.projectId, approval_id, decision, note);
|
|
1147
|
+
return { content: [{ type: 'text', text: `Change request ${approval_id} in ${resolved.project.name} is now ${status}.` }] };
|
|
1148
|
+
}
|
|
1149
|
+
catch (err) {
|
|
1150
|
+
return { content: [{ type: 'text', text: `Could not decide the change request: ${err.message}` }] };
|
|
1151
|
+
}
|
|
1152
|
+
});
|
|
1153
|
+
server.registerPrompt('handoff_for_branch', {
|
|
1154
|
+
title: 'Handoff for a branch',
|
|
1155
|
+
description: 'Generate a handoff limited to one git branch and present it.',
|
|
1156
|
+
argsSchema: { branch: z.string().describe('Branch name such as main or feature/login.') },
|
|
1157
|
+
}, ({ branch }) => ({
|
|
1158
|
+
messages: [
|
|
1159
|
+
{
|
|
1160
|
+
role: 'user',
|
|
1161
|
+
content: {
|
|
1162
|
+
type: 'text',
|
|
1163
|
+
text: `Write a handoff for the branch "${branch}" of the active Flow Relay project. Use set_active_project first if no project is active (list_projects shows the choices). Call list_filter_options and find every git source (github, gitlab, bitbucket, azure_devops) whose branches include "${branch}". Then call generate_handoff with filters that limit each of those sources to that branch. Present the finished handoff as Markdown and name the sources it covered. If no source carries the branch, say so and do not generate.`,
|
|
1164
|
+
},
|
|
1165
|
+
},
|
|
1166
|
+
],
|
|
1167
|
+
}));
|
|
1168
|
+
server.registerPrompt('onboard_me', {
|
|
1169
|
+
title: 'Onboard me to a project',
|
|
1170
|
+
description: 'Generate an onboarding brief tailored to a role and a focus area.',
|
|
1171
|
+
argsSchema: {
|
|
1172
|
+
role: z.string().describe('The role of the person being onboarded, for example backend engineer.'),
|
|
1173
|
+
focus: z.string().optional().describe('The repository or feature area they will work on.'),
|
|
1174
|
+
},
|
|
1175
|
+
}, ({ role, focus }) => ({
|
|
1176
|
+
messages: [
|
|
1177
|
+
{
|
|
1178
|
+
role: 'user',
|
|
1179
|
+
content: {
|
|
1180
|
+
type: 'text',
|
|
1181
|
+
text: `Onboard me to the active Flow Relay project as a ${role}${focus ? ` focused on ${focus}` : ''}. Use set_active_project first if no project is active (list_projects shows the choices). Check list_insights for a recent onboarding brief before spending credits. If none fits, call generate_onboarding_brief with new_member_role "${role}"${focus ? ` and focus_area "${focus}"` : ''}. Present the brief as Markdown and end with the three things I should read first.`,
|
|
1182
|
+
},
|
|
1183
|
+
},
|
|
1184
|
+
],
|
|
1185
|
+
}));
|
|
1186
|
+
server.registerPrompt('weekly_status', {
|
|
1187
|
+
title: 'Weekly status',
|
|
1188
|
+
description: 'Summarize the week of the active project from its plan and its activity.',
|
|
1189
|
+
}, () => ({
|
|
1190
|
+
messages: [
|
|
1191
|
+
{
|
|
1192
|
+
role: 'user',
|
|
1193
|
+
content: {
|
|
1194
|
+
type: 'text',
|
|
1195
|
+
text: 'Write a status update for the week of the active Flow Relay project. Use set_active_project first if no project is active (list_projects shows the choices). Read list_work_items for the plan, list_raid for open risks and list_events for the last days of activity. Say what moved, what is blocked, what is at risk and what comes next, using item keys such as FR-12. Do not guess dates: take them from the plan. Keep it under 250 words.',
|
|
1196
|
+
},
|
|
1197
|
+
},
|
|
1198
|
+
],
|
|
1199
|
+
}));
|
|
1200
|
+
server.registerResource('latest_handoff', new ResourceTemplate('flowrelay://projects/{project_id}/handoffs/latest', { list: undefined }), {
|
|
1201
|
+
title: 'Latest handoff',
|
|
1202
|
+
description: 'The latest active handoff of a project, rendered as Markdown.',
|
|
1203
|
+
mimeType: 'text/markdown',
|
|
1204
|
+
}, async (uri, { project_id }) => {
|
|
1205
|
+
const { handoffs } = await api.listHandoffs('active', 1, String(project_id));
|
|
1206
|
+
const handoff = handoffs[0];
|
|
1207
|
+
if (!handoff)
|
|
1208
|
+
throw new Error(`No active handoff in project ${String(project_id)}.`);
|
|
1209
|
+
return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text: handoff.markdown ?? `# ${handoff.title}\n\n${handoff.summary}\n` }] };
|
|
1210
|
+
});
|
|
632
1211
|
return server;
|
|
633
1212
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@flowrelay/mcp-server",
|
|
3
|
-
"version": "1.0
|
|
3
|
+
"version": "1.8.0",
|
|
4
4
|
"description": "Flow Relay MCP Server for Claude Desktop and Claude Code – handoffs, integrations and context events via natural conversation.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "AGPL-3.0-or-later",
|