@elixium.ai/mcp-server 0.3.3 → 0.4.0

package/dist/__tests__/board-isolation.test.js

@@ -0,0 +1,83 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { selectBoard, resetBoardContext, getRuntimeBoardId, } from "../board-context.js";
+import { ALL_BOARDS, BOARD_ALPHA, BOARD_BETA, ALPHA_STORIES, BETA_STORIES, ALL_STORIES, ALPHA_EPICS, BETA_EPICS, } from "./fixtures/boards.js";
+const mockClient = {
+    get: vi.fn(),
+    post: vi.fn(),
+};
+beforeEach(() => {
+    vi.clearAllMocks();
+    resetBoardContext();
+});
+/**
+ * Simulates how fetchStories filters by boardId in the MCP server.
+ * This mirrors the logic in index.ts that will use getRuntimeBoardId().
+ */
+const fetchStoriesForBoard = (boardId, allStories) => {
+    if (!boardId)
+        return allStories;
+    return allStories.filter((s) => s.boardId === boardId || !s.boardId);
+};
+const fetchEpicsForBoard = (boardId, allEpics) => {
+    if (!boardId)
+        return allEpics;
+    return allEpics.filter((e) => e.boardId === boardId || !e.boardId);
+};
+describe("board isolation", () => {
+    it("4.1 stories are scoped to selected board", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "alpha");
+        const boardId = getRuntimeBoardId();
+        const stories = fetchStoriesForBoard(boardId, ALL_STORIES);
+        expect(stories).toHaveLength(ALPHA_STORIES.length);
+        expect(stories.every((s) => s.boardId === BOARD_ALPHA.id)).toBe(true);
+    });
+    it("4.1b beta board returns only beta stories", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "beta");
+        const boardId = getRuntimeBoardId();
+        const stories = fetchStoriesForBoard(boardId, ALL_STORIES);
+        expect(stories).toHaveLength(BETA_STORIES.length);
+        expect(stories.every((s) => s.boardId === BOARD_BETA.id)).toBe(true);
+    });
+    it("4.2 creating a story assigns it to selected board", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "alpha");
+        const boardId = getRuntimeBoardId();
+        // Simulate what create_story handler does
+        const payload = {
+            title: "New Story",
+            lane: "Current",
+            ...(boardId ? { boardId } : {}),
+        };
+        expect(payload.boardId).toBe(BOARD_ALPHA.id);
+    });
+    it("4.3 epics respect board context", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "alpha");
+        const boardId = getRuntimeBoardId();
+        const allEpics = [...ALPHA_EPICS, ...BETA_EPICS];
+        const epics = fetchEpicsForBoard(boardId, allEpics);
+        expect(epics).toHaveLength(1);
+        expect(epics[0].boardId).toBe(BOARD_ALPHA.id);
+    });
+    it("4.5 no board selected falls back to all stories", async () => {
+        // No select_board called, no env var
+        const boardId = getRuntimeBoardId();
+        expect(boardId).toBeNull();
+        const stories = fetchStoriesForBoard(boardId, ALL_STORIES);
+        expect(stories).toHaveLength(ALL_STORIES.length);
+    });
+    it("switching boards changes story scope", async () => {
+        // Select alpha
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "alpha");
+        let stories = fetchStoriesForBoard(getRuntimeBoardId(), ALL_STORIES);
+        expect(stories).toHaveLength(ALPHA_STORIES.length);
+        // Switch to beta
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "beta");
+        stories = fetchStoriesForBoard(getRuntimeBoardId(), ALL_STORIES);
+        expect(stories).toHaveLength(BETA_STORIES.length);
+    });
+});

package/dist/__tests__/create-board.test.js

