@flowrelay/mcp-server 0.6.0 → 0.8.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.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

@@ -78,6 +78,12 @@ export interface InsightResult {
     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;
 } | {
@@ -98,10 +104,10 @@ export declare class FlowRelayAPI {
     listHandoffs(status?: string, limit?: number, projectId?: string | null): Promise<{
         handoffs: HandoffResult[];
     }>;
-    generateHandoff(sources?: string[], filters?: Record<string, {
+    generateHandoff(sources: string[] | undefined, filters: Record<string, {
         projects?: string[];
         eventTypes?: string[];
-    }>, projectId?: string | null): Promise<GenerateHandoffResponse>;
+    }> | undefined, projectId: string): Promise<GenerateHandoffResponse>;
     getJob(jobId: string): Promise<{
         job: AiJob;
         result: HandoffResult | InsightResult | null;
@@ -152,4 +158,5 @@ export declare class FlowRelayAPI {
         ok: boolean;
         message_id: string;
     }>;
+    listUntrackedResources(): Promise<UntrackedResource[]>;
 }

package/dist/api.js

@@ -48,8 +48,7 @@ export class FlowRelayAPI {
             body.sources = sources;
         if (filters && Object.keys(filters).length > 0)
             body.filters = filters;
-        if (projectId)
-            body.project_id = projectId;
+        body.project_id = projectId;
         const { status, body: data } = await this.requestRaw('/handoffs', {
             method: 'POST',
             body: JSON.stringify(body),
@@ -115,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.6.0',
+    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,7 +208,7 @@ 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 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;
@@ -242,6 +262,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowrelay/mcp-server",
-  "version": "0.6.0",
+  "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",
@@ -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"