refine-backlog-mcp 1.0.0

package/README.md

@@ -0,0 +1,107 @@
+# Refine Backlog MCP Server
+
+Use Refine Backlog directly inside Claude Desktop, Cursor, or any MCP-compatible client.
+Tell your AI to refine your backlog and it calls the API automatically — no copy-paste required.
+
+## What it does
+
+Exposes a single tool: `refine_backlog`
+
+Give it a list of rough backlog items. Get back structured work items with:
+- Clean, actionable titles
+- Problem statements
+- Acceptance criteria (2-4 per item)
+- T-shirt size estimates (XS/S/M/L/XL)
+- Priorities with rationale
+- Tags
+- Clarifying assumptions (when needed)
+
+## Quick Start
+
+### Option 1: npx (no install)
+
+```bash
+npx refine-backlog-mcp
+```
+
+### Option 2: Local build
+
+```bash
+cd mcp
+npm install
+npm run build
+node dist/server.js
+```
+
+## Claude Desktop Setup
+
+Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json` on Mac):
+
+```json
+{
+  "mcpServers": {
+    "refine-backlog": {
+      "command": "npx",
+      "args": ["refine-backlog-mcp"]
+    }
+  }
+}
+```
+
+With a license key (Pro/Team tier):
+
+```json
+{
+  "mcpServers": {
+    "refine-backlog": {
+      "command": "npx",
+      "args": ["refine-backlog-mcp"],
+      "env": {
+        "REFINE_LICENSE_KEY": "your-license-key-here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. You'll see "refine_backlog" in the tools list.
+
+## Cursor Setup
+
+Add to your Cursor MCP config (`~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "refine-backlog": {
+      "command": "npx",
+      "args": ["refine-backlog-mcp"]
+    }
+  }
+}
+```
+
+## Usage Examples
+
+Once configured, just talk to your AI naturally:
+
+> "Refine these backlog items: fix login bug, add CSV export, improve dashboard load time"
+
+> "Take these 10 stories and run them through Refine Backlog. Context: we're building a B2B SaaS for HR teams."
+
+> "Refine this backlog item as a user story with Gherkin acceptance criteria: users need to reset their password"
+
+## Rate Limits
+
+| Tier | Items per request | Price |
+|------|-------------------|-------|
+| Free | 5 | $0 — no key needed |
+| Pro  | 25 | $9/month |
+| Team | 50 | $29/month |
+
+Get a license key at [refinebacklog.com/pricing](https://refinebacklog.com/pricing)
+
+## API Reference
+
+Full API docs: [refinebacklog.com/llms.txt](https://refinebacklog.com/llms.txt)  
+OpenAPI spec: [refinebacklog.com/openapi.yaml](https://refinebacklog.com/openapi.yaml)

package/dist/server.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * Refine Backlog MCP Server
+ *
+ * Exposes Refine Backlog (https://refinebacklog.com) as a Model Context Protocol tool.
+ * Compatible with Claude Desktop, Cursor, and any MCP-capable client.
+ *
+ * Usage: npx refine-backlog-mcp
+ */
+export {};

package/dist/server.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+/**
+ * Refine Backlog MCP Server
+ *
+ * Exposes Refine Backlog (https://refinebacklog.com) as a Model Context Protocol tool.
+ * Compatible with Claude Desktop, Cursor, and any MCP-capable client.
+ *
+ * Usage: npx refine-backlog-mcp
+ */
+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 API_BASE = "https://refinebacklog.com";
+const ESTIMATE_LABELS = {
+    XS: "< 1 day",
+    S: "1–2 days",
+    M: "3–5 days",
+    L: "1–2 weeks",
+    XL: "2+ weeks",
+};
+function formatRefinedItems(items) {
+    return items
+        .map((item, i) => {
+        const lines = [
+            `## ${i + 1}. ${item.title}`,
+            ``,
+            `**Problem:** ${item.problem}`,
+            ``,
+            `**Estimate:** ${item.estimate} (${ESTIMATE_LABELS[item.estimate] ?? item.estimate})`,
+            `**Priority:** ${item.priority}`,
+            `**Tags:** ${item.tags.join(", ")}`,
+            ``,
+            `**Acceptance Criteria:**`,
+            ...item.acceptanceCriteria.map((ac) => `- ${ac}`),
+        ];
+        if (item.assumptions && item.assumptions.length > 0) {
+            lines.push(``, `**Assumptions / Open Questions:**`);
+            item.assumptions.forEach((a) => lines.push(`- ${a}`));
+        }
+        return lines.join("\n");
+    })
+        .join("\n\n---\n\n");
+}
+const REFINE_TOOL = {
+    name: "refine_backlog",
+    description: "Refine messy backlog items into structured, actionable work items. " +
+        "Returns each item with a clean title, problem statement, acceptance criteria, " +
+        "T-shirt size estimate (XS/S/M/L/XL), priority with rationale, tags, and optional assumptions. " +
+        "Free tier: up to 5 items per request. Pro: 25. Team: 50.",
+    inputSchema: {
+        type: "object",
+        required: ["items"],
+        properties: {
+            items: {
+                type: "array",
+                items: { type: "string" },
+                minItems: 1,
+                maxItems: 50,
+                description: "Array of raw backlog item strings to refine. " +
+                    "Each string is a rough description of work to be done.",
+            },
+            context: {
+                type: "string",
+                description: "Optional project context to improve relevance. " +
+                    'Example: "B2B SaaS CRM for enterprise sales teams" or "Mobile fitness app for casual runners".',
+            },
+            licenseKey: {
+                type: "string",
+                description: "Optional. Refine Backlog license key for Pro or Team tier. " +
+                    "Obtain at https://refinebacklog.com/pricing. Free tier (5 items) works without a key.",
+            },
+            useUserStories: {
+                type: "boolean",
+                description: 'Format titles as user stories: "As a [user], I want [goal], so that [benefit]". Default: false.',
+            },
+            useGherkin: {
+                type: "boolean",
+                description: "Format acceptance criteria as Gherkin: Given/When/Then. Default: false.",
+            },
+        },
+    },
+};
+const server = new Server({
+    name: "refine-backlog",
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [REFINE_TOOL],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name !== "refine_backlog") {
+        return {
+            content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+            isError: true,
+        };
+    }
+    const args = request.params.arguments;
+    if (!args.items || args.items.length === 0) {
+        return {
+            content: [{ type: "text", text: "Error: items array is required and must not be empty." }],
+            isError: true,
+        };
+    }
+    const headers = {
+        "Content-Type": "application/json",
+    };
+    if (args.licenseKey) {
+        headers["x-license-key"] = args.licenseKey;
+    }
+    const body = {
+        items: args.items,
+    };
+    if (args.context)
+        body.context = args.context;
+    if (args.useUserStories !== undefined)
+        body.useUserStories = args.useUserStories;
+    if (args.useGherkin !== undefined)
+        body.useGherkin = args.useGherkin;
+    try {
+        const response = await fetch(`${API_BASE}/api/groom`, {
+            method: "POST",
+            headers,
+            body: JSON.stringify(body),
+        });
+        if (response.status === 429) {
+            return {
+                content: [{
+                        type: "text",
+                        text: "Rate limit exceeded. Free tier allows 5 items per request. Upgrade at https://refinebacklog.com/pricing",
+                    }],
+                isError: true,
+            };
+        }
+        if (response.status === 503) {
+            return {
+                content: [{ type: "text", text: "Refine Backlog AI service is temporarily unavailable. Please try again in a moment." }],
+                isError: true,
+            };
+        }
+        if (!response.ok) {
+            const error = await response.json().catch(() => ({ error: "Unknown error" }));
+            return {
+                content: [{ type: "text", text: `Error from Refine Backlog API: ${error.error ?? response.statusText}` }],
+                isError: true,
+            };
+        }
+        const data = await response.json();
+        const formatted = formatRefinedItems(data.items);
+        const meta = data._meta;
+        const summary = [
+            `\n\n---`,
+            `*Refined ${data.items.length} item${data.items.length !== 1 ? "s" : ""} · ` +
+                `${meta.latencyMs}ms · ` +
+                `Tier: ${meta.tier} · ` +
+                `Cost: $${meta.costUsd.toFixed(6)}*`,
+        ].join("\n");
+        return {
+            content: [{ type: "text", text: formatted + summary }],
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: "text", text: `Failed to reach Refine Backlog API: ${message}` }],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Refine Backlog MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "refine-backlog-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Refine Backlog — AI-powered backlog refinement",
+  "type": "module",
+  "main": "server.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node server.js",
+    "dev": "ts-node server.ts"
+  },
+  "bin": {
+    "refine-backlog-mcp": "./server.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "ts-node": "^10.9.0"
+  }
+}

package/server.ts

@@ -0,0 +1,244 @@
+#!/usr/bin/env node
+/**
+ * Refine Backlog MCP Server
+ *
+ * Exposes Refine Backlog (https://refinebacklog.com) as a Model Context Protocol tool.
+ * Compatible with Claude Desktop, Cursor, and any MCP-capable client.
+ *
+ * Usage: npx refine-backlog-mcp
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  Tool,
+} from "@modelcontextprotocol/sdk/types.js";
+
+const API_BASE = "https://refinebacklog.com";
+
+interface RefinedItem {
+  title: string;
+  problem: string;
+  acceptanceCriteria: string[];
+  estimate: "XS" | "S" | "M" | "L" | "XL";
+  priority: string;
+  tags: string[];
+  assumptions?: string[];
+}
+
+interface RefineResponse {
+  items: RefinedItem[];
+  _meta: {
+    requestId: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    latencyMs: number;
+    tier: string;
+  };
+}
+
+const ESTIMATE_LABELS: Record<string, string> = {
+  XS: "< 1 day",
+  S: "1–2 days",
+  M: "3–5 days",
+  L: "1–2 weeks",
+  XL: "2+ weeks",
+};
+
+function formatRefinedItems(items: RefinedItem[]): string {
+  return items
+    .map((item, i) => {
+      const lines = [
+        `## ${i + 1}. ${item.title}`,
+        ``,
+        `**Problem:** ${item.problem}`,
+        ``,
+        `**Estimate:** ${item.estimate} (${ESTIMATE_LABELS[item.estimate] ?? item.estimate})`,
+        `**Priority:** ${item.priority}`,
+        `**Tags:** ${item.tags.join(", ")}`,
+        ``,
+        `**Acceptance Criteria:**`,
+        ...item.acceptanceCriteria.map((ac) => `- ${ac}`),
+      ];
+
+      if (item.assumptions && item.assumptions.length > 0) {
+        lines.push(``, `**Assumptions / Open Questions:**`);
+        item.assumptions.forEach((a) => lines.push(`- ${a}`));
+      }
+
+      return lines.join("\n");
+    })
+    .join("\n\n---\n\n");
+}
+
+const REFINE_TOOL: Tool = {
+  name: "refine_backlog",
+  description:
+    "Refine messy backlog items into structured, actionable work items. " +
+    "Returns each item with a clean title, problem statement, acceptance criteria, " +
+    "T-shirt size estimate (XS/S/M/L/XL), priority with rationale, tags, and optional assumptions. " +
+    "Free tier: up to 5 items per request. Pro: 25. Team: 50.",
+  inputSchema: {
+    type: "object",
+    required: ["items"],
+    properties: {
+      items: {
+        type: "array",
+        items: { type: "string" },
+        minItems: 1,
+        maxItems: 50,
+        description:
+          "Array of raw backlog item strings to refine. " +
+          "Each string is a rough description of work to be done.",
+      },
+      context: {
+        type: "string",
+        description:
+          "Optional project context to improve relevance. " +
+          'Example: "B2B SaaS CRM for enterprise sales teams" or "Mobile fitness app for casual runners".',
+      },
+      licenseKey: {
+        type: "string",
+        description:
+          "Optional. Refine Backlog license key for Pro or Team tier. " +
+          "Obtain at https://refinebacklog.com/pricing. Free tier (5 items) works without a key.",
+      },
+      useUserStories: {
+        type: "boolean",
+        description:
+          'Format titles as user stories: "As a [user], I want [goal], so that [benefit]". Default: false.',
+      },
+      useGherkin: {
+        type: "boolean",
+        description:
+          "Format acceptance criteria as Gherkin: Given/When/Then. Default: false.",
+      },
+    },
+  },
+};
+
+const server = new Server(
+  {
+    name: "refine-backlog",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [REFINE_TOOL],
+}));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  if (request.params.name !== "refine_backlog") {
+    return {
+      content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+      isError: true,
+    };
+  }
+
+  const args = request.params.arguments as {
+    items: string[];
+    context?: string;
+    licenseKey?: string;
+    useUserStories?: boolean;
+    useGherkin?: boolean;
+  };
+
+  if (!args.items || args.items.length === 0) {
+    return {
+      content: [{ type: "text", text: "Error: items array is required and must not be empty." }],
+      isError: true,
+    };
+  }
+
+  const headers: Record<string, string> = {
+    "Content-Type": "application/json",
+  };
+
+  if (args.licenseKey) {
+    headers["x-license-key"] = args.licenseKey;
+  }
+
+  const body: Record<string, unknown> = {
+    items: args.items,
+  };
+
+  if (args.context) body.context = args.context;
+  if (args.useUserStories !== undefined) body.useUserStories = args.useUserStories;
+  if (args.useGherkin !== undefined) body.useGherkin = args.useGherkin;
+
+  try {
+    const response = await fetch(`${API_BASE}/api/groom`, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+    });
+
+    if (response.status === 429) {
+      return {
+        content: [{
+          type: "text",
+          text: "Rate limit exceeded. Free tier allows 5 items per request. Upgrade at https://refinebacklog.com/pricing",
+        }],
+        isError: true,
+      };
+    }
+
+    if (response.status === 503) {
+      return {
+        content: [{ type: "text", text: "Refine Backlog AI service is temporarily unavailable. Please try again in a moment." }],
+        isError: true,
+      };
+    }
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({ error: "Unknown error" })) as { error?: string };
+      return {
+        content: [{ type: "text", text: `Error from Refine Backlog API: ${error.error ?? response.statusText}` }],
+        isError: true,
+      };
+    }
+
+    const data = await response.json() as RefineResponse;
+    const formatted = formatRefinedItems(data.items);
+
+    const meta = data._meta;
+    const summary = [
+      `\n\n---`,
+      `*Refined ${data.items.length} item${data.items.length !== 1 ? "s" : ""} · ` +
+        `${meta.latencyMs}ms · ` +
+        `Tier: ${meta.tier} · ` +
+        `Cost: $${meta.costUsd.toFixed(6)}*`,
+    ].join("\n");
+
+    return {
+      content: [{ type: "text", text: formatted + summary }],
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      content: [{ type: "text", text: `Failed to reach Refine Backlog API: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Refine Backlog MCP server running on stdio");
+}
+
+main().catch((err) => {
+  console.error("Fatal error:", err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "outDir": "./dist",
+    "rootDir": ".",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["server.ts"],
+  "exclude": ["node_modules", "dist"]
+}