@elixium.ai/mcp-server 0.1.6 → 0.1.8

package/LICENSE

@@ -0,0 +1 @@
+Copyright (c) 2026 IndirectTek. All rights reserved.

package/README.md

@@ -42,7 +42,8 @@ Add the following to your IDE's MCP configuration file (e.g., `mcp_config.json`)
       "env": {
         "ELIXIUM_API_KEY": "<YOUR_API_KEY>",
         "ELIXIUM_API_URL": "https://<YOUR_TENANT>.elixium.ai/api",
-        "ELIXIUM_BOARD_SLUG": "main"
+        "ELIXIUM_BOARD_SLUG": "main",
+        "ELIXIUM_USER_EMAIL": "<YOUR_EMAIL>"
       }
     }
   }
@@ -52,6 +53,7 @@ Add the following to your IDE's MCP configuration file (e.g., `mcp_config.json`)
 Replace:
 - `<YOUR_API_KEY>` with the API key from your administrator
 - `<YOUR_TENANT>` with your workspace subdomain (e.g., `acme` for `acme.elixium.ai`)
+- `<YOUR_EMAIL>` with your email address (used as the "requester" on stories you create)
 
 > [!NOTE]
 > Different IDEs and MCP clients expect different top-level keys and file paths.
@@ -116,6 +118,7 @@ If you're using multiple MCP servers, combine them in the same config:
 | `ELIXIUM_API_KEY` | ✅ Yes | Your tenant-scoped API key |
 | `ELIXIUM_API_URL` | ✅ Yes | Your tenant's API endpoint (e.g., `https://acme.elixium.ai/api`) |
 | `ELIXIUM_BOARD_SLUG` | ⚠️ Recommended | Board slug to scope operations (e.g., `main`) |
+| `ELIXIUM_USER_EMAIL` | Optional | Your email address. Sets the "Requested by" field when creating stories. Defaults to API key owner. |
 | `ELIXIUM_LANE_STYLE` | Optional | `upper` for `BACKLOG/CURRENT` or `title` for `Backlog/Current` (auto-detected) |
 
 > [!IMPORTANT]
@@ -130,6 +133,39 @@ Once configured, your AI agent will have access to tools like:
 - `list_epics` - View epics on the board
 - `get_iteration_context` - Get current iteration and backlog for planning
 
+### TDD Workflow Tools
+These tools enforce Test-Driven Development for AI agents:
+
+- `start_story` - Start TDD workflow: creates branch, sets workflow_stage to `tdd_start`
+- `propose_test_plan` - Submit test plan for human review (BLOCKS implementation)
+- `submit_for_review` - Submit implementation for human review (requires approved tests)
+
+See the [TDD Workflow Guide](/docs/tdd-workflow) for the complete workflow.
+
+> [!NOTE]
+> Many MCP clients namespace tools by server name. If your MCP config uses the
+> server key `"elixium"`, Codex will typically expose these tools as
+> `mcp_elixium_list_stories`, `mcp_elixium_get_iteration_context`, etc.
+
+## Initialize Agent Workflows
+
+New projects can scaffold the agent workflow documentation with:
+
+```bash
+npx @elixium.ai/mcp-server init
+```
+
+This creates `.agent/workflows/` with:
+- `implement-story.md` - TDD implementation workflow
+- `manage-board.md` - Board management commands
+- `load-board-context.md` - Session context loading
+
+If you already have workflows and want to restore the originals:
+```bash
+rm -rf .agent/workflows
+npx @elixium.ai/mcp-server init
+```
+
 ## Development (Source Build)
 If you're contributing or developing from source:
 

package/dist/index.js

@@ -9,6 +9,7 @@ const API_KEY = process.env.ELIXIUM_API_KEY;
 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
 const CLI_ARGS = process.argv.slice(2);
 const hasArg = (flag) => CLI_ARGS.includes(flag);
 const getArgValue = (flag) => {
@@ -276,6 +277,10 @@ const createServer = () => {
                                 type: "number",
                                 description: "Points (0, 1, 2, 3, 5, 8)",
                             },
+                            requester: {
+                                type: "string",
+                                description: "Email of the person requesting this story. Defaults to ELIXIUM_USER_EMAIL env var or API key owner.",
+                            },
                         },
                         required: ["title"],
                     },
