refine-backlog-mcp 1.0.4 → 1.0.6

package/Dockerfile

@@ -1,7 +1,7 @@
 FROM node:22-alpine
 
 # Install the published MCP server package
-RUN npm install -g refine-backlog-mcp@1.0.2
+RUN npm install -g refine-backlog-mcp@1.0.5
 
 # Run as non-root for security
 USER node

package/README.md

@@ -101,6 +101,17 @@ Once configured, just talk to your AI naturally:
 
 Get a license key at [refinebacklog.com/pricing](https://refinebacklog.com/pricing)
 
+## Prefer automation over chat?
+
+If you want to run Refine Backlog in scripts, GitHub Actions, or CI pipelines — without an LLM in the loop — use the CLI instead:
+
+```bash
+npx refine-backlog-cli "Fix login bug" --gherkin
+cat backlog.txt | npx refine-backlog-cli --user-stories --format json
+```
+
+**CLI repo:** [github.com/DavidNielsen1031/refine-backlog-cli](https://github.com/DavidNielsen1031/refine-backlog-cli)
+
 ## API Reference
 
 Full API docs: [refinebacklog.com/llms.txt](https://refinebacklog.com/llms.txt)  

package/dist/server.js

@@ -11,6 +11,9 @@ 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";
+// License key from MCP server environment — set REFINE_BACKLOG_KEY in Claude Desktop config.
+// This is the preferred way for MCP users with a paid subscription.
+const ENV_LICENSE_KEY = process.env.REFINE_BACKLOG_KEY ?? null;
 const ESTIMATE_LABELS = {
     XS: "< 1 day",
     S: "1–2 days",
@@ -46,7 +49,14 @@ const REFINE_TOOL = {
     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.",
+        "Free tier: up to 5 items per request. Pro: 25. Team: 50.\n\n" +
+        "BEFORE calling this tool, ask the user TWO quick questions if they haven't already specified:\n" +
+        "1. Would you like titles formatted as user stories? (\"As a [user], I want [goal], so that [benefit]\")\n" +
+        "2. Would you like acceptance criteria in Gherkin format? (Given/When/Then)\n" +
+        "Set useUserStories and useGherkin accordingly based on their answers. Both default to false.\n\n" +
+        "LICENSE KEY: For unlimited requests and higher item limits, set REFINE_BACKLOG_KEY in your MCP server " +
+        "environment config (Claude Desktop → claude_desktop_config.json → env section). " +
+        "Get a key at https://refinebacklog.com/pricing",
     inputSchema: {
         type: "object",
         required: ["items"],
@@ -67,7 +77,8 @@ const REFINE_TOOL = {
             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.",
+                    "Preferred: set REFINE_BACKLOG_KEY in your MCP server env config instead of passing inline. " +
+                    "Get a key at https://refinebacklog.com/pricing. Free tier (5 items, 3 req/day) works without a key.",
             },
             useUserStories: {
                 type: "boolean",
@@ -108,8 +119,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const headers = {
         "Content-Type": "application/json",
     };
-    if (args.licenseKey) {
-        headers["x-license-key"] = args.licenseKey;
+    // Inline arg takes precedence; env var is the recommended approach for MCP configs
+    const resolvedKey = args.licenseKey ?? ENV_LICENSE_KEY;
+    if (resolvedKey) {
+        headers["x-license-key"] = resolvedKey;
     }
     const body = {
         items: args.items,
@@ -121,7 +134,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     if (args.useGherkin !== undefined)
         body.useGherkin = args.useGherkin;
     try {
-        const response = await fetch(`${API_BASE}/api/groom`, {
+        const response = await fetch(`${API_BASE}/api/refine`, {
             method: "POST",
             headers,
             body: JSON.stringify(body),
@@ -132,7 +145,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             return {
                 content: [{
                         type: "text",
-                        text: `⚠️ ${msg}\n\n👉 Upgrade at https://refinebacklog.com/pricing — add your license key to the Claude Desktop MCP config as: "licenseKey": "your-key-here"`,
+                        text: `⚠️ ${msg}\n\n👉 Upgrade at https://refinebacklog.com/pricing\n\nOnce you have a key, add it to your Claude Desktop config:\n{\n  "mcpServers": {\n    "refine-backlog": {\n      "command": "npx",\n      "args": ["-y", "refine-backlog-mcp"],\n      "env": { "REFINE_BACKLOG_KEY": "your-key-here" }\n    }\n  }\n}`,
                     }],
                 isError: true,
             };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "refine-backlog-mcp",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "MCP server for Refine Backlog — AI-powered backlog refinement",
   "license": "MIT",
   "type": "module",

package/server.ts

@@ -18,6 +18,10 @@ import {
 
 const API_BASE = "https://refinebacklog.com";
 
+// License key from MCP server environment — set REFINE_BACKLOG_KEY in Claude Desktop config.
+// This is the preferred way for MCP users with a paid subscription.
+const ENV_LICENSE_KEY = process.env.REFINE_BACKLOG_KEY ?? null;
+
 interface RefinedItem {
   title: string;
   problem: string;
@@ -85,7 +89,10 @@ const REFINE_TOOL: Tool = {
     "BEFORE calling this tool, ask the user TWO quick questions if they haven't already specified:\n" +
     "1. Would you like titles formatted as user stories? (\"As a [user], I want [goal], so that [benefit]\")\n" +
     "2. Would you like acceptance criteria in Gherkin format? (Given/When/Then)\n" +
-    "Set useUserStories and useGherkin accordingly based on their answers. Both default to false.",
+    "Set useUserStories and useGherkin accordingly based on their answers. Both default to false.\n\n" +
+    "LICENSE KEY: For unlimited requests and higher item limits, set REFINE_BACKLOG_KEY in your MCP server " +
+    "environment config (Claude Desktop → claude_desktop_config.json → env section). " +
+    "Get a key at https://refinebacklog.com/pricing",
   inputSchema: {
     type: "object",
     required: ["items"],
@@ -109,7 +116,8 @@ const REFINE_TOOL: Tool = {
         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.",
+          "Preferred: set REFINE_BACKLOG_KEY in your MCP server env config instead of passing inline. " +
+          "Get a key at https://refinebacklog.com/pricing. Free tier (5 items, 3 req/day) works without a key.",
       },
       useUserStories: {
         type: "boolean",
@@ -168,8 +176,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     "Content-Type": "application/json",
   };
 
-  if (args.licenseKey) {
-    headers["x-license-key"] = args.licenseKey;
+  // Inline arg takes precedence; env var is the recommended approach for MCP configs
+  const resolvedKey = args.licenseKey ?? ENV_LICENSE_KEY;
+  if (resolvedKey) {
+    headers["x-license-key"] = resolvedKey;
   }
 
   const body: Record<string, unknown> = {
@@ -181,7 +191,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (args.useGherkin !== undefined) body.useGherkin = args.useGherkin;
 
   try {
-    const response = await fetch(`${API_BASE}/api/groom`, {
+    const response = await fetch(`${API_BASE}/api/refine`, {
       method: "POST",
       headers,
       body: JSON.stringify(body),
@@ -193,7 +203,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       return {
         content: [{
           type: "text",
-          text: `⚠️ ${msg}\n\n👉 Upgrade at https://refinebacklog.com/pricing — add your license key to the Claude Desktop MCP config as: "licenseKey": "your-key-here"`,
+          text: `⚠️ ${msg}\n\n👉 Upgrade at https://refinebacklog.com/pricing\n\nOnce you have a key, add it to your Claude Desktop config:\n{\n  "mcpServers": {\n    "refine-backlog": {\n      "command": "npx",\n      "args": ["-y", "refine-backlog-mcp"],\n      "env": { "REFINE_BACKLOG_KEY": "your-key-here" }\n    }\n  }\n}`,
         }],
         isError: true,
       };