@flowrelay/mcp-server 0.4.1 → 0.8.0

package/README.md

@@ -1,101 +1,104 @@
-# Flow Relay MCP Server
-
-Flow Relay MCP Server adds project-aware, multi-tenant Flow Relay tools to MCP clients such as Claude Desktop and Claude Code.
-
-It connects to Flow Relay API v1 using an API key and supports both:
-
-- Personal stream scope
-- Project scope (personal project or organization project)
-
-## Package
-
-- Name: @flowrelay/mcp-server
-- Version: 0.4.1
-
-## What Is Included
-
-The server currently exposes these tools:
-
-- get_workspace_context
-- list_projects
-- set_active_project
-- list_handoffs
-- generate_handoff
-- list_integrations
-- list_events
-- discord_list_channels
-- discord_send_message
-
-## Environment Variables
-
-Required:
-
-- FLOWRELAY_API_KEY
-
-Optional:
-
-- FLOWRELAY_PROJECT_ID
-- FLOWRELAY_BASE_URL
-
-If FLOWRELAY_PROJECT_ID is set, it becomes the default project context for project-aware tools unless you override it per call.
-
-## Quick Start (Claude Desktop)
-
-Add this to your claude_desktop_config.json:
-
-```json
-{
-  "mcpServers": {
-    "flowrelay": {
-      "command": "npx",
-      "args": ["-y", "@flowrelay/mcp-server"],
-      "env": {
-        "FLOWRELAY_API_KEY": "fr_your_api_key_here",
-        "FLOWRELAY_PROJECT_ID": "optional_project_id"
-      }
-    }
-  }
-}
-```
-
-## Multi-Tenant Behavior
-
-- If no project is active, tools run in personal stream scope.
-- You can select a project during the MCP session with set_active_project.
-- You can override scope per call by passing project_id where supported.
-
-Recommended flow:
-
-1. Call get_workspace_context
-2. Call list_projects
-3. Call set_active_project
-4. Run handoff and query tools in the selected scope
-
-## Local Development
-
-From this folder:
-
-```bash
-npm install
-npm run build
-```
-
-Create a tarball package:
-
-```bash
-npm pack
-```
-
-## Troubleshooting
-
-- Error: Missing FLOWRELAY_API_KEY
-  - Set FLOWRELAY_API_KEY in your MCP client configuration.
-- Project not found or inaccessible
-  - Run list_projects and use one of the returned IDs.
-- No events or handoffs returned
-  - Verify active scope and data availability in that scope.
-
-## Related Docs
-
-- Repository overview: ../README.md
-- Release notes: ../RELEASE_NOTES_v0.4.0.md
+# Flow Relay MCP Server
+
+Flow Relay MCP Server adds project-aware, multi-tenant Flow Relay tools to MCP clients such as Claude Desktop and Claude Code.
+
+It connects to Flow Relay API v1 using an API key and supports:
+
+- Project scope (personal project or organization project). Every handoff and AI insight is tied to a project. Events and integrations remain user-level.
+
+## Package
+
+- Name: @flowrelay/mcp-server
+- Version: 0.8.0
+
+## What Is Included
+
+The server currently exposes these tools:
+
+- get_workspace_context
+- list_projects
+- set_active_project
+- list_handoffs (returns project-specific handoffs, or an aggregated view of all accessible project handoffs if no project is active)
+- generate_handoff (processed asynchronously, and the server automatically polls until the job finishes. Requires active project or project_id.)
+- generate_correlation_insight
+- generate_onboarding_brief
+- generate_architecture_insight
+- list_insights
+- list_integrations
+- list_events
+- list_untracked_resources (lists event-producing resources not scoped to any project — useful for discovering untracked activity)
+- discord_list_channels
+- discord_send_message
+
+## Environment Variables
+
+Required:
+
+- FLOWRELAY_API_KEY
+
+Optional:
+
+- FLOWRELAY_PROJECT_ID
+- FLOWRELAY_BASE_URL
+
+If FLOWRELAY_PROJECT_ID is set, it becomes the default project context for project-aware tools unless you override it per call.
+
+## Quick Start (Claude Desktop)
+
+Add this to your claude_desktop_config.json:
+
+```json
+{
+  "mcpServers": {
+    "flowrelay": {
+      "command": "npx",
+      "args": ["-y", "@flowrelay/mcp-server"],
+      "env": {
+        "FLOWRELAY_API_KEY": "fr_your_api_key_here",
+        "FLOWRELAY_PROJECT_ID": "optional_project_id"
+      }
+    }
+  }
+}
+```
+
+## Multi-Tenant Behavior
+
+- Every handoff and insight is tied to a project; you need an active project (`set_active_project`) or `project_id`. Events and integrations remain user-level.
+- You can select a project during the MCP session with set_active_project.
+- You can override scope per call by passing project_id where supported.
+
+Recommended flow:
+
+1. Call get_workspace_context
+2. Call list_projects
+3. Call set_active_project
+4. Run handoff and query tools in the selected scope
+
+## Local Development
+
+From this folder:
+
+```bash
+npm install
+npm run build
+```
+
+Create a tarball package:
+
+```bash
+npm pack
+```
+
+## Troubleshooting
+
+- Error: Missing FLOWRELAY_API_KEY
+  - Set FLOWRELAY_API_KEY in your MCP client configuration.
+- Project not found or inaccessible
+  - Run list_projects and use one of the returned IDs.
+- No events or handoffs returned
+  - Verify active scope and data availability in that scope.
+
+## Related Docs
+
+- Repository overview: ../README.md

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,101 @@ 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 interface UntrackedResource {
+    source: string;
+    resource_id: string;
+    resource_name: string;
+    resource_type: 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, {
+    generateHandoff(sources: string[] | undefined, 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;
-        };
+    }> | undefined, projectId: string): 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;
@@ -108,4 +158,5 @@ export declare class FlowRelayAPI {
         ok: boolean;
         message_id: string;
     }>;
