wflow-mcp 1.1.0

package/README.md

@@ -0,0 +1,52 @@
+# wflow MCP Server
+
+MCP server for AI assistants — extensible tool platform for the wflow ecosystem.
+
+## Quick Start
+
+### 1. Get your API key
+
+Ask your team for the `WFLOW_MCP_API_KEY` (matches the `MASTER_KEY` in the wflow Convex ecosystem).
+
+### 2. Add to Claude Code
+
+```bash
+claude mcp add -s user -e WFLOW_MCP_API_KEY=your-secret-key wflow-product-mcp -- npx -y wflow-mcp
+```
+
+That's it. Tools are loaded dynamically from the backend — no config needed.
+
+### 3. Verify
+
+```bash
+claude mcp list
+```
+
+You should see `wflow-product-mcp` in the list.
+
+## Available Tools
+
+Tools are fetched dynamically from the backend at startup. Currently available:
+
+### `productboard_check_existence`
+
+Semantic duplicate search across features, insights, tasks, and bugs. Uses vector search + LLM validation.
+
+**Parameters:**
+- `description` (string) — What you're searching for
+- `type` (enum) — `feature`, `insight`, `jira_task`, or `jira_bug`
+
+**Example usage in Claude Code:**
+> "Check if there's already a feature for invoice approval on line items"
+
+## Architecture
+
+This package is a thin pass-through client. It contains no business logic or internal API URLs. All tool definitions and routing logic live on the backend — adding new tools requires no package update.
+
+## Development
+
+```bash
+git clone https://github.com/wflowcom/product_mcp.git
+cd product_mcp/mcp-server
+npm install && npm run build
+```

package/dist/auth.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Authentication for the MCP server.
+ * Validates WFLOW_MCP_API_KEY env var on startup.
+ * Also used as Authorization header when calling Convex HTTP Actions.
+ */
+export declare function getApiKey(): string;

package/dist/auth.js

@@ -0,0 +1,15 @@
+/**
+ * Authentication for the MCP server.
+ * Validates WFLOW_MCP_API_KEY env var on startup.
+ * Also used as Authorization header when calling Convex HTTP Actions.
+ */
+export function getApiKey() {
+    const key = process.env.WFLOW_MCP_API_KEY;
+    if (!key) {
+        console.error("ERROR: WFLOW_MCP_API_KEY environment variable is required.\n" +
+            "Set it before running the MCP server:\n" +
+            '  export WFLOW_MCP_API_KEY="your-secret-key"');
+        process.exit(1);
+    }
+    return key;
+}

package/dist/gateway.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Thin gateway client — communicates with the product_mcp Convex backend.
+ * The MCP client only knows this one URL; all routing happens server-side.
+ */
+export interface ToolDefinition {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+interface InvokeResult {
+    content: Array<{
+        type: string;
+        text: string;
+    }>;
+}
+/**
+ * Fetch available tool definitions from the gateway.
+ */
+export declare function fetchTools(gatewayUrl: string): Promise<ToolDefinition[]>;
+/**
+ * Invoke a tool on the gateway.
+ */
+export declare function invokeTool(gatewayUrl: string, apiKey: string, toolName: string, args: Record<string, unknown>): Promise<InvokeResult>;
+export {};

package/dist/gateway.js

@@ -0,0 +1,42 @@
+/**
+ * Thin gateway client — communicates with the product_mcp Convex backend.
+ * The MCP client only knows this one URL; all routing happens server-side.
+ */
+/**
+ * Fetch available tool definitions from the gateway.
+ */
+export async function fetchTools(gatewayUrl) {
+    const response = await fetch(`${gatewayUrl}/api/mcp/tools`, {
+        method: "GET",
+        headers: { "Content-Type": "application/json" },
+    });
+    if (!response.ok) {
+        throw new Error(`Gateway returned ${response.status} ${response.statusText}`);
+    }
+    const result = await response.json();
+    if (!result.success || !Array.isArray(result.data)) {
+        throw new Error(result.error || "Invalid response from gateway");
+    }
+    return result.data;
+}
+/**
+ * Invoke a tool on the gateway.
+ */
+export async function invokeTool(gatewayUrl, apiKey, toolName, args) {
+    const response = await fetch(`${gatewayUrl}/api/mcp/invoke`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: apiKey,
+        },
+        body: JSON.stringify({ tool: toolName, arguments: args }),
+    });
+    if (!response.ok) {
+        throw new Error(`Gateway returned ${response.status} ${response.statusText}`);
+    }
+    const result = await response.json();
+    if (!result.content) {
+        throw new Error(result.error || "Unknown error from gateway");
+    }
+    return { content: result.content };
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * wflow MCP server — thin pass-through client.
+ *
+ * Fetches tool definitions from the Convex gateway at startup,
+ * registers them dynamically, and forwards all invocations.
+ * Contains no business logic or internal API URLs.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * wflow MCP server — thin pass-through client.
+ *
+ * Fetches tool definitions from the Convex gateway at startup,
+ * registers them dynamically, and forwards all invocations.
+ * Contains no business logic or internal API URLs.
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { ListToolsRequestSchema, CallToolRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { getApiKey } from "./auth.js";
+import { fetchTools, invokeTool, } from "./gateway.js";
+const GATEWAY_URL = "https://zealous-rhinoceros-886.eu-west-1.convex.site";
+const apiKey = getApiKey();
+// Fetch tool definitions from the gateway at startup
+let tools = [];
+try {
+    tools = await fetchTools(GATEWAY_URL);
+}
+catch (error) {
+    // stderr only — stdout is reserved for MCP protocol
+    console.error(`Warning: Failed to fetch tools from gateway: ${error instanceof Error ? error.message : String(error)}`);
+    console.error("MCP server starting with no tools available.");
+}
+const server = new Server({ name: "wflow-mcp", version: "1.1.0" }, { capabilities: { tools: { listChanged: false } } });
+// tools/list — return definitions fetched from gateway
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map((t) => ({
+        name: t.name,
+        description: t.description,
+        inputSchema: t.inputSchema,
+    })),
+}));
+// tools/call — forward invocation to gateway
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const knownTool = tools.find((t) => t.name === name);
+    if (!knownTool) {
+        return {
+            content: [
+                { type: "text", text: `Error: Unknown tool "${name}"` },
+            ],
+            isError: true,
+        };
+    }
+    try {
+        const result = await invokeTool(GATEWAY_URL, apiKey, name, args ?? {});
+        return { content: result.content };
+    }
+    catch (error) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: `Error invoking tool: ${error instanceof Error ? error.message : String(error)}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+// Start stdio transport
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "wflow-mcp",
+  "version": "1.1.0",
+  "description": "wflow MCP server for AI assistants — extensible tool platform",
+  "type": "module",
+  "bin": {
+    "wflow-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/index.js",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.3"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "private": false
+}