@elixium.ai/mcp-server 0.5.0 → 0.6.0

package/README.md

@@ -7,6 +7,7 @@ This server implements the [Model Context Protocol (MCP)](https://modelcontextpr
 - **Create Story**: Add new stories directly from your editor.
 - **Update Story**: Move stories between lanes and update fields.
 - **Iteration Context**: Provide the AI with the full context of your Current and Backlog lanes for better planning.
+- **Board Context** (new in 0.6.0): One-call grounding tool (`get_board_context`) that returns a time-balanced workspace snapshot — in-flight work, queued/icebox/recently-completed stories and epics, recent decisions, objectives, learnings, and workspace configuration — so agents ground themselves before drafting or updating content. Requires a backend release that includes `GET /api/board-context` (SaaS: live since 2026-05-17; self-hosted: update to a matching release). Falls back gracefully with a usable message if the backend is older.
 
 ## Quick Start
 

package/dist/constants/featureConfigFallback.js

@@ -0,0 +1,30 @@
+/**
+ * Error-fallback feature config used by the mcp-server when the backend
+ * `/config/features` endpoint is unreachable. Extracted from `src/index.ts`
+ * so it can be imported into tests without triggering the entrypoint's
+ * top-level await (`startStdioServer` / `startSseServer`).
+ *
+ * `useDeliveredState` defaults to `false` (3-state simple) per story 16f8ede4
+ * — matches the backend smart default, so a transient fetch failure won't
+ * silently re-introduce 4-state behavior on the agent side.
+ */
+export const MCP_FEATURE_CONFIG_ERROR_FALLBACK = {
+    features: {
+        balancedTeam: false,
+        learningLoop: false,
+        tddWorkflow: true,
+        aiTools: true,
+        teamDecisions: false,
+        ragKnowledgeBase: false,
+        useDeliveredState: false,
+    },
+    source: {
+        balancedTeam: "error-fallback",
+        learningLoop: "error-fallback",
+        tddWorkflow: "error-fallback",
+        aiTools: "error-fallback",
+        teamDecisions: "error-fallback",
+        ragKnowledgeBase: "error-fallback",
+        useDeliveredState: "error-fallback",
+    },
+};

package/dist/index.js

@@ -8,6 +8,7 @@ import * as http from "node:http";
 import { CREATE_STORY_INPUT_SCHEMA, UPDATE_STORY_INPUT_SCHEMA, GET_STAKEHOLDERS_INPUT_SCHEMA, PROPOSE_FIELD_DRAFT_INPUT_SCHEMA, ENDORSE_PROPOSAL_INPUT_SCHEMA, REJECT_PROPOSAL_INPUT_SCHEMA, DRAFT_HYPOTHESIS_INPUT_SCHEMA, GET_TRUST_LEAKAGE_INPUT_SCHEMA, } from "./toolSchemas.js";
 import { deriveStakeholders } from "./stakeholders.js";
 import { formatWorkflowModelLine } from "./constants/workflowModelLabels.js";
+import { MCP_FEATURE_CONFIG_ERROR_FALLBACK } from "./constants/featureConfigFallback.js";
 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;
@@ -314,27 +315,8 @@ const fetchFeatureConfig = async () => {
         return response.data;
     }
     catch (error) {
-        console.error("Failed to fetch feature config, defaulting to all enabled:", error);
-        return {
-            features: {
-                balancedTeam: true,
-                learningLoop: true,
-                tddWorkflow: true,
-                aiTools: true,
-                teamDecisions: false,
-                ragKnowledgeBase: false,
-                useDeliveredState: true,
-            },
-            source: {
-                balancedTeam: "error-fallback",
-                learningLoop: "error-fallback",
-                tddWorkflow: "error-fallback",
-                aiTools: "error-fallback",
-                teamDecisions: "error-fallback",
-                ragKnowledgeBase: "error-fallback",
-                useDeliveredState: "error-fallback",
-            },
-        };
+        console.error("Failed to fetch feature config, using error fallback:", error);
+        return MCP_FEATURE_CONFIG_ERROR_FALLBACK;
     }
 };
 // Helper functions to check individual features
