featurepulse-mcp 1.0.0

package/README.md

@@ -0,0 +1,127 @@
+# FeaturePulse MCP Server
+
+A Model Context Protocol (MCP) server for [FeaturePulse](https://featurepul.se) feedback management. Connect FeaturePulse to any MCP-compatible AI client to query feature requests, analyze MRR impact, and manage your product roadmap through natural language.
+
+## Features
+
+- **5 Tools** — Feature requests, stats, search, grouping, and status updates
+- **MRR Data** — Every request includes revenue impact from paying customers
+- **Search & Filter** — By status, priority, votes, or free-text search
+- **Write Access** — Update feature request status and priority directly
+
+## Prerequisites
+
+- **Node.js** v18+
+- **MCP Client** — Claude Code, Claude Desktop, Cursor, Windsurf, or any MCP-compatible client
+- **FeaturePulse API Key** — Get one from your [FeaturePulse dashboard](https://featurepul.se/dashboard) under Project Settings
+
+## Quick Start with Claude Code
+
+The fastest way to start — run `npx` directly through Claude Code. No clone, no build.
+
+### Step 1: Get Your API Key
+
+1. Go to your [FeaturePulse dashboard](https://featurepul.se/dashboard)
+2. Open **Project Settings**
+3. Copy your **API Key**
+
+### Step 2: Add the MCP Server
+
+```bash
+claude mcp add --transport stdio featurepulse \
+  --scope user \
+  --env FEATUREPULSE_API_KEY=<YOUR_API_KEY> \
+  -- npx -y featurepulse-mcp
+```
+
+Replace `<YOUR_API_KEY>` with your API key.
+
+### Step 3: Restart Claude Code
+
+Quit and reopen Claude Code for the new server to load.
+
+### Step 4: Verify
+
+Ask Claude:
+
+```
+List the available FeaturePulse tools.
+```
+
+You should see 5 tools including `list_feature_requests` and `get_project_stats`.
+
+## Setup with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "featurepulse": {
+      "command": "npx",
+      "args": ["-y", "featurepulse-mcp"],
+      "env": {
+        "FEATUREPULSE_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+## Setup with Cursor / Windsurf
+
+Add the same configuration to your editor's MCP settings file. Both Cursor and Windsurf support the MCP standard.
+
+## Available Tools
+
+| Tool | Type | Description |
+|------|------|-------------|
+| `list_feature_requests` | Read | Browse and filter feature requests with MRR data. Filter by status, priority; sort by votes, MRR, or date. |
+| `get_project_stats` | Read | High-level overview — total requests, votes, MRR by status and priority. Top 10 by votes and MRR. |
+| `search_feedback` | Read | Full-text search across feature request titles. |
+| `analyze_feedback_by_group` | Read | Group requests by status or priority with aggregated counts and MRR. |
+| `update_feature_status` | Write | Change the status, priority, or status message of a feature request. |
+
+## Example Prompts
+
+- "What are the top feature requests by MRR?"
+- "Show me all pending high-priority requests"
+- "How much revenue is behind planned features?"
+- "Search for feedback about dark mode"
+- "Mark the dark mode request as in_progress"
+- "Give me a summary of feature requests grouped by status"
+
+## Configuration
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `FEATUREPULSE_API_KEY` | Yes | Your project API key from the FeaturePulse dashboard |
+| `FEATUREPULSE_URL` | No | API base URL (defaults to `https://featurepul.se`) |
+
+## How It Works
+
+```
+AI Assistant  ←→  MCP Server (stdio/JSON-RPC)  ←→  FeaturePulse API (HTTPS)
+```
+
+The MCP server communicates over stdio using JSON-RPC. When your AI assistant calls a tool (e.g. `list_feature_requests`), the server makes authenticated requests to the FeaturePulse API and returns formatted results.
+
+## Development
+
+```bash
+cd mcp-server
+npm install
+npm run dev    # Run with tsx (auto-reload)
+npm run build  # Compile TypeScript
+npm start      # Run compiled version
+```
+
+### Testing with MCP Inspector
+
+```bash
+npx @modelcontextprotocol/inspector npx featurepulse-mcp
+```
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,366 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+const FEATUREPULSE_URL = process.env.FEATUREPULSE_URL || "https://featurepul.se";
+const API_KEY = process.env.FEATUREPULSE_API_KEY;
+if (!API_KEY) {
+    console.error("Error: FEATUREPULSE_API_KEY environment variable is required.\n" +
+        "Get your API key from the FeaturePulse dashboard under Project Settings.");
+    process.exit(1);
+}
+// ─── HTTP helpers ────────────────────────────────────────────────────────────
+async function apiFetch(path, params) {
+    const url = new URL(`${FEATUREPULSE_URL}/api/mcp${path}`);
+    if (params) {
+        for (const [k, v] of Object.entries(params)) {
+            if (v !== undefined && v !== "")
+                url.searchParams.set(k, v);
+        }
+    }
+    const res = await fetch(url.toString(), {
+        headers: { "x-api-key": API_KEY },
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`FeaturePulse API error ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+// ─── Tool definitions ────────────────────────────────────────────────────────
+const PROJECT_ID_PROP = {
+    project_id: {
+        type: "string",
+        description: "Project UUID. Required if your API key has multiple projects. " +
+            "Use list_projects to see available projects.",
+    },
+};
+const TOOLS = [
+    {
+        name: "list_projects",
+        description: "List all projects accessible with your API key. Use this to find the project_id " +
+            "needed for other tools when you have multiple projects.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "list_feature_requests",
+        description: "List feature requests from FeaturePulse. Supports filtering by status and priority, " +
+            "full-text search, and sorting. Each result includes MRR data (revenue at risk) and " +
+            "vote breakdown so you can prioritize development by business impact.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...PROJECT_ID_PROP,
+                status: {
+                    type: "string",
+                    enum: [
+                        "pending",
+                        "approved",
+                        "planned",
+                        "in_progress",
+                        "completed",
+                        "rejected",
+                    ],
+                    description: "Filter by status",
+                },
+                priority: {
+                    type: "string",
+                    enum: ["low", "medium", "high"],
+                    description: "Filter by priority",
+                },
+                sort_by: {
+                    type: "string",
+                    enum: ["vote_count", "mrr", "created_at"],
+                    description: "Sort order: vote_count (most votes first), mrr (highest revenue impact first), created_at (newest first). Default: vote_count",
+                },
+                q: {
+                    type: "string",
+                    description: "Search term to filter by title",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max results to return (1–200, default 50)",
+                },
+                offset: {
+                    type: "number",
+                    description: "Pagination offset (default 0)",
+                },
+            },
+        },
+    },
+    {
+        name: "get_project_stats",
+        description: "Get a high-level statistical overview of your FeaturePulse project: total requests, " +
+            "votes, and MRR grouped by status and priority. Includes top-10 requests by votes and " +
+            "by revenue impact (MRR). Use this before diving into individual requests to understand " +
+            "the overall landscape.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...PROJECT_ID_PROP,
+            },
+        },
+    },
+    {
+        name: "search_feedback",
+        description: "Search feature requests by a text query. Returns the most relevant matching requests " +
+            "with their vote counts and MRR. Useful for finding related feedback before opening a " +
+            "new request or exploring a specific feature area.",
+        inputSchema: {
+            type: "object",
+            required: ["q"],
+            properties: {
+                ...PROJECT_ID_PROP,
+                q: {
+                    type: "string",
+                    description: "Search term",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max results (default 20)",
+                },
+            },
+        },
+    },
+    {
+        name: "analyze_feedback_by_group",
+        description: "Analyze and group all feature requests by a chosen dimension (status or priority), " +
+            "returning counts, total votes, and aggregated MRR for each group. Ideal for generating " +
+            "summaries like 'how much revenue is waiting on planned features?' or 'what's the MRR " +
+            "impact of unaddressed high-priority requests?'",
+        inputSchema: {
+            type: "object",
+            required: ["group_by"],
+            properties: {
+                ...PROJECT_ID_PROP,
+                group_by: {
+                    type: "string",
+                    enum: ["status", "priority"],
+                    description: "Dimension to group by",
+                },
+            },
+        },
+    },
+    {
+        name: "update_feature_status",
+        description: "Update the status or priority of a feature request. Use this to move requests through " +
+            "the workflow (e.g., pending → approved → in_progress → completed) or to set/change priority.",
+        inputSchema: {
+            type: "object",
+            required: ["feature_request_id"],
+            properties: {
+                ...PROJECT_ID_PROP,
+                feature_request_id: {
+                    type: "string",
+                    description: "UUID of the feature request to update",
+                },
+                status: {
+                    type: "string",
+                    enum: [
+                        "pending",
+                        "approved",
+                        "planned",
+                        "in_progress",
+                        "completed",
+                        "rejected",
+                    ],
+                    description: "New status",
+                },
+                priority: {
+                    type: "string",
+                    enum: ["low", "medium", "high"],
+                    description: "New priority",
+                },
+                status_message: {
+                    type: "string",
+                    description: "Optional message shown to users explaining the status change",
+                },
+            },
+        },
+    },
+];
+// ─── Tool handlers ────────────────────────────────────────────────────────────
+function projectParam(args) {
+    const params = {};
+    if (args.project_id)
+        params.project_id = String(args.project_id);
+    return params;
+}
+async function handleListProjects() {
+    // The API returns project info; we fetch stats which includes the project
+    // For multi-project support, we make a lightweight call
+    try {
+        const data = await apiFetch("/stats");
+        return `## Your Project\n\n- **${data.project.name}** (ID: \`${data.project.id}\`)\n  - ${data.overview.total_feature_requests} feature requests, ${data.overview.total_votes} votes, $${data.overview.total_mrr.toFixed(2)}/mo MRR`;
+    }
+    catch {
+        return "Could not fetch projects. Make sure your API key is valid.";
+    }
+}
+async function handleListFeatureRequests(args) {
+    const params = { ...projectParam(args) };
+    if (args.status)
+        params.status = String(args.status);
+    if (args.priority)
+        params.priority = String(args.priority);
+    if (args.sort_by)
+        params.sort_by = String(args.sort_by);
+    if (args.q)
+        params.q = String(args.q);
+    if (args.limit)
+        params.limit = String(args.limit);
+    if (args.offset)
+        params.offset = String(args.offset);
+    const data = await apiFetch("/feature-requests", params);
+    return formatFeatureRequestList(data);
+}
+async function handleGetProjectStats(args) {
+    const data = await apiFetch("/stats", projectParam(args));
+    return formatStats(data);
+}
+async function handleSearchFeedback(args) {
+    const params = {
+        ...projectParam(args),
+        q: String(args.q),
+        limit: String(args.limit || 20),
+    };
+    const data = await apiFetch("/feature-requests", params);
+    return formatFeatureRequestList(data);
+}
+async function handleAnalyzeFeedbackByGroup(args) {
+    const data = await apiFetch("/stats", projectParam(args));
+    const groupBy = String(args.group_by);
+    const groups = groupBy === "status" ? data.by_status : data.by_priority;
+    const lines = [
+        `## Feature Requests Grouped by ${groupBy.charAt(0).toUpperCase() + groupBy.slice(1)}\n`,
+    ];
+    for (const [key, val] of Object.entries(groups)) {
+        lines.push(`### ${key} (${val.count} request${val.count !== 1 ? "s" : ""})`);
+        lines.push(`- Total MRR at stake: $${val.total_mrr.toFixed(2)}/mo\n`);
+    }
+    return lines.join("\n");
+}
+async function handleUpdateFeatureStatus(args) {
+    const id = String(args.feature_request_id);
+    const body = {};
+    if (args.status)
+        body.status = args.status;
+    if (args.priority)
+        body.priority = args.priority;
+    if (args.status_message)
+        body.status_message = args.status_message;
+    const pidQuery = args.project_id ? `?project_id=${args.project_id}` : "";
+    const url = `${FEATUREPULSE_URL}/api/mcp/feature-requests/${id}${pidQuery}`;
+    const res = await fetch(url, {
+        method: "PATCH",
+        headers: {
+            "x-api-key": API_KEY,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Failed to update feature request: ${text}`);
+    }
+    const updated = await res.json();
+    return (`Successfully updated feature request "${updated.title}".\n` +
+        `Status: ${updated.status} | Priority: ${updated.priority}`);
+}
+// ─── Formatters ──────────────────────────────────────────────────────────────
+function formatFeatureRequestList(data) {
+    const { feature_requests, total, project } = data;
+    if (!feature_requests.length) {
+        return "No feature requests found matching the given filters.";
+    }
+    const lines = [
+        `## ${project.name} — Feature Requests (${feature_requests.length} of ${total} total)\n`,
+    ];
+    for (const fr of feature_requests) {
+        lines.push(`### ${fr.title}`);
+        lines.push(`- **ID**: ${fr.id}`);
+        lines.push(`- **Status**: ${fr.status} | **Priority**: ${fr.priority}`);
+        lines.push(`- **Votes**: ${fr.vote_count} (${fr.paying_customer_votes ?? "?"} paying, ${fr.free_votes ?? "?"} free)`);
+        lines.push(`- **MRR impact**: $${(fr.total_mrr ?? 0).toFixed(2)}/mo`);
+        if (fr.description) {
+            const excerpt = fr.description.length > 200
+                ? fr.description.slice(0, 200) + "…"
+                : fr.description;
+            lines.push(`- **Description**: ${excerpt}`);
+        }
+        if (fr.status_message) {
+            lines.push(`- **Status note**: ${fr.status_message}`);
+        }
+        lines.push(`- **Created**: ${new Date(fr.created_at).toLocaleDateString()}\n`);
+    }
+    return lines.join("\n");
+}
+function formatStats(data) {
+    const { project, overview, by_status, by_priority, top_by_votes, top_by_mrr } = data;
+    const lines = [
+        `## ${project.name} — Feedback Overview\n`,
+        `**Total requests**: ${overview.total_feature_requests}`,
+        `**Total votes**: ${overview.total_votes}`,
+        `**Total MRR at stake**: $${overview.total_mrr.toFixed(2)}/mo\n`,
+        `### By Status`,
+    ];
+    for (const [status, val] of Object.entries(by_status)) {
+        lines.push(`- **${status}**: ${val.count} request${val.count !== 1 ? "s" : ""} — $${val.total_mrr.toFixed(2)}/mo MRR`);
+    }
+    lines.push(`\n### By Priority`);
+    for (const [priority, val] of Object.entries(by_priority)) {
+        lines.push(`- **${priority}**: ${val.count} request${val.count !== 1 ? "s" : ""} — $${val.total_mrr.toFixed(2)}/mo MRR`);
+    }
+    lines.push(`\n### Top 10 by Votes`);
+    for (const fr of top_by_votes) {
+        lines.push(`- [${fr.status}/${fr.priority}] **${fr.title}** — ${fr.vote_count} votes`);
+    }
+    lines.push(`\n### Top 10 by MRR Impact`);
+    for (const fr of top_by_mrr) {
+        lines.push(`- [${fr.status}/${fr.priority}] **${fr.title}** — $${(fr.total_mrr ?? 0).toFixed(2)}/mo`);
+    }
+    return lines.join("\n");
+}
+// ─── MCP Server setup ─────────────────────────────────────────────────────────
+const server = new Server({ name: "featurepulse", version: "1.0.0" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    try {
+        let text;
+        switch (name) {
+            case "list_projects":
+                text = await handleListProjects();
+                break;
+            case "list_feature_requests":
+                text = await handleListFeatureRequests(args);
+                break;
+            case "get_project_stats":
+                text = await handleGetProjectStats(args);
+                break;
+            case "search_feedback":
+                text = await handleSearchFeedback(args);
+                break;
+            case "analyze_feedback_by_group":
+                text = await handleAnalyzeFeedbackByGroup(args);
+                break;
+            case "update_feature_status":
+                text = await handleUpdateFeatureStatus(args);
+                break;
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return { content: [{ type: "text", text }] };
+    }
+    catch (err) {
+        return {
+            content: [{ type: "text", text: `Error: ${err.message}` }],
+            isError: true,
+        };
+    }
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "featurepulse-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for FeaturePulse — query feature requests, analyze MRR impact, and manage your roadmap from Claude, Cursor, or any MCP-compatible AI tool",
+  "type": "module",
+  "bin": {
+    "featurepulse-mcp": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "featurepulse",
+    "feature-requests",
+    "feedback",
+    "claude",
+    "cursor",
+    "ai",
+    "product-management"
+  ],
+  "author": "FeaturePulse",
+  "license": "MIT",
+  "homepage": "https://featurepul.se/integrations/claude-mcp",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/featurepulse/featurepulse-mcp"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  }
+}