@flowrelay/mcp-server 0.6.0 → 0.9.0

package/README.md

@@ -1,105 +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.6.0
-
-## What Is Included
-
-The server currently exposes these tools:
-
-- get_workspace_context
-- list_projects
-- set_active_project
-- list_handoffs
-- 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
-- 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.9.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; 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)
+- 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": "your_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

@@ -78,9 +78,19 @@ export interface InsightResult {
     created_at: string;
     updated_at?: string;
 }
+export interface UntrackedResource {
+    source: string;
+    resource_id: string;
+    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;
 };
@@ -98,10 +108,7 @@ export declare class FlowRelayAPI {
     listHandoffs(status?: string, limit?: number, projectId?: string | null): Promise<{
         handoffs: HandoffResult[];
     }>;
-    generateHandoff(sources?: string[], filters?: Record<string, {
-        projects?: string[];
-        eventTypes?: string[];
-    }>, projectId?: string | null): 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;
@@ -152,4 +159,5 @@ export declare class FlowRelayAPI {
         ok: boolean;
         message_id: string;
     }>;
+    listUntrackedResources(): Promise<UntrackedResource[]>;
 }

package/dist/api.js

@@ -48,15 +48,11 @@ export class FlowRelayAPI {
             body.sources = sources;
         if (filters && Object.keys(filters).length > 0)
             body.filters = filters;
-        if (projectId)
-            body.project_id = projectId;
-        const { status, body: data } = await this.requestRaw('/handoffs', {
+        body.project_id = projectId;
+        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;
@@ -115,4 +111,7 @@ export class FlowRelayAPI {
             body: JSON.stringify({ channel_id: channelId, content }),
         });
     }
+    async listUntrackedResources() {
+        return this.request('/integrations/untracked');
+    }
 }

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;
@@ -29,7 +38,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 +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.6.0',
+    version: '0.9.0',
 });
 async function getTenantContext() {
     const context = await api.listProjects();
@@ -73,6 +82,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 +122,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 +147,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 +168,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).', {
-    status: z.enum(['active', 'archived', 'completed']).default('active').describe('Filter by status'),
+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.'),
 }, 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)
@@ -181,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 resolveProject(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 resolved = await requireProject(project_id);
+        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`;
@@ -242,6 +261,32 @@ server.tool('list_integrations', 'List integrations in the current scope. In pro
     }).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
@@ -297,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,
         });
@@ -322,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,
@@ -351,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,
@@ -378,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.6.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",
@@ -8,7 +8,7 @@
   "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"