+    listUntrackedResources(): Promise<UntrackedResource[]>;
 }

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');
@@ -45,12 +48,46 @@ export class FlowRelayAPI {
             body.sources = sources;
         if (filters && Object.keys(filters).length > 0)
             body.filters = filters;
-        if (projectId)
-            body.project_id = projectId;
-        return this.request('/handoffs', {
+        body.project_id = projectId;
+        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();
@@ -77,4 +114,7 @@ export class FlowRelayAPI {
             body: JSON.stringify({ channel_id: channelId, content }),
         });
     }
+    async listUntrackedResources() {
+        return this.request('/integrations/untracked');
+    }
 }

package/dist/index.js

@@ -29,7 +29,7 @@ function normalizeProjectId(value) {
 }
 function formatProjectScope(project) {
     if (!project)
-        return 'No project (personal stream)';
+        return 'No project selected (required for handoffs & insights)';
     if (project.project_type === 'personal') {
         return `Personal project: ${project.name}`;
     }
@@ -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.8.0',
 });
 async function getTenantContext() {
     const context = await api.listProjects();
@@ -73,6 +73,20 @@ async function resolveProject(projectId) {
     }
     return { projectId: resolvedProjectId, project };
 }
+async function requireProject(projectId) {
+    const explicitProjectId = normalizeProjectId(projectId);
+    const resolvedProjectId = explicitProjectId ?? activeProjectId;
+    if (!resolvedProjectId) {
+        throw new Error('A project is required. Use set_active_project or pass project_id. Run list_projects to see available projects.');
+    }
+    const context = await getTenantContext();
+    const project = context.projects.find((candidate) => candidate.id === resolvedProjectId) ?? null;
+    if (!project) {
+        activeProjectId = null;
+        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.');
+    }
+    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 () => {
     const context = await getTenantContext();
@@ -99,7 +113,7 @@ server.tool('list_projects', 'List all projects available to this API key, inclu
         return {
             content: [{
                     type: 'text',
-                    text: 'No accessible projects found. Use personal stream or get added to a project team.',
+                    text: 'No accessible projects found. Create a project in Flow Relay or get added to a project team.',
                 }],
         };
     }
@@ -124,7 +138,7 @@ server.tool('set_active_project', 'Set or clear the active project context used
 }, async ({ project_id, clear }) => {
     if (clear || !normalizeProjectId(project_id)) {
         activeProjectId = null;
-        return { content: [{ type: 'text', text: 'Active project cleared. Using no-project personal scope.' }] };
+        return { content: [{ type: 'text', text: 'Active project cleared. Handoff/insight generation requires selecting a project.' }] };
     }
     const context = await getTenantContext();
     const selected = context.projects.find((project) => project.id === project_id);
@@ -145,23 +159,29 @@ 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 (personal stream or selected project).', {
+server.tool('list_handoffs', 'List Flow Relay handoffs in the current tenant scope (all accessible projects or selected project).', {
     status: z.enum(['active', 'archived', 'completed']).default('active').describe('Filter by 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.'),
 }, async ({ status, limit, project_id }) => {
-    const resolved = await resolveProject(project_id);
-    const { handoffs } = await api.listHandoffs(status, limit, resolved.projectId);
+    const explicitProjectId = normalizeProjectId(project_id);
+    const resolvedProjectId = explicitProjectId ?? activeProjectId;
+    let resolvedProject = null;
+    if (resolvedProjectId) {
+        const context = await getTenantContext();
+        resolvedProject = context.projects.find((p) => p.id === resolvedProjectId) ?? null;
+        if (!resolvedProject)
+            activeProjectId = null;
+    }
+    const { handoffs } = await api.listHandoffs(status, limit, resolvedProject?.id ?? null);
     if (handoffs.length === 0) {
-        const scopeLabel = formatProjectScope(resolved.project);
+        const scopeLabel = resolvedProject ? formatProjectScope(resolvedProject) : 'all projects';
         return { content: [{ type: 'text', text: `No ${status} handoffs found in scope: ${scopeLabel}.` }] };
     }
     const text = handoffs.map((h) => {
         let out = `## ${h.title}\n`;
         out += `**Status:** ${h.status} · **Sources:** ${h.sources.join(', ') || 'all'}\n`;
-        if (h.project_name) {
-            out += `**Project:** ${h.project_name}\n`;
-        }
+        out += `**Project:** ${h.project_name ?? 'Unknown'}\n`;
         out += `**Created:** ${new Date(h.created_at).toLocaleString()}\n\n`;
         out += `${h.summary}\n`;
         if (h.key_changes?.length)
@@ -188,12 +208,24 @@ server.tool('generate_handoff', 'Generate a new context handoff for personal sco
     project_id: z.string().optional().describe('Optional project scope override for this call.'),
 }, async ({ sources, filters, project_id }) => {
     try {
-        const resolved = await resolveProject(project_id);
-        const { handoff } = await api.generateHandoff(sources, filters, resolved.projectId);
+        const resolved = await requireProject(project_id);
+        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,12 +256,38 @@ 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}` }] };
 });
+// ── 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 () => {
+    try {
+        const resources = await api.listUntrackedResources();
+        if (resources.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'All discovered active resources are already tracked in your projects. Good job!',
+                    }],
+            };
+        }
+        const text = resources.map((r) => {
+            return `- **[${r.source}]** ${r.resource_name} (type: ${r.resource_type}, id: ${r.resource_id})`;
+        }).join('\n');
+        return {
+            content: [{
+                    type: 'text',
+                    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.*`,
+                }],
+        };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Failed to list untracked resources: ${err.message}` }] };
+    }
+});
 // ── Tool: list recent events ─────────────────────────────────────────
 server.tool('list_events', 'List recent context events in current scope (personal or selected project).', {
     source: SourceEnum
@@ -259,7 +317,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 +339,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,14 +1,14 @@
 {
   "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.8.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",
   "homepage": "https://www.flowrelay.it",
   "repository": {
     "type": "git",
-    "url": "https://github.com/atrisorb/flow-relay.git"
+    "url": "git+https://github.com/atrisorb/flow-relay.git"
   },
   "keywords": [
     "mcp",
@@ -19,7 +19,7 @@
     "ai"
   ],
   "bin": {
-    "flowrelay-mcp": "./dist/index.js"
+    "flowrelay-mcp": "dist/index.js"
   },
   "files": [
     "dist"