@flowrelay/mcp-server 1.0.29 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -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.29
14
+ - Version: 1.7.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 18 tools. Every tool carries the four MCP annotations (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`): the `list_*` and `get_*` tools are read-only and idempotent, the `generate_*` tools, `ask_project` and `discord_send_message` are non-idempotent (each call spends credits or posts a message) and no tool is destructive.
35
+ The server currently exposes 36 tools. 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`, `request_change` and `discord_send_message` are non-idempotent (each call spends credits, creates an item, files a request or posts a message), `update_work_item` and `link_evidence` write but are idempotent (the same values twice leave the item unchanged) and no tool is destructive.
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 role.
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,26 @@ 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
+ - `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.
73
+
74
+ Work item tools, `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`).
55
75
 
56
76
  ### Filter Dimensions
57
77
 
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,293 @@ 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 ScheduleForecast {
281
+ mode: 'schedule';
282
+ uncertainty: string;
283
+ iterations: number;
284
+ project: {
285
+ plan: string | null;
286
+ target: string | null;
287
+ p50: string | null;
288
+ p80: string | null;
289
+ p95: string | null;
290
+ chance: number | null;
291
+ };
292
+ milestones: {
293
+ ref: string;
294
+ title: string;
295
+ plan: string | null;
296
+ deadline: string | null;
297
+ p50: string | null;
298
+ p80: string | null;
299
+ p95: string | null;
300
+ chance: number | null;
301
+ }[];
302
+ critical: {
303
+ ref: string;
304
+ title: string;
305
+ index: number;
306
+ }[];
307
+ }
308
+ export interface ThroughputForecast {
309
+ mode: 'throughput';
310
+ iterations: number;
311
+ available: boolean;
312
+ backlog: number;
313
+ weeksOfHistory: number;
314
+ p50: string | null;
315
+ p80: string | null;
316
+ p95: string | null;
317
+ weeks: {
318
+ p50: number;
319
+ p80: number;
320
+ p95: number;
321
+ } | null;
322
+ chance: number | null;
323
+ capped: boolean;
324
+ }
325
+ export type ForecastResult = ScheduleForecast | ThroughputForecast;
326
+ export interface WhatIfResult {
327
+ explanation: string;
328
+ changes: string[];
329
+ left_out: string[];
330
+ comparison: {
331
+ projectFinish: {
332
+ now: string | null;
333
+ scenario: string | null;
334
+ deltaWorkingDays: number | null;
335
+ };
336
+ milestones: {
337
+ ref: string;
338
+ title: string;
339
+ now: string | null;
340
+ scenario: string | null;
341
+ deltaWorkingDays: number | null;
342
+ }[];
343
+ moved: number;
344
+ criticalBecame: number;
345
+ criticalLeft: number;
346
+ warnings: number;
347
+ } | null;
348
+ errors: string[];
349
+ }
350
+ export interface AutomationSummary {
351
+ id: string;
352
+ name: string;
353
+ enabled: boolean;
354
+ summary: string;
355
+ runCount: number;
356
+ lastRunAt: string | null;
357
+ lastStatus: string | null;
358
+ }
359
+ export interface TemplateSummary {
360
+ id: string;
361
+ kind: 'project' | 'item';
362
+ name: string;
363
+ description: string;
364
+ itemCount: number;
365
+ }
366
+ export interface ApprovalSummary {
367
+ id: string;
368
+ kind: 'scope' | 'baseline';
369
+ title: string;
370
+ note: string;
371
+ summary: string[];
372
+ status: 'pending' | 'approved' | 'rejected' | 'withdrawn' | 'failed';
373
+ requestedBy: string | null;
374
+ decidedBy: string | null;
375
+ decidedAt: string | null;
376
+ decisionNote: string | null;
377
+ createdAt: string;
378
+ }
379
+ export interface RequestChangeInput {
380
+ item: string;
381
+ title: string;
382
+ note?: string;
383
+ changes: Record<string, unknown>;
384
+ }
385
+ export interface PortfolioProject {
386
+ id: string;
387
+ key: string;
388
+ name: string;
389
+ status: string;
390
+ programId: string | null;
391
+ percentComplete: number | null;
392
+ projectStart: string | null;
393
+ scheduledFinish: string | null;
394
+ targetFinish: string | null;
395
+ openRisks: number;
396
+ nextMilestone: {
397
+ ref: string;
398
+ title: string;
399
+ finish: string;
400
+ } | null;
401
+ health: {
402
+ verdict: 'green' | 'amber' | 'red';
403
+ overridden: boolean;
404
+ comment: string | null;
405
+ schedule: 'green' | 'amber' | 'red';
406
+ scope: 'green' | 'amber' | 'red' | null;
407
+ delivery: 'green' | 'amber' | 'red' | null;
408
+ computedOn: string;
409
+ slipWorkingDays: number | null;
410
+ overdueItems: number | null;
411
+ openItems: number | null;
412
+ } | null;
413
+ }
414
+ export interface PortfolioResult {
415
+ organizationId: string;
416
+ projects: PortfolioProject[];
417
+ programs: {
418
+ id: string;
419
+ name: string;
420
+ }[];
421
+ dependencies: {
422
+ from: string;
423
+ to: string;
424
+ count: number;
425
+ }[];
426
+ }
139
427
  export declare class FlowRelayAPI {
140
428
  private baseUrl;
141
429
  private apiKey;
@@ -169,7 +457,7 @@ export declare class FlowRelayAPI {
169
457
  answer: string;
170
458
  citations: string[];
171
459
  }>;
172
- generateInsight(projectId: string, kind: 'correlation' | 'onboarding' | 'architecture' | 'release_notes', body?: Record<string, unknown>): Promise<GenerateInsightResponse>;
460
+ generateInsight(projectId: string, kind: 'correlation' | 'onboarding' | 'architecture' | 'release_notes' | 'plan_review', body?: Record<string, unknown>): Promise<GenerateInsightResponse>;
173
461
  listDigests(projectId: string, limit?: number): Promise<{
174
462
  digests: Array<{
175
463
  id: string;
@@ -224,4 +512,61 @@ export declare class FlowRelayAPI {
224
512
  message_id: string;
225
513
  }>;
226
514
  listUntrackedResources(): Promise<UntrackedResource[]>;
515
+ listWorkItems(projectId: string, opts?: {
516
+ status?: string[];
517
+ assignee?: 'me';
518
+ limit?: number;
519
+ cursor?: number;
520
+ }): Promise<{
521
+ timezone: string;
522
+ items: WorkItemSummary[];
523
+ nextCursor: number | null;
524
+ }>;
525
+ getWorkItem(projectId: string, ref: string): Promise<{
526
+ timezone: string;
527
+ item: WorkItemDetail;
528
+ }>;
529
+ createWorkItem(projectId: string, input: WorkItemInput): Promise<{
530
+ item: WorkItemDetail;
531
+ }>;
532
+ updateWorkItem(projectId: string, ref: string, input: WorkItemInput): Promise<{
533
+ item: WorkItemDetail;
534
+ }>;
535
+ listMyWork(): Promise<{
536
+ items: MyWorkEntry[];
537
+ }>;
538
+ listSuggestions(projectId: string): Promise<{
539
+ suggestions: WorkSuggestion[];
540
+ }>;
541
+ linkEvidence(projectId: string, ref: string, input: EvidenceLinkInput): Promise<{
542
+ linked: boolean;
543
+ url: string;
544
+ }>;
545
+ getEarnedValue(projectId: string, baseline?: number): Promise<EarnedValueResult>;
546
+ listRaid(projectId: string, query?: RaidQuery): Promise<{
547
+ entries: RaidEntry[];
548
+ }>;
549
+ getPortfolio(organizationId: string): Promise<PortfolioResult>;
550
+ getForecast(projectId: string, query?: {
551
+ mode?: string;
552
+ uncertainty?: string;
553
+ }): Promise<ForecastResult>;
554
+ planWhatIf(projectId: string, question: string): Promise<WhatIfResult>;
555
+ listAutomations(projectId: string): Promise<{
556
+ automations: AutomationSummary[];
557
+ }>;
558
+ listTemplates(projectId: string): Promise<{
559
+ templates: TemplateSummary[];
560
+ }>;
561
+ applyTemplate(projectId: string, templateId: string, parent?: string): Promise<{
562
+ created: number;
563
+ version: number;
564
+ }>;
565
+ listApprovals(projectId: string, pendingOnly: boolean): Promise<{
566
+ approvals: ApprovalSummary[];
567
+ }>;
568
+ requestChange(projectId: string, input: RequestChangeInput): Promise<{
569
+ id: string;
570
+ status: string;
571
+ }>;
227
572
  }
package/dist/api.js CHANGED
@@ -134,4 +134,101 @@ 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
+ }
137
234
  }
package/dist/server.js CHANGED
@@ -76,6 +76,7 @@ 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 };
79
80
  export function normalizeProjectId(value) {
80
81
  if (typeof value !== 'string')
81
82
  return null;
@@ -95,6 +96,148 @@ function formatProjectScope(project) {
95
96
  : 'owner';
96
97
  return `Org project: ${project.name} (${project.organization_name ?? 'Unknown org'}, ${role})`;
97
98
  }
99
+ function workItemLine(item) {
100
+ const facts = [`${item.percentComplete}%`];
101
+ if (item.finish)
102
+ facts.push(`finish ${item.finish}`);
103
+ if (item.deadline)
104
+ facts.push(`deadline ${item.deadline}`);
105
+ if ('assignees' in item && item.assignees.length > 0)
106
+ facts.push(item.assignees.map((a) => a.name).join(', '));
107
+ return `- ${item.key} [${item.status}${item.blocked ? ', blocked' : ''}] ${item.title} (${facts.join(', ')})`;
108
+ }
109
+ function workItemDetail(item, timezone) {
110
+ const links = (list) => list.map((l) => `${l.key ?? 'unknown'} (${l.type.toUpperCase()})`).join(', ');
111
+ const deadline = item.deadline ? ` · **Deadline:** ${item.deadline}` : '';
112
+ const lines = [
113
+ `# ${item.key} ${item.title}`,
114
+ `**Status:** ${item.status}${item.blocked ? ' (blocked)' : ''} · **Progress:** ${item.percentComplete}% · **Kind:** ${item.kind}`,
115
+ `**Start:** ${item.start ?? 'not scheduled'} · **Finish:** ${item.finish ?? 'not scheduled'}${deadline} (${timezone})`,
116
+ `**Assignees:** ${item.assignees.map((a) => a.name).join(', ') || 'none'}`,
117
+ ];
118
+ if (item.predecessors.length > 0)
119
+ lines.push(`**Predecessors:** ${links(item.predecessors)}`);
120
+ if (item.successors.length > 0)
121
+ lines.push(`**Successors:** ${links(item.successors)}`);
122
+ lines.push(`**Comments:** ${item.commentCount} · **Link:** ${item.url}`);
123
+ if (item.description)
124
+ lines.push('', item.description);
125
+ if (item.evidence.length > 0) {
126
+ lines.push('', '## Evidence', ...item.evidence.map((e) => `- [${e.source}/${e.kind}] ${e.title ?? 'Untitled'} (${e.occurredAt.slice(0, 10)})${e.url ? ` ${e.url}` : ''}`));
127
+ }
128
+ return lines.join('\n');
129
+ }
130
+ function suggestionLine(s) {
131
+ const text = (value, fallback) => (typeof value === 'string' && value.length > 0 ? value : fallback);
132
+ const p = s.payload;
133
+ const summary = {
134
+ status_change: () => `${s.item ?? 'An item'}: move to ${text(p.to, 'a new status')}`,
135
+ create_item: () => `New item: ${text(p.title, 'Untitled')}`,
136
+ dependency: () => `${text(p.predecessor, 'An item')} should finish before ${text(p.successor, 'another item')} starts`,
137
+ evidence: () => `${s.item ?? 'An item'}: "${text(p.title, 'Untitled')}" from ${text(p.source, 'activity')} as evidence`,
138
+ }[s.type]();
139
+ const reason = typeof p.reason === 'string' && p.reason.length > 0 ? ` – ${p.reason}` : '';
140
+ return `- ${summary}${reason} (id ${s.id}${s.forYou ? ', for you' : ''})`;
141
+ }
142
+ function moneyText(cents, currency) {
143
+ return cents === null ? 'n/a' : new Intl.NumberFormat('en', { style: 'currency', currency }).format(cents / 100);
144
+ }
145
+ function earnedValueText(name, r) {
146
+ const e = r.earnedValue;
147
+ const m = (v) => moneyText(v, r.currency);
148
+ const index = (v) => (v === null ? 'n/a' : v.toFixed(2));
149
+ return [
150
+ `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'}.`,
151
+ `Planned cost ${m(r.plannedCostCents)}, actual cost ${m(r.actualCostCents)}${r.budgetCents === null ? '' : `, budget ${m(r.budgetCents)}`}.`,
152
+ `Budget at completion ${m(e.budgetAtCompletionCents)}, planned value ${m(e.plannedValueCents)}, earned value ${m(e.earnedValueCents)}.`,
153
+ `Schedule variance ${m(e.scheduleVarianceCents)}, cost variance ${m(e.costVarianceCents)}, SPI ${index(e.spi)}, CPI ${index(e.cpi)}, TCPI ${index(e.tcpi)}.`,
154
+ `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)}.`,
155
+ ].join('\n');
156
+ }
157
+ function forecastText(name, f) {
158
+ const date = (v) => (v ? v.slice(0, 10) : 'n/a');
159
+ const pct = (v) => (v === null ? 'n/a' : `${Math.round(v * 100)}%`);
160
+ if (f.mode === 'throughput') {
161
+ if (!f.available)
162
+ 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).`;
163
+ return [
164
+ `Throughput forecast of ${name}: ${f.backlog} open items at the pace of the last ${f.weeksOfHistory} weeks (${f.iterations} simulated runs).`,
165
+ `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)}`}.`,
166
+ ...(f.capped ? ['Some runs did not finish within ten years: the pace is too low for the backlog.'] : []),
167
+ ].join('\n');
168
+ }
169
+ return [
170
+ `Forecast of ${name}: ${f.iterations} simulated runs with ${f.uncertainty} uncertainty on the durations.`,
171
+ `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)}` : ''}.`,
172
+ ...(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)}` : ''}`)] : []),
173
+ ...(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`)] : []),
174
+ ].join('\n');
175
+ }
176
+ function whatIfText(r) {
177
+ const date = (v) => (v ? v.slice(0, 10) : 'n/a');
178
+ const lines = [r.explanation || 'What-if result.'];
179
+ if (r.changes.length === 0)
180
+ lines.push('No change in the plan could express this question, so nothing was compared.');
181
+ else
182
+ lines.push('Changes tried:', ...r.changes.map((c) => `- ${c}`));
183
+ if (r.left_out.length > 0)
184
+ lines.push(`Left out: ${r.left_out.join('; ')}.`);
185
+ if (r.comparison) {
186
+ const c = r.comparison;
187
+ const d = c.projectFinish.deltaWorkingDays;
188
+ 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.`);
189
+ 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)`}`));
190
+ }
191
+ if (r.errors.length > 0)
192
+ lines.push(`Could not compare: ${r.errors.join('; ')}.`);
193
+ lines.push('Nothing was saved or changed in the plan.');
194
+ return lines.join('\n');
195
+ }
196
+ function portfolioText(r) {
197
+ if (r.projects.length === 0)
198
+ return 'No project in this portfolio that you can open.';
199
+ const programs = new Map(r.programs.map((p) => [p.id, p.name]));
200
+ const names = new Map(r.projects.map((p) => [p.id, p.name]));
201
+ const verdict = { green: 'on track', amber: 'at risk', red: 'off track' };
202
+ const lines = r.projects.map((p) => {
203
+ const h = p.health;
204
+ const slip = h?.slipWorkingDays ?? null;
205
+ const parts = [
206
+ h ? `${verdict[h.verdict]}${h.overridden ? ' (set by hand)' : ''}` : 'health not computed yet',
207
+ p.percentComplete === null ? null : `${Math.round(p.percentComplete)}% complete`,
208
+ p.scheduledFinish ? `forecast finish ${p.scheduledFinish.slice(0, 10)}` : null,
209
+ p.targetFinish ? `target ${p.targetFinish.slice(0, 10)}` : null,
210
+ slip === null ? null : slip > 0 ? `${slip} working days late` : slip < 0 ? `${-slip} working days ahead` : 'on schedule',
211
+ h?.overdueItems ? `${h.overdueItems} overdue items` : null,
212
+ p.openRisks > 0 ? `${p.openRisks} open risks` : null,
213
+ p.nextMilestone ? `next milestone ${p.nextMilestone.ref} ${p.nextMilestone.title} on ${p.nextMilestone.finish.slice(0, 10)}` : null,
214
+ p.programId ? `program ${programs.get(p.programId) ?? 'unknown'}` : null,
215
+ ].filter((part) => part !== null);
216
+ return `- ${p.key} ${p.name}: ${parts.join(', ')}${h?.comment ? ` – ${h.comment}` : ''}`;
217
+ });
218
+ 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'})`);
219
+ return [`Portfolio, ${r.projects.length} ${r.projects.length === 1 ? 'project' : 'projects'}:`, ...lines, ...(waits.length > 0 ? ['', 'Dependencies between projects:', ...waits] : [])].join('\n');
220
+ }
221
+ function automationLine(a) {
222
+ const ran = a.runCount === 0 ? 'not run yet' : `ran ${a.runCount} time${a.runCount === 1 ? '' : 's'}, last ${a.lastStatus ?? 'ok'}`;
223
+ return `- ${a.name} [${a.enabled ? 'on' : 'off'}, ${ran}]: ${a.summary}`;
224
+ }
225
+ function templateLine(t) {
226
+ 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}` : ''}`;
227
+ }
228
+ function approvalLine(a) {
229
+ const state = a.status === 'pending' ? 'waiting for a decision' : a.status === 'failed' ? 'approved but not applied' : a.status;
230
+ const by = a.requestedBy ? `, asked by ${a.requestedBy}` : '';
231
+ const said = a.decidedBy ? `, ${a.decidedBy}${a.decisionNote ? ` said: ${a.decisionNote}` : ''}` : '';
232
+ return `- ${a.title} [${a.kind === 'scope' ? 'plan change' : 'baseline'}, ${state}${by}${said}]: ${a.summary.join('; ')}`;
233
+ }
234
+ function raidLine(e) {
235
+ const score = e.score === null ? '' : `, score ${e.score} (probability ${e.probability} x impact ${e.impact})`;
236
+ const due = e.dueOn ? `, due ${e.dueOn}` : '';
237
+ const item = e.item ? `, on ${e.item}` : '';
238
+ const response = e.response ? ` – ${e.response}` : '';
239
+ return `- R-${e.number} ${e.type} [${e.status}${score}${due}${item}]: ${e.title}${response}`;
240
+ }
98
241
  export function createFlowRelayServer(api, initialProjectId) {
99
242
  let activeProjectId = initialProjectId;
100
243
  const server = new McpServer({
@@ -118,6 +261,8 @@ export function createFlowRelayServer(api, initialProjectId) {
118
261
  '',
119
262
  '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
263
  '',
264
+ '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. 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.',
265
+ '',
121
266
  'Scope and access follow the API key\'s tenant role; a tool only ever sees projects the key can access.',
122
267
  ].join('\n'),
123
268
  });
@@ -181,7 +326,7 @@ export function createFlowRelayServer(api, initialProjectId) {
181
326
  }
182
327
  });