@@ -350,13 +355,21 @@ const createServer = () => {
                                 description: "Roadmap stage",
                                 enum: ["in_progress", "next", "soon", "someday", "archived"],
                             },
+                            hypothesis: { type: "string", description: "We believe that... (outcome hypothesis)" },
+                            successMetrics: { type: "string", description: "We'll know it works when... (success criteria)" },
+                            targetDate: { type: "number", description: "Unix timestamp - when to evaluate outcome (not ship date)" },
+                            outcomeStatus: {
+                                type: "string",
+                                description: "Outcome validation status",
+                                enum: ["exploring", "validating", "achieved", "abandoned"],
+                            },
                         },
                         required: ["title"],
                     },
                 },
                 {
                     name: "update_epic",
-                    description: "Update an epic (title, description, or stage)",
+                    description: "Update an epic (title, description, stage, or outcome fields)",
                     inputSchema: {
                         type: "object",
                         properties: {
@@ -368,6 +381,14 @@ const createServer = () => {
                                 description: "Roadmap stage",
                                 enum: ["in_progress", "next", "soon", "someday", "archived"],
                             },
+                            hypothesis: { type: "string", description: "We believe that... (outcome hypothesis)" },
+                            successMetrics: { type: "string", description: "We'll know it works when... (success criteria)" },
+                            targetDate: { type: "number", description: "Unix timestamp - when to evaluate outcome (not ship date)" },
+                            outcomeStatus: {
+                                type: "string",
+                                description: "Outcome validation status",
+                                enum: ["exploring", "validating", "achieved", "abandoned"],
+                            },
                         },
                         required: ["epicId"],
                     },
@@ -429,6 +450,79 @@ const createServer = () => {
                         required: ["storyId"],
                     },
                 },
+                // TDD Workflow Tools
+                {
+                    name: "start_story",
+                    description: "Start TDD workflow for a story. By default creates a feature branch. Set trunkBased=true to work directly on main (recommended for small changes).",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            storyId: {
+                                type: "string",
+                                description: "ID of the story to start",
+                            },
+                            branchPrefix: {
+                                type: "string",
+                                description: "Branch prefix (feat, fix, chore) - ignored if trunkBased=true",
+                                enum: ["feat", "fix", "chore"],
+                            },
+                            trunkBased: {
+                                type: "boolean",
+                                description: "If true, skip branch creation and commit directly to main. Recommended for small, well-tested changes.",
+                            },
+                        },
+                        required: ["storyId"],
+                    },
+                },
+                {
+                    name: "propose_test_plan",
+                    description: "Submit a test plan for human review. Sets workflow_stage to tests_proposed. Implementation is BLOCKED until human approves.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            storyId: {
+                                type: "string",
+                                description: "ID of the story",
+                            },
+                            testPlan: {
+                                type: "string",
+                                description: "Markdown test plan describing test strategy",
+                            },
+                            testFilePaths: {
+                                type: "array",
+                                items: { type: "string" },
+                                description: "Paths to created test files",
+                            },
+                        },
+                        required: ["storyId", "testPlan"],
+                    },
+                },
+                {
+                    name: "submit_for_review",
+                    description: "Submit implementation for human review. Only works if tests are approved. Sets state to finished.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            storyId: {
+                                type: "string",
+                                description: "ID of the story",
+                            },
+                            commitHash: {
+                                type: "string",
+                                description: "Latest commit SHA",
+                            },
+                            testResults: {
+                                type: "string",
+                                description: "Test output summary",
+                            },
+                            implementationNotes: {
+                                type: "string",
+                                description: "What was implemented",
+                            },
+                        },
+                        required: ["storyId"],
+                    },
+                },
             ],
         };
     });
