@flowrelay/mcp-server 0.4.1 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@ It connects to Flow Relay API v1 using an API key and supports both:
 ## Package
 
 - Name: @flowrelay/mcp-server
-- Version: 0.4.1
+- Version: 0.6.0
 
 ## What Is Included
 
@@ -20,7 +20,11 @@ The server currently exposes these tools:
 - list_projects
 - set_active_project
 - list_handoffs
-- generate_handoff
+- generate_handoff (Note: Personal stream handoffs are synchronous. Project-scoped handoffs are processed asynchronously, and the server automatically polls until the job finishes.)
+- generate_correlation_insight
+- generate_onboarding_brief
+- generate_architecture_insight
+- list_insights
 - list_integrations
 - list_events
 - discord_list_channels

package/dist/api.d.ts

@@ -1,5 +1,5 @@
 /**
- * Flow Relay API client — talks to flowrelay.it/api/v1/*
+ * Flow Relay API client – talks to flowrelay.it/api/v1/*
  */
 export type AccountType = 'personal' | 'business';
 export type AccessRole = 'owner' | 'admin' | 'member';
@@ -28,51 +28,95 @@ export interface TenantContext {
     organizations: TenantOrganization[];
     projects: TenantProject[];
 }
+export type AiJobStatus = 'pending' | 'processing' | 'completed' | 'failed';
+export interface AiJob {
+    id: string;
+    project_id: string;
+    kind: string;
+    status: AiJobStatus;
+    result_kind: 'handoff' | 'insight' | null;
+    result_id: string | null;
+    error: string | null;
+    error_code: string | null;
+    error_meta: Record<string, unknown>;
+    created_at: string;
+    updated_at: string;
+}
+export interface HandoffResult {
+    id: string;
+    user_id: string;
+    project_id: string | null;
+    project_name?: string | null;
+    scope_type?: 'personal' | 'project';
+    title: string;
+    summary: string;
+    status: string;
+    sources: string[];
+    key_changes?: string[];
+    decisions: string[];
+    open_questions: string[];
+    next_steps: string[];
+    created_at: string;
+    updated_at?: string;
+}
+export interface InsightResult {
+    id: string;
+    project_id: string;
+    requested_by: string;
+    kind: 'onboarding_brief' | 'cross_source_correlation' | 'architecture_insight';
+    title: string;
+    summary: string;
+    data: Record<string, unknown>;
+    model_used: string;
+    token_usage: {
+        prompt_tokens: number;
+        completion_tokens: number;
+        total_tokens: number;
+    };
+    status: string;
+    related_event_ids: string[];
+    created_at: string;
+    updated_at?: string;
+}
+export type GenerateHandoffResponse = {
+    handoff: HandoffResult;
+} | {
+    jobId: string;
+    status: AiJobStatus;
+};
+export type GenerateInsightResponse = {
+    jobId: string;
+    status: AiJobStatus;
+};
 export declare class FlowRelayAPI {
     private baseUrl;
     private apiKey;
     constructor(apiKey: string, baseUrl?: string);
+    private requestRaw;
     private request;
     listProjects(): Promise<TenantContext>;
     listHandoffs(status?: string, limit?: number, projectId?: string | null): Promise<{
-        handoffs: Array<{
-            id: string;
-            user_id: string;
-            project_id: string | null;
-            project_name?: string | null;
-            scope_type?: "personal" | "project";
-            title: string;
-            summary: string;
-            status: string;
-            sources: string[];
-            key_changes?: string[];
-            decisions: string[];
-            open_questions: string[];
-            next_steps: string[];
-            created_at: string;
-            updated_at: string;
-        }>;
+        handoffs: HandoffResult[];
     }>;
     generateHandoff(sources?: string[], filters?: Record<string, {
         projects?: string[];
         eventTypes?: string[];
-    }>, projectId?: string | null): Promise<{
-        handoff: {
-            id: string;
-            user_id: string;
-            project_id: string | null;
-            project_name?: string | null;
-            scope_type?: "personal" | "project";
-            title: string;
-            summary: string;
-            sources: string[];
-            key_changes?: string[];
-            decisions: string[];
-            open_questions: string[];
-            next_steps: string[];
-            created_at: string;
-        };
+    }>, projectId?: string | null): Promise<GenerateHandoffResponse>;
+    getJob(jobId: string): Promise<{
+        job: AiJob;
+        result: HandoffResult | InsightResult | null;
+    }>;
+    waitForJob(jobId: string, opts?: {
+        intervalMs?: number;
+        timeoutMs?: number;
+    }): Promise<{
+        job: AiJob;
+        result: HandoffResult | InsightResult | null;
+    }>;
+    listInsights(projectId: string, kind?: string, status?: string, limit?: number): Promise<{
+        insights: InsightResult[];
     }>;
