@elixium.ai/mcp-server 0.3.6 → 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 } : {}),
+});

package/dist/index.js

@@ -44,6 +44,7 @@ const SSE_PATH = ensurePath(getArgValue("--sse-path") ?? process.env.ELIXIUM_MCP
 const MESSAGE_PATH = ensurePath(getArgValue("--message-path") ??
     process.env.ELIXIUM_MCP_MESSAGE_PATH ??
     "/message", "/message");
+import { listBoards, createBoard, selectBoard, getActiveBoardSlug, getRuntimeBoardId, } from "./board-context.js";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
@@ -98,6 +99,119 @@ const client = axios.create({
         ...(BOARD_SLUG ? { "x-board-slug": BOARD_SLUG } : {}),
     },
 });
+// ── Contract Scanning for prepare_implementation ──
+const CONTRACT_STOP_WORDS = new Set([
+    "the", "a", "an", "is", "are", "was", "were", "be", "been", "being",
+    "have", "has", "had", "do", "does", "did", "will", "would", "could",
+    "should", "may", "might", "shall", "can", "for", "and", "nor", "but",
+    "or", "yet", "so", "in", "on", "at", "to", "of", "by", "with", "from",
+    "up", "about", "into", "through", "during", "before", "after", "above",
+    "below", "between", "out", "off", "over", "under", "again", "further",
+    "then", "once", "here", "there", "when", "where", "why", "how", "all",
+    "each", "every", "both", "few", "more", "most", "other", "some", "such",
+    "no", "not", "only", "own", "same", "than", "too", "very", "just",
+    "because", "as", "until", "while", "that", "this", "these", "those",
+    "it", "its", "we", "they", "add", "update", "fix", "implement", "create",
+    "new", "remove", "change", "make", "use", "set", "get", "check", "ensure",
+    "story", "feature", "bug", "chore", "task",
+]);
+function extractKeywords(title, description = "") {
+    const text = `${title} ${description}`.toLowerCase();
+    const words = text
+        .replace(/[^a-z0-9\s-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !CONTRACT_STOP_WORDS.has(w));
+    return [...new Set(words)];
+}
+function categorizeMatch(content) {
+    if (/\b(create|generate|produce|emit|publish|write|return|send|build|insert)\b/i.test(content))
+        return "producer";
+    if (/\b(consume|read|validate|verify|import|parse|receive|fetch|load|decode|check)\b/i.test(content))
+        return "consumer";
+    return "reference";
+}
+function scanCodebaseForContracts(keywords, cwd) {
+    if (keywords.length === 0)
+        return [];
+    const matches = [];
+    const searchDirs = ["app", "backend/api/src", "mcp-server/src", "components"].map(d => path.join(cwd, d));
+    const extensions = new Set([".ts", ".tsx", ".js", ".jsx"]);
+    const maxMatches = 50;
+    function searchDir(dir) {
+        if (matches.length >= maxMatches)
+            return;
+        try {
+            const entries = fs.readdirSync(dir, { withFileTypes: true });
+            for (const entry of entries) {
+                if (matches.length >= maxMatches)
+                    return;
+                const fullPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    if (entry.name === "node_modules" || entry.name === ".next" || entry.name === "dist")
+                        continue;
+                    searchDir(fullPath);
+                }
+                else if (extensions.has(path.extname(entry.name))) {
+                    try {
+                        const content = fs.readFileSync(fullPath, "utf-8");
+                        const lines = content.split("\n");
+                        for (let i = 0; i < lines.length && matches.length < maxMatches; i++) {
+                            const line = lines[i];
+                            const lineLower = line.toLowerCase();
+                            if (keywords.some((kw) => lineLower.includes(kw))) {
+                                const trimmed = line.trim();
+                                if (trimmed.length > 0 && !trimmed.startsWith("//") && !trimmed.startsWith("*")) {
+                                    matches.push({
+                                        file: path.relative(cwd, fullPath),
+                                        line: i + 1,
+                                        content: trimmed.substring(0, 200),
+                                        role: categorizeMatch(trimmed),
+                                    });
+                                }
+                            }
+                        }
+                    }
+                    catch { /* skip unreadable files */ }
+                }
+            }
+        }
+        catch { /* skip inaccessible dirs */ }
+    }
+    for (const dir of searchDirs) {
+        if (fs.existsSync(dir))
+            searchDir(dir);
+    }
+    return matches;
+}
+function formatContractsSection(matches) {
+    if (matches.length === 0) {
+        return "\n## Integration Contracts\nNo downstream consumers detected.\n";
+    }
+    const producers = matches.filter((m) => m.role === "producer");
+    const consumers = matches.filter((m) => m.role === "consumer");
+    const references = matches.filter((m) => m.role === "reference");
+    let section = "\n## Integration Contracts\n\nThis story touches systems with upstream/downstream dependencies:\n";
+    if (producers.length > 0) {
+        section += "\n**Produces (writes/creates/returns):**\n";
+        for (const p of producers.slice(0, 10)) {
+            section += `- \`${p.file}:${p.line}\` — ${p.content}\n`;
+        }
+    }
+    if (consumers.length > 0) {
+        section += "\n**Consumed by (reads/validates/imports):**\n";
+        for (const c of consumers.slice(0, 10)) {
+            section += `- \`${c.file}:${c.line}\` — ${c.content}\n`;
+        }
+    }
+    if (references.length > 0 && producers.length + consumers.length < 5) {
+        section += "\n**Other references:**\n";
+        for (const r of references.slice(0, 5)) {
+            section += `- \`${r.file}:${r.line}\` — ${r.content}\n`;
+        }
+    }
+    section += "\n> **Note:** This section is informational. Review these contracts before writing your test plan.\n";
+    return section;
+}
 const LANE_TITLE = {
     backlog: "Backlog",
     icebox: "Icebox",
@@ -153,6 +267,10 @@ const normalizeBoardSlug = (value) => {
 let cachedBoardId = null;
 let cachedBoardSlug = null;
 const resolveBoardId = async () => {
+    // Prefer runtime selection from select_board tool
+    const runtimeId = getRuntimeBoardId();
+    if (runtimeId)
+        return runtimeId;
     const slug = normalizeBoardSlug(BOARD_SLUG);
     if (!slug)
         return null;
@@ -336,7 +454,7 @@ const formatDorWarnings = (boardSettings, dorChecklist) => {
 };
 const fetchStories = async () => {
     const boardId = await resolveBoardId();
-    const slug = normalizeBoardSlug(BOARD_SLUG);
+    const slug = getActiveBoardSlug(BOARD_SLUG) ?? normalizeBoardSlug(BOARD_SLUG);
     const isMainBoard = slug === "main";
     // For the "main" board, fetch ALL stories (no boardId filter) then filter
     // client-side. This matches the frontend behavior: legacy stories have
@@ -354,7 +472,7 @@ const fetchStories = async () => {
 };
 const fetchEpics = async () => {
     const boardId = await resolveBoardId();
-    const slug = normalizeBoardSlug(BOARD_SLUG);
+    const slug = getActiveBoardSlug(BOARD_SLUG) ?? normalizeBoardSlug(BOARD_SLUG);
     const isMainBoard = slug === "main";
     const response = await client.get("/epics", {
         params: boardId && !isMainBoard ? { boardId } : undefined,
@@ -434,6 +552,55 @@ const createServer = () => {
         const teamDecisionsEnabled = featureConfig.features.teamDecisions;
         const ragKnowledgeBaseEnabled = featureConfig.features.ragKnowledgeBase;
         const baseTools = [
+            {
+                name: "list_boards",
+                description: "List all boards in the workspace. Returns id, name, slug, and story count for each board. Marks the currently selected board.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        includeArchived: {
+                            type: "boolean",
+                            description: "Include archived boards (default false)",
+                        },
+                    },
+                },
+            },
+            {
+                name: "create_board",
+                description: "Create a new board in the workspace. Auto-generates slug from name if not provided. Max 3 active boards per tenant.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        name: {
+                            type: "string",
+                            description: "Name for the new board",
+                        },
+                        description: {
+                            type: "string",
+                            description: "Optional description",
+                        },
+                        slug: {
+                            type: "string",
+                            description: "Optional custom slug (auto-generated from name if omitted)",
+                        },
+                    },
+                    required: ["name"],
+                },
+            },
+            {
+                name: "select_board",
+                description: "Switch the active board context. All subsequent tool calls (list_stories, create_story, list_epics, etc.) will operate against the selected board. Overrides ELIXIUM_BOARD_SLUG env var for this session.",
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        slug: {
+                            type: "string",
+                            description: "Slug of the board to select (case-insensitive)",
+                        },
+                    },
+                    required: ["slug"],
+                },
+            },
             {
                 name: "get_feature_config",
                 description: "Get the feature configuration for this board/workspace. Returns enabled features, team profile, and smart defaults context.",
@@ -757,6 +924,14 @@ const createServer = () => {
                             type: "boolean",
                             description: "If true with trunkBased, creates a short-lived branch that auto-merges to main on submit_for_review. Branch is deleted after merge.",
                         },
+                        skipGates: {
+                            type: "boolean",
+                            description: "If true, bypasses the test plan approval gate. For hotfixes/emergencies only. Bypass is recorded in the story audit trail.",
+                        },
+                        skipReason: {
+                            type: "string",
+                            description: "Reason for bypassing gates (e.g., 'hotfix for production outage'). Recorded in the audit trail.",
+                        },
                     },
                     required: ["storyId"],
                 },
