@elixium.ai/mcp-server 0.2.1 → 0.3.0

package/dist/index.js

@@ -10,6 +10,14 @@ const API_URL = process.env.ELIXIUM_API_URL || "https://elixium.ai/api";
 const BOARD_SLUG = process.env.ELIXIUM_BOARD_SLUG;
 const LANE_STYLE_ENV = process.env.ELIXIUM_LANE_STYLE;
 const USER_EMAIL = process.env.ELIXIUM_USER_EMAIL; // Optional: Override requester email for stories
+// UUID v4 format validation — prevents 500s from partial/truncated IDs
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function assertUUID(value, label) {
+    if (!UUID_RE.test(value)) {
+        throw new Error(`Invalid ${label}: "${value}" is not a valid UUID. ` +
+            `Expected format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx (full UUID from list_stories/list_epics).`);
+    }
+}
 const CLI_ARGS = process.argv.slice(2);
 const hasArg = (flag) => CLI_ARGS.includes(flag);
 const getArgValue = (flag) => {
@@ -219,6 +227,105 @@ const getTeamProfile = async () => {
     const config = await fetchFeatureConfig();
     return config.teamProfile;
 };
+const formatTeamContext = (config) => {
+    const features = config.features;
+    const tp = config.teamProfile;
+    const bd = config.branchingDefaults;
+    const infra = config.infrastructureProfile;
+    return `
+## Team Context
+
+### Enabled Features
+${features.balancedTeam ? "✅" : "❌"} Balanced Team
+${features.learningLoop ? "✅" : "❌"} Learning Loop
+${features.tddWorkflow ? "✅" : "❌"} TDD Workflow
+${features.aiTools ? "✅" : "❌"} AI Tools
+
+### Team Profile
+${tp ? `- Team Size: ${tp.teamSize || "Not set"}
+- Has Designer: ${tp.hasDesigner ? "Yes" : "No"}
+- Has Product Manager: ${tp.hasProductManager ? "Yes" : "No"}
+- Has QA: ${tp.hasQA ? "Yes" : "No"}
+- Development Approach: ${tp.developmentApproach || "Not set"}` : "Team profile not configured. Set up in Settings → Profile."}
+
+### Branching Strategy
+- Trunk-Based: ${bd?.trunkBased ? "Yes" : "No"}
+- Auto-Merge: ${bd?.autoMerge ? "Yes" : "No"}
+- Source: ${bd?.source || "default"}
+${infra?.provider ? `
+### Infrastructure
+- Provider: ${infra.provider.toUpperCase()}
+- Regions: ${infra.regions?.join(", ") || "Not set"}
+- Compliance: ${infra.complianceFrameworks?.map((f) => f.toUpperCase()).join(", ") || "None"}` : ""}
+`.trim();
+};
+const fetchBoardSettings = async () => {
+    try {
+        const boardId = await resolveBoardId();
+        if (!boardId)
+            return undefined;
+        const response = await client.get("/boards");
+        const boards = Array.isArray(response.data) ? response.data : [];
+        const board = boards.find((b) => b.id === boardId);
+        return board?.settings;
+    }
+    catch {
+        return undefined;
+    }
+};
+const formatDorDodSection = (boardSettings, dorChecklist, dodChecklist) => {
+    if (!boardSettings)
+        return "";
+    const sections = [];
+    const dorConfig = boardSettings.definitionOfReady;
+    if (dorConfig?.enabled && dorConfig.items?.length > 0) {
+        const cl = dorChecklist || {};
+        const lines = dorConfig.items.map((item) => {
+            const met = cl[item.id] === true;
+            return `- ${met ? "✅" : "❌"} ${item.label}`;
+        });
+        const unmetItems = dorConfig.items.filter((item) => cl[item.id] !== true);
+        const met = dorConfig.items.length - unmetItems.length;
+        sections.push(`### Definition of Ready (${met}/${dorConfig.items.length})`);
+        sections.push(lines.join("\n"));
+        if (unmetItems.length > 0) {
+            const unmetLabels = unmetItems.map((i) => i.label).join(", ");
+            sections.push(`\n> **DoR unmet:** ${unmetLabels}`);
+        }
+    }
+    const dodConfig = boardSettings.definitionOfDone;
+    if (dodConfig?.enabled && dodConfig.items?.length > 0) {
+        const cl = dodChecklist || {};
+        const lines = dodConfig.items.map((item) => {
+            const met = cl[item.id] === true;
+            return `- ${met ? "✅" : "❌"} ${item.label}`;
+        });
+        const unmetItems = dodConfig.items.filter((item) => cl[item.id] !== true);
+        const met = dodConfig.items.length - unmetItems.length;
+        sections.push(`### Definition of Done (${met}/${dodConfig.items.length})`);
+        sections.push(lines.join("\n"));
+        if (unmetItems.length > 0) {
+            const unmetLabels = unmetItems.map((i) => i.label).join(", ");
+            sections.push(`\n> **DoD unmet:** ${unmetLabels}`);
+        }
+    }
+    if (sections.length === 0)
+        return "";
+    return `\n## Checklists\n${sections.join("\n")}\n`;
+};
+const formatDorWarnings = (boardSettings, dorChecklist) => {
+    if (!boardSettings)
+        return "";
+    const dorConfig = boardSettings.definitionOfReady;
+    if (!dorConfig?.enabled || dorConfig.enforcement !== "warn")
+        return "";
+    const cl = dorChecklist || {};
+    const unmetItems = (dorConfig.items || []).filter((item) => cl[item.id] !== true);
+    if (unmetItems.length === 0)
+        return "";
+    const warningLines = unmetItems.map((i) => `- ⚠️ DoR not met: ${i.label}`).join("\n");
+    return `\n## ⚠️ DoR Warnings\n${warningLines}\n\nConsider addressing these before starting implementation.\n`;
+};
 const fetchStories = async () => {
     const boardId = await resolveBoardId();
     const slug = normalizeBoardSlug(BOARD_SLUG);
@@ -604,6 +711,20 @@ const createServer = () => {
                     required: ["storyId", "testPlan"],
                 },
             },
+            {
+                name: "approve_tests",
+                description: "Approve a proposed test plan so implementation can proceed. Transitions workflow from tests_proposed to tests_approved. This is the human approval gate in the TDD workflow.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        storyId: {
+                            type: "string",
+                            description: "ID of the story whose test plan to approve",
+                        },
+                    },
+                    required: ["storyId"],
+                },
+            },
             {
                 name: "submit_for_review",
                 description: "Submit implementation for human review. Only works if tests are approved. Sets state to finished.",
@@ -630,6 +751,20 @@ const createServer = () => {
                     required: ["storyId"],
                 },
             },
