@flowrelay/mcp-server 0.1.0

package/dist/api.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Flow Relay API client — talks to flowrelay.it/api/v1/*
+ */
+export declare class FlowRelayAPI {
+    private baseUrl;
+    private apiKey;
+    constructor(apiKey: string, baseUrl?: string);
+    private request;
+    listHandoffs(status?: string, limit?: number): Promise<{
+        handoffs: Array<{
+            id: string;
+            title: string;
+            summary: string;
+            status: string;
+            sources: string[];
+            decisions: string[];
+            open_questions: string[];
+            next_steps: string[];
+            created_at: string;
+            updated_at: string;
+        }>;
+    }>;
+    generateHandoff(sources?: string[]): Promise<{
+        handoff: {
+            id: string;
+            title: string;
+            summary: string;
+            sources: string[];
+            decisions: string[];
+            open_questions: string[];
+            next_steps: string[];
+            created_at: string;
+        };
+    }>;
+    listIntegrations(): Promise<{
+        integrations: Array<{
+            source: string;
+            workspace_id: string | null;
+            workspace_name: string | null;
+            connected_at: string;
+        }>;
+    }>;
+    listEvents(source?: string, limit?: number): Promise<{
+        events: Array<{
+            id: string;
+            source: string;
+            event_type: string;
+            title: string;
+            content: string;
+            created_at: string;
+        }>;
+    }>;
+}

package/dist/api.js

@@ -0,0 +1,47 @@
+/**
+ * Flow Relay API client — talks to flowrelay.it/api/v1/*
+ */
+const DEFAULT_BASE_URL = 'https://www.flowrelay.it';
+export class FlowRelayAPI {
+    baseUrl;
+    apiKey;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = baseUrl ?? DEFAULT_BASE_URL;
+    }
+    async request(path, options) {
+        const url = `${this.baseUrl}/api/v1${path}`;
+        const res = await fetch(url, {
+            ...options,
+            headers: {
+                'Authorization': `Bearer ${this.apiKey}`,
+                'Content-Type': 'application/json',
+                ...options?.headers,
+            },
+        });
+        if (!res.ok) {
+            const body = await res.json().catch(() => ({ error: res.statusText }));
+            throw new Error(body.error ?? `API error ${res.status}`);
+        }
+        return res.json();
+    }
+    async listHandoffs(status = 'active', limit = 10) {
+        return this.request(`/handoffs?status=${status}&limit=${limit}`);
+    }
+    async generateHandoff(sources) {
+        return this.request('/handoffs', {
+            method: 'POST',
+            body: JSON.stringify(sources?.length ? { sources } : {}),
+        });
+    }
+    async listIntegrations() {
+        return this.request('/integrations');
+    }
+    async listEvents(source, limit = 20) {
+        const params = new URLSearchParams();
+        if (source)
+            params.set('source', source);
+        params.set('limit', String(limit));
+        return this.request(`/events?${params}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,92 @@
+#!/usr/bin/env node
+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 apiKey = process.env.FLOWRELAY_API_KEY;
+if (!apiKey) {
+    console.error('Error: FLOWRELAY_API_KEY environment variable is required.');
+    console.error('Create an API key at https://www.flowrelay.it/settings');
+    process.exit(1);
+}
+const api = new FlowRelayAPI(apiKey, process.env.FLOWRELAY_BASE_URL);
+const server = new McpServer({
+    name: 'flowrelay',
+    version: '0.1.0',
+});
+// ── Tool: list handoffs ──────────────────────────────────────────────
+server.tool('list_handoffs', 'List your Flow Relay handoffs. Returns recent handoffs with summaries, decisions, and next steps.', {
+    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);
+    if (handoffs.length === 0) {
+        return { content: [{ type: 'text', text: `No ${status} handoffs found.` }] };
+    }
+    const text = handoffs.map((h) => {
+        let out = `## ${h.title}\n`;
+        out += `**Status:** ${h.status} · **Sources:** ${h.sources.join(', ') || 'all'}\n`;
+        out += `**Created:** ${new Date(h.created_at).toLocaleString()}\n\n`;
+        out += `${h.summary}\n`;
+        if (h.decisions.length)
+            out += `\n**Decisions:**\n${h.decisions.map((d) => `- ${d}`).join('\n')}\n`;
+        if (h.next_steps.length)
+            out += `\n**Next steps:**\n${h.next_steps.map((s) => `- ${s}`).join('\n')}\n`;
+        if (h.open_questions.length)
+            out += `\n**Open questions:**\n${h.open_questions.map((q) => `- ${q}`).join('\n')}\n`;
+        return out;
+    }).join('\n---\n\n');
+    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.', {
+    sources: z.array(z.enum(['github', 'slack', 'linear', 'notion', 'jira', 'gitlab']))
+        .optional()
+        .describe('Specific sources to include (omit for all connected sources)'),
+}, async ({ sources }) => {
+    try {
+        const { handoff } = await api.generateHandoff(sources);
+        let text = `# ${handoff.title}\n\n${handoff.summary}\n`;
+        text += `\n**Sources:** ${handoff.sources.join(', ')}\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`;
+        return { content: [{ type: 'text', text }] };
+    }
+    catch (err) {
+        return { content: [{ type: 'text', text: `Could not generate handoff: ${err.message}` }] };
+    }
+});
+// ── Tool: list integrations ─────────────────────────────────────────
+server.tool('list_integrations', 'List your connected Flow Relay integrations (GitHub, Slack, Linear, Notion, Jira, GitLab).', {}, async () => {
+    const { integrations } = await api.listIntegrations();
+    if (integrations.length === 0) {
+        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})` : '';
+        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', 'linear', 'notion', 'jira', 'gitlab'])
+        .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);
+    if (events.length === 0) {
+        return { content: [{ type: 'text', text: `No recent events${source ? ` from ${source}` : ''}.` }] };
+    }
+    const text = events.map((e) => {
+        const time = new Date(e.created_at).toLocaleString();
+        return `- **[${e.source}/${e.event_type}]** ${e.title} _(${time})_`;
+    }).join('\n');
+    return { content: [{ type: 'text', text: `**Recent events:**\n${text}` }] };
+});
+// ── Start ────────────────────────────────────────────────────────────
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@flowrelay/mcp-server",
+  "version": "0.1.0",
+  "description": "Flow Relay MCP Server for Claude Desktop and Claude Code — handoffs, integrations, and context events via natural conversation.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Adriano Sorbello",
+  "homepage": "https://www.flowrelay.it",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/AdrianSorbello/flow-relay"
+  },
+  "keywords": ["mcp", "claude", "flow-relay", "context", "handoff", "ai"],
+  "bin": {
+    "flowrelay-mcp": "./dist/index.js"
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0",
+    "@types/node": "^20"
+  }
+}