@@ -648,7 +630,7 @@ const createServer = () => {
             },
             {
                 name: "create_story",
-                description: "Create a new story on the Elixium board. Accepts storyType (feature/bug/chore/platform) at create time.",
+                description: "Create a story on the active board. New stories enter the Backlog lane and are attributed to the user bound to your API key. Stories you create without current board context risk duplicating in-flight work or contradicting recent decisions. Ensure you are grounded before writing — if you haven't grounded this session, call `get_board_context` (optionally with `intent` set to the user's request for similar-story matching). This is the normal path when a user asks you to draft a story; it is not a bypass of human review, which happens at downstream workflow gates. Accepts storyType (feature/bug/chore/platform) at create time. Use `propose_field_draft` for asynchronous suggestions on fields of an existing story.",
                 inputSchema: CREATE_STORY_INPUT_SCHEMA,
             },
             {
@@ -659,6 +641,19 @@ const createServer = () => {
                     properties: {},
                 },
             },
+            {
+                name: "get_board_context",
+                description: "Get a snapshot of the workspace's board state for grounding before drafting or updating content. Returns time-balanced sections: inFlight (Current lane + in_progress epics), queued (Backlog + next/soon epics), icebox (Icebox + someday epics), recentlyCompleted (Done + archived epics), decisions, objectives, learnings, plus configuration (feature flags, workflow stages). Pass `intent` (free-form text of what you're about to do; the user's verbatim request is fine) to additionally receive `similar` — existing stories ranked by relevance. Stories you create or update without current board context risk duplicating in-flight work or contradicting recent decisions; ensure you are grounded before writing.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        intent: {
+                            type: "string",
+                            description: "Optional free-form text describing what you're about to do (e.g., the user's verbatim request, or a short topic phrase). When provided, the response additionally includes a `similar` section ranked by relevance.",
+                        },
+                    },
+                },
+            },
             {
                 name: "list_objectives",
                 description: "List objectives for the current workspace",
@@ -677,7 +672,7 @@ const createServer = () => {
             },
             {
                 name: "create_epic",
-                description: "Create a new epic for the current board",
+                description: "Create an epic for the active board. Epics group related stories around an outcome hypothesis. Before creating, ensure you are grounded — call `get_board_context` to surface existing epics, workspace objectives, and recent decisions; duplicate or overlapping epics are easy to introduce without that context. Epics are attributed to the user bound to your API key. Use `update_epic` to revise an existing epic rather than duplicating.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -702,7 +697,7 @@ const createServer = () => {
             },
             {
                 name: "update_epic",
-                description: "Update an epic (title, description, stage, or outcome fields)",
+                description: "Update an epic's title, description, stage, or outcome fields (hypothesis, success metrics, outcome status, target date). Before updating, ensure you are grounded — call `get_board_context` for current board state and recent decisions that may affect this epic. Updates are attributed to the user bound to your API key.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -728,7 +723,7 @@ const createServer = () => {
             },
             {
                 name: "update_story",
-                description: "Update fields on an existing story. Accepts Learning Loop fields (hypothesis, confidence_score, hidden_unknowns, risk_profile) and storyType in addition to the basics.",
+                description: "Update fields on an existing story. Accepts Learning Loop fields (hypothesis, confidence_score, hidden_unknowns, risk_profile) and storyType in addition to the basics. Before updating, call `get_story` to inspect current state, and `get_board_context` if your update relates to a topic that may be governed by a recent team decision. Updates are attributed to the user bound to your API key.",
                 inputSchema: UPDATE_STORY_INPUT_SCHEMA,
             },
             {
@@ -738,7 +733,7 @@ const createServer = () => {
             },
             {
                 name: "propose_field_draft",
-                description: "Submit an AI-drafted value for a Learning Loop field as a pending proposal. The draft does NOT change the story until a human endorses via endorse_proposal. Caller should disclose `provider` (LLM model) and `agent` (client+version) for trust attribution.",
+                description: "Submit an AI-drafted value for a Learning Loop field as a pending proposal. The draft does NOT change the story until a human endorses via endorse_proposal. Caller should disclose `provider` (LLM model) and `agent` (client+version) for trust attribution. Stories whose fields you propose without current board context risk contradicting recent decisions in this area. Ensure you are grounded before drafting — call `get_board_context` if you haven't grounded this session.",
                 inputSchema: PROPOSE_FIELD_DRAFT_INPUT_SCHEMA,
             },
             {
@@ -753,7 +748,7 @@ const createServer = () => {
             },
             {
                 name: "draft_hypothesis",
-                description: "Reference consumer of the proposal primitive: backend calls AI_PROVIDER to generate a hypothesis draft for the given story, then submits it as a pending proposal. Pattern for §4 outcome-from-evidence and §6 v2 missing-field drafter to follow.",
+                description: "Generate an AI-drafted hypothesis for the given story and submit it as a pending proposal. The backend calls the configured AI_PROVIDER, drafts the hypothesis text, and creates a proposal that a human must endorse via `endorse_proposal` before the story's hypothesis field is updated. The draft does not change the story until endorsed.",
                 inputSchema: DRAFT_HYPOTHESIS_INPUT_SCHEMA,
             },
             {
@@ -879,7 +874,7 @@ const createServer = () => {
             },
             {
                 name: "propose_test_plan",
-                description: "Submit a test plan for human review. Sets workflow_stage to tests_proposed. Implementation is BLOCKED until human approves.",
+                description: "Submit a test plan for human review. Sets workflow_stage to tests_proposed. Implementation is BLOCKED until human approves. Before proposing, call `get_story` to inspect the story's hypothesis, hidden_unknowns, and risk_profile (the test plan should ground in those fields). Use `draft_test_plan` first for a scaffold seeded from the story's premortem assumptions.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -987,7 +982,7 @@ const createServer = () => {
         const learningLoopTools = learningLoopEnabled ? [
             {
                 name: "create_hypothesis",
-                description: "Create a new assumption/hypothesis in the Icebox for validation",
+                description: "Create a new assumption/hypothesis in the Icebox for validation. Before creating, ensure you are grounded — call `get_board_context` to check for existing related hypotheses and recent decisions in this area. The hypothesis is attributed to the user bound to your API key.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -1005,7 +1000,7 @@ const createServer = () => {
             },
             {
                 name: "record_learning",
-                description: "Record a learning outcome for a completed story",
+                description: "Record a learning outcome for a completed story (sets the story's outcome_summary field). The learning is visible in the workspace's recent-learnings surface. Before recording, call `get_story` to inspect the story's current state, and `get_board_context` to surface recently-recorded learnings on related stories that may already capture the same insight.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -1023,7 +1018,7 @@ const createServer = () => {
         const teamDecisionsTools = teamDecisionsEnabled ? [
             {
                 name: "record_decision",
-                description: "Record a team decision, meeting outcome, or architectural choice. These are shared across all team members' AI sessions.",
+                description: "Record a team decision, meeting outcome, or architectural choice. These are shared across all team members' AI sessions. Before recording, ensure you are grounded — call `get_board_context` to check whether a recent decision already covers this area; duplicate or contradictory decisions are exactly what this tool exists to prevent.",
                 inputSchema: {
                     type: "object",
                     properties: {
@@ -1366,6 +1361,58 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                         ],
                     };
                 }
+                case "get_board_context": {
+                    // Thin wrapper around GET /api/board-context. The backend composes
+                    // the response; this handler forwards the optional `intent` query
+                    // param and wraps the response in MCP content format.
+                    //
+                    // Note: the backend also supports a `since` parameter for conditional
+                    // return (sentinel when workspace state hasn't shifted), but it is
+                    // intentionally NOT exposed at the MCP layer until the
+                    // context_version invariant ships (separate follow-on story:
+                    // "Wire context_version invariant with chosen atomicity pattern").
+                    // Without per-write version bumps, the sentinel would be unreliable
+                    // (stale `unchanged: true` for state that did change).
+                    //
+                    // Graceful 404 fallback: if the backend is older than 2026-05-17
+                    // (or a self-hosted release that doesn't include this endpoint),
+                    // return a structured message pointing the agent at the existing
+                    // multi-tool orchestration path rather than throwing an opaque
+                    // error. Version skew between mcp-server and backend is the most
+                    // common failure mode for new MCP tools; surfacing it well here
+                    // is cheaper than every customer filing the same bug report.
+                    const args = request.params.arguments ?? {};
+                    const params = {};
+                    if (typeof args.intent === "string" && args.intent.trim()) {
+                        params.intent = args.intent.trim();
+                    }
+                    try {
+                        const response = await client.get("/board-context", { params });
+                        return {
+                            content: [
+                                { type: "text", text: JSON.stringify(response.data, null, 2) },
+                            ],
+                        };
+                    }
+                    catch (err) {
+                        if (err?.response?.status === 404) {
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: JSON.stringify({
+                                            error: "get_board_context is not available on this backend",
+                                            reason: "The backend does not expose GET /api/board-context. This is likely a version-skew issue: the tool was added in mcp-server 0.6.0 (2026-05-17) and requires a backend release that includes the matching endpoint.",
+                                            fallback: "Until the backend is updated, orchestrate grounding manually: call `get_iteration_context` (in-flight work), `list_epics` (queued and in-progress epics), `list_decisions` (recent team decisions in the workspace), and `get_feature_config` (workspace configuration). The trade-offs are more tool calls and no time-balanced sections or similar-story matching, but the agent still gets the underlying grounding data.",
+                                            action: "Self-hosted: update the backend to a release that includes GET /api/board-context. SaaS (elixium.ai-hosted): contact support — the endpoint should already be live on hosted backends.",
+                                        }, null, 2),
+                                    },
+                                ],
+                            };
+                        }
+                        throw err;
+                    }
+                }
                 case "create_hypothesis": {
                     const args = request.params.arguments;
                     const normalizedLane = await normalizeLane("Icebox");

package/dist/toolSchemas.js

@@ -69,6 +69,11 @@ export const CREATE_STORY_INPUT_SCHEMA = {
             description: "Categorizes the story for filtering and Learning Loop signals (feature, bug, chore, platform).",
             enum: STORY_TYPE_ENUM,
         },
+        owners: {
+            type: "array",
+            items: { type: "string" },
+            description: "Story d9541094 — Firebase UIDs of the story's owners. If omitted, the backend auto-assigns the API key's owner UID (so MCP-created stories show up under the user's 'My Stories' filter). Pass an explicit array to assign teammates, or `[]` to create intentionally unowned.",
+        },
     },
     required: ["title"],
 };
@@ -230,6 +235,11 @@ export const UPDATE_STORY_INPUT_SCHEMA = {
             description: "Categorizes risk (User, Tech, Market, Compliance, Model_Drift). Earns trust with governance and compliance audiences.",
             enum: RISK_PROFILE_ENUM,
         },
+        owners: {
+            type: "array",
+            items: { type: "string" },
+            description: "Story d9541094 — Firebase UIDs of the story's owners. Replaces the existing array (PATCH semantics). Pass `[]` to clear owners. Use this to retroactively assign yourself or a teammate to a story whose owners were dropped before the auto-assign fix landed.",
+        },
     },
     required: ["storyId"],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elixium.ai/mcp-server",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "MCP Server for Elixium.ai",
   "mcpName": "io.github.IndirectTek/mcp-server",
@@ -31,5 +31,10 @@
     "@types/node": "^20.0.0",
     "ts-node": "^10.9.0",
     "typescript": "^5.3.0"
+  },
+  "overrides": {
+    "ip-address": "^10.1.1",
+    "hono": "^4.12.18",
+    "fast-uri": "^3.1.2"
   }
 }