@flowrelay/mcp-server 1.0.1 → 1.0.3

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: 1.0.0
+- Version: 1.0.3
 
 ## What Is Included
 
@@ -18,12 +18,14 @@ The server currently exposes these tools:
 - get_workspace_context
 - list_projects
 - set_active_project
-- 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_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; also reports whether Figma is selectable, since Figma requires the project's processing region to be Global)
 - 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)
+
+Selecting Figma in `sources` or `filters` attaches visual context to the generation (rendered frame previews plus the indexed design scene: layout, texts, prototype flows). It works on projects whose processing region is Global and adds a flat 1-credit surcharge per generation.
 - list_insights
 - list_integrations
 - list_events

package/dist/api.d.ts

@@ -58,6 +58,8 @@ export interface HandoffResult {
     next_steps: string[];
     created_at: string;
     updated_at?: string;
+    /** Canonical Markdown rendered server-side – identical to the dashboard copy button. */
+    markdown?: string;
 }
 export interface InsightResult {
     id: string;
@@ -77,6 +79,8 @@ export interface InsightResult {
     related_event_ids: string[];
     created_at: string;
     updated_at?: string;
+    /** Canonical Markdown rendered server-side – identical to the dashboard copy button. */
+    markdown?: string;
 }
 export interface UntrackedResource {
     source: string;
@@ -122,6 +126,13 @@ export interface AvailableSourceFilter {
     }[];
 }
 export type AvailableFilters = Record<string, AvailableSourceFilter>;
+export interface FigmaGateInfo {
+    selectable: boolean;
+    region: string;
+    scope: string;
+    canManageResidency: boolean;
+    residencyHref: string | null;
+}
 export declare class FlowRelayAPI {
     private baseUrl;
     private apiKey;
@@ -129,7 +140,10 @@ export declare class FlowRelayAPI {
     private requestRaw;
     private request;
     listProjects(): Promise<TenantContext>;
-    getHandoffFilters(projectId: string): Promise<AvailableFilters>;
+    getHandoffFilters(projectId: string): Promise<{
+        filters: AvailableFilters;
+        figma: FigmaGateInfo | null;
+    }>;
     listHandoffs(status?: string, limit?: number, projectId?: string | null): Promise<{
         handoffs: HandoffResult[];
     }>;

package/dist/api.js

@@ -35,8 +35,8 @@ export class FlowRelayAPI {
         return this.request('/projects');
     }
     async getHandoffFilters(projectId) {
-        const { filters } = await this.request(`/handoffs/filters?project_id=${encodeURIComponent(projectId)}`);
-        return filters ?? {};
+        const { filters, figma } = await this.request(`/handoffs/filters?project_id=${encodeURIComponent(projectId)}`);
+        return { filters: filters ?? {}, figma: figma ?? null };
     }
     async listHandoffs(status = 'active', limit = 10, projectId) {
         const params = new URLSearchParams();

package/dist/index.js

@@ -222,16 +222,8 @@ server.tool('generate_handoff', 'Generate a new context handoff for personal sco
             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`;
-        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`;
-        if (handoff.decisions.length)
-            text += `\n**Decisions:**\n${handoff.decisions.map((d) => `- ${d}`).join('\n')}\n`;
-        if (handoff.next_steps.length)
-            text += `\n**Next steps:**\n${handoff.next_steps.map((s) => `- ${s}`).join('\n')}\n`;
+        // Server renders the canonical Markdown; fall back for pre-markdown servers.
+        const text = handoff.markdown ?? `# ${handoff.title}\n\n${handoff.summary}\n`;
         return { content: [{ type: 'text', text }] };
     }
     catch (err) {
@@ -369,7 +361,7 @@ server.tool('generate_correlation_insight', 'Generate a cross-source correlation
             return { content: [{ type: 'text', text: `Could not generate correlation insight: ${reason}` }] };
         }
         const insight = result;
-        return { content: [{ type: 'text', text: `# ${insight.title}\n\n${insight.summary}` }] };
+        return { content: [{ type: 'text', text: insight.markdown ?? `# ${insight.title}\n\n${insight.summary}` }] };
     }
     catch (err) {
         return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
@@ -400,7 +392,7 @@ server.tool('generate_onboarding_brief', 'Generate an onboarding brief AI insigh
             return { content: [{ type: 'text', text: `Could not generate onboarding brief: ${reason}` }] };
         }
         const insight = result;
-        return { content: [{ type: 'text', text: `# ${insight.title}\n\n${insight.summary}` }] };
+        return { content: [{ type: 'text', text: insight.markdown ?? `# ${insight.title}\n\n${insight.summary}` }] };
     }
     catch (err) {
         return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
@@ -429,7 +421,7 @@ server.tool('generate_architecture_insight', 'Generate an architecture insight A
             return { content: [{ type: 'text', text: `Could not generate architecture insight: ${reason}` }] };
         }
         const insight = result;
-        return { content: [{ type: 'text', text: `# ${insight.title}\n\n${insight.summary}` }] };
+        return { content: [{ type: 'text', text: insight.markdown ?? `# ${insight.title}\n\n${insight.summary}` }] };
     }
     catch (err) {
         return { content: [{ type: 'text', text: `Failed: ${err.message}` }] };
@@ -462,7 +454,7 @@ server.tool('list_filter_options', 'List the real per-source filter values (reso
 }, async ({ project_id }) => {
     try {
         const resolved = await requireProject(project_id);
-        const filters = await api.getHandoffFilters(resolved.projectId);
+        const { filters, figma } = 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}.` }] };
@@ -483,6 +475,12 @@ server.tool('list_filter_options', 'List the real per-source filter values (reso
                 lines.push(`- Priorities: ${f.priorities.map((p) => p.value).join(', ')}`);
             return lines.join('\n');
         });
+        if (figma && !figma.selectable) {
+            blocks.push('### figma\n- NOT selectable on this project: Figma visual context requires the Global processing region. ' +
+                (figma.canManageResidency
+                    ? 'Switch the project to Global in its Data Residency settings first.'
+                    : 'Ask an organization admin to switch the project to Global first.'));
+        }
         return { content: [{ type: 'text', text: `Filter options for ${resolved.project.name}:\n\n${blocks.join('\n\n')}` }] };
     }
     catch (err) {

package/package.json

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