+            {
+                name: "review_pr",
+                description: "Run AI review on a story's PR diff against acceptance criteria and DoD. Fetches diff, runs AI validation, posts findings as GitHub PR comment, and stores results on the story.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        storyId: {
+                            type: "string",
+                            description: "ID of the story to review",
+                        },
+                    },
+                    required: ["storyId"],
+                },
+            },
         ] : [];
         // Learning Loop tools (conditional on feature flag)
         const learningLoopTools = learningLoopEnabled ? [
@@ -674,7 +809,7 @@ const createServer = () => {
         try {
             const toolName = request.params.name;
             // Check TDD workflow tools
-            const tddWorkflowTools = ["start_story", "propose_test_plan", "submit_for_review"];
+            const tddWorkflowTools = ["start_story", "propose_test_plan", "submit_for_review", "review_pr"];
             if (tddWorkflowTools.includes(toolName)) {
                 const enabled = await isTddWorkflowEnabled();
                 if (!enabled) {
@@ -836,6 +971,7 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                 case "record_learning": {
                     const args = request.params.arguments;
                     const { storyId, outcome_summary } = args;
+                    assertUUID(storyId, "storyId");
                     const response = await client.patch(`/stories/${storyId}`, {
                         outcome_summary,
                     });
@@ -851,6 +987,7 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                     if (!storyId) {
                         throw new Error("storyId is required");
                     }
+                    assertUUID(storyId, "storyId");
                     // Guardrail: Block AI from setting accepted/rejected states (human-in-the-loop)
                     const blockedStates = ["accepted", "rejected"];
                     if (state && blockedStates.includes(state.toLowerCase())) {
@@ -862,11 +999,38 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                         ...(state ? { state } : {}),
                         ...(normalizedLane ? { lane: normalizedLane } : {}),
                     }).filter(([, value]) => value !== undefined));
-                    const response = await client.patch(`/stories/${storyId}`, payload);
+                    let response;
+                    try {
+                        response = await client.patch(`/stories/${storyId}`, payload);
+                    }
+                    catch (err) {
+                        // DoR/DoD enforcement: surface 422 with unmet criteria to agent
+                        if (err.response?.status === 422 && err.response?.data?.unmetCriteria) {
+                            const errorMsg = err.response.data.error || "Checklist not met";
+                            const unmet = err.response.data.unmetCriteria;
+                            const unmetList = unmet.map((c) => `- ❌ ${c.label}`).join("\n");
+                            const isDod = errorMsg.includes("Done");
+                            const checklistField = isDod ? "dodChecklist" : "dorChecklist";
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: `# ⛔ ${errorMsg}\n\nCannot move story. The following criteria are unmet:\n\n${unmetList}\n\n**Action:** Update the story's \`${checklistField}\` to mark items as met, or ask the team to review the requirements in Board Settings.`,
+                                    },
+                                ],
+                            };
+                        }
+                        throw err;
+                    }
+                    const data = response.data;
+                    let resultText = JSON.stringify(data, null, 2);
+                    // Surface DoR warnings to agent
+                    if (data.warnings && data.warnings.length > 0) {
+                        const warningList = data.warnings.map((w) => `- ⚠️ ${w}`).join("\n");
+                        resultText += `\n\n---\n# ⚠️ DoR Warnings\n\nStory moved to Current, but the following DoR items are unmet:\n\n${warningList}\n\nConsider addressing these before starting implementation.`;
+                    }
                     return {
-                        content: [
-                            { type: "text", text: JSON.stringify(response.data, null, 2) },
-                        ],
+                        content: [{ type: "text", text: resultText }],
                     };
                 }
                 case "list_objectives": {
@@ -904,6 +1068,7 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                     if (!epicId) {
                         throw new Error("epicId is required");
                     }
+                    assertUUID(epicId, "epicId");
                     const payload = Object.fromEntries(Object.entries(rest).filter(([, value]) => value !== undefined));
                     const response = await client.patch(`/epics/${epicId}`, payload);
                     return {
@@ -915,7 +1080,13 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                 case "prepare_implementation": {
                     const args = request.params.arguments;
                     const { storyId } = args;
-                    const storyResponse = await client.get(`/stories/${storyId}`);
+                    assertUUID(storyId, "storyId");
+                    // Fetch story, team context, and board settings in parallel
+                    const [storyResponse, teamConfig, boardSettings] = await Promise.all([
+                        client.get(`/stories/${storyId}`),
+                        fetchFeatureConfig(),
+                        fetchBoardSettings(),
+                    ]);
                     const story = storyResponse.data;
                     // Validation & Guardrails
                     const storyLane = typeof story.lane === "string" ? story.lane.trim().toLowerCase() : "";
@@ -931,11 +1102,23 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                         story.learningGoals ||
                         story.hypothesis ||
                         "No specific learning goals identified.";
+                    const revisionFeedbackSection = story.test_plan_feedback
+                        ? `\n## Test Plan Revision Feedback\n> ${story.test_plan_feedback.split("\n").join("\n> ")}\n\n> **Action:** Revise your test plan based on this feedback and call \`propose_test_plan\` again.\n`
+                        : "";
+                    let aiReviewSection = "";
+                    if (story.ai_review) {
+                        const r = story.ai_review;
+                        aiReviewSection = `\n## Previous AI Review\n> ${r.summary || "Review completed."}\n`;
+                        if (r.concerns?.length > 0) {
+                            aiReviewSection += "\n**Concerns to address:**\n" +
+                                r.concerns.map((c) => `- **${c.severity}:** ${c.description}`).join("\n") + "\n";
+                        }
+                    }
                     const formattedBrief = `
 # Implementation Brief: ${story.title}
 
 ${statusWarning}
-
+${revisionFeedbackSection}${aiReviewSection}
 ## Acceptance Criteria
 Here’s the acceptance criteria I’m going to satisfy:
 ${acceptanceCriteria}
@@ -944,6 +1127,8 @@ ${acceptanceCriteria}
 Here are the assumptions I think we’re testing:
 ${assumptions}
 
+${formatTeamContext(teamConfig)}
+${formatDorDodSection(boardSettings, story.dorChecklist, story.dodChecklist)}
 ## Proposal
 Here’s the smallest change that will validate it:
 [Agent should fill this in based on the context above]
@@ -959,12 +1144,20 @@ Here’s the smallest change that will validate it:
                     if (!storyId) {
                         throw new Error("storyId is required");
                     }
-                    const response = await client.post(`/stories/${storyId}/start`, {
-                        branchPrefix: branchPrefix || "feat",
-                        trunkBased,
-                        autoMerge,
-                    });
+                    assertUUID(storyId, "storyId");
+                    // Fetch story start, team config, and board settings in parallel
+                    const [response, teamConfig, boardSettings] = await Promise.all([
+                        client.post(`/stories/${storyId}/start`, {
+                            branchPrefix: branchPrefix || "feat",
+                            trunkBased,
+                            autoMerge,
+                        }),
+                        fetchFeatureConfig(),
+                        fetchBoardSettings(),
+                    ]);
                     const result = response.data;
+                    const teamContext = formatTeamContext(teamConfig);
+                    const dorWarnings = formatDorWarnings(boardSettings, result.dorChecklist);
                     const isTrunk = result.trunkBased;
                     const isAutoMerge = result.autoMerge;
                     let formattedResult;
@@ -989,7 +1182,9 @@ ${result.acceptance_criteria || "No specific AC provided."}
 
 > **Feature Flag:** Wrap new behavior with \`${result.featureFlagName}\` for safe isolation.
 > **TDD Workflow:** Write tests first, then call \`propose_test_plan\` before implementing.
-`;
+
+${teamContext}
+${dorWarnings}`;
                     }
                     else if (isTrunk && isAutoMerge) {
                         formattedResult = `
@@ -1013,7 +1208,9 @@ ${result.acceptance_criteria || "No specific AC provided."}
 
 > **Feature Flag:** Wrap new behavior with \`${result.featureFlagName}\` for safe isolation.
 > **TDD Workflow:** Write tests first, then call \`propose_test_plan\` before implementing.
-`;
+
+${teamContext}
+${dorWarnings}`;
                     }
                     else {
                         formattedResult = `
@@ -1029,7 +1226,9 @@ ${result.acceptance_criteria || "No specific AC provided."}
 ${result.workflow_reminder}
 
 > **TDD Workflow:** Write tests first, then call \`propose_test_plan\` before implementing.
-`;
+
+${teamContext}
+${dorWarnings}`;
                     }
                     return {
                         content: [{ type: "text", text: formattedResult.trim() }],
@@ -1041,20 +1240,33 @@ ${result.workflow_reminder}
                     if (!storyId) {
                         throw new Error("storyId is required");
                     }
+                    assertUUID(storyId, "storyId");
                     if (!testPlan) {
                         throw new Error("testPlan is required");
                     }
+                    // Fetch story to check for previous revision feedback
+                    let previousFeedback = null;
+                    try {
+                        const storyResponse = await client.get(`/stories/${storyId}`);
+                        previousFeedback = storyResponse.data?.test_plan_feedback || null;
+                    }
+                    catch (_) {
+                        // Non-blocking — proceed without feedback context
+                    }
                     const response = await client.post(`/stories/${storyId}/propose-tests`, {
                         testPlan,
                         testFilePaths,
                     });
                     const result = response.data;
+                    const feedbackSection = previousFeedback
+                        ? `\n## Previous Revision Feedback\n> ${previousFeedback.split("\n").join("\n> ")}\n`
+                        : "";
                     const formattedResult = `
 # Test Plan Proposed
 
 **Story ID:** ${storyId}
 **Workflow Stage:** ${result.workflow_stage}
-
+${feedbackSection}
 ## Test Files
 ${(result.test_file_paths || []).map((p) => `- \`${p}\``).join("\n") || "No test files specified"}
 
@@ -1062,6 +1274,30 @@ ${(result.test_file_paths || []).map((p) => `- \`${p}\``).join("\n") || "No test
 ${result.message}
 
 > 🛑 **BLOCKED:** Implementation cannot proceed until a human approves this test plan.
+`;
+                    return {
+                        content: [{ type: "text", text: formattedResult.trim() }],
+                    };
+                }
+                case "approve_tests": {
+                    const args = request.params.arguments;
+                    const { storyId } = args;
+                    if (!storyId) {
+                        throw new Error("storyId is required");
+                    }
+                    assertUUID(storyId, "storyId");
+                    const response = await client.post(`/stories/${storyId}/approve-tests`);
+                    const result = response.data;
+                    const formattedResult = `
+# Test Plan Approved
+
+**Story ID:** ${storyId}
+**Workflow Stage:** ${result.workflow_stage}
+
+## Status
+${result.message}
+
+> ✅ **Approved:** Agent may now proceed with implementation.
 `;
                     return {
                         content: [{ type: "text", text: formattedResult.trim() }],
@@ -1073,6 +1309,7 @@ ${result.message}
                     if (!storyId) {
                         throw new Error("storyId is required");
                     }
+                    assertUUID(storyId, "storyId");
                     const response = await client.post(`/stories/${storyId}/submit-review`, {
                         commitHash,
                         testResults,
@@ -1098,6 +1335,14 @@ git branch -d ${instr.sourceBranch}
 \`\`\`
 `;
                     }
+                    // Format PR section if PR was created or failed
+                    let prSection = "";
+                    if (result.pr_url && result.pr_number) {
+                        prSection = `\n## Pull Request\n**PR:** [#${result.pr_number}](${result.pr_url})\n**Status:** ${result.pr_state || "open"}\n> DoD checklist and acceptance criteria included in PR body.\n`;
+                    }
+                    else if (result.pr_error) {
+                        prSection = `\n## Pull Request\n> PR creation failed: ${result.pr_error}\n> Workflow proceeded successfully — create PR manually if needed.\n`;
+                    }
                     const formattedResult = `
 # Implementation Submitted for Review
 
@@ -1113,7 +1358,7 @@ ${result.featureFlagName ? `**Feature Flag:** \`${result.featureFlagName}\`` : "
 
 ## Commits
 ${(result.commit_hashes || []).map((h) => `- \`${h}\``).join("\n") || "No commits recorded"}
-${autoMergeSection}
+${autoMergeSection}${prSection}
 ## Next Step
 ${result.next_step}
 
@@ -1125,12 +1370,53 @@ ${result.next_step}
                         content: [{ type: "text", text: formattedResult.trim() }],
                     };
                 }