@@ -1046,6 +1221,50 @@ const createServer = () => {
                 }
             }
             switch (toolName) {
+                case "list_boards": {
+                    const args = request.params.arguments;
+                    const result = await listBoards(client, {
+                        includeArchived: args?.includeArchived,
+                    });
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+                    };
+                }
+                case "create_board": {
+                    const args = request.params.arguments;
+                    const board = await createBoard(client, {
+                        name: args.name,
+                        description: args.description,
+                        slug: args.slug,
+                    });
+                    // Invalidate feature config cache since board list changed
+                    cachedFeatureConfig = null;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `# Board Created\n\n- **Name:** ${board.name}\n- **Slug:** ${board.slug}\n- **ID:** ${board.id}\n\n> Use \`select_board\` with slug "${board.slug}" to switch to this board.`,
+                            },
+                        ],
+                    };
+                }
+                case "select_board": {
+                    const args = request.params.arguments;
+                    const board = await selectBoard(client, args.slug);
+                    // Invalidate caches so subsequent calls use new board context
+                    cachedFeatureConfig = null;
+                    cachedBoardId = null;
+                    cachedBoardSlug = null;
+                    cachedLaneStyle = null;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: `# Board Selected\n\n- **Name:** ${board.name}\n- **Slug:** ${board.slug}\n- **ID:** ${board.id}\n\nAll subsequent tool calls will operate against this board.`,
+                            },
+                        ],
+                    };
+                }
                 case "get_feature_config": {
                     const config = await fetchFeatureConfig();
                     const formattedConfig = `
@@ -1402,6 +1621,17 @@ ${config.infrastructureProfile?.provider ? `- Provider: ${config.infrastructureP
                         }).join("\n");
                         knowledgeSection = `\n## Related Knowledge\n${formatted}\n`;
                     }
