@flowrelay/mcp-server 0.8.0 → 0.9.0

package/README.md

@@ -9,7 +9,7 @@ It connects to Flow Relay API v1 using an API key and supports:
 ## Package
 
 - Name: @flowrelay/mcp-server
-- Version: 0.8.0
+- Version: 0.9.0
 
 ## What Is Included
 
@@ -18,15 +18,15 @@ 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_handoffs (returns project-specific handoffs, or an aggregated view of all accessible project handoffs if no project is active; filter by status: active, archived, or all)
+- generate_handoff (processed asynchronously, and the server automatically polls until the job finishes. Requires active project or project_id. Accepts per-source filters: projects, eventTypes, branches, priorities.)
+- generate_correlation_insight (accepts per-source filters)
+- generate_onboarding_brief (accepts per-source filters)
+- generate_architecture_insight (accepts per-source filters)
 - list_insights
 - list_integrations
 - list_events
-- list_untracked_resources (lists event-producing resources not scoped to any project — useful for discovering untracked activity)
+- list_untracked_resources (lists event-producing resources not scoped to any project – useful for discovering untracked activity)
 - discord_list_channels
 - discord_send_message
 
@@ -55,7 +55,7 @@ Add this to your claude_desktop_config.json:
       "args": ["-y", "@flowrelay/mcp-server"],
       "env": {
         "FLOWRELAY_API_KEY": "fr_your_api_key_here",
-        "FLOWRELAY_PROJECT_ID": "optional_project_id"
+        "FLOWRELAY_PROJECT_ID": "your_project_id"
       }
     }
   }

package/dist/api.d.ts

@@ -84,9 +84,13 @@ export interface UntrackedResource {
     resource_name: string;
     resource_type: string;
 }
+export interface SourceFilter {
+    projects?: string[];
+    eventTypes?: string[];
+    branches?: string[];
+    priorities?: string[];
+}
 export type GenerateHandoffResponse = {
-    handoff: HandoffResult;
-} | {
     jobId: string;
     status: AiJobStatus;
 };
@@ -104,10 +108,7 @@ export declare class FlowRelayAPI {
     listHandoffs(status?: string, limit?: number, projectId?: string | null): Promise<{
         handoffs: HandoffResult[];
     }>;
-    generateHandoff(sources: string[] | undefined, filters: Record<string, {
-        projects?: string[];
-        eventTypes?: string[];
-    }> | undefined, projectId: string): Promise<GenerateHandoffResponse>;
+    generateHandoff(sources: string[] | undefined, filters: Record<string, SourceFilter> | undefined, projectId: string): Promise<GenerateHandoffResponse>;
     getJob(jobId: string): Promise<{
         job: AiJob;
         result: HandoffResult | InsightResult | null;

package/dist/api.js

@@ -49,13 +49,10 @@ export class FlowRelayAPI {
         if (filters && Object.keys(filters).length > 0)
             body.filters = filters;
         body.project_id = projectId;
-        const { status, body: data } = await this.requestRaw('/handoffs', {
+        return this.request('/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;

package/dist/index.js

@@ -21,6 +21,15 @@ const SOURCES = [
     'datadog',
 ];
 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'),
+});
+const FiltersSchema = z.record(z.string(), SourceFilterSchema)
+    .optional()
+    .describe('Per-source advanced filters, AND-combined across dimensions');
 function normalizeProjectId(value) {
     if (typeof value !== 'string')
         return null;
@@ -50,7 +59,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.8.0',
+    version: '0.9.0',
 });
 async function getTenantContext() {
     const context = await api.listProjects();
@@ -160,7 +169,7 @@ 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', 'completed']).default('active').describe('Filter by status'),
+    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.'),
 }, async ({ status, limit, project_id }) => {
@@ -201,28 +210,18 @@ server.tool('generate_handoff', 'Generate a new context handoff for personal sco
     sources: z.array(SourceEnum)
         .optional()
         .describe('Specific sources to include (omit for all connected sources)'),
-    filters: z.record(z.string(), 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")'),
-    })).optional().describe('Per-source advanced filters'),
+    filters: FiltersSchema,
     project_id: z.string().optional().describe('Optional project scope override for this call.'),
 }, async ({ sources, filters, project_id }) => {
     try {
         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;
+        const { jobId } = await api.generateHandoff(sources, filters, resolved.projectId);
+        const { job, result } = await api.waitForJob(jobId);
+        if (job.status === 'failed' || !result) {
+            const reason = job.error ?? 'unknown error';
+            return { content: [{ type: 'text', text: `Could not generate handoff: ${reason}` }] };
         }
+        const handoff = result;
         let text = `# ${handoff.title}\n\n${handoff.summary}\n`;
         if (handoff.project_name)
             text += `\n**Project:** ${handoff.project_name}\n`;
@@ -343,12 +342,14 @@ server.tool('discord_send_message', 'Send a message to a Discord channel in your
 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")'),
+    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'),
-}, async ({ project_id, sources, lookback_hours, max_events }) => {
+}, async ({ project_id, sources, filters, lookback_hours, max_events }) => {
     try {
         const res = await api.generateInsight(project_id, 'correlation', {
             sources,
+            filters,
             lookbackHours: lookback_hours,
             maxEvents: max_events,
         });
@@ -368,14 +369,16 @@ server.tool('generate_correlation_insight', 'Generate a cross-source correlation
 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'),
+    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'),
-}, async ({ project_id, sources, new_member_role, focus_area, lookback_days, max_events }) => {
+}, async ({ project_id, sources, filters, new_member_role, focus_area, lookback_days, max_events }) => {
     try {
         const res = await api.generateInsight(project_id, 'onboarding', {
             sources,
+            filters,
             newMemberRole: new_member_role,
             focusArea: focus_area,
             lookbackDays: lookback_days,
@@ -397,13 +400,15 @@ server.tool('generate_onboarding_brief', 'Generate an onboarding brief AI insigh
 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'),
+    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'),
-}, async ({ project_id, sources, focus_question, lookback_days, max_events }) => {
+}, async ({ project_id, sources, filters, focus_question, lookback_days, max_events }) => {
     try {
         const res = await api.generateInsight(project_id, 'architecture', {
             sources,
+            filters,
             focusQuestion: focus_question,
             lookbackDays: lookback_days,
             maxEvents: max_events,
@@ -424,7 +429,7 @@ server.tool('generate_architecture_insight', 'Generate an architecture insight A
 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'),
+    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'),
 }, async ({ project_id, kind, status, limit }) => {
     try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowrelay/mcp-server",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Flow Relay MCP Server for Claude Desktop and Claude Code – handoffs, integrations, and context events via natural conversation.",
   "type": "module",
   "license": "MIT",