@@ -0,0 +1,97 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { createBoard, resetBoardContext } from "../board-context.js";
+const mockClient = {
+    get: vi.fn(),
+    post: vi.fn(),
+};
+beforeEach(() => {
+    vi.clearAllMocks();
+    resetBoardContext();
+});
+describe("create_board", () => {
+    it("2.1 creates board with name and description", async () => {
+        const created = {
+            id: "new-board-id",
+            slug: "sprint-board",
+            name: "Sprint Board",
+            description: "For sprints",
+            is_archived: false,
+            created_at: "2026-03-23T00:00:00.000Z",
+        };
+        mockClient.post.mockResolvedValue({ data: created });
+        const result = await createBoard(mockClient, {
+            name: "Sprint Board",
+            description: "For sprints",
+        });
+        expect(mockClient.post).toHaveBeenCalledWith("/boards", {
+            name: "Sprint Board",
+            slug: "sprint-board",
+            description: "For sprints",
+        });
+        expect(result.id).toBe("new-board-id");
+        expect(result.slug).toBe("sprint-board");
+        expect(result.name).toBe("Sprint Board");
+    });
+    it("2.2 auto-generates slug from name", async () => {
+        mockClient.post.mockResolvedValue({
+            data: {
+                id: "gen-id",
+                slug: "my-sprint-board",
+                name: "My Sprint Board",
+                is_archived: false,
+                created_at: "2026-03-23T00:00:00.000Z",
+            },
+        });
+        await createBoard(mockClient, { name: "My Sprint Board" });
+        expect(mockClient.post).toHaveBeenCalledWith("/boards", {
+            name: "My Sprint Board",
+            slug: "my-sprint-board",
+            description: "",
+        });
+    });
+    it("2.3 creates board with only required name field", async () => {
+        mockClient.post.mockResolvedValue({
+            data: {
+                id: "min-id",
+                slug: "backlog",
+                name: "Backlog",
+                description: "",
+                is_archived: false,
+                created_at: "2026-03-23T00:00:00.000Z",
+            },
+        });
+        const result = await createBoard(mockClient, { name: "Backlog" });
+        expect(result.name).toBe("Backlog");
+        expect(result.description).toBe("");
+    });
+    it("2.4 rejects creation when board limit reached", async () => {
+        mockClient.post.mockRejectedValue({
+            response: {
+                status: 422,
+                data: { error: "Maximum 3 active boards per tenant" },
+            },
+            message: "Request failed with status code 422",
+        });
+        await expect(createBoard(mockClient, { name: "Fourth Board" })).rejects.toMatchObject({
+            response: { status: 422 },
+        });
+    });
+    it("2.5 rejects duplicate slug within tenant", async () => {
+        mockClient.post.mockRejectedValue({
+            response: {
+                status: 409,
+                data: { error: "Board slug already exists" },
+            },
+            message: "Request failed with status code 409",
+        });
+        await expect(createBoard(mockClient, { name: "Alpha Board" })).rejects.toMatchObject({
+            response: { status: 409 },
+        });
+    });
+    it("2.6 validates name is non-empty", async () => {
+        await expect(createBoard(mockClient, { name: "" })).rejects.toThrow("Board name cannot be empty");
+        await expect(createBoard(mockClient, { name: "   " })).rejects.toThrow("Board name cannot be empty");
+        // Should not call API
+        expect(mockClient.post).not.toHaveBeenCalled();
+    });
+});

package/dist/__tests__/fixtures/boards.js