+                    // Scan codebase for integration contracts (non-blocking)
+                    let contractsSection = "";
+                    try {
+                        const keywords = extractKeywords(story.title, story.description || "");
+                        const cwd = process.cwd();
+                        const contractMatches = scanCodebaseForContracts(keywords, cwd);
+                        contractsSection = formatContractsSection(contractMatches);
+                    }
+                    catch {
+                        contractsSection = "\n## Integration Contracts\nContract scanning unavailable.\n";
+                    }
                     const formattedBrief = `
 # Implementation Brief: ${story.title}
 
@@ -1414,7 +1644,7 @@ ${acceptanceCriteria}
 ## Assumptions
 Here are the assumptions I think we’re testing:
 ${assumptions}
-${decisionsSection}${knowledgeSection}
+${decisionsSection}${knowledgeSection}${contractsSection}
 ${formatTeamContext(teamConfig)}
 ${formatDorDodSection(boardSettings, story.dorChecklist, story.dodChecklist)}
 ## Proposal
@@ -1428,7 +1658,7 @@ Here’s the smallest change that will validate it:
                 // TDD Workflow Handlers
                 case "start_story": {
                     const args = request.params.arguments;
-                    const { storyId, branchPrefix, trunkBased, autoMerge } = args;
+                    const { storyId, branchPrefix, trunkBased, autoMerge, skipGates, skipReason } = args;
                     if (!storyId) {
                         throw new Error("storyId is required");
                     }
@@ -1439,6 +1669,8 @@ Here’s the smallest change that will validate it:
                             branchPrefix: branchPrefix || "feat",
                             trunkBased,
                             autoMerge,
+                            ...(skipGates && { skipGates: true }),
+                            ...(skipReason && { skipReason }),
                         }),
                         fetchFeatureConfig(),
                         fetchBoardSettings(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elixium.ai/mcp-server",
-  "version": "0.3.6",
+  "version": "0.4.0",
   "type": "module",
   "description": "MCP Server for Elixium.ai",
   "mcpName": "io.github.IndirectTek/mcp-server",
@@ -19,6 +19,8 @@
   },
   "scripts": {
     "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "start": "node dist/index.js",
     "dev": "ts-node src/index.ts"
   },
@@ -30,6 +32,7 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "ts-node": "^10.9.0",
-    "typescript": "^5.3.0"
+    "typescript": "^5.3.0",
+    "vitest": "^4.1.1"
   }
 }