@flowrelay/mcp-server 1.0.4 → 1.0.6

package/dist/index.js

@@ -5,6 +5,9 @@ import { z } from 'zod';
 import { FlowRelayAPI } from './api.js';
 import { createRequire } from 'node:module';
 const { version: PKG_VERSION } = createRequire(import.meta.url)('../package.json');
+// Canonical source vocabulary. Mirrors ALL_SOURCES in the web app's @/types
+// (this is a separate published package, so it can't import it). The parity
+// test tests/client-source-parity.test.ts fails if the two ever diverge.
 const SOURCES = [
     'github',
     'slack',
@@ -21,17 +24,20 @@ const SOURCES = [
     'microsoft_teams',
     'sentry',
     'datadog',
+    'pagerduty',
+    'asana',
+    'gmail',
 ];
 const SourceEnum = z.enum(SOURCES);
 const SourceFilterSchema = z.object({
-    projects: z.array(z.string()).optional().describe('Filter to specific repos, channels, projects, or teams'),
-    eventTypes: z.array(z.string()).optional().describe('Filter to specific event types (e.g. "push", "issue_created")'),
-    branches: z.array(z.string()).optional().describe('Git branch names (e.g. "main", "develop") – versioning sources only'),
-    priorities: z.array(z.string()).optional().describe('Priority levels (e.g. "high", "urgent") – Jira, Linear, Sentry only'),
+    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.'),
+    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).'),
+    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.'),
+    priorities: z.array(z.string()).optional().describe('Priority values from list_filter_options (e.g. "high", "urgent") – jira, linear, sentry, pagerduty only. Using this on another source is a 400; unrecognized values simply match no events.'),
 });
 const FiltersSchema = z.record(z.string(), SourceFilterSchema)
     .optional()