@@ -0,0 +1,117 @@
+/**
+ * Test fixtures for multi-board MCP tools.
+ */
+export const BOARD_ALPHA = {
+    id: "aaaaaaaa-1111-2222-3333-444444444444",
+    slug: "alpha",
+    name: "Alpha Board",
+    description: "First test board",
+    is_archived: false,
+    created_at: "2026-03-01T00:00:00.000Z",
+    settings: {},
+};
+export const BOARD_BETA = {
+    id: "bbbbbbbb-1111-2222-3333-444444444444",
+    slug: "beta",
+    name: "Beta Board",
+    description: "Second test board",
+    is_archived: false,
+    created_at: "2026-03-02T00:00:00.000Z",
+    settings: {},
+};
+export const BOARD_ARCHIVED = {
+    id: "cccccccc-1111-2222-3333-444444444444",
+    slug: "archived-board",
+    name: "Archived Board",
+    description: "An archived board",
+    is_archived: true,
+    created_at: "2026-02-15T00:00:00.000Z",
+    settings: {},
+};
+export const ALL_BOARDS = [BOARD_ALPHA, BOARD_BETA, BOARD_ARCHIVED];
+export const ACTIVE_BOARDS = [BOARD_ALPHA, BOARD_BETA];
+// Stories assigned to specific boards
+export const ALPHA_STORIES = [
+    {
+        id: "s1111111-1111-1111-1111-111111111111",
+        title: "Alpha Story 1",
+        lane: "Current",
+        state: "started",
+        points: 3,
+        owners: ["user-1"],
+        labels: [],
+        epicId: null,
+        boardId: BOARD_ALPHA.id,
+        storyType: "feature",
+        createdAt: "2026-03-10T00:00:00.000Z",
+    },
+    {
+        id: "s2222222-2222-2222-2222-222222222222",
+        title: "Alpha Story 2",
+        lane: "Backlog",
+        state: "unstarted",
+        points: 2,
+        owners: [],
+        labels: [],
+        epicId: null,
+        boardId: BOARD_ALPHA.id,
+        storyType: "bug",
+        createdAt: "2026-03-11T00:00:00.000Z",
+    },
+];
+export const BETA_STORIES = [
+    {
+        id: "s3333333-3333-3333-3333-333333333333",
+        title: "Beta Story 1",
+        lane: "Current",
+        state: "unstarted",
+        points: 5,
+        owners: ["user-2"],
+        labels: [],
+        epicId: null,
+        boardId: BOARD_BETA.id,
+        storyType: "feature",
+        createdAt: "2026-03-12T00:00:00.000Z",
+    },
+    {
+        id: "s4444444-4444-4444-4444-444444444444",
+        title: "Beta Story 2",
+        lane: "Current",
+        state: "started",
+        points: 1,
+        owners: [],
+        labels: [],
+        epicId: null,
+        boardId: BOARD_BETA.id,
+        storyType: "chore",
+        createdAt: "2026-03-13T00:00:00.000Z",
+    },
+    {
+        id: "s5555555-5555-5555-5555-555555555555",
+        title: "Beta Story 3",
+        lane: "Backlog",
+        state: "unstarted",
+        points: 8,
+        owners: [],
+        labels: [],
+        epicId: null,
+        boardId: BOARD_BETA.id,
+        storyType: "feature",
+        createdAt: "2026-03-14T00:00:00.000Z",
+    },
+];
+export const ALL_STORIES = [...ALPHA_STORIES, ...BETA_STORIES];
+export const ALPHA_EPICS = [
+    {
+        id: "e1111111-1111-1111-1111-111111111111",
+        name: "Alpha Epic",
+        boardId: BOARD_ALPHA.id,
+    },
+];
+export const BETA_EPICS = [
+    {
+        id: "e2222222-2222-2222-2222-222222222222",
+        name: "Beta Epic",
+        boardId: BOARD_BETA.id,
+    },
+];

package/dist/__tests__/list-boards.test.js

@@ -0,0 +1,54 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { listBoards, resetBoardContext, selectBoard } from "../board-context.js";
+import { ALL_BOARDS, ACTIVE_BOARDS, } from "./fixtures/boards.js";
+const mockClient = {
+    get: vi.fn(),
+    post: vi.fn(),
+};
+beforeEach(() => {
+    vi.clearAllMocks();
+    resetBoardContext();
+});
+describe("list_boards", () => {
+    it("1.1 returns all boards with required fields", async () => {
+        mockClient.get.mockResolvedValue({ data: ACTIVE_BOARDS });
+        const result = await listBoards(mockClient);
+        expect(result.boards).toHaveLength(2);
+        for (const board of result.boards) {
+            expect(board).toHaveProperty("id");
+            expect(board).toHaveProperty("name");
+            expect(board).toHaveProperty("slug");
+            expect(board).toHaveProperty("createdAt");
+        }
+    });
+    it("1.2 returns empty array when no boards exist", async () => {
+        mockClient.get.mockResolvedValue({ data: [] });
+        const result = await listBoards(mockClient);
+        expect(result.boards).toEqual([]);
+    });
+    it("1.3 excludes archived boards by default", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        const result = await listBoards(mockClient);
+        expect(result.boards).toHaveLength(2);
+        expect(result.boards.every((b) => !b.isArchived)).toBe(true);
+    });
+    it("1.4 includes archived boards when requested", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        const result = await listBoards(mockClient, { includeArchived: true });
+        expect(result.boards).toHaveLength(3);
+        const archived = result.boards.find((b) => b.slug === "archived-board");
+        expect(archived?.isArchived).toBe(true);
+    });
+    it("1.5 indicates currently selected board", async () => {
+        // First select alpha
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "alpha");
+        // Then list
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        const result = await listBoards(mockClient);
+        const alpha = result.boards.find((b) => b.slug === "alpha");
+        const beta = result.boards.find((b) => b.slug === "beta");
+        expect(alpha?.selected).toBe(true);
+        expect(beta?.selected).toBeUndefined();
+    });
+});