@@ -448,10 +542,13 @@ const createServer = () => {
                     const args = request.params.arguments;
                     const normalizedLane = await normalizeLane(args.lane);
                     const boardId = await resolveBoardId();
+                    // Use requester from args, fall back to env var, then let backend use API key owner
+                    const requester = args.requester || USER_EMAIL;
                     const response = await client.post("/stories", {
                         ...args,
                         lane: normalizedLane,
                         ...(boardId ? { boardId } : {}),
+                        ...(requester ? { requester } : {}),
                     });
                     return {
                         content: [
@@ -489,11 +586,14 @@ const createServer = () => {
                     const args = request.params.arguments;
                     const normalizedLane = await normalizeLane("Icebox");
                     const boardId = await resolveBoardId();
+                    // Use requester from env var if set
+                    const requester = USER_EMAIL;
                     // Enforce Icebox lane
                     const payload = {
                         ...args,
                         lane: normalizedLane, // Map to lane style expected by API
                         ...(boardId ? { boardId } : {}),
+                        ...(requester ? { requester } : {}),
                     };
                     const response = await client.post("/stories", payload);
                     return {
@@ -621,6 +721,122 @@ Here’s the smallest change that will validate it:
                         content: [{ type: "text", text: formattedBrief.trim() }],
                     };
                 }
+                // TDD Workflow Handlers
+                case "start_story": {
+                    const args = request.params.arguments;
+                    const { storyId, branchPrefix, trunkBased } = args;
+                    if (!storyId) {
+                        throw new Error("storyId is required");
+                    }
+                    const response = await client.post(`/stories/${storyId}/start`, {
+                        branchPrefix: branchPrefix || "feat",
+                        trunkBased: trunkBased || false,
+                    });
+                    const result = response.data;
+                    const isTrunk = trunkBased || result.branch === "main";
+                    const formattedResult = isTrunk ? `
+# Story Started (Trunk-Based): ${storyId}
+
+**Mode:** 🚀 Direct to main (trunk-based development)
+**Workflow Stage:** ${result.workflow_stage}
+
+## Acceptance Criteria
+${result.acceptance_criteria || "No specific AC provided."}
+
+## Trunk-Based Workflow
+1. ✅ Write tests first
+2. ✅ Call \`propose_test_plan\` and wait for approval
+3. ✅ Implement (make tests pass)
+4. ✅ Run \`npm run build\` to verify
+5. ✅ Commit directly to main
+6. 🚀 Auto-deploy on green CI
+
+> ⚠️ **TDD Workflow:** Write tests first, then call \`propose_test_plan\` before implementing.
+` : `
+# Story Started: ${storyId}
+
+**Branch:** \`${result.branch}\`
+**Workflow Stage:** ${result.workflow_stage}
+
+## Acceptance Criteria
+${result.acceptance_criteria || "No specific AC provided."}
+
+## Next Steps
+${result.workflow_reminder}
+
+> ⚠️ **TDD Workflow:** Write tests first, then call \`propose_test_plan\` before implementing.
+`;
+                    return {
+                        content: [{ type: "text", text: formattedResult.trim() }],
+                    };
+                }
+                case "propose_test_plan": {
+                    const args = request.params.arguments;
+                    const { storyId, testPlan, testFilePaths } = args;
+                    if (!storyId) {
+                        throw new Error("storyId is required");
+                    }
+                    if (!testPlan) {
+                        throw new Error("testPlan is required");
+                    }
+                    const response = await client.post(`/stories/${storyId}/propose-tests`, {
+                        testPlan,
+                        testFilePaths,
+                    });
+                    const result = response.data;
+                    const formattedResult = `
+# Test Plan Proposed
+
+**Story ID:** ${storyId}
+**Workflow Stage:** ${result.workflow_stage}
+
+## Test Files
+${(result.test_file_paths || []).map((p) => `- \`${p}\``).join("\n") || "No test files specified"}
+
+## Status
+${result.message}
+
+> 🛑 **BLOCKED:** Implementation cannot proceed until a human approves this test plan.
+`;
+                    return {
+                        content: [{ type: "text", text: formattedResult.trim() }],
+                    };
+                }
+                case "submit_for_review": {
+                    const args = request.params.arguments;
+                    const { storyId, commitHash, testResults, implementationNotes } = args;
+                    if (!storyId) {
+                        throw new Error("storyId is required");
+                    }
+                    const response = await client.post(`/stories/${storyId}/submit-review`, {
+                        commitHash,
+                        testResults,
+                        implementationNotes,
+                    });
+                    const result = response.data;
+                    const formattedResult = `
+# Implementation Submitted for Review
+
+**Story ID:** ${storyId}
+**Status:** ${result.status}
+**Workflow Stage:** ${result.workflow_stage}
+**State:** ${result.state}
+
+## Branch
+\`${result.branch || "No branch recorded"}\`
+
+## Commits
+${(result.commit_hashes || []).map((h) => `- \`${h}\``).join("\n") || "No commits recorded"}
+
+## Next Step
+${result.next_step}
+
+> ✅ **Ready for Review:** Human should review diff and move story to Done lane.
+`;
+                    return {
+                        content: [{ type: "text", text: formattedResult.trim() }],
+                    };
+                }
                 default:
                     throw new Error("Unknown tool");
             }

package/package.json

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

package/templates/workflows/implement-story.md

@@ -4,16 +4,89 @@ description: How to implement an Elixium story using the agent and MCP
 
 Follow this workflow when a developer selects a story for implementation.
 
+> [!IMPORTANT]
+> This workflow enforces **Test-Driven Development**. You cannot skip tests.
+
+## Workflow Modes
+
+| Mode | When to Use | Branch Strategy |
+|------|-------------|-----------------|
+| **Trunk-Based** (recommended) | Small, well-scoped stories (<1 day) | Direct to `main` |
+| **Branch-Based** | Large features, breaking changes | Feature branch → PR → merge |
+
+### 0. Check the North Star
+- **Before any implementation**, read `docs/NORTHSTAR.md` to understand current priorities and principles.
+- Verify the story aligns with the decision framework.
+- If unsure, ask: *"Does this work offline? Is it additive, not modifying?"*
+
 ### 1. Identify & Prepare the Story
 - Ask the developer which story they want to work on, or list the stories in the **Current** lane using `mcp_elixium_list_stories`.
 - Once a story is selected, run the `mcp_elixium_prepare_implementation` tool.
+- Collaborate with developer to refine description and acceptance criteria if needed.
+
+### 2. Start TDD Workflow (MANDATORY)
+- Call `mcp_elixium_start_story` with the storyId.
+- **For trunk-based (default for small changes):** Add `trunkBased: true`
+- **For branch-based (large features):** Omit trunkBased or set to false
+- This sets `workflow_stage: tdd_start`.
+
+```
+// Trunk-based (recommended for most stories)
+mcp_elixium_start_story({ storyId: "abc123", trunkBased: true })
+
+// Branch-based (for larger features)
+mcp_elixium_start_story({ storyId: "abc123", branchPrefix: "feat" })
+```
+
+### 3. Write Tests First (MANDATORY)
+- Create test files that cover the acceptance criteria.
+- Call `mcp_elixium_propose_test_plan` with:
+  - `storyId`: The story ID
+  - `testPlan`: Markdown describing your test strategy
+  - `testFilePaths`: Array of test file paths you created
+
+> [!WARNING]
+> **BLOCKED**: You cannot proceed to implementation until the human approves the test plan.
+> The API will reject `submit_for_review` if tests are not approved.
+
+### 4. Wait for Human Approval
+- The developer will see the "Test Plan" tab in the Elixium UI.
+- They will review your tests and click "Approve Test Plan".
+- Once approved, `workflow_stage` changes to `tests_approved`.
+
+### 5. Implement (Make Tests Pass)
+- Write the minimal code to make tests pass.
+- Run tests frequently: `npm test` or `npx playwright test`.
+- Keep changes small and focused.
+
+### 6. Build Verification (MANDATORY before push)
+- **Run `npm run build`** before EVERY commit/push.
+- This catches:
+    - TypeScript errors
+    - ESLint issues
+    - SSR prerendering failures (e.g., missing Suspense boundaries)
+    - Next.js-specific requirements
+- **DO NOT PUSH if the build fails.**
+- `npx tsc --noEmit` is NOT sufficient - it only checks types, not runtime/SSR issues.
+
+### 7. Submit for Review
+- Call `mcp_elixium_submit_for_review` with:
+  - `storyId`: The story ID
+  - `commitHash`: The commit SHA (optional but recommended)
+  - `implementationNotes`: Summary of what was implemented
+- This sets `state: finished` and `workflow_stage: review`.
+
+### 8. Merge & Deploy
+- **Trunk-based:** Push to main → CI runs → auto-deploys to prod on green ✅
+- **Branch-based:** Create PR → review → merge → auto-deploys to prod
 
-### 2. Review the Brief
-- The tool will output an **Implementation Brief** containing:
-    - **Acceptance Criteria**
-    - **Assumptions / Learning Goals**
-    - **Guardrail Warnings** (e.g., if the story is in the wrong lane)
+### 9. Final Human Review
+- The developer reviews the deployment in production.
+- **Only the developer** can move the story to Done lane.
+- **Only the developer** can set state to `accepted`.
 
-### 3. Propose & Confirm
-- Review the brief and add a **Proposal**: "Here’s the smallest change that will validate it: [Describe minimal slice]"
-- Only after the developer confirms the plan should the agent transition to `EXECUTION` mode.
+### 10. Record Learning
+- Before the developer moves to Done, use `mcp_elixium_record_learning` to capture:
+    - What was validated?
+    - What new risks appeared?
+    - What should be preserved for next time?

package/templates/workflows/load-board-context.md

@@ -9,7 +9,7 @@ Use this workflow at the beginning of a session or when the user asks about boar
 
 ### 1. Load context
 - Call `mcp_elixium_get_iteration_context` immediately.
-- Cache the `current` and `backlog` stories for the rest of the session.
+- Cache the returned `currentIteration` and `backlog` lists for the rest of the session.
 
 ### 2. Keep context fresh
 - Re-run `mcp_elixium_get_iteration_context` if the user asks for the “latest” state

package/templates/workflows/manage-board.md

@@ -8,6 +8,37 @@ Use this workflow for any project management requests (creating stories, checkin
 > **ALWAYS** use the `mcp_elixium_*` tools. **NEVER** try to write scripts to interact with the API directly.
 > The MCP server is your authenticated, context-aware interface to the board.
 
+---
+
+## Available Tools
+
+### Board & Story Management
+| Tool | Purpose |
+|------|---------|
+| `mcp_elixium_list_stories` | View all stories on the board |
+| `mcp_elixium_list_epics` | View high-level initiatives |
+| `mcp_elixium_create_story` | Create a new story |
+| `mcp_elixium_update_story` | Update story fields or move lanes |
+| `mcp_elixium_create_epic` | Create a large initiative |
+| `mcp_elixium_update_epic` | Update epic details or stage |
+| `mcp_elixium_create_hypothesis` | Create assumption for validation |
+| `mcp_elixium_get_iteration_context` | Get Current + Backlog for planning |
+| `mcp_elixium_prepare_implementation` | Get full context for a story |
+| `mcp_elixium_record_learning` | Record outcome after completion |
+
+### TDD Workflow Tools (for implementation)
+| Tool | Purpose |
+|------|---------|
+| `mcp_elixium_start_story` | Start TDD workflow, create branch |
+| `mcp_elixium_propose_test_plan` | Submit tests for human approval |
+| `mcp_elixium_submit_for_review` | Submit implementation for review |
+
+> See `.agent/workflows/implement-story.md` for the full TDD workflow.
+
+---
+
+## Common Operations
+
 ### 1. View the Board
 - Use `mcp_elixium_list_stories` to see the current state of the board.
 - Use `mcp_elixium_list_epics` to see high-level initiatives.