-    .describe('Per-source advanced filters, AND-combined across dimensions');
+    .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.');
 function normalizeProjectId(value) {
     if (typeof value !== 'string')
         return null;
@@ -62,6 +68,26 @@ let activeProjectId = normalizeProjectId(process.env.FLOWRELAY_PROJECT_ID);
 const server = new McpServer({
     name: 'flowrelay',
     version: PKG_VERSION,
+    websiteUrl: 'https://www.flowrelay.it',
+    icons: [
+        { src: 'https://www.flowrelay.it/icon.png', mimeType: 'image/png', sizes: ['1024x1024'] },
+    ],
+}, {
+    instructions: [
+        '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:',
+        '- A HANDOFF: a snapshot of recent activity, decisions, open questions and next steps for a project – used to hand work off or catch up.',
+        '- 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).',
+        '',
+        'Typical flow:',
+        '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.',
+        '2. Optionally set_active_project so later tools can omit project_id.',
+        '3. Before generating with filters, call list_filter_options to get the real selectable values for that project.',
+        '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.',
+        '',
+        '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.',
+        '',
+        'Scope and access follow the API key\'s tenant role; a tool only ever sees projects the key can access.',
+    ].join('\n'),
 });
 async function getTenantContext() {
     const context = await api.listProjects();
@@ -99,7 +125,7 @@ async function requireProject(projectId) {
     return { projectId: resolvedProjectId, project };
 }
 // ── Tool: workspace context ─────────────────────────────────────────
-server.tool('get_workspace_context', 'Show Flow Relay tenant context: personal/business mode, active project scope, and current role.', {}, async () => {
+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.', {}, async () => {
     const context = await getTenantContext();
     const activeProject = activeProjectId
         ? context.projects.find((project) => project.id === activeProjectId) ?? null
@@ -118,7 +144,7 @@ server.tool('get_workspace_context', 'Show Flow Relay tenant context: personal/b
     return { content: [{ type: 'text', text: lines.join('\n') }] };
 });
 // ── Tool: list projects ─────────────────────────────────────────────
-server.tool('list_projects', 'List all projects available to this API key, including personal and organization projects with role information.', {}, async () => {
+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.', {}, async () => {
     const context = await getTenantContext();
     if (context.projects.length === 0) {
         return {
@@ -143,9 +169,9 @@ server.tool('list_projects', 'List all projects available to this API key, inclu
     };
 });
 // ── Tool: set active project ────────────────────────────────────────
-server.tool('set_active_project', 'Set or clear the active project context used by project-aware tools when project_id is omitted.', {
-    project_id: z.string().optional().describe('Project ID to set as active. Omit to clear.'),
-    clear: z.boolean().default(false).describe('Clear active project and use no-project personal scope.'),
+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.', {
+    project_id: z.string().optional().describe('Project id (from list_projects) to set as active. Omit, or set clear, to unset it.'),
+    clear: z.boolean().default(false).describe('Clear the active project. Generation then requires an explicit project_id again.'),
 }, async ({ project_id, clear }) => {
     if (clear || !normalizeProjectId(project_id)) {
         activeProjectId = null;
@@ -170,10 +196,10 @@ server.tool('set_active_project', 'Set or clear the active project context used
     };
 });
 // ── Tool: list handoffs ──────────────────────────────────────────────
-server.tool('list_handoffs', 'List Flow Relay handoffs in the current tenant scope (all accessible projects or selected project).', {
-    status: z.enum(['active', 'archived', 'all']).default('active').describe('Filter by status ("all" returns every status)'),
-    limit: z.number().min(1).max(50).default(10).describe('Max number of handoffs to return'),
-    project_id: z.string().optional().describe('Optional project scope override for this call.'),
+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.', {
+    status: z.enum(['active', 'archived', 'all']).default('active').describe('active = current handoffs, archived = superseded ones, all = both.'),
+    limit: z.number().int().min(1).max(50).default(10).describe('Max handoffs to return (1-50, default 10).'),
+    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.'),
 }, async ({ status, limit, project_id }) => {
     const explicitProjectId = normalizeProjectId(project_id);
     const resolvedProjectId = explicitProjectId ?? activeProjectId;
@@ -208,12 +234,12 @@ server.tool('list_handoffs', 'List Flow Relay handoffs in the current tenant sco
     return { content: [{ type: 'text', text }] };
 });
 // ── Tool: generate handoff ───────────────────────────────────────────
-server.tool('generate_handoff', 'Generate a new context handoff for the active project. Requires an active project or explicit project_id. Supports per-source filters.', {
+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.', {
     sources: z.array(SourceEnum)
         .optional()
-        .describe('Specific sources to include (omit for all connected sources)'),
+        .describe('Restrict to these source ids (omit for all connected sources). Unknown source ids are rejected with 400.'),
     filters: FiltersSchema,
-    project_id: z.string().optional().describe('Optional project scope override for this call.'),
+    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.'),
 }, async ({ sources, filters, project_id }) => {
     try {
         const resolved = await requireProject(project_id);
@@ -233,8 +259,8 @@ server.tool('generate_handoff', 'Generate a new context handoff for the active p
     }
 });
 // ── Tool: list integrations ─────────────────────────────────────────
-server.tool('list_integrations', 'List integrations in the current scope. In project scope this returns project resources with health metadata.', {
-    project_id: z.string().optional().describe('Optional project scope override for this call.'),
+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.', {
+    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.'),
 }, async ({ project_id }) => {
     const resolved = await resolveProject(project_id);
     const { integrations } = await api.listIntegrations(resolved.projectId);
@@ -256,7 +282,7 @@ server.tool('list_integrations', 'List integrations in the current scope. In pro
     return { content: [{ type: 'text', text: `**Connected integrations:**\n${text}` }] };
 });
 // ── Tool: list untracked resources ───────────────────────────────────
-server.tool('list_untracked_resources', 'List discovered active resources across all connected user integrations that have not yet been assigned to any project.', {}, async () => {
+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.', {}, async () => {
     try {
         const resources = await api.listUntrackedResources();
         if (resources.length === 0) {
@@ -282,12 +308,12 @@ server.tool('list_untracked_resources', 'List discovered active resources across
     }
 });
 // ── Tool: list recent events ─────────────────────────────────────────
-server.tool('list_events', 'List recent context events in current scope (personal or selected project).', {
+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.', {
     source: SourceEnum
         .optional()
-        .describe('Filter by integration source'),
-    limit: z.number().min(1).max(100).default(20).describe('Max number of events'),
-    project_id: z.string().optional().describe('Optional project scope override for this call.'),
+        .describe('Restrict to one source id (e.g. "github"). Unknown ids are rejected with 400.'),
+    limit: z.number().int().min(1).max(100).default(20).describe('Max events to return (1-100, default 20).'),
+    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.'),
 }, async ({ source, limit, project_id }) => {
     const resolved = await resolveProject(project_id);
     const { events } = await api.listEvents(source, limit, resolved.projectId);
@@ -303,7 +329,7 @@ server.tool('list_events', 'List recent context events in current scope (persona
     return { content: [{ type: 'text', text: `**Recent events:**\n${text}` }] };
 });
 // ── Tool: discord list channels ──────────────────────────────────────
-server.tool('discord_list_channels', 'List text channels in your connected Discord server.', {}, async () => {
+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.', {}, async () => {
     try {
         const { channels } = await api.discordListChannels();
         if (channels.length === 0) {
@@ -321,10 +347,10 @@ server.tool('discord_list_channels', 'List text channels in your connected Disco
 });
 // ── Tool: discord send message ──────────────────────────────────────
 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, with project_id) to send the latest active artifact of that kind.', {
-    channel_id: z.string().describe('The Discord channel ID to send to'),
+    channel_id: z.string().describe('Discord channel id from discord_list_channels.'),
     content: z.string().optional().describe('Inline message text. Mutually exclusive with handoff_id / insight_id / artifact'),
-    handoff_id: z.string().optional().describe('UUID of a handoff to render and attach as a .md file'),
-    insight_id: z.string().optional().describe('UUID of an insight to render and attach as a .md file'),
+    handoff_id: z.string().optional().describe('Id of a handoff (from list_handoffs) to render and attach as a .md file'),
+    insight_id: z.string().optional().describe('Id of an insight (from list_insights) to render and attach as a .md file'),
     artifact: z
         .enum(['last_handoff', 'last_correlation', 'last_onboarding', 'last_architecture'])
         .optional()
@@ -343,12 +369,12 @@ server.tool('discord_send_message', 'Send to a Discord channel in your connected
     }
 });
 // ── Tool: generate correlation insight ──────────────────────────────
-server.tool('generate_correlation_insight', 'Generate a cross-source correlation AI insight for the specified project scope.', {
-    project_id: z.string().describe('The project ID scope to generate the correlation insight for.'),
-    sources: z.array(SourceEnum).optional().describe('Filter events to specific sources (e.g. "github", "slack")'),
+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.', {
+    project_id: z.string().describe('Project id from list_projects to generate the insight for.'),
+    sources: z.array(SourceEnum).optional().describe('Restrict to these source ids (e.g. "github", "slack"). Unknown ids are rejected with 400.'),
     filters: FiltersSchema,
-    lookback_hours: z.number().optional().describe('Number of hours of activity to analyze'),
-    max_events: z.number().optional().describe('Maximum number of events to process'),
+    lookback_hours: z.number().int().optional().describe('Hours of activity to analyze (1-2160, default 168 = 7 days).'),
+    max_events: z.number().int().optional().describe('Cap on events processed (1-1000, default 150).'),
 }, async ({ project_id, sources, filters, lookback_hours, max_events }) => {
     try {
         const res = await api.generateInsight(project_id, 'correlation', {
@@ -370,14 +396,14 @@ server.tool('generate_correlation_insight', 'Generate a cross-source correlation
     }
 });
 // ── Tool: generate onboarding brief ──────────────────────────────────
-server.tool('generate_onboarding_brief', 'Generate an onboarding brief AI insight for the specified project scope.', {
-    project_id: z.string().describe('The project ID scope to generate the onboarding brief for.'),
-    sources: z.array(SourceEnum).optional().describe('Filter events to specific sources'),
+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.', {
+    project_id: z.string().describe('Project id from list_projects to generate the brief for.'),
+    sources: z.array(SourceEnum).optional().describe('Restrict to these source ids. Unknown ids are rejected with 400.'),
     filters: FiltersSchema,
-    new_member_role: z.string().optional().describe('Expected role/focus of the new team member'),
-    focus_area: z.string().optional().describe('Specific repository or feature area they will work on'),
-    lookback_days: z.number().optional().describe('Number of days of history to review'),
-    max_events: z.number().optional().describe('Maximum events to process'),
+    new_member_role: z.string().optional().describe('Role/focus of the person being onboarded (e.g. "backend engineer"). Tailors the brief.'),
+    focus_area: z.string().optional().describe('Repository or feature area they will work on. Narrows the brief.'),
+    lookback_days: z.number().int().optional().describe('Days of history to review (1-365, default 30).'),
+    max_events: z.number().int().optional().describe('Cap on events processed (1-1000, default 400).'),
 }, async ({ project_id, sources, filters, new_member_role, focus_area, lookback_days, max_events }) => {
     try {
         const res = await api.generateInsight(project_id, 'onboarding', {
@@ -401,13 +427,13 @@ server.tool('generate_onboarding_brief', 'Generate an onboarding brief AI insigh
     }
 });
 // ── Tool: generate architecture insight ─────────────────────────────
-server.tool('generate_architecture_insight', 'Generate an architecture insight AI insight for the specified project scope.', {
-    project_id: z.string().describe('The project ID scope to generate the architecture insight for.'),
-    sources: z.array(SourceEnum).optional().describe('Filter events to specific sources'),
+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.', {
+    project_id: z.string().describe('Project id from list_projects to generate the insight for.'),
+    sources: z.array(SourceEnum).optional().describe('Restrict to these source ids. Unknown ids are rejected with 400.'),
     filters: FiltersSchema,
-    focus_question: z.string().optional().describe('Specific architectural question or component to focus on'),
-    lookback_days: z.number().optional().describe('Number of days of history to review'),
-    max_events: z.number().optional().describe('Maximum events to process'),
+    focus_question: z.string().optional().describe('A specific architectural question or component to investigate (e.g. "is the billing layer coupled to providers?").'),
+    lookback_days: z.number().int().optional().describe('Days of history to review (1-365, default 14).'),
+    max_events: z.number().int().optional().describe('Cap on events processed (1-1000, default 250).'),
 }, async ({ project_id, sources, filters, focus_question, lookback_days, max_events }) => {
     try {
         const res = await api.generateInsight(project_id, 'architecture', {
@@ -430,11 +456,11 @@ server.tool('generate_architecture_insight', 'Generate an architecture insight A
     }
 });
 // ── Tool: list insights ─────────────────────────────────────────────
-server.tool('list_insights', 'List project AI insights for a selected project scope.', {
-    project_id: z.string().describe('The project ID context to list insights for.'),
-    kind: z.enum(['onboarding_brief', 'cross_source_correlation', 'architecture_insight']).optional().describe('Filter by insight kind'),
-    status: z.enum(['active', 'archived', 'all']).default('active').describe('Filter by status ("all" returns every status)'),
-    limit: z.number().min(1).max(50).default(20).describe('Max number of insights to return'),
+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.', {
+    project_id: z.string().describe('Project id from list_projects to list insights for.'),
+    kind: z.enum(['onboarding_brief', 'cross_source_correlation', 'architecture_insight']).optional().describe('Restrict to one kind (matches the three generate_*_insight tools). Omit for all kinds.'),
+    status: z.enum(['active', 'archived', 'all']).default('active').describe('active = current, archived = superseded, all = both.'),
+    limit: z.number().int().min(1).max(50).default(20).describe('Max insights to return (1-50, default 20).'),
 }, async ({ project_id, kind, status, limit }) => {
     try {
         const { insights } = await api.listInsights(project_id, kind, status, limit);

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@flowrelay/mcp-server",
-  "version": "1.0.4",
-  "description": "Flow Relay MCP Server for Claude Desktop and Claude Code – handoffs, integrations, and context events via natural conversation.",
+  "version": "1.0.6",
+  "description": "Flow Relay MCP Server for Claude Desktop and Claude Code – handoffs, integrations and context events via natural conversation.",
   "type": "module",
   "license": "MIT",
-  "author": "Adriano Sorbello",
+  "author": "atrisorb",
   "homepage": "https://www.flowrelay.it",
   "repository": {
     "type": "git",