183
328
  // ── 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 () => {
329
+ 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
330
  try {
186
331
  const context = await getTenantContext();
187
332
  if (context.projects.length === 0) {
@@ -197,7 +342,9 @@ export function createFlowRelayServer(api, initialProjectId) {
197
342
  const scope = project.project_type === 'personal'
198
343
  ? 'personal'
199
344
  : `org:${project.organization_name ?? 'unknown'}`;
200
- return `- ${project.name} (${scope}, role=${project.access_role})\n id: ${project.id}${active}`;
345
+ const key = project.key ? `, keys=${project.key}-n` : '';
346
+ const org = project.organization_id ? `, organization_id=${project.organization_id}` : '';
347
+ return `- ${project.name} (${scope}, role=${project.access_role}${key}${org})\n id: ${project.id}${active}`;
201
348
  });
202
349
  return {
203
350
  content: [{
@@ -557,7 +704,7 @@ export function createFlowRelayServer(api, initialProjectId) {
557
704
  });
558
705
  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
706
  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.'),
707
+ 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
708
  status: z.enum(['active', 'archived', 'all']).default('active').describe('active = current, archived = superseded, all = both.'),
562
709
  limit: z.number().int().min(1).max(50).default(20).describe('Max insights to return (1-50, default 20).'),
563
710
  }, READ_ONLY, async ({ project_id, kind, status, limit }) => {
@@ -629,5 +776,314 @@ export function createFlowRelayServer(api, initialProjectId) {
629
776
  return { content: [{ type: 'text', text: `Could not load filter options: ${err.message}` }] };
630
777
  }
631
778
  });
779
+ 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.', {
780
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
781
+ status: z.array(z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled'])).optional().describe('Only items in these statuses. Omit for every status.'),
782
+ mine: z.boolean().default(false).describe('Only items assigned to you.'),
783
+ limit: z.number().int().min(1).max(200).default(50).describe('Max items to return (1-200, default 50).'),
784
+ cursor: z.number().int().min(0).optional().describe('The cursor printed at the end of a previous page.'),
785
+ }, READ_ONLY, async ({ project_id, status, mine, limit, cursor }) => {
786
+ try {
787
+ const resolved = await requireProject(project_id);
788
+ const page = await api.listWorkItems(resolved.projectId, { status, assignee: mine ? 'me' : undefined, limit, cursor });
789
+ if (page.items.length === 0) {
790
+ return { content: [{ type: 'text', text: `No work items found in ${resolved.project.name}.` }] };
791
+ }
792
+ const more = page.nextCursor !== null ? `\n\nMore items: call again with cursor=${page.nextCursor}` : '';
793
+ const text = `Work items in ${resolved.project.name} (times in ${page.timezone}):\n${page.items.map(workItemLine).join('\n')}${more}`;
794
+ return { content: [{ type: 'text', text }] };
795
+ }
796
+ catch (err) {
797
+ return { content: [{ type: 'text', text: `Could not list work items: ${err.message}` }] };
798
+ }
799
+ });
800
+ 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.', {
801
+ ref: z.string().min(1).max(100).describe('Item key such as FR-12, or the item id.'),
802
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
803
+ }, READ_ONLY, async ({ ref, project_id }) => {
804
+ try {
805
+ const resolved = await requireProject(project_id);
806
+ const { timezone, item } = await api.getWorkItem(resolved.projectId, ref);
807
+ return { content: [{ type: 'text', text: workItemDetail(item, timezone) }] };
808
+ }
809
+ catch (err) {
810
+ return { content: [{ type: 'text', text: `Could not read work item: ${err.message}` }] };
811
+ }
812
+ });
813
+ 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 () => {
814
+ try {
815
+ const { items } = await api.listMyWork();
816
+ if (items.length === 0) {
817
+ return { content: [{ type: 'text', text: 'Nothing is assigned to you right now.' }] };
818
+ }
819
+ const text = `Your work:\n${items.map((item) => `${workItemLine(item)} – ${item.project.name}`).join('\n')}`;
820
+ return { content: [{ type: 'text', text }] };
821
+ }
822
+ catch (err) {
823
+ return { content: [{ type: 'text', text: `Could not list your work: ${err.message}` }] };
824
+ }
825
+ });
826
+ 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.', {
827
+ title: z.string().min(1).max(500).describe('Item title, 1-500 characters.'),
828
+ description: z.string().max(50000).optional().describe('Description in plain text or Markdown.'),
829
+ 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.'),
830
+ kind: z.enum(['task', 'milestone']).optional().describe('task (default) or milestone.'),
831
+ status: z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled']).optional().describe('Initial status (default todo).'),
832
+ priority: z.number().int().min(0).max(4).optional().describe('0 lowest, 1 low, 2 medium (default), 3 high, 4 urgent.'),
833
+ duration: z.string().optional().describe('Duration such as "4h", "3d", "2w", "3ed" (elapsed days) or "2d?" (an estimate).'),
834
+ deadline: z.string().optional().describe('Deadline as YYYY-MM-DD or YYYY-MM-DDTHH:mm in the plan time zone.'),
835
+ assign_to_me: z.boolean().default(false).describe('Assign the new item to yourself.'),
836
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
837
+ }, MUTATING, async ({ title, description, parent, kind, status, priority, duration, deadline, assign_to_me, project_id }) => {
838
+ try {
839
+ const resolved = await requireProject(project_id);
840
+ const { item } = await api.createWorkItem(resolved.projectId, {
841
+ title,
842
+ description,
843
+ parent,
844
+ kind,
845
+ status,
846
+ priority,
847
+ duration,
848
+ deadline,
849
+ assignee: assign_to_me ? 'me' : undefined,
850
+ });
851
+ return { content: [{ type: 'text', text: `Created ${item.key}: ${item.title}\n${item.url}` }] };
852
+ }
853
+ catch (err) {
854
+ return { content: [{ type: 'text', text: `Could not create work item: ${err.message}` }] };
855
+ }
856
+ });
857
+ 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.', {
858
+ ref: z.string().min(1).max(100).describe('Item key such as FR-12, or the item id.'),
859
+ status: z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled']).optional().describe('New status.'),
860
+ percent_complete: z.number().int().min(0).max(100).optional().describe('Progress 0-100. 100 marks the item done.'),
861
+ title: z.string().min(1).max(500).optional().describe('New title, 1-500 characters.'),
862
+ description: z.string().max(50000).optional().describe('New description in plain text or Markdown.'),
863
+ priority: z.number().int().min(0).max(4).optional().describe('0 lowest, 1 low, 2 medium, 3 high, 4 urgent.'),
864
+ blocked: z.boolean().optional().describe('Flag or unflag the item as blocked. A flag, not a status.'),
865
+ duration: z.string().optional().describe('Duration such as "4h", "3d", "2w", "3ed" (elapsed days) or "2d?" (an estimate).'),
866
+ 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.'),
867
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
868
+ }, WRITE_IDEMPOTENT, async ({ ref, status, percent_complete, title, description, priority, blocked, duration, deadline, project_id }) => {
869
+ try {
870
+ const resolved = await requireProject(project_id);
871
+ const { item } = await api.updateWorkItem(resolved.projectId, ref, {
872
+ status,
873
+ percentComplete: percent_complete,
874
+ title,
875
+ description,
876
+ priority,
877
+ blocked,
878
+ duration,
879
+ deadline,
880
+ });
881
+ return { content: [{ type: 'text', text: `Updated ${item.key} [${item.status}] ${item.percentComplete}%: ${item.title}\n${item.url}` }] };
882
+ }
883
+ catch (err) {
884
+ return { content: [{ type: 'text', text: `Could not update work item: ${err.message}` }] };
885
+ }
886
+ });
887
+ 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.', {
888
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
889
+ }, READ_ONLY, async ({ project_id }) => {
890
+ try {
891
+ const resolved = await requireProject(project_id);
892
+ const { suggestions } = await api.listSuggestions(resolved.projectId);
893
+ if (suggestions.length === 0) {
894
+ return { content: [{ type: 'text', text: `No pending suggestions in ${resolved.project.name}.` }] };
895
+ }
896
+ return { content: [{ type: 'text', text: `Pending suggestions in ${resolved.project.name}:\n${suggestions.map(suggestionLine).join('\n')}` }] };
897
+ }
898
+ catch (err) {
899
+ return { content: [{ type: 'text', text: `Could not list suggestions: ${err.message}` }] };
900
+ }
901
+ });
902
+ 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.', {
903
+ ref: z.string().min(1).max(100).describe('Item key such as FR-12, or the item id.'),
904
+ url: z.string().min(1).max(500).describe('The https link to attach.'),
905
+ title: z.string().min(1).max(300).optional().describe('Short title for the link. Defaults to the link itself.'),
906
+ 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).'),
907
+ occurred_at: z.string().optional().describe('When the work happened, as an ISO 8601 date and time. Defaults to now.'),
908
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
909
+ }, WRITE_IDEMPOTENT, async ({ ref, url, title, kind, occurred_at, project_id }) => {
910
+ try {
911
+ const resolved = await requireProject(project_id);
912
+ const linked = await api.linkEvidence(resolved.projectId, ref, { url, title, kind, occurredAt: occurred_at });
913
+ return { content: [{ type: 'text', text: `Linked ${linked.url} to ${ref}.` }] };
914
+ }
915
+ catch (err) {
916
+ return { content: [{ type: 'text', text: `Could not link evidence: ${err.message}` }] };
917
+ }
918
+ });
919
+ 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.', {
920
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
921
+ filters: FiltersSchema,
922
+ }, MUTATING, async ({ project_id, filters }) => {
923
+ try {
924
+ const resolved = await requireProject(project_id);
925
+ const res = await api.generateInsight(resolved.projectId, 'plan_review', { filters });
926
+ const { job, result } = await api.waitForJob(res.jobId);
927
+ if (job.status === 'failed' || !result) {
928
+ const reason = job.error ?? 'unknown error';
929
+ return { content: [{ type: 'text', text: `Could not generate the plan review: ${reason}` }] };
930
+ }
931
+ const insight = result;
932
+ return { content: [{ type: 'text', text: insight.markdown ?? `# ${insight.title}\n\n${insight.summary}` }] };
933
+ }
934
+ catch (err) {
935
+ return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
936
+ }
937
+ });
938
+ 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.', {
939
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
940
+ baseline: z.number().int().min(0).max(10).optional().describe('Baseline slot to measure against, 0 to 10 (default 0).'),
941
+ }, READ_ONLY, async ({ project_id, baseline }) => {
942
+ try {
943
+ const resolved = await requireProject(project_id);
944
+ const evm = await api.getEarnedValue(resolved.projectId, baseline);
945
+ return { content: [{ type: 'text', text: earnedValueText(resolved.project.name, evm) }] };
946
+ }
947
+ catch (err) {
948
+ return { content: [{ type: 'text', text: `Could not read earned value: ${err.message}` }] };
949
+ }
950
+ });
951
+ 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.', {
952
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
953
+ kind: z.enum(['risk', 'assumption', 'issue', 'decision', 'dependency']).optional().describe('Restrict to one type. Omit for all types.'),
954
+ status: z.enum(['open', 'monitoring', 'closed', 'all']).optional().describe('Restrict to one status, or all. Omit for every entry that is not closed.'),
955
+ limit: z.number().int().min(1).max(200).default(50).describe('Max entries to return (1-200, default 50).'),
956
+ }, READ_ONLY, async ({ project_id, kind, status, limit }) => {
957
+ try {
958
+ const resolved = await requireProject(project_id);
959
+ const { entries } = await api.listRaid(resolved.projectId, { kind, status, limit });
960
+ if (entries.length === 0) {
961
+ return { content: [{ type: 'text', text: `No register entries match in ${resolved.project.name}.` }] };
962
+ }
963
+ return { content: [{ type: 'text', text: `RAID register of ${resolved.project.name}:\n${entries.map(raidLine).join('\n')}` }] };
964
+ }
965
+ catch (err) {
966
+ return { content: [{ type: 'text', text: `Could not list the register: ${err.message}` }] };
967
+ }
968
+ });
969
+ 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.', {
970
+ organization_id: z.string().describe('Organization id: shown as organization_id on the projects of list_projects.'),
971
+ }, READ_ONLY, async ({ organization_id }) => {
972
+ try {
973
+ const portfolio = await api.getPortfolio(organization_id);
974
+ return { content: [{ type: 'text', text: portfolioText(portfolio) }] };
975
+ }
976
+ catch (err) {
977
+ return { content: [{ type: 'text', text: `Could not read the portfolio: ${err.message}` }] };
978
+ }
979
+ });
980
+ 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.', {
981
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
982
+ mode: z.enum(['schedule', 'throughput']).optional().describe('schedule varies the durations of the plan (default); throughput uses the weekly pace of the team.'),
983
+ uncertainty: z.enum(['low', 'medium', 'high']).optional().describe('How much the durations may vary in schedule mode (default medium).'),
984
+ }, READ_ONLY, async ({ project_id, mode, uncertainty }) => {
985
+ try {
986
+ const resolved = await requireProject(project_id);
987
+ const forecast = await api.getForecast(resolved.projectId, { mode, uncertainty });
988
+ return { content: [{ type: 'text', text: forecastText(resolved.project.name, forecast) }] };
989
+ }
990
+ catch (err) {
991
+ return { content: [{ type: 'text', text: `Could not forecast: ${err.message}` }] };
992
+ }
993
+ });
994
+ 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.', {
995
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
996
+ question: z.string().min(5).max(500).describe('The what-if question, in words, about the work of the plan.'),
997
+ }, MUTATING, async ({ project_id, question }) => {
998
+ try {
999
+ const resolved = await requireProject(project_id);
1000
+ const result = await api.planWhatIf(resolved.projectId, question);
1001
+ return { content: [{ type: 'text', text: whatIfText(result) }] };
1002
+ }
1003
+ catch (err) {
1004
+ return { content: [{ type: 'text', text: `Could not answer the what-if: ${err.message}` }] };
1005
+ }
1006
+ });
1007
+ 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.', {
1008
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
1009
+ }, READ_ONLY, async ({ project_id }) => {
1010
+ try {
1011
+ const resolved = await requireProject(project_id);
1012
+ const { automations } = await api.listAutomations(resolved.projectId);
1013
+ if (automations.length === 0)
1014
+ return { content: [{ type: 'text', text: `${resolved.project.name} has no automation rules.` }] };
1015
+ return { content: [{ type: 'text', text: `Automation rules of ${resolved.project.name}:\n${automations.map(automationLine).join('\n')}` }] };
1016
+ }
1017
+ catch (err) {
1018
+ return { content: [{ type: 'text', text: `Could not list the automations: ${err.message}` }] };
1019
+ }
1020
+ });
1021
+ 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.', {
1022
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
1023
+ }, READ_ONLY, async ({ project_id }) => {
1024
+ try {
1025
+ const resolved = await requireProject(project_id);
1026
+ const { templates } = await api.listTemplates(resolved.projectId);
1027
+ if (templates.length === 0)
1028
+ return { content: [{ type: 'text', text: `No templates are saved for ${resolved.project.name}.` }] };
1029
+ return { content: [{ type: 'text', text: `Templates for ${resolved.project.name}:\n${templates.map(templateLine).join('\n')}` }] };
1030
+ }
1031
+ catch (err) {
1032
+ return { content: [{ type: 'text', text: `Could not list the templates: ${err.message}` }] };
1033
+ }
1034
+ });
1035
+ 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.', {
1036
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
1037
+ template_id: z.string().describe('Template id from list_templates.'),
1038
+ parent: z.string().optional().describe('Item key such as FR-12 or item id to add the template under. Omit for the top level.'),
1039
+ }, MUTATING, async ({ project_id, template_id, parent }) => {
1040
+ try {
1041
+ const resolved = await requireProject(project_id);
1042
+ const result = await api.applyTemplate(resolved.projectId, template_id, parent);
1043
+ return { content: [{ type: 'text', text: `Added ${result.created} item${result.created === 1 ? '' : 's'} from the template to ${resolved.project.name}.` }] };
1044
+ }
1045
+ catch (err) {
1046
+ return { content: [{ type: 'text', text: `Could not apply the template: ${err.message}` }] };
1047
+ }
1048
+ });
1049
+ 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.', {
1050
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
1051
+ pending_only: z.boolean().optional().describe('Only the requests waiting for a decision.'),
1052
+ }, READ_ONLY, async ({ project_id, pending_only }) => {
1053
+ try {
1054
+ const resolved = await requireProject(project_id);
1055
+ const { approvals } = await api.listApprovals(resolved.projectId, pending_only === true);
1056
+ if (approvals.length === 0)
1057
+ return { content: [{ type: 'text', text: `${resolved.project.name} has no change requests${pending_only ? ' waiting for a decision' : ''}.` }] };
1058
+ return { content: [{ type: 'text', text: `Change requests of ${resolved.project.name}:\n${approvals.map(approvalLine).join('\n')}` }] };
1059
+ }
1060
+ catch (err) {
1061
+ return { content: [{ type: 'text', text: `Could not list the change requests: ${err.message}` }] };
1062
+ }
1063
+ });
1064
+ 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.', {
1065
+ ref: z.string().min(1).max(100).describe('Item key such as FR-12, or the item id.'),
1066
+ title: z.string().min(1).max(200).describe('What you want changed, in a few words.'),
1067
+ note: z.string().max(2000).optional().describe('Why the change is needed.'),
1068
+ status: z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled']).optional().describe('New status.'),
1069
+ percent_complete: z.number().int().min(0).max(100).optional().describe('Progress 0-100.'),
1070
+ priority: z.number().int().min(0).max(4).optional().describe('0 lowest, 1 low, 2 medium, 3 high, 4 urgent.'),
1071
+ blocked: z.boolean().optional().describe('Flag or unflag the item as blocked.'),
1072
+ duration: z.string().optional().describe('Duration such as "4h", "3d", "2w", "3ed" (elapsed days) or "2d?" (an estimate).'),
1073
+ 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.'),
1074
+ project_id: z.string().optional().describe('Project id from list_projects. Omit to use the active project.'),
1075
+ }, MUTATING, async ({ ref, title, note, status, percent_complete, priority, blocked, duration, deadline, project_id }) => {
1076
+ try {
1077
+ const resolved = await requireProject(project_id);
1078
+ const changes = Object.fromEntries(Object.entries({ status, percentComplete: percent_complete, priority, blocked, duration, deadline }).filter(([, v]) => v !== undefined));
1079
+ if (Object.keys(changes).length === 0)
1080
+ return { content: [{ type: 'text', text: 'Give at least one change to ask for.' }] };
1081
+ await api.requestChange(resolved.projectId, { item: ref, title, note, changes });
1082
+ 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.` }] };
1083
+ }
1084
+ catch (err) {
1085
+ return { content: [{ type: 'text', text: `Could not send the change request: ${err.message}` }] };
1086
+ }
1087
+ });
632
1088
  return server;
633
1089
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@flowrelay/mcp-server",
3
- "version": "1.0.29",
3
+ "version": "1.7.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",