package/dist/__tests__/select-board.test.js

@@ -0,0 +1,74 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { selectBoard, resetBoardContext, getActiveBoardSlug, getRuntimeBoardId, } from "../board-context.js";
+import { ALL_BOARDS, BOARD_ALPHA, BOARD_BETA } from "./fixtures/boards.js";
+const mockClient = {
+    get: vi.fn(),
+    post: vi.fn(),
+};
+beforeEach(() => {
+    vi.clearAllMocks();
+    resetBoardContext();
+});
+describe("select_board", () => {
+    it("3.1 selects board by slug and confirms selection", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        const result = await selectBoard(mockClient, "alpha");
+        expect(result.id).toBe(BOARD_ALPHA.id);
+        expect(result.name).toBe("Alpha Board");
+        expect(result.slug).toBe("alpha");
+        expect(getActiveBoardSlug()).toBe("alpha");
+        expect(getRuntimeBoardId()).toBe(BOARD_ALPHA.id);
+    });
+    it("3.2 case-insensitive slug matching", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        const result1 = await selectBoard(mockClient, "Alpha");
+        expect(result1.id).toBe(BOARD_ALPHA.id);
+        resetBoardContext();
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        const result2 = await selectBoard(mockClient, "ALPHA");
+        expect(result2.id).toBe(BOARD_ALPHA.id);
+    });
+    it("3.3 returns error for invalid slug", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await expect(selectBoard(mockClient, "nonexistent")).rejects.toThrow('Board "nonexistent" not found');
+        // Board context should remain unset
+        expect(getActiveBoardSlug()).toBeNull();
+        expect(getRuntimeBoardId()).toBeNull();
+    });
+    it("3.3b preserves previous selection on error", async () => {
+        // Select alpha first
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "alpha");
+        expect(getActiveBoardSlug()).toBe("alpha");
+        // Try to select nonexistent — should fail
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await expect(selectBoard(mockClient, "nonexistent")).rejects.toThrow();
+        // Alpha should still be selected
+        expect(getActiveBoardSlug()).toBe("alpha");
+        expect(getRuntimeBoardId()).toBe(BOARD_ALPHA.id);
+    });
+    it("3.4 subsequent calls use selected board", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "alpha");
+        // getActiveBoardSlug should return "alpha" for downstream tools
+        expect(getActiveBoardSlug()).toBe("alpha");
+        expect(getRuntimeBoardId()).toBe(BOARD_ALPHA.id);
+    });
+    it("3.5 switching boards updates context", async () => {
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "alpha");
+        expect(getActiveBoardSlug()).toBe("alpha");
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "beta");
+        expect(getActiveBoardSlug()).toBe("beta");
+        expect(getRuntimeBoardId()).toBe(BOARD_BETA.id);
+    });
+    it("3.6 overrides ELIXIUM_BOARD_SLUG env var", async () => {
+        // Before runtime selection, env var is used
+        expect(getActiveBoardSlug("alpha")).toBe("alpha");
+        // After runtime selection, runtime wins
+        mockClient.get.mockResolvedValue({ data: ALL_BOARDS });
+        await selectBoard(mockClient, "beta");
+        expect(getActiveBoardSlug("alpha")).toBe("beta");
+    });
+});

