@flowrelay/mcp-server 0.8.0 → 1.0.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: 1.0.0
 
 ## What Is Included
 
@@ -18,15 +18,16 @@ 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_filter_options (lists the selectable resources, branches, event types and priorities per source for a project – call this before generating so handoff/insight filters use real values instead of guesses)
+- 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 +56,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;
 };
@@ -94,6 +98,30 @@ export type GenerateInsightResponse = {
     jobId: string;
     status: AiJobStatus;
 };
+export interface AvailableSourceFilter {
+    projects: {
+        id: string;
+        label: string;
+    }[];
+    eventTypes: {
+        value: string;
+        label: string;
+    }[];
+    branches?: {
+        value: string;
+        label: string;
+    }[];
+    branchesByProject?: Record<string, {
+        value: string;
+        label: string;
+    }[]>;
+    defaultBranchByProject?: Record<string, string>;
+    priorities: {
+        value: string;
+        label: string;
+    }[];
+}
+export type AvailableFilters = Record<string, AvailableSourceFilter>;
 export declare class FlowRelayAPI {
     private baseUrl;
     private apiKey;
@@ -101,13 +129,11 @@ export declare class FlowRelayAPI {
     private requestRaw;
     private request;
     listProjects(): Promise<TenantContext>;
+    getHandoffFilters(projectId: string): Promise<AvailableFilters>;
     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

@@ -34,6 +34,10 @@ export class FlowRelayAPI {
     async listProjects() {
         return this.request('/projects');
     }
+    async getHandoffFilters(projectId) {
+        const { filters } = await this.request(`/handoffs/filters?project_id=${encodeURIComponent(projectId)}`);
+        return filters ?? {};
+    }
     async listHandoffs(status = 'active', limit = 10, projectId) {
         const params = new URLSearchParams();
         params.set('status', status);
@@ -49,13 +53,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: '1.0.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 {
@@ -441,6 +446,39 @@ server.tool('list_insights', 'List project AI insights for a selected project sc
         return { content: [{ type: 'text', text: `Failed to list insights: ${err.message}` }] };
     }
 });
+// ── Tool: list filter options ───────────────────────────────────────
+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.', {
+    project_id: z.string().optional().describe('Project scope. Omit to use the active project.'),
+}, async ({ project_id }) => {
+    try {
+        const resolved = await requireProject(project_id);
+        const filters = await api.getHandoffFilters(resolved.projectId);
+        const sources = Object.keys(filters);
+        if (sources.length === 0) {
+            return { content: [{ type: 'text', text: `No connected sources with filter options for ${resolved.project.name}.` }] };
+        }
+        const blocks = sources.map((src) => {
+            const f = filters[src];
+            const lines = [`### ${src}`];
+            if (f.projects?.length) {
+                const items = f.projects.slice(0, 50).map((p) => (p.label && p.label !== p.id ? `${p.label} (id: ${p.id})` : p.id));
+                const more = f.projects.length > 50 ? ` (+${f.projects.length - 50} more)` : '';
+                lines.push(`- Resources: ${items.join(', ')}${more}`);
+            }
+            if (f.branches?.length)
+                lines.push(`- Branches: ${f.branches.map((b) => b.value).join(', ')}`);
+            if (f.eventTypes?.length)
+                lines.push(`- Event types: ${f.eventTypes.map((e) => e.value).join(', ')}`);
+            if (f.priorities?.length)
+                lines.push(`- Priorities: ${f.priorities.map((p) => p.value).join(', ')}`);
+            return lines.join('\n');
+        });
+        return { content: [{ type: 'text', text: `Filter options for ${resolved.project.name}:\n\n${blocks.join('\n\n')}` }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Could not load filter options: ${err.message}` }] };
+    }
+});
 // ── Start ────────────────────────────────────────────────────────────
 const transport = new StdioServerTransport();
 await server.connect(transport);

package/package.json

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