+    generateInsight(projectId: string, kind: 'correlation' | 'onboarding' | 'architecture', body?: Record<string, unknown>): Promise<GenerateInsightResponse>;
     listIntegrations(projectId?: string | null): Promise<{
         integrations: Array<{
             source: string;

package/dist/api.js

@@ -1,5 +1,5 @@
 /**
- * Flow Relay API client — talks to flowrelay.it/api/v1/*
+ * Flow Relay API client – talks to flowrelay.it/api/v1/*
  */
 const DEFAULT_BASE_URL = 'https://www.flowrelay.it';
 export class FlowRelayAPI {
@@ -9,7 +9,7 @@ export class FlowRelayAPI {
         this.apiKey = apiKey;
         this.baseUrl = baseUrl ?? DEFAULT_BASE_URL;
     }
-    async request(path, options) {
+    async requestRaw(path, options) {
         const url = `${this.baseUrl}/api/v1${path}`;
         const res = await fetch(url, {
             ...options,
@@ -23,10 +23,13 @@ export class FlowRelayAPI {
             const body = await res.json().catch(() => ({ error: res.statusText }));
             throw new Error(body.error ?? `API error ${res.status}`);
         }
-        if (res.status === 204) {
-            return {};
-        }
-        return res.json();
+        if (res.status === 204)
+            return { status: 204, body: {} };
+        return { status: res.status, body: (await res.json()) };
+    }
+    async request(path, options) {
+        const { body } = await this.requestRaw(path, options);
+        return body;
     }
     async listProjects() {
         return this.request('/projects');
@@ -47,10 +50,45 @@ export class FlowRelayAPI {
             body.filters = filters;
         if (projectId)
             body.project_id = projectId;
-        return this.request('/handoffs', {
+        const { status, body: data } = await this.requestRaw('/handoffs', {
             method: 'POST',
             body: JSON.stringify(body),
         });
+        // 202 → async job; 200 → inline handoff. Caller branches on the shape.
+        void status;
+        return data;
+    }
+    async getJob(jobId) {
+        return (await this.requestRaw(`/jobs/${jobId}`)).body;
+    }
+    async waitForJob(jobId, opts = {}) {
+        const intervalMs = opts.intervalMs ?? 2500;
+        const timeoutMs = opts.timeoutMs ?? 180_000; // 3 min hard cap
+        const deadline = Date.now() + timeoutMs;
+        while (true) {
+            const res = await this.getJob(jobId);
+            if (res.job.status === 'completed' || res.job.status === 'failed') {
+                return res;
+            }
+            if (Date.now() > deadline) {
+                throw new Error(`AI Job timed out after ${Math.round(timeoutMs / 1000)}s (job ${jobId} still ${res.job.status}).`);
+            }
+            await new Promise((r) => setTimeout(r, intervalMs));
+        }
+    }
+    async listInsights(projectId, kind, status = 'active', limit = 20) {
+        const params = new URLSearchParams();
+        if (kind)
+            params.set('kind', kind);
+        params.set('status', status);
+        params.set('limit', String(limit));
+        return this.request(`/projects/${projectId}/insights?${params.toString()}`);
+    }
+    async generateInsight(projectId, kind, body) {
+        return this.request(`/projects/${projectId}/insights/${kind}`, {
+            method: 'POST',
+            body: JSON.stringify(body ?? {}),
+        });
     }
     async listIntegrations(projectId) {
         const params = new URLSearchParams();

package/dist/index.js

@@ -50,7 +50,7 @@ const api = new FlowRelayAPI(apiKey, process.env.FLOWRELAY_BASE_URL);
 let activeProjectId = normalizeProjectId(process.env.FLOWRELAY_PROJECT_ID);
 const server = new McpServer({
     name: 'flowrelay',
-    version: '0.4.1',
+    version: '0.6.0',
 });
 async function getTenantContext() {
     const context = await api.listProjects();
@@ -189,11 +189,23 @@ server.tool('generate_handoff', 'Generate a new context handoff for personal sco
 }, async ({ sources, filters, project_id }) => {
     try {
         const resolved = await resolveProject(project_id);
-        const { handoff } = await api.generateHandoff(sources, filters, resolved.projectId);
+        const res = await api.generateHandoff(sources, filters, resolved.projectId);
+        // Async path (project handoff): poll until the worker finishes.
+        let handoff;
+        if ('jobId' in res) {
+            const { job, result } = await api.waitForJob(res.jobId);
+            if (job.status === 'failed' || !result) {
+                const reason = job.error ?? 'unknown error';
+                return { content: [{ type: 'text', text: `Could not generate handoff: ${reason}` }] };
+            }
+            handoff = result;
+        }
+        else {
+            handoff = res.handoff;
+        }
         let text = `# ${handoff.title}\n\n${handoff.summary}\n`;
-        if (handoff.project_name) {
+        if (handoff.project_name)
             text += `\n**Project:** ${handoff.project_name}\n`;
-        }
         text += `\n**Sources:** ${handoff.sources.join(', ')}\n`;
         if (handoff.key_changes?.length)
             text += `\n**Key changes:**\n${handoff.key_changes.map((c) => `- ${c}`).join('\n')}\n`;
@@ -224,9 +236,9 @@ server.tool('list_integrations', 'List integrations in the current scope. In pro
         if (i.scope === 'project') {
             const status = i.connection_status ?? 'unknown';
             const providers = i.providers_connected ?? 0;
-            return `- **${i.source}**${name} — status: ${status}, providers connected: ${providers}`;
+            return `- **${i.source}**${name} – status: ${status}, providers connected: ${providers}`;
         }
-        return `- **${i.source}**${name} — connected ${new Date(i.connected_at).toLocaleDateString()}`;
+        return `- **${i.source}**${name} – connected ${new Date(i.connected_at).toLocaleDateString()}`;
     }).join('\n');
     return { content: [{ type: 'text', text: `**Connected integrations:**\n${text}` }] };
 });
@@ -259,7 +271,7 @@ server.tool('discord_list_channels', 'List text channels in your connected Disco
             return { content: [{ type: 'text', text: 'No text channels found in the connected Discord server.' }] };
         }
         const text = channels.map((ch) => {
-            const topic = ch.topic ? ` — ${ch.topic}` : '';
+            const topic = ch.topic ? ` – ${ch.topic}` : '';
             return `- **#${ch.name}** (${ch.id})${topic}`;
         }).join('\n');
         return { content: [{ type: 'text', text: `**Discord channels:**\n${text}` }] };
@@ -281,6 +293,108 @@ server.tool('discord_send_message', 'Send a message to a Discord channel in your
         return { content: [{ type: 'text', text: `Failed to send message: ${err.message}` }] };
     }
 });
+// ── 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")'),
+    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'),
+}, async ({ project_id, sources, lookback_hours, max_events }) => {
+    try {
+        const res = await api.generateInsight(project_id, 'correlation', {
+            sources,
+            lookbackHours: lookback_hours,
+            maxEvents: max_events,
+        });
+        const { job, result } = await api.waitForJob(res.jobId);
+        if (job.status === 'failed' || !result) {
+            const reason = job.error ?? 'unknown error';
+            return { content: [{ type: 'text', text: `Could not generate correlation insight: ${reason}` }] };
+        }
+        const insight = result;
+        return { content: [{ type: 'text', text: `# ${insight.title}\n\n${insight.summary}` }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
+    }
+});
+// ── 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'),
+    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'),
+}, async ({ project_id, sources, new_member_role, focus_area, lookback_days, max_events }) => {
+    try {
+        const res = await api.generateInsight(project_id, 'onboarding', {
+            sources,
+            newMemberRole: new_member_role,
+            focusArea: focus_area,
+            lookbackDays: lookback_days,
+            maxEvents: max_events,
+        });
+        const { job, result } = await api.waitForJob(res.jobId);
+        if (job.status === 'failed' || !result) {
+            const reason = job.error ?? 'unknown error';
+            return { content: [{ type: 'text', text: `Could not generate onboarding brief: ${reason}` }] };
+        }
+        const insight = result;
+        return { content: [{ type: 'text', text: `# ${insight.title}\n\n${insight.summary}` }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
+    }
+});
+// ── 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'),
+    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'),
+}, async ({ project_id, sources, focus_question, lookback_days, max_events }) => {
+    try {
+        const res = await api.generateInsight(project_id, 'architecture', {
+            sources,
+            focusQuestion: focus_question,
+            lookbackDays: lookback_days,
+            maxEvents: max_events,
+        });
+        const { job, result } = await api.waitForJob(res.jobId);
+        if (job.status === 'failed' || !result) {
+            const reason = job.error ?? 'unknown error';
+            return { content: [{ type: 'text', text: `Could not generate architecture insight: ${reason}` }] };
+        }
+        const insight = result;
+        return { content: [{ type: 'text', text: `# ${insight.title}\n\n${insight.summary}` }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
+    }
+});
+// ── 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', 'completed']).default('active').describe('Filter by status'),
+    limit: z.number().min(1).max(50).default(20).describe('Max number of insights to return'),
+}, async ({ project_id, kind, status, limit }) => {
+    try {
+        const { insights } = await api.listInsights(project_id, kind, status, limit);
+        if (insights.length === 0) {
+            return { content: [{ type: 'text', text: `No ${status} insights found.` }] };
+        }
+        const text = insights.map((insight) => {
+            return `## ${insight.title} (${insight.kind})\n**Status:** ${insight.status} · **Created:** ${new Date(insight.created_at).toLocaleString()}\n\n${insight.summary}`;
+        }).join('\n---\n\n');
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Failed to list insights: ${err.message}` }] };
+    }
+});
 // ── Start ────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@flowrelay/mcp-server",
-  "version": "0.4.1",
-  "description": "Flow Relay MCP Server for Claude Desktop and Claude Code — handoffs, integrations, and context events via natural conversation.",
+  "version": "0.6.0",
+  "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",