+                case "review_pr": {
+                    const args = request.params.arguments;
+                    const { storyId } = args;
+                    if (!storyId)
+                        throw new Error("storyId is required");
+                    assertUUID(storyId, "storyId");
+                    const reviewResponse = await client.post(`/stories/${storyId}/ai-review`);
+                    const reviewResult = reviewResponse.data;
+                    const review = reviewResult.ai_review;
+                    let acSection = "";
+                    if (review?.acCoverage?.length > 0) {
+                        acSection = "\n## Acceptance Criteria Coverage\n" +
+                            review.acCoverage.map((ac) => {
+                                const icon = ac.status === "met" ? "+" : ac.status === "partial" ? "~" : "-";
+                                return `[${icon}] **${ac.status.toUpperCase()}:** ${ac.criterion}\n    ${ac.evidence}`;
+                            }).join("\n");
+                    }
+                    let dodSection = "";
+                    if (review?.dodValidation?.length > 0) {
+                        dodSection = "\n\n## Definition of Done Validation\n" +
+                            review.dodValidation.map((d) => `[${d.aiVerified ? "x" : " "}] ${d.label} — ${d.note}`).join("\n");
+                    }
+                    let concernsSection = "";
+                    if (review?.concerns?.length > 0) {
+                        concernsSection = "\n\n## Concerns\n" +
+                            review.concerns.map((c) => `- **${c.severity}:** ${c.description}${c.file ? ` (${c.file}${c.line ? `:${c.line}` : ""})` : ""}`).join("\n");
+                    }
+                    const formattedReview = `
+# AI Review — Story ${storyId.substring(0, 8)}
+
+${review?.summary || "Review completed."}
+${acSection}${dodSection}${concernsSection}
+
+---
+_Generated by Elixium AI Review Intelligence_
+`.trim();
+                    return {
+                        content: [{ type: "text", text: formattedReview }],
+                    };
+                }
                 case "estimate_cost": {
                     const args = request.params.arguments;
                     const { storyId, constraints } = args;
                     let { provider } = args;
                     if (!storyId)
                         throw new Error("storyId is required");
+                    assertUUID(storyId, "storyId");
                     // Default provider from infrastructure profile if not explicitly provided
                     if (!provider) {
                         const costConfig = await fetchFeatureConfig();
@@ -1200,6 +1486,7 @@ ${(estimate.assumptions || []).map((a) => `- ${a}`).join("\n")}
                     const { epicId } = args;
                     if (!epicId)
                         throw new Error("epicId is required");
+                    assertUUID(epicId, "epicId");
                     // Fetch all stories and filter by epicId
                     const allStories = await fetchStories();
                     const epicStories = allStories.filter((s) => s.epicId === epicId);
@@ -1302,11 +1589,20 @@ ${unestimated.length === 0
             if (error.response) {
                 console.error("Response data:", error.response.data);
             }
+            let errorText = `Error: ${error.message}`;
+            if (error.response?.status) {
+                errorText += ` (HTTP ${error.response.status})`;
+            }
+            if (error.response?.data) {
+                const data = error.response.data;
+                const detail = typeof data === "string" ? data : JSON.stringify(data);
+                errorText += `\nDetails: ${detail}`;
+            }
             return {
                 content: [
                     {
                         type: "text",
-                        text: `Error: ${error.message}`,
+                        text: errorText,
                     },
                 ],
                 isError: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elixium.ai/mcp-server",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "type": "module",
   "description": "MCP Server for Elixium.ai",
   "publishConfig": {