@elixium.ai/mcp-server 0.4.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
 
@@ -125,6 +126,30 @@ If you're using multiple MCP servers, combine them in the same config:
 > If you set `ELIXIUM_BOARD_SLUG`, the MCP server will only read/write stories for that board.
 > The server resolves the board slug to a boardId on startup, so the slug must match an existing board.
 
+## Required Scopes (for Scoped API Keys)
+
+If you generate a **scoped** API key (via the Command Center → Integrations → *Advanced: Key Scopes*), the key must include the scopes below to use the corresponding MCP tools. An **unscoped** key (all scopes picker collapsed when generating) has full access and works with every tool.
+
+| Tool category | Tools | Required scopes |
+|---|---|---|
+| **Read stories** | `list_stories`, `get_story`, `get_iteration_context`, `prepare_implementation`, `estimate_cost` | `stories:read` |
+| **Write stories** | `create_story`, `update_story`, `start_story`, `propose_test_plan`, `submit_for_review`, `record_learning`, `create_hypothesis` | `stories:read` + `stories:write` |
+| **Read epics** | `list_epics`, `get_epic_cost_rollup` | `epics:read` |
+| **Write epics** | `create_epic`, `update_epic`, `prioritize_epic` | `epics:read` + `epics:write` |
+| **Read boards** | `list_boards`, `select_board` | `boards:read` |
+| **Write boards** | `create_board` | `boards:read` + `boards:write` |
+| **Read workspace config** | `get_feature_config`, `get_infrastructure_profile` | `workspace:read` |
+| **Team decisions** | `list_decisions`, `search_decisions` | `stories:read` |
+| **Team decisions (write)** | `record_decision` | `stories:read` + `stories:write` |
+| **Objectives** | `list_objectives` | `stories:read` |
+
+**Recommended baseline for full MCP functionality:**
+```
+stories:read, stories:write, epics:read, epics:write, boards:read, workspace:read
+```
+
+If a scoped key is missing a scope, the MCP server surfaces an actionable error message naming the missing scope and directing you to regenerate the key with the required scope. You do NOT need to restart the MCP server after regenerating — just update `ELIXIUM_API_KEY` in your config and reload the server.
+
 ## Usage
 Once configured, your AI agent will have access to tools like:
 - `list_stories` - View all stories on the board

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/constants/workflowModelLabels.js

@@ -0,0 +1,59 @@
+/**
+ * Canonical workflow model labels for MCP tool responses.
+ *
+ * Story 69c3a615 — surfaces the active workflow model in `start_story` and
+ * `submit_for_review` responses so agents (and through them, users) know
+ * what state transitions to expect. Story 79f641d5 (Team Profile UI) will
+ * import the same constants to keep terminology aligned across layers.
+ *
+ * AC: "model name matches the Team Profile UI's label exactly (no
+ * terminology drift between layers)" — this module is the single source.
+ */
+export const WORKFLOW_MODEL_NAMES = {
+    /** Pivotal-style 4-state model with explicit `delivered` step. */
+    pivotal4State: "4-state (Pivotal)",
+    /** Trunk-based 3-state model — no delivered step, finished → accepted. */
+    trunk3State: "3-state (simple)",
+};
+/** Per-state parenthetical explanations under each model. */
+export const WORKFLOW_MODEL_STATE_EXPLANATION = {
+    pivotal4State: {
+        delivered: "work is on main, awaiting acceptance",
+        finished: "PR pending merge, advances to delivered when merged",
+    },
+    trunk3State: {
+        finished: "story moves directly to accepted on human review",
+    },
+};
+/** At-start (no state yet) explanations — used by `start_story`. */
+export const WORKFLOW_MODEL_START_EXPLANATION = {
+    pivotal4State: "submit will set delivered (auto-merge) or finished (PR pending)",
+    trunk3State: "submit advances to finished, accept moves to accepted",
+};
+/**
+ * Formats the canonical "Workflow Model:" line for MCP tool responses.
+ *
+ * Examples:
+ *   { useDeliveredState: true, state: "delivered" }
+ *     → "4-state (Pivotal — work is on main, awaiting acceptance)"
+ *   { useDeliveredState: false, state: "finished" }
+ *     → "3-state (simple — story moves directly to accepted on human review)"
+ *   { useDeliveredState: true } (no state — start_story case)
+ *     → "4-state (Pivotal — submit will set delivered (auto-merge) or finished (PR pending))"
+ *
+ * Single-line output guarantee: the returned string never contains a newline
+ * — callers can safely interpolate it as one row in a markdown response.
+ */
+export function formatWorkflowModelLine(args) {
+    const modelKey = args.useDeliveredState ? "pivotal4State" : "trunk3State";
+    const baseName = args.useDeliveredState ? "4-state" : "3-state";
+    const typeLabel = args.useDeliveredState ? "Pivotal" : "simple";
+    let explanation = WORKFLOW_MODEL_START_EXPLANATION[modelKey];
+    if (args.state) {
+        const stateExplanations = WORKFLOW_MODEL_STATE_EXPLANATION[modelKey];
+        const found = stateExplanations[args.state];
+        if (found)
+            explanation = found;
+    }
+    return `${baseName} (${typeLabel} — ${explanation})`;
+}