@flowrelay/mcp-server 1.0.23 → 1.0.25
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 +68 -37
- package/dist/index.js +3 -583
- package/dist/server.d.ts +11 -0
- package/dist/server.js +627 -0
- package/package.json +5 -3
package/dist/server.js
ADDED
|
@@ -0,0 +1,627 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @license
|
|
3
|
+
* Flow Relay MCP Server
|
|
4
|
+
* Copyright (c) 2026 Adriano Sorbello (atrisorb) <https://github.com/atrisorb>
|
|
5
|
+
* Licensed under GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later)
|
|
6
|
+
*/
|
|
7
|
+
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
|
|
8
|
+
import { z } from 'zod';
|
|
9
|
+
import { createRequire } from 'node:module';
|
|
10
|
+
export const PKG_VERSION = createRequire(import.meta.url)('../package.json').version;
|
|
11
|
+
// Canonical source vocabulary.
|
|
12
|
+
const SOURCES = [
|
|
13
|
+
'github',
|
|
14
|
+
'slack',
|
|
15
|
+
'discord',
|
|
16
|
+
'linear',
|
|
17
|
+
'notion',
|
|
18
|
+
'confluence',
|
|
19
|
+
'jira',
|
|
20
|
+
'gitlab',
|
|
21
|
+
'bitbucket',
|
|
22
|
+
'azure_devops',
|
|
23
|
+
'figma',
|
|
24
|
+
'microsoft_outlook',
|
|
25
|
+
'microsoft_teams',
|
|
26
|
+
'sentry',
|
|
27
|
+
'datadog',
|
|
28
|
+
'pagerduty',
|
|
29
|
+
'asana',
|
|
30
|
+
'gmail',
|
|
31
|
+
'buildkite',
|
|
32
|
+
'circleci',
|
|
33
|
+
'vercel',
|
|
34
|
+
'incident_io',
|
|
35
|
+
'netlify',
|
|
36
|
+
'render',
|
|
37
|
+
'railway',
|
|
38
|
+
'cloudflare_pages',
|
|
39
|
+
'clickup',
|
|
40
|
+
'monday_com',
|
|
41
|
+
'shortcut',
|
|
42
|
+
'intercom',
|
|
43
|
+
'zendesk',
|
|
44
|
+
'snyk',
|
|
45
|
+
'fireflies',
|
|
46
|
+
'zoom',
|
|
47
|
+
'grafana',
|
|
48
|
+
'google_calendar',
|
|
49
|
+
'google_drive',
|
|
50
|
+
'launchdarkly',
|
|
51
|
+
'hcp_terraform',
|
|
52
|
+
'sonarqube',
|
|
53
|
+
'miro',
|
|
54
|
+
'new_relic',
|
|
55
|
+
'jira_service_management',
|
|
56
|
+
'posthog',
|
|
57
|
+
'hubspot',
|
|
58
|
+
'salesforce',
|
|
59
|
+
];
|
|
60
|
+
const SourceEnum = z.enum(SOURCES);
|
|
61
|
+
const SourceFilterSchema = z.object({
|
|
62
|
+
projects: z.array(z.string()).optional().describe('Resource ids from list_filter_options[source].projects (repos, channels, boards). Use the exact id, not the display label.'),
|
|
63
|
+
eventTypes: z.array(z.string()).optional().describe('Event-type values from list_filter_options (e.g. "push", "issue_created"). Case-sensitive; provider-driven. A value that does not exist matches no events (it is not rejected).'),
|
|
64
|
+
branches: z.array(z.string()).optional().describe('Git branch names (e.g. "main", "develop") – git sources only (github, gitlab, bitbucket, azure_devops). Using this on a non-git source is a 400.'),
|
|
65
|
+
priorities: z.array(z.string()).optional().describe('Priority values from list_filter_options (e.g. "high", "urgent") – jira, jira_service_management, linear, sentry, pagerduty, incident_io, clickup, zendesk, snyk, grafana, new_relic, hubspot, salesforce only. Using this on another source is a 400; unrecognized values simply match no events.'),
|
|
66
|
+
});
|
|
67
|
+
const FiltersSchema = z.record(z.string(), SourceFilterSchema)
|
|
68
|
+
.optional()
|
|
69
|
+
.describe('Per-source advanced filters, AND-combined across dimensions. Keys MUST be source ids (an unknown source id is rejected with 400). The dimension VALUES are matched leniently – call list_filter_options first to get the real selectable values for the project rather than guessing.');
|
|
70
|
+
const READ_ONLY = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true };
|
|
71
|
+
const MUTATING = { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
|
|
72
|
+
const SESSION_STATE = { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false };
|
|
73
|
+
export function normalizeProjectId(value) {
|
|
74
|
+
if (typeof value !== 'string')
|
|
75
|
+
return null;
|
|
76
|
+
const trimmed = value.trim();
|
|
77
|
+
return trimmed.length > 0 ? trimmed : null;
|
|
78
|
+
}
|
|
79
|
+
function formatProjectScope(project) {
|
|
80
|
+
if (!project)
|
|
81
|
+
return 'No project selected (required for handoffs & insights)';
|
|
82
|
+
if (project.project_type === 'personal') {
|
|
83
|
+
return `Personal project: ${project.name}`;
|
|
84
|
+
}
|
|
85
|
+
const role = project.access_role === 'admin'
|
|
86
|
+
? 'admin'
|
|
87
|
+
: project.access_role === 'member'
|
|
88
|
+
? 'member'
|
|
89
|
+
: 'owner';
|
|
90
|
+
return `Org project: ${project.name} (${project.organization_name ?? 'Unknown org'}, ${role})`;
|
|
91
|
+
}
|
|
92
|
+
export function createFlowRelayServer(api, initialProjectId) {
|
|
93
|
+
let activeProjectId = initialProjectId;
|
|
94
|
+
const server = new McpServer({
|
|
95
|
+
name: 'flowrelay',
|
|
96
|
+
version: PKG_VERSION,
|
|
97
|
+
websiteUrl: 'https://www.flowrelay.it',
|
|
98
|
+
icons: [
|
|
99
|
+
{ src: 'https://www.flowrelay.it/icon.png', mimeType: 'image/png', sizes: ['1024x1024'] },
|
|
100
|
+
],
|
|
101
|
+
}, {
|
|
102
|
+
instructions: [
|
|
103
|
+
'Flow Relay captures your team\'s work context from connected integrations (GitHub, Slack, Jira, Linear, and more) and synthesizes it into two kinds of artifact:',
|
|
104
|
+
'- A HANDOFF: a snapshot of recent activity, decisions, open questions and next steps for a project – used to hand work off or catch up.',
|
|
105
|
+
'- An INSIGHT, in three flavors: CORRELATION (links related events across different sources), ONBOARDING BRIEF (a getting-started guide for someone new to the project) and ARCHITECTURE (trade-offs, risks and patterns inferred from the code).',
|
|
106
|
+
'',
|
|
107
|
+
'Typical flow:',
|
|
108
|
+
'1. Call list_projects to see accessible projects and their ids. Every id you ever pass (project, handoff, insight, Discord channel) comes from a list_* tool – never invent one.',
|
|
109
|
+
'2. Optionally set_active_project so later tools can omit project_id.',
|
|
110
|
+
'3. Before generating with filters, call list_filter_options to get the real selectable values for that project.',
|
|
111
|
+
'4. Call a generate_* tool. These run the AI synchronously here: the tool waits for completion (tens of seconds) and returns the finished artifact as Markdown – you do not poll.',
|
|
112
|
+
'',
|
|
113
|
+
'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.',
|
|
114
|
+
'',
|
|
115
|
+
'Scope and access follow the API key\'s tenant role; a tool only ever sees projects the key can access.',
|
|
116
|
+
].join('\n'),
|
|
117
|
+
});
|
|
118
|
+
async function getTenantContext() {
|
|
119
|
+
const context = await api.listProjects();
|
|
120
|
+
if (activeProjectId && !context.projects.some((project) => project.id === activeProjectId)) {
|
|
121
|
+
activeProjectId = null;
|
|
122
|
+
}
|
|
123
|
+
return context;
|
|
124
|
+
}
|
|
125
|
+
async function resolveProject(projectId) {
|
|
126
|
+
const explicitProjectId = normalizeProjectId(projectId);
|
|
127
|
+
const resolvedProjectId = explicitProjectId ?? activeProjectId;
|
|
128
|
+
if (!resolvedProjectId) {
|
|
129
|
+
return { projectId: null, project: null };
|
|
130
|
+
}
|
|
131
|
+
const context = await getTenantContext();
|
|
132
|
+
const project = context.projects.find((candidate) => candidate.id === resolvedProjectId) ?? null;
|
|
133
|
+
if (!project) {
|
|
134
|
+
activeProjectId = null;
|
|
135
|
+
return { projectId: null, project: null };
|
|
136
|
+
}
|
|
137
|
+
return { projectId: resolvedProjectId, project };
|
|
138
|
+
}
|
|
139
|
+
async function requireProject(projectId) {
|
|
140
|
+
const explicitProjectId = normalizeProjectId(projectId);
|
|
141
|
+
const resolvedProjectId = explicitProjectId ?? activeProjectId;
|
|
142
|
+
if (!resolvedProjectId) {
|
|
143
|
+
throw new Error('A project is required. Use set_active_project or pass project_id. Run list_projects to see available projects.');
|
|
144
|
+
}
|
|
145
|
+
const context = await getTenantContext();
|
|
146
|
+
const project = context.projects.find((candidate) => candidate.id === resolvedProjectId) ?? null;
|
|
147
|
+
if (!project) {
|
|
148
|
+
activeProjectId = null;
|
|
149
|
+
throw new Error('A project is required. The selected project was not found or is inaccessible. Use set_active_project or pass project_id. Run list_projects to see available projects.');
|
|
150
|
+
}
|
|
151
|
+
return { projectId: resolvedProjectId, project };
|
|
152
|
+
}
|
|
153
|
+
// ── Tool: workspace context ─────────────────────────────────────────
|
|
154
|
+
server.tool('get_workspace_context', 'Show the current Flow Relay context: personal vs business mode, number of organizations and accessible projects, the active project scope and the caller\'s role. Good first call to orient yourself before other tools.', {}, READ_ONLY, async () => {
|
|
155
|
+
try {
|
|
156
|
+
const context = await getTenantContext();
|
|
157
|
+
const activeProject = activeProjectId
|
|
158
|
+
? context.projects.find((project) => project.id === activeProjectId) ?? null
|
|
159
|
+
: null;
|
|
160
|
+
const isBusiness = context.account_type === 'business' || context.organizations.length > 0;
|
|
161
|
+
const roleLine = activeProject
|
|
162
|
+
? `Role: ${activeProject.access_role}`
|
|
163
|
+
: 'Role: n/a (no project selected)';
|
|
164
|
+
const lines = [
|
|
165
|
+
`Account mode: ${isBusiness ? 'business' : 'personal'}`,
|
|
166
|
+
`Organizations: ${context.organizations.length}`,
|
|
167
|
+
`Accessible projects: ${context.projects.length}`,
|
|
168
|
+
`Active scope: ${formatProjectScope(activeProject)}`,
|
|
169
|
+
roleLine,
|
|
170
|
+
];
|
|
171
|
+
return { content: [{ type: 'text', text: lines.join('\n') }] };
|
|
172
|
+
}
|
|
173
|
+
catch (err) {
|
|
174
|
+
return { content: [{ type: 'text', text: `Could not load workspace context: ${err.message}` }] };
|
|
175
|
+
}
|
|
176
|
+
});
|
|
177
|
+
// ── Tool: list projects ─────────────────────────────────────────────
|
|
178
|
+
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 () => {
|
|
179
|
+
try {
|
|
180
|
+
const context = await getTenantContext();
|
|
181
|
+
if (context.projects.length === 0) {
|
|
182
|
+
return {
|
|
183
|
+
content: [{
|
|
184
|
+
type: 'text',
|
|
185
|
+
text: 'No accessible projects found. Create a project in Flow Relay or get added to a project team.',
|
|
186
|
+
}],
|
|
187
|
+
};
|
|
188
|
+
}
|
|
189
|
+
const lines = context.projects.map((project) => {
|
|
190
|
+
const active = project.id === activeProjectId ? ' [active]' : '';
|
|
191
|
+
const scope = project.project_type === 'personal'
|
|
192
|
+
? 'personal'
|
|
193
|
+
: `org:${project.organization_name ?? 'unknown'}`;
|
|
194
|
+
return `- ${project.name} (${scope}, role=${project.access_role})\n id: ${project.id}${active}`;
|
|
195
|
+
});
|
|
196
|
+
return {
|
|
197
|
+
content: [{
|
|
198
|
+
type: 'text',
|
|
199
|
+
text: `Projects:\n${lines.join('\n')}`,
|
|
200
|
+
}],
|
|
201
|
+
};
|
|
202
|
+
}
|
|
203
|
+
catch (err) {
|
|
204
|
+
return { content: [{ type: 'text', text: `Could not list projects: ${err.message}` }] };
|
|
205
|
+
}
|
|
206
|
+
});
|
|
207
|
+
// ── Tool: set active project ────────────────────────────────────────
|
|
208
|
+
server.tool('set_active_project', 'Set the active project so later tools can omit project_id (a convenience for a multi-step session on one project). Set it once from a list_projects id, then call generate_handoff / list_events / etc. without repeating project_id. Not required if you always pass project_id explicitly.', {
|
|
209
|
+
project_id: z.string().optional().describe('Project id (from list_projects) to set as active. Omit, or set clear, to unset it.'),
|
|
210
|
+
clear: z.boolean().default(false).describe('Clear the active project. Generation then requires an explicit project_id again.'),
|
|
211
|
+
}, SESSION_STATE, async ({ project_id, clear }) => {
|
|
212
|
+
try {
|
|
213
|
+
if (clear || !normalizeProjectId(project_id)) {
|
|
214
|
+
activeProjectId = null;
|
|
215
|
+
return { content: [{ type: 'text', text: 'Active project cleared. Handoff/insight generation requires selecting a project.' }] };
|
|
216
|
+
}
|
|
217
|
+
const context = await getTenantContext();
|
|
218
|
+
const selected = context.projects.find((project) => project.id === project_id);
|
|
219
|
+
if (!selected) {
|
|
220
|
+
return {
|
|
221
|
+
content: [{
|
|
222
|
+
type: 'text',
|
|
223
|
+
text: `Project not found or inaccessible: ${project_id}. Run list_projects first.`,
|
|
224
|
+
}],
|
|
225
|
+
};
|
|
226
|
+
}
|
|
227
|
+
activeProjectId = selected.id;
|
|
228
|
+
return {
|
|
229
|
+
content: [{
|
|
230
|
+
type: 'text',
|
|
231
|
+
text: `Active project set to ${selected.name} (${selected.id}).`,
|
|
232
|
+
}],
|
|
233
|
+
};
|
|
234
|
+
}
|
|
235
|
+
catch (err) {
|
|
236
|
+
return { content: [{ type: 'text', text: `Could not set active project: ${err.message}` }] };
|
|
237
|
+
}
|
|
238
|
+
});
|
|
239
|
+
// ── Tool: list handoffs ──────────────────────────────────────────────
|
|
240
|
+
server.tool('list_handoffs', 'List existing handoffs (newest first) with their full content, across all accessible projects or one project. Use this to read what has already been generated before spending credits on a new generate_handoff. Each row\'s id can be sent to Discord via discord_send_message.', {
|
|
241
|
+
status: z.enum(['active', 'archived', 'all']).default('active').describe('active = current handoffs, archived = superseded ones, all = both.'),
|
|
242
|
+
limit: z.number().int().min(1).max(50).default(10).describe('Max handoffs to return (1-50, default 10).'),
|
|
243
|
+
project_id: z.string().optional().describe('Project id (from list_projects) to scope to. Omit to span every accessible project, or rely on the active project.'),
|
|
244
|
+
}, READ_ONLY, async ({ status, limit, project_id }) => {
|
|
245
|
+
try {
|
|
246
|
+
const explicitProjectId = normalizeProjectId(project_id);
|
|
247
|
+
const resolvedProjectId = explicitProjectId ?? activeProjectId;
|
|
248
|
+
let resolvedProject = null;
|
|
249
|
+
if (resolvedProjectId) {
|
|
250
|
+
const context = await getTenantContext();
|
|
251
|
+
resolvedProject = context.projects.find((p) => p.id === resolvedProjectId) ?? null;
|
|
252
|
+
if (!resolvedProject)
|
|
253
|
+
activeProjectId = null;
|
|
254
|
+
}
|
|
255
|
+
const { handoffs } = await api.listHandoffs(status, limit, resolvedProject?.id ?? null);
|
|
256
|
+
if (handoffs.length === 0) {
|
|
257
|
+
const scopeLabel = resolvedProject ? formatProjectScope(resolvedProject) : 'all projects';
|
|
258
|
+
return { content: [{ type: 'text', text: `No ${status} handoffs found in scope: ${scopeLabel}.` }] };
|
|
259
|
+
}
|
|
260
|
+
const text = handoffs.map((h) => {
|
|
261
|
+
let out = `## ${h.title}\n`;
|
|
262
|
+
out += `**Status:** ${h.status} · **Sources:** ${h.sources.join(', ') || 'all'}\n`;
|
|
263
|
+
out += `**Project:** ${h.project_name ?? 'Unknown'}\n`;
|
|
264
|
+
out += `**Created:** ${new Date(h.created_at).toLocaleString()}\n\n`;
|
|
265
|
+
out += `${h.summary}\n`;
|
|
266
|
+
if (h.key_changes?.length)
|
|
267
|
+
out += `\n**Key changes:**\n${h.key_changes.map((c) => `- ${c}`).join('\n')}\n`;
|
|
268
|
+
if (h.decisions.length)
|
|
269
|
+
out += `\n**Decisions:**\n${h.decisions.map((d) => `- ${d}`).join('\n')}\n`;
|
|
270
|
+
if (h.next_steps.length)
|
|
271
|
+
out += `\n**Next steps:**\n${h.next_steps.map((s) => `- ${s}`).join('\n')}\n`;
|
|
272
|
+
if (h.open_questions.length)
|
|
273
|
+
out += `\n**Open questions:**\n${h.open_questions.map((q) => `- ${q}`).join('\n')}\n`;
|
|
274
|
+
return out;
|
|
275
|
+
}).join('\n---\n\n');
|
|
276
|
+
return { content: [{ type: 'text', text }] };
|
|
277
|
+
}
|
|
278
|
+
catch (err) {
|
|
279
|
+
return { content: [{ type: 'text', text: `Could not list handoffs: ${err.message}` }] };
|
|
280
|
+
}
|
|
281
|
+
});
|
|
282
|
+
// ── Tool: generate handoff ───────────────────────────────────────────
|
|
283
|
+
server.tool('generate_handoff', 'Generate a project handoff: an AI summary of recent activity, key changes, decisions, open questions and next steps for a project. Runs synchronously – waits for completion (tens of seconds) and returns the finished Markdown. Requires an active project (set_active_project) or an explicit project_id from list_projects. Consumes credits from the user\'s plan, charged once on success – prefer list_handoffs to read an existing one before generating a new one. To scope it, pass sources and/or filters (call list_filter_options first for valid values); omit both to use the project\'s saved scope preferences.', {
|
|
284
|
+
sources: z.array(SourceEnum)
|
|
285
|
+
.optional()
|
|
286
|
+
.describe('Restrict to these source ids (omit for all connected sources). Unknown source ids are rejected with 400.'),
|
|
287
|
+
filters: FiltersSchema,
|
|
288
|
+
project_id: z.string().optional().describe('Project id from list_projects. Overrides the active project for this call; required if no active project is set.'),
|
|
289
|
+
}, MUTATING, async ({ sources, filters, project_id }) => {
|
|
290
|
+
try {
|
|
291
|
+
const resolved = await requireProject(project_id);
|
|
292
|
+
const { jobId } = await api.generateHandoff(sources, filters, resolved.projectId);
|
|
293
|
+
const { job, result } = await api.waitForJob(jobId);
|
|
294
|
+
if (job.status === 'failed' || !result) {
|
|
295
|
+
const reason = job.error ?? 'unknown error';
|
|
296
|
+
return { content: [{ type: 'text', text: `Could not generate handoff: ${reason}` }] };
|
|
297
|
+
}
|
|
298
|
+
const handoff = result;
|
|
299
|
+
// Server renders the canonical Markdown; fall back for pre-markdown servers.
|
|
300
|
+
const text = handoff.markdown ?? `# ${handoff.title}\n\n${handoff.summary}\n`;
|
|
301
|
+
return { content: [{ type: 'text', text }] };
|
|
302
|
+
}
|
|
303
|
+
catch (err) {
|
|
304
|
+
return { content: [{ type: 'text', text: `Could not generate handoff: ${err.message}` }] };
|
|
305
|
+
}
|
|
306
|
+
});
|
|
307
|
+
// ── Tool: list integrations ─────────────────────────────────────────
|
|
308
|
+
server.tool('list_integrations', 'List connected integrations. With a project scope it returns the resources bound to that project plus their health (connection status, provider coverage); without one it returns the sources the API key owner has connected. Use it to check what data a generation can draw on.', {
|
|
309
|
+
project_id: z.string().optional().describe('Project id (from list_projects) for project-scoped resources. Omit (or rely on the active project) for the owner\'s connected sources.'),
|
|
310
|
+
}, READ_ONLY, async ({ project_id }) => {
|
|
311
|
+
try {
|
|
312
|
+
const resolved = await resolveProject(project_id);
|
|
313
|
+
const { integrations } = await api.listIntegrations(resolved.projectId);
|
|
314
|
+
if (integrations.length === 0) {
|
|
315
|
+
if (resolved.project) {
|
|
316
|
+
return { content: [{ type: 'text', text: `No integrations configured for project ${resolved.project.name}.` }] };
|
|
317
|
+
}
|
|
318
|
+
return { content: [{ type: 'text', text: 'No integrations connected. Visit https://www.flowrelay.it/integrations to set up.' }] };
|
|
319
|
+
}
|
|
320
|
+
const text = integrations.map((i) => {
|
|
321
|
+
const name = i.workspace_name ? ` (${i.workspace_name})` : '';
|
|
322
|
+
if (i.scope === 'project') {
|
|
323
|
+
const status = i.connection_status ?? 'unknown';
|
|
324
|
+
const providers = i.providers_connected ?? 0;
|
|
325
|
+
return `- **${i.source}**${name} – status: ${status}, providers connected: ${providers}`;
|
|
326
|
+
}
|
|
327
|
+
return `- **${i.source}**${name} – connected ${new Date(i.connected_at).toLocaleDateString()}`;
|
|
328
|
+
}).join('\n');
|
|
329
|
+
return { content: [{ type: 'text', text: `**Connected integrations:**\n${text}` }] };
|
|
330
|
+
}
|
|
331
|
+
catch (err) {
|
|
332
|
+
return { content: [{ type: 'text', text: `Could not list integrations: ${err.message}` }] };
|
|
333
|
+
}
|
|
334
|
+
});
|
|
335
|
+
// ── Tool: list untracked resources ───────────────────────────────────
|
|
336
|
+
server.tool('list_untracked_resources', 'List active resources (repos, channels, boards) that produced events recently but are not yet assigned to any project. Use it to spot data the user connected but has not organized into a project yet – mapping them (in the web dashboard) makes their events available to generations.', {}, READ_ONLY, async () => {
|
|
337
|
+
try {
|
|
338
|
+
const resources = await api.listUntrackedResources();
|
|
339
|
+
if (resources.length === 0) {
|
|
340
|
+
return {
|
|
341
|
+
content: [{
|
|
342
|
+
type: 'text',
|
|
343
|
+
text: 'All discovered active resources are already tracked in your projects. Good job!',
|
|
344
|
+
}],
|
|
345
|
+
};
|
|
346
|
+
}
|
|
347
|
+
const text = resources.map((r) => {
|
|
348
|
+
return `- **[${r.source}]** ${r.resource_name} (type: ${r.resource_type}, id: ${r.resource_id})`;
|
|
349
|
+
}).join('\n');
|
|
350
|
+
return {
|
|
351
|
+
content: [{
|
|
352
|
+
type: 'text',
|
|
353
|
+
text: `**Untracked active resources:**\n${text}\n\n*Note: Map these resources to Flow Relay projects in the web dashboard or CLI to start tracking their events.*`,
|
|
354
|
+
}],
|
|
355
|
+
};
|
|
356
|
+
}
|
|
357
|
+
catch (err) {
|
|
358
|
+
return { content: [{ type: 'text', text: `Failed to list untracked resources: ${err.message}` }] };
|
|
359
|
+
}
|
|
360
|
+
});
|
|
361
|
+
// ── Tool: list recent events ─────────────────────────────────────────
|
|
362
|
+
server.tool('list_events', 'List recent raw context events (individual pieces of tracked activity: a push, a message, an issue update) newest first. Use it to inspect the underlying signal a generation would draw on, or to check whether a source is producing data. With a project scope it is limited to that project\'s bound resources.', {
|
|
363
|
+
source: SourceEnum
|
|
364
|
+
.optional()
|
|
365
|
+
.describe('Restrict to one source id (e.g. "github"). Unknown ids are rejected with 400.'),
|
|
366
|
+
limit: z.number().int().min(1).max(100).default(20).describe('Max events to return (1-100, default 20).'),
|
|
367
|
+
project_id: z.string().optional().describe('Project id (from list_projects) to scope to. Omit (or rely on the active project) for the owner\'s personal-stream events.'),
|
|
368
|
+
}, READ_ONLY, async ({ source, limit, project_id }) => {
|
|
369
|
+
try {
|
|
370
|
+
const resolved = await resolveProject(project_id);
|
|
371
|
+
const { events } = await api.listEvents(source, limit, resolved.projectId);
|
|
372
|
+
if (events.length === 0) {
|
|
373
|
+
const scopeLabel = formatProjectScope(resolved.project);
|
|
374
|
+
return { content: [{ type: 'text', text: `No recent events${source ? ` from ${source}` : ''} in scope: ${scopeLabel}.` }] };
|
|
375
|
+
}
|
|
376
|
+
const text = events.map((e) => {
|
|
377
|
+
const time = new Date(e.created_at).toLocaleString();
|
|
378
|
+
const author = e.user_id ? ` user=${e.user_id}` : '';
|
|
379
|
+
return `- **[${e.source}/${e.event_type}]** ${e.title} _(${time})_${author}`;
|
|
380
|
+
}).join('\n');
|
|
381
|
+
return { content: [{ type: 'text', text: `**Recent events:**\n${text}` }] };
|
|
382
|
+
}
|
|
383
|
+
catch (err) {
|
|
384
|
+
return { content: [{ type: 'text', text: `Could not list events: ${err.message}` }] };
|
|
385
|
+
}
|
|
386
|
+
});
|
|
387
|
+
// ── Tool: discord list channels ──────────────────────────────────────
|
|
388
|
+
server.tool('discord_list_channels', 'List the text channels in the Discord server connected to this account, each with its id. Call this to get a channel_id before discord_send_message.', {}, READ_ONLY, async () => {
|
|
389
|
+
try {
|
|
390
|
+
const { channels } = await api.discordListChannels();
|
|
391
|
+
if (channels.length === 0) {
|
|
392
|
+
return { content: [{ type: 'text', text: 'No text channels found in the connected Discord server.' }] };
|
|
393
|
+
}
|
|
394
|
+
const text = channels.map((ch) => {
|
|
395
|
+
const topic = ch.topic ? ` – ${ch.topic}` : '';
|
|
396
|
+
return `- **#${ch.name}** (${ch.id})${topic}`;
|
|
397
|
+
}).join('\n');
|
|
398
|
+
return { content: [{ type: 'text', text: `**Discord channels:**\n${text}` }] };
|
|
399
|
+
}
|
|
400
|
+
catch (err) {
|
|
401
|
+
return { content: [{ type: 'text', text: `Could not list Discord channels: ${err.message}` }] };
|
|
402
|
+
}
|
|
403
|
+
});
|
|
404
|
+
// ── Tool: discord send message ──────────────────────────────────────
|
|
405
|
+
server.tool('discord_send_message', 'Send to a Discord channel in your connected server. Provide exactly one of: content (inline text); handoff_id or insight_id (sends that artifact, rendered to Markdown, as a .md file attachment); or artifact (last_handoff / last_correlation / last_onboarding / last_architecture / last_release_notes, with project_id) to send the latest active artifact of that kind.', {
|
|
406
|
+
channel_id: z.string().describe('Discord channel id from discord_list_channels.'),
|
|
407
|
+
content: z.string().optional().describe('Inline message text. Mutually exclusive with handoff_id / insight_id / artifact'),
|
|
408
|
+
handoff_id: z.string().optional().describe('Id of a handoff (from list_handoffs) to render and attach as a .md file'),
|
|
409
|
+
insight_id: z.string().optional().describe('Id of an insight (from list_insights) to render and attach as a .md file'),
|
|
410
|
+
artifact: z
|
|
411
|
+
.enum(['last_handoff', 'last_correlation', 'last_onboarding', 'last_architecture', 'last_release_notes'])
|
|
412
|
+
.optional()
|
|
413
|
+
.describe('Send the latest active artifact of this kind. Requires project_id'),
|
|
414
|
+
project_id: z.string().optional().describe('Project UUID. Required only when artifact is set'),
|
|
415
|
+
}, MUTATING, async ({ channel_id, content, handoff_id, insight_id, artifact, project_id, }) => {
|
|
416
|
+
if (!content && !handoff_id && !insight_id && !artifact) {
|
|
417
|
+
return { content: [{ type: 'text', text: 'Provide content, handoff_id, insight_id, or artifact.' }] };
|
|
418
|
+
}
|
|
419
|
+
try {
|
|
420
|
+
const result = await api.discordSendMessage(channel_id, { content, handoff_id, insight_id, artifact, project_id });
|
|
421
|
+
return { content: [{ type: 'text', text: `Message sent (ID: ${result.message_id})` }] };
|
|
422
|
+
}
|
|
423
|
+
catch (err) {
|
|
424
|
+
return { content: [{ type: 'text', text: `Failed to send message: ${err.message}` }] };
|
|
425
|
+
}
|
|
426
|
+
});
|
|
427
|
+
// ── Tool: generate correlation insight ──────────────────────────────
|
|
428
|
+
server.tool('generate_correlation_insight', 'Generate a cross-source correlation insight: finds related events across different sources (e.g. a Slack thread, a Jira ticket and the PR that resolved it) and surfaces the links, patterns and open threads. Use when the user wants to understand how activity connects across tools. Runs synchronously and returns Markdown. Consumes credits, charged once on success. Call list_filter_options before using filters.', {
|
|
429
|
+
project_id: z.string().describe('Project id from list_projects to generate the insight for.'),
|
|
430
|
+
sources: z.array(SourceEnum).optional().describe('Restrict to these source ids (e.g. "github", "slack"). Unknown ids are rejected with 400.'),
|
|
431
|
+
filters: FiltersSchema,
|
|
432
|
+
lookback_hours: z.number().int().optional().describe('Hours of activity to analyze (1-2160, default 168 = 7 days).'),
|
|
433
|
+
max_events: z.number().int().optional().describe('Cap on events processed (1-1000, default 150).'),
|
|
434
|
+
}, MUTATING, async ({ project_id, sources, filters, lookback_hours, max_events }) => {
|
|
435
|
+
try {
|
|
436
|
+
const res = await api.generateInsight(project_id, 'correlation', {
|
|
437
|
+
sources,
|
|
438
|
+
filters,
|
|
439
|
+
lookbackHours: lookback_hours,
|
|
440
|
+
maxEvents: max_events,
|
|
441
|
+
});
|
|
442
|
+
const { job, result } = await api.waitForJob(res.jobId);
|
|
443
|
+
if (job.status === 'failed' || !result) {
|
|
444
|
+
const reason = job.error ?? 'unknown error';
|
|
445
|
+
return { content: [{ type: 'text', text: `Could not generate correlation insight: ${reason}` }] };
|
|
446
|
+
}
|
|
447
|
+
const insight = result;
|
|
448
|
+
return { content: [{ type: 'text', text: insight.markdown ?? `# ${insight.title}\n\n${insight.summary}` }] };
|
|
449
|
+
}
|
|
450
|
+
catch (err) {
|
|
451
|
+
return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
|
|
452
|
+
}
|
|
453
|
+
});
|
|
454
|
+
// ── Tool: generate onboarding brief ──────────────────────────────────
|
|
455
|
+
server.tool('generate_onboarding_brief', 'Generate an onboarding brief: a getting-started guide for someone new to the project – key people, key decisions, pitfalls and recommended reading drawn from recent activity. Use when a new team member needs to get up to speed. Runs synchronously and returns Markdown. Consumes credits, charged once on success. Call list_filter_options before using filters.', {
|
|
456
|
+
project_id: z.string().describe('Project id from list_projects to generate the brief for.'),
|
|
457
|
+
sources: z.array(SourceEnum).optional().describe('Restrict to these source ids. Unknown ids are rejected with 400.'),
|
|
458
|
+
filters: FiltersSchema,
|
|
459
|
+
new_member_role: z.string().optional().describe('Role/focus of the person being onboarded (e.g. "backend engineer"). Tailors the brief.'),
|
|
460
|
+
focus_area: z.string().optional().describe('Repository or feature area they will work on. Narrows the brief.'),
|
|
461
|
+
lookback_days: z.number().int().optional().describe('Days of history to review (1-365, default 30).'),
|
|
462
|
+
max_events: z.number().int().optional().describe('Cap on events processed (1-1000, default 400).'),
|
|
463
|
+
}, MUTATING, async ({ project_id, sources, filters, new_member_role, focus_area, lookback_days, max_events }) => {
|
|
464
|
+
try {
|
|
465
|
+
const res = await api.generateInsight(project_id, 'onboarding', {
|
|
466
|
+
sources,
|
|
467
|
+
filters,
|
|
468
|
+
newMemberRole: new_member_role,
|
|
469
|
+
focusArea: focus_area,
|
|
470
|
+
lookbackDays: lookback_days,
|
|
471
|
+
maxEvents: max_events,
|
|
472
|
+
});
|
|
473
|
+
const { job, result } = await api.waitForJob(res.jobId);
|
|
474
|
+
if (job.status === 'failed' || !result) {
|
|
475
|
+
const reason = job.error ?? 'unknown error';
|
|
476
|
+
return { content: [{ type: 'text', text: `Could not generate onboarding brief: ${reason}` }] };
|
|
477
|
+
}
|
|
478
|
+
const insight = result;
|
|
479
|
+
return { content: [{ type: 'text', text: insight.markdown ?? `# ${insight.title}\n\n${insight.summary}` }] };
|
|
480
|
+
}
|
|
481
|
+
catch (err) {
|
|
482
|
+
return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
|
|
483
|
+
}
|
|
484
|
+
});
|
|
485
|
+
// ── Tool: generate architecture insight ─────────────────────────────
|
|
486
|
+
server.tool('generate_architecture_insight', 'Generate an architecture insight: trade-offs, risks, patterns and recommendations inferred from the project\'s code activity (requires a connected code source – github, gitlab, bitbucket or azure_devops). This is the deepest and most expensive insight (it runs extended reasoning). Use for technical review of architectural direction. Runs synchronously and returns Markdown. Consumes credits, charged once on success. Call list_filter_options before using filters.', {
|
|
487
|
+
project_id: z.string().describe('Project id from list_projects to generate the insight for.'),
|
|
488
|
+
sources: z.array(SourceEnum).optional().describe('Restrict to these source ids. Unknown ids are rejected with 400.'),
|
|
489
|
+
filters: FiltersSchema,
|
|
490
|
+
focus_question: z.string().optional().describe('A specific architectural question or component to investigate (e.g. "is the billing layer coupled to providers?").'),
|
|
491
|
+
lookback_days: z.number().int().optional().describe('Days of history to review (1-365, default 14).'),
|
|
492
|
+
max_events: z.number().int().optional().describe('Cap on events processed (1-1000, default 250).'),
|
|
493
|
+
}, MUTATING, async ({ project_id, sources, filters, focus_question, lookback_days, max_events }) => {
|
|
494
|
+
try {
|
|
495
|
+
const res = await api.generateInsight(project_id, 'architecture', {
|
|
496
|
+
sources,
|
|
497
|
+
filters,
|
|
498
|
+
focusQuestion: focus_question,
|
|
499
|
+
lookbackDays: lookback_days,
|
|
500
|
+
maxEvents: max_events,
|
|
501
|
+
});
|
|
502
|
+
const { job, result } = await api.waitForJob(res.jobId);
|
|
503
|
+
if (job.status === 'failed' || !result) {
|
|
504
|
+
const reason = job.error ?? 'unknown error';
|
|
505
|
+
return { content: [{ type: 'text', text: `Could not generate architecture insight: ${reason}` }] };
|
|
506
|
+
}
|
|
507
|
+
const insight = result;
|
|
508
|
+
return { content: [{ type: 'text', text: insight.markdown ?? `# ${insight.title}\n\n${insight.summary}` }] };
|
|
509
|
+
}
|
|
510
|
+
catch (err) {
|
|
511
|
+
return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
|
|
512
|
+
}
|
|
513
|
+
});
|
|
514
|
+
// ── Tool: list insights ─────────────────────────────────────────────
|
|
515
|
+
server.tool('generate_release_notes', 'Generate release notes or a PR description from recent code activity (commits, PRs, builds). Runs synchronously and returns Markdown. Consumes 3 credits on success.', {
|
|
516
|
+
project_id: z.string().describe('Project id from list_projects.'),
|
|
517
|
+
source: SourceEnum.default('github').describe('Code source id (github, gitlab, bitbucket, azure_devops).'),
|
|
518
|
+
repo: z.string().optional().describe('Repository name to scope changes to.'),
|
|
519
|
+
style: z.enum(['release_notes', 'pr_description']).default('release_notes').describe('Output style.'),
|
|
520
|
+
filters: FiltersSchema,
|
|
521
|
+
}, MUTATING, async ({ project_id, source, repo, style, filters }) => {
|
|
522
|
+
try {
|
|
523
|
+
const res = await api.generateInsight(project_id, 'release_notes', { source, repo, style, filters });
|
|
524
|
+
const { job, result } = await api.waitForJob(res.jobId);
|
|
525
|
+
if (job.status === 'failed' || !result) {
|
|
526
|
+
const reason = job.error ?? 'unknown error';
|
|
527
|
+
return { content: [{ type: 'text', text: `Could not generate release notes: ${reason}` }] };
|
|
528
|
+
}
|
|
529
|
+
const insight = result;
|
|
530
|
+
return { content: [{ type: 'text', text: insight.markdown ?? `# ${insight.title}\n\n${insight.summary}` }] };
|
|
531
|
+
}
|
|
532
|
+
catch (err) {
|
|
533
|
+
return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
|
|
534
|
+
}
|
|
535
|
+
});
|
|
536
|
+
server.tool('list_digests', 'List past scheduled activity digests for a project.', {
|
|
537
|
+
project_id: z.string().describe('Project id from list_projects.'),
|
|
538
|
+
limit: z.number().int().min(1).max(50).default(10).describe('Max digests to return (1-50, default 10).'),
|
|
539
|
+
}, READ_ONLY, async ({ project_id, limit }) => {
|
|
540
|
+
try {
|
|
541
|
+
const { digests } = await api.listDigests(project_id, limit);
|
|
542
|
+
if (digests.length === 0) {
|
|
543
|
+
return { content: [{ type: 'text', text: 'No digests found for this project.' }] };
|
|
544
|
+
}
|
|
545
|
+
const text = digests.map((d) => d.markdown).join('\n\n---\n\n');
|
|
546
|
+
return { content: [{ type: 'text', text }] };
|
|
547
|
+
}
|
|
548
|
+
catch (err) {
|
|
549
|
+
return { content: [{ type: 'text', text: `Failed to list digests: ${err.message}` }] };
|
|
550
|
+
}
|
|
551
|
+
});
|
|
552
|
+
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.', {
|
|
553
|
+
project_id: z.string().describe('Project id from list_projects to list insights for.'),
|
|
554
|
+
kind: z.enum(['onboarding_brief', 'cross_source_correlation', 'architecture_insight', 'release_notes']).optional().describe('Restrict to one kind. Omit for all kinds.'),
|
|
555
|
+
status: z.enum(['active', 'archived', 'all']).default('active').describe('active = current, archived = superseded, all = both.'),
|
|
556
|
+
limit: z.number().int().min(1).max(50).default(20).describe('Max insights to return (1-50, default 20).'),
|
|
557
|
+
}, READ_ONLY, async ({ project_id, kind, status, limit }) => {
|
|
558
|
+
try {
|
|
559
|
+
const { insights } = await api.listInsights(project_id, kind, status, limit);
|
|
560
|
+
if (insights.length === 0) {
|
|
561
|
+
return { content: [{ type: 'text', text: `No ${status} insights found.` }] };
|
|
562
|
+
}
|
|
563
|
+
const text = insights.map((insight) => {
|
|
564
|
+
return `## ${insight.title} (${insight.kind})\n**Status:** ${insight.status} · **Created:** ${new Date(insight.created_at).toLocaleString()}\n\n${insight.summary}`;
|
|
565
|
+
}).join('\n---\n\n');
|
|
566
|
+
return { content: [{ type: 'text', text }] };
|
|
567
|
+
}
|
|
568
|
+
catch (err) {
|
|
569
|
+
return { content: [{ type: 'text', text: `Failed to list insights: ${err.message}` }] };
|
|
570
|
+
}
|
|
571
|
+
});
|
|
572
|
+
// ── Tool: ask project ───────────────────────────────────────────────
|
|
573
|
+
server.tool('ask_project', 'Ask one question about a project and get an answer grounded in its indexed codebase, connected baselines and last 14 days of activity. Answers synchronously – there is no job to poll. Costs 2 credits per question, so prefer list_handoffs / list_insights when an existing artifact already answers it.', {
|
|
574
|
+
question: z.string().min(1).max(2000).describe('The question, 1-2000 characters.'),
|
|
575
|
+
project_id: z.string().optional().describe('Project scope. Omit to use the active project.'),
|
|
576
|
+
}, MUTATING, async ({ question, project_id }) => {
|
|
577
|
+
try {
|
|
578
|
+
const resolved = await requireProject(project_id);
|
|
579
|
+
const { answer, citations } = await api.askProject(resolved.projectId, question);
|
|
580
|
+
const refs = citations.length > 0 ? `\n\n_Evidence: ${citations.join(' ')}_` : '';
|
|
581
|
+
return { content: [{ type: 'text', text: `${answer}${refs}` }] };
|
|
582
|
+
}
|
|
583
|
+
catch (err) {
|
|
584
|
+
return { content: [{ type: 'text', text: `Could not answer: ${err.message}` }] };
|
|
585
|
+
}
|
|
586
|
+
});
|
|
587
|
+
// ── Tool: list filter options ───────────────────────────────────────
|
|
588
|
+
server.tool('list_filter_options', 'List the real per-source filter values (resources, branches, event types, priorities) available for a project. Call this BEFORE generate_handoff or any generate_*_insight so the "filters" argument uses real values instead of guesses. Pass a resource id into filters[source].projects, a branch name into .branches, an event type into .eventTypes, a priority into .priorities.', {
|
|
589
|
+
project_id: z.string().optional().describe('Project scope. Omit to use the active project.'),
|
|
590
|
+
}, READ_ONLY, async ({ project_id }) => {
|
|
591
|
+
try {
|
|
592
|
+
const resolved = await requireProject(project_id);
|
|
593
|
+
const { filters, figma } = await api.getHandoffFilters(resolved.projectId);
|
|
594
|
+
const sources = Object.keys(filters);
|
|
595
|
+
if (sources.length === 0) {
|
|
596
|
+
return { content: [{ type: 'text', text: `No connected sources with filter options for ${resolved.project.name}.` }] };
|
|
597
|
+
}
|
|
598
|
+
const blocks = sources.map((src) => {
|
|
599
|
+
const f = filters[src];
|
|
600
|
+
const lines = [`### ${src}`];
|
|
601
|
+
if (f.projects?.length) {
|
|
602
|
+
const items = f.projects.slice(0, 50).map((p) => (p.label && p.label !== p.id ? `${p.label} (id: ${p.id})` : p.id));
|
|
603
|
+
const more = f.projects.length > 50 ? ` (+${f.projects.length - 50} more)` : '';
|
|
604
|
+
lines.push(`- Resources: ${items.join(', ')}${more}`);
|
|
605
|
+
}
|
|
606
|
+
if (f.branches?.length)
|
|
607
|
+
lines.push(`- Branches: ${f.branches.map((b) => b.value).join(', ')}`);
|
|
608
|
+
if (f.eventTypes?.length)
|
|
609
|
+
lines.push(`- Event types: ${f.eventTypes.map((e) => e.value).join(', ')}`);
|
|
610
|
+
if (f.priorities?.length)
|
|
611
|
+
lines.push(`- Priorities: ${f.priorities.map((p) => p.value).join(', ')}`);
|
|
612
|
+
return lines.join('\n');
|
|
613
|
+
});
|
|
614
|
+
if (figma && !figma.selectable) {
|
|
615
|
+
blocks.push('### figma\n- NOT selectable on this project: Figma visual context requires the Global processing region. ' +
|
|
616
|
+
(figma.canManageResidency
|
|
617
|
+
? 'Switch the project to Global in its Data Residency settings first.'
|
|
618
|
+
: 'Ask an organization admin to switch the project to Global first.'));
|
|
619
|
+
}
|
|
620
|
+
return { content: [{ type: 'text', text: `Filter options for ${resolved.project.name}:\n\n${blocks.join('\n\n')}` }] };
|
|
621
|
+
}
|
|
622
|
+
catch (err) {
|
|
623
|
+
return { content: [{ type: 'text', text: `Could not load filter options: ${err.message}` }] };
|
|
624
|
+
}
|
|
625
|
+
});
|
|
626
|
+
return server;
|
|
627
|
+
}
|