package/dist/board-context.js

@@ -0,0 +1,111 @@
+/**
+ * Board context management for multi-board MCP support.
+ *
+ * Provides runtime board selection that overrides the static
+ * ELIXIUM_BOARD_SLUG env var. All board-aware tools (list_stories,
+ * create_story, list_epics, etc.) use getActiveBoardSlug() to
+ * determine which board to operate on.
+ */
+// Runtime-selected board slug (overrides env var when set)
+let runtimeBoardSlug = null;
+let runtimeBoardId = null;
+/**
+ * Get the active board slug, preferring runtime selection over env var.
+ */
+export const getActiveBoardSlug = (envSlug) => {
+    if (runtimeBoardSlug)
+        return runtimeBoardSlug;
+    if (!envSlug)
+        return null;
+    const normalized = envSlug.trim().toLowerCase();
+    return normalized.length > 0 ? normalized : null;
+};
+/**
+ * Get the runtime-selected board ID (if select_board was called).
+ */
+export const getRuntimeBoardId = () => runtimeBoardId;
+/**
+ * Select a board by slug. Validates that the board exists via API.
+ * Returns the matched board or throws if not found.
+ */
+export const selectBoard = async (client, slug) => {
+    const normalized = slug.trim().toLowerCase();
+    if (!normalized) {
+        throw new Error("Board slug cannot be empty");
+    }
+    const response = await client.get("/boards");
+    const boards = Array.isArray(response.data) ? response.data : [];
+    const match = boards.find((b) => {
+        if (typeof b?.slug !== "string")
+            return false;
+        return b.slug.trim().toLowerCase() === normalized;
+    });
+    if (!match?.id) {
+        const available = boards
+            .filter((b) => !b.is_archived)
+            .map((b) => b.slug)
+            .join(", ");
+        throw new Error(`Board "${slug}" not found. Available boards: ${available || "none"}`);
+    }
+    runtimeBoardSlug = normalized;
+    runtimeBoardId = match.id;
+    return normalizeBoardResponse(match);
+};
+/**
+ * List all boards for the current workspace.
+ */
+export const listBoards = async (client, opts) => {
+    const response = await client.get("/boards");
+    let boards = Array.isArray(response.data) ? response.data : [];
+    if (!opts?.includeArchived) {
+        boards = boards.filter((b) => !b.is_archived);
+    }
+    const summaries = boards.map((b) => normalizeBoardResponse(b));
+    // Mark the currently selected board
+    const activeSlug = getActiveBoardSlug();
+    for (const board of summaries) {
+        if (activeSlug && board.slug === activeSlug) {
+            board.selected = true;
+        }
+    }
+    return { boards: summaries };
+};
+/**
+ * Create a new board via API.
+ */
+export const createBoard = async (client, args) => {
+    const name = args.name?.trim();
+    if (!name) {
+        throw new Error("Board name cannot be empty");
+    }
+    const slug = args.slug?.trim().toLowerCase() ||
+        name
+            .toLowerCase()
+            .replace(/[^a-z0-9]+/g, "-")
+            .replace(/^-|-$/g, "");
+    const response = await client.post("/boards", {
+        name,
+        slug,
+        description: args.description || "",
+    });
+    return normalizeBoardResponse(response.data);
+};
+/**
+ * Reset runtime board selection (for testing).
+ */
+export const resetBoardContext = () => {
+    runtimeBoardSlug = null;
+    runtimeBoardId = null;
+};
+/**
+ * Normalize API board response to BoardSummary.
+ */
+const normalizeBoardResponse = (raw) => ({
+    id: raw.id,
+    slug: raw.slug,
+    name: raw.name,
+    description: raw.description || "",
+    isArchived: raw.is_archived ?? raw.isArchived ?? false,
+    createdAt: raw.created_at ?? raw.createdAt ?? "",
+    ...(raw.storyCount != null ? { storyCount: raw.storyCount } : {}),
+});