@flowrelay/mcp-server 0.3.8 → 0.4.0

package/README.md

@@ -0,0 +1,101 @@
+# 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.0
+
+## 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

package/dist/api.d.ts

@@ -1,14 +1,46 @@
 /**
  * Flow Relay API client — talks to flowrelay.it/api/v1/*
  */
+export type AccountType = 'personal' | 'business';
+export type AccessRole = 'owner' | 'admin' | 'member';
+export interface TenantOrganization {
+    id: string;
+    name: string;
+    slug: string;
+    role: 'admin' | 'member';
+    is_temporary_admin: boolean;
+}
+export interface TenantProject {
+    id: string;
+    name: string;
+    slug: string;
+    description: string;
+    organization_id: string | null;
+    organization_name: string | null;
+    organization_slug: string | null;
+    project_type: 'personal' | 'organization';
+    access_role: AccessRole;
+    created_at: string;
+    updated_at: string;
+}
+export interface TenantContext {
+    account_type: AccountType;
+    organizations: TenantOrganization[];
+    projects: TenantProject[];
+}
 export declare class FlowRelayAPI {
     private baseUrl;
     private apiKey;
     constructor(apiKey: string, baseUrl?: string);
     private request;
-    listHandoffs(status?: string, limit?: number): Promise<{
+    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;
@@ -24,9 +56,13 @@ export declare class FlowRelayAPI {
     generateHandoff(sources?: string[], filters?: Record<string, {
         projects?: string[];
         eventTypes?: string[];
-    }>): Promise<{
+    }>, 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[];
@@ -37,17 +73,23 @@ export declare class FlowRelayAPI {
             created_at: string;
         };
     }>;
-    listIntegrations(): Promise<{
+    listIntegrations(projectId?: string | null): Promise<{
         integrations: Array<{
             source: string;
             workspace_id: string | null;
             workspace_name: string | null;
             connected_at: string;
+            scope?: "personal" | "project";
+            resource_type?: string | null;
+            connection_status?: string | null;
+            providers_connected?: number;
+            last_validated_at?: string | null;
         }>;
     }>;
-    listEvents(source?: string, limit?: number): Promise<{
+    listEvents(source?: string, limit?: number, projectId?: string | null): Promise<{
         events: Array<{
             id: string;
+            user_id?: string;
             source: string;
             event_type: string;
             title: string;

package/dist/api.js

@@ -23,30 +23,49 @@ 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();
     }
-    async listHandoffs(status = 'active', limit = 10) {
-        return this.request(`/handoffs?status=${status}&limit=${limit}`);
+    async listProjects() {
+        return this.request('/projects');
     }
-    async generateHandoff(sources, filters) {
+    async listHandoffs(status = 'active', limit = 10, projectId) {
+        const params = new URLSearchParams();
+        params.set('status', status);
+        params.set('limit', String(limit));
+        if (projectId)
+            params.set('project_id', projectId);
+        return this.request(`/handoffs?${params.toString()}`);
+    }
+    async generateHandoff(sources, filters, projectId) {
         const body = {};
         if (sources?.length)
             body.sources = sources;
         if (filters && Object.keys(filters).length > 0)
             body.filters = filters;
+        if (projectId)
+            body.project_id = projectId;
         return this.request('/handoffs', {
             method: 'POST',
             body: JSON.stringify(body),
         });
     }
-    async listIntegrations() {
-        return this.request('/integrations');
+    async listIntegrations(projectId) {
+        const params = new URLSearchParams();
+        if (projectId)
+            params.set('project_id', projectId);
+        const suffix = params.toString();
+        return this.request(`/integrations${suffix ? `?${suffix}` : ''}`);
     }
-    async listEvents(source, limit = 20) {
+    async listEvents(source, limit = 20, projectId) {
         const params = new URLSearchParams();
         if (source)
             params.set('source', source);
         params.set('limit', String(limit));
+        if (projectId)
+            params.set('project_id', projectId);
         return this.request(`/events?${params}`);
     }
     async discordListChannels() {

package/dist/index.js

@@ -3,6 +3,43 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
 import { FlowRelayAPI } from './api.js';
+const SOURCES = [
+    'github',
+    'slack',
+    'discord',
+    'linear',
+    'notion',
+    'confluence',
+    'jira',
+    'gitlab',
+    'bitbucket',
+    'azure_devops',
+    'figma',
+    'microsoft_outlook',
+    'microsoft_teams',
+    'sentry',
+    'datadog',
+];
+const SourceEnum = z.enum(SOURCES);
+function normalizeProjectId(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function formatProjectScope(project) {
+    if (!project)
+        return 'No project (personal stream)';
+    if (project.project_type === 'personal') {
+        return `Personal project: ${project.name}`;
+    }
+    const role = project.access_role === 'admin'
+        ? 'admin'
+        : project.access_role === 'member'
+            ? 'member'
+            : 'owner';
+    return `Org project: ${project.name} (${project.organization_name ?? 'Unknown org'}, ${role})`;
+}
 const apiKey = process.env.FLOWRELAY_API_KEY;
 if (!apiKey) {
     console.error('Error: FLOWRELAY_API_KEY environment variable is required.');
@@ -10,22 +47,121 @@ if (!apiKey) {
     process.exit(1);
 }
 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.3.7',
+    version: '0.4.0',
+});
+async function getTenantContext() {
+    const context = await api.listProjects();
+    if (activeProjectId && !context.projects.some((project) => project.id === activeProjectId)) {
+        activeProjectId = null;
+    }
+    return context;
+}
+async function resolveProject(projectId) {
+    const explicitProjectId = normalizeProjectId(projectId);
+    const resolvedProjectId = explicitProjectId ?? activeProjectId;
+    if (!resolvedProjectId) {
+        return { projectId: null, project: null };
+    }
+    const context = await getTenantContext();
+    const project = context.projects.find((candidate) => candidate.id === resolvedProjectId) ?? null;
+    if (!project) {
+        activeProjectId = null;
+        return { projectId: null, project: null };
+    }
+    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();
+    const activeProject = activeProjectId
+        ? context.projects.find((project) => project.id === activeProjectId) ?? null
+        : null;
+    const isBusiness = context.account_type === 'business' || context.organizations.length > 0;
+    const roleLine = activeProject
+        ? `Role: ${activeProject.access_role}`
+        : 'Role: n/a (no project selected)';
+    const lines = [
+        `Account mode: ${isBusiness ? 'business' : 'personal'}`,
+        `Organizations: ${context.organizations.length}`,
+        `Accessible projects: ${context.projects.length}`,
+        `Active scope: ${formatProjectScope(activeProject)}`,
+        roleLine,
+    ];
+    return { content: [{ type: 'text', text: lines.join('\n') }] };
+});
+// ── Tool: list projects ─────────────────────────────────────────────
+server.tool('list_projects', 'List all projects available to this API key, including personal and organization projects with role information.', {}, async () => {
+    const context = await getTenantContext();
+    if (context.projects.length === 0) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'No accessible projects found. Use personal stream or get added to a project team.',
+                }],
+        };
+    }
+    const lines = context.projects.map((project) => {
+        const active = project.id === activeProjectId ? ' [active]' : '';
+        const scope = project.project_type === 'personal'
+            ? 'personal'
+            : `org:${project.organization_name ?? 'unknown'}`;
+        return `- ${project.name} (${scope}, role=${project.access_role})\n  id: ${project.id}${active}`;
+    });
+    return {
+        content: [{
+                type: 'text',
+                text: `Projects:\n${lines.join('\n')}`,
+            }],
+    };
+});
+// ── Tool: set active project ────────────────────────────────────────
+server.tool('set_active_project', 'Set or clear the active project context used by project-aware tools when project_id is omitted.', {
+    project_id: z.string().optional().describe('Project ID to set as active. Omit to clear.'),
+    clear: z.boolean().default(false).describe('Clear active project and use no-project personal scope.'),
+}, async ({ project_id, clear }) => {
+    if (clear || !normalizeProjectId(project_id)) {
+        activeProjectId = null;
+        return { content: [{ type: 'text', text: 'Active project cleared. Using no-project personal scope.' }] };
+    }
+    const context = await getTenantContext();
+    const selected = context.projects.find((project) => project.id === project_id);
+    if (!selected) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Project not found or inaccessible: ${project_id}. Run list_projects first.`,
+                }],
+        };
+    }
+    activeProjectId = selected.id;
+    return {
+        content: [{
+                type: 'text',
+                text: `Active project set to ${selected.name} (${selected.id}).`,
+            }],
+    };
 });
 // ── Tool: list handoffs ──────────────────────────────────────────────
-server.tool('list_handoffs', 'List your Flow Relay handoffs. Returns recent handoffs with summaries, decisions, and next steps.', {
+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'),
     limit: z.number().min(1).max(50).default(10).describe('Max number of handoffs to return'),
-}, async ({ status, limit }) => {
-    const { handoffs } = await api.listHandoffs(status, limit);
+    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);
     if (handoffs.length === 0) {
-        return { content: [{ type: 'text', text: `No ${status} handoffs found.` }] };
+        const scopeLabel = formatProjectScope(resolved.project);
+        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 += `**Created:** ${new Date(h.created_at).toLocaleString()}\n\n`;
         out += `${h.summary}\n`;
         if (h.key_changes?.length)
@@ -41,18 +177,23 @@ server.tool('list_handoffs', 'List your Flow Relay handoffs. Returns recent hand
     return { content: [{ type: 'text', text }] };
 });
 // ── Tool: generate handoff ───────────────────────────────────────────
-server.tool('generate_handoff', 'Generate a new context handoff from your connected integrations. Summarizes recent activity into decisions, open questions, and next steps. Optionally filter by specific projects/repos/channels and event types per source.', {
-    sources: z.array(z.enum(['github', 'slack', 'discord', 'linear', 'notion', 'confluence', 'jira', 'gitlab', 'bitbucket', 'azure_devops', 'figma', 'microsoft_outlook', 'microsoft_teams', 'sentry']))
+server.tool('generate_handoff', 'Generate a new context handoff for personal scope or a selected project. Supports per-source filters.', {
+    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'),
-}, async ({ sources, filters }) => {
+    project_id: z.string().optional().describe('Optional project scope override for this call.'),
+}, async ({ sources, filters, project_id }) => {
     try {
-        const { handoff } = await api.generateHandoff(sources, filters);
+        const resolved = await resolveProject(project_id);
+        const { handoff } = await api.generateHandoff(sources, filters, resolved.projectId);
         let text = `# ${handoff.title}\n\n${handoff.summary}\n`;
+        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`;
@@ -67,31 +208,46 @@ server.tool('generate_handoff', 'Generate a new context handoff from your connec
     }
 });
 // ── Tool: list integrations ─────────────────────────────────────────
-server.tool('list_integrations', 'List your connected Flow Relay integrations (GitHub, Slack, Discord, Linear, Notion, Confluence, Jira, GitLab, Bitbucket, Azure DevOps, Figma, Microsoft Outlook, Microsoft Teams, Sentry).', {}, async () => {
-    const { integrations } = await api.listIntegrations();
+server.tool('list_integrations', 'List integrations in the current scope. In project scope this returns project resources with health metadata.', {
+    project_id: z.string().optional().describe('Optional project scope override for this call.'),
+}, async ({ project_id }) => {
+    const resolved = await resolveProject(project_id);
+    const { integrations } = await api.listIntegrations(resolved.projectId);
     if (integrations.length === 0) {
+        if (resolved.project) {
+            return { content: [{ type: 'text', text: `No integrations configured for project ${resolved.project.name}.` }] };
+        }
         return { content: [{ type: 'text', text: 'No integrations connected. Visit https://www.flowrelay.it/integrations to set up.' }] };
     }
     const text = integrations.map((i) => {
         const name = i.workspace_name ? ` (${i.workspace_name})` : '';
+        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} — connected ${new Date(i.connected_at).toLocaleDateString()}`;
     }).join('\n');
     return { content: [{ type: 'text', text: `**Connected integrations:**\n${text}` }] };
 });
 // ── Tool: list recent events ─────────────────────────────────────────
-server.tool('list_events', 'List recent context events (commits, messages, issues, etc.) from your connected integrations.', {
-    source: z.enum(['github', 'slack', 'discord', 'linear', 'notion', 'confluence', 'jira', 'gitlab', 'bitbucket', 'azure_devops', 'figma', 'microsoft_outlook', 'microsoft_teams', 'sentry'])
+server.tool('list_events', 'List recent context events in current scope (personal or selected project).', {
+    source: SourceEnum
         .optional()
         .describe('Filter by integration source'),
     limit: z.number().min(1).max(100).default(20).describe('Max number of events'),
-}, async ({ source, limit }) => {
-    const { events } = await api.listEvents(source, limit);
+    project_id: z.string().optional().describe('Optional project scope override for this call.'),
+}, async ({ source, limit, project_id }) => {
+    const resolved = await resolveProject(project_id);
+    const { events } = await api.listEvents(source, limit, resolved.projectId);
     if (events.length === 0) {
-        return { content: [{ type: 'text', text: `No recent events${source ? ` from ${source}` : ''}.` }] };
+        const scopeLabel = formatProjectScope(resolved.project);
+        return { content: [{ type: 'text', text: `No recent events${source ? ` from ${source}` : ''} in scope: ${scopeLabel}.` }] };
     }
     const text = events.map((e) => {
         const time = new Date(e.created_at).toLocaleString();
-        return `- **[${e.source}/${e.event_type}]** ${e.title} _(${time})_`;
+        const author = e.user_id ? ` user=${e.user_id}` : '';
+        return `- **[${e.source}/${e.event_type}]** ${e.title} _(${time})_${author}`;
     }).join('\n');
     return { content: [{ type: 'text', text: `**Recent events:**\n${text}` }] };
 });

package/package.json

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