@zeroclickdev/zeroboard-mcp 0.1.0

package/README.md

@@ -0,0 +1,101 @@
+# @zeroclickdev/zeroboard-mcp
+
+An [MCP](https://modelcontextprotocol.io) server for **ZeroBoard** — manage your boards, columns, and cards from any MCP‑compatible coding agent (Claude Code, Cursor, Zed, Windsurf).
+
+> Status: **v1 core** (issue #9). Read/write tools + resources over stdio, authenticated with your ZeroBoard (Supabase) account. See [Roadmap](#roadmap) for what's next.
+
+## Quick start
+
+```bash
+# Sign in once — opens your browser (Google or email); stores a refreshable
+# session under ~/.zeroboard.
+npx -y @zeroclickdev/zeroboard-mcp login
+
+# Headless / no browser? Use password sign-in instead:
+ZEROBOARD_EMAIL=you@example.com ZEROBOARD_PASSWORD=… npx -y @zeroclickdev/zeroboard-mcp login --password
+
+# Check who you are
+npx -y @zeroclickdev/zeroboard-mcp status
+```
+
+Then add the server to your agent (below). The default command (no subcommand) runs the MCP server over stdio.
+
+## Client configuration
+
+**Claude Code**
+```bash
+claude mcp add zeroboard -- npx -y @zeroclickdev/zeroboard-mcp
+```
+
+**Cursor** — `~/.cursor/mcp.json`
+```json
+{ "mcpServers": { "zeroboard": { "command": "npx", "args": ["-y", "@zeroclickdev/zeroboard-mcp"] } } }
+```
+
+**Zed** — `settings.json`
+```json
+{ "context_servers": { "zeroboard": { "command": { "path": "npx", "args": ["-y", "@zeroclickdev/zeroboard-mcp"] } } } }
+```
+
+**Windsurf** — `mcp_config.json`
+```json
+{ "mcpServers": { "zeroboard": { "command": "npx", "args": ["-y", "@zeroclickdev/zeroboard-mcp"] } } }
+```
+
+Add `"--read-only"` to `args` (or set `ZEROBOARD_READONLY=1`) to expose only the read tools.
+
+## Tools
+
+**Read:** `list_boards`, `get_board`, `list_columns`, `list_cards`, `get_card`, `search`
+
+**Write:** `create_board`, `generate_board` (AI — create a board from a prompt), `update_board`, `delete_board`, `add_column`, `update_column`, `remove_column`, `reorder_columns`, `add_card`, `update_card`, `move_card`, `archive_card`, `restore_card`, `duplicate_card`, `delete_card`, `add_checklist_item`, `toggle_checklist_item`, `add_label`, `remove_label`, `set_target_date`, `set_cover_image`
+
+Destructive tools (`delete_board`, `delete_card`, `remove_column`) carry a `destructiveHint`; reads carry `readOnlyHint`, so clients can warn or auto-approve appropriately.
+
+## Resources
+
+- `zeroboard://me` — the signed‑in account
+- `zeroboard://boards` — index of your boards
+- `zeroboard://board/{boardId}` — a full board (columns + cards) as JSON
+
+## Auth & security
+
+- Uses **Supabase Auth** with the public anon key only — **never** the service‑role key. Postgres **RLS** (`auth.uid() = user_id`) enforces that you only ever see/modify your own data.
+- `login` opens the ZeroBoard web app's `/auth/cli` page, which signs you in with the app's normal Supabase auth (Google or email) and hands the session back to a short‑lived loopback listener on `127.0.0.1`, gated by a one‑time random `state`. No password is typed into the CLI. (`--password` / `ZEROBOARD_EMAIL`+`ZEROBOARD_PASSWORD` do a headless password grant instead.)
+- The CLI validates the delivered session before accepting it, so a stale/expired session is rejected rather than stored.
+- It stores `{ access_token, refresh_token }` in `~/.zeroboard/credentials.json` (mode `0600`). The long‑lived server auto‑refreshes the access token and rewrites the rotated refresh token. `logout` wipes it.
+- Card titles/contents are returned verbatim to your agent. As with any data source, treat board text as **untrusted input** (possible prompt injection) — the server never executes it.
+
+## Concurrency
+
+Board columns/cards live in a single `boards.data` JSONB blob (the same source of truth the web app uses). Writes are read‑modify‑write and **last‑write‑wins** — a simultaneous edit in the web UI (which syncs on a debounce) and via MCP can clobber each other. The server always reads the freshest row immediately before writing to keep the window small. Scoped tokens and conditional updates are planned for v2.
+
+## Configuration
+
+| Env var | Purpose |
+| --- | --- |
+| `ZEROBOARD_SUPABASE_URL` / `ZEROBOARD_SUPABASE_ANON_KEY` | Override the target project (defaults baked in at publish; fall back to `VITE_SUPABASE_URL` / `VITE_SUPABASE_ANON_KEY`) |
+| `ZEROBOARD_EMAIL` / `ZEROBOARD_PASSWORD` | Non‑interactive `login --password` credentials |
+| `ZEROBOARD_WEB_URL` | ZeroBoard web app base URL for browser login (default `https://board.zeroclickdev.ai`) |
+| `ZEROBOARD_NO_BROWSER=1` | Don't auto‑open a browser during `login` (just print the URL) |
+| `ZEROBOARD_READONLY=1` | Read‑only mode |
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run smoke   # exercises the data layer against real Supabase (needs E2E_EMAIL/PASSWORD + VITE_SUPABASE_* in ../.env.local)
+```
+
+## Roadmap
+
+- ✅ Browser login via the hosted `/auth/cli` route (Google + email) — done; a future hardening is a full server-side PKCE code exchange (the current flow binds the loopback delivery with a one‑time `state` and validates the session before storing).
+- ✅ `generate_board` tool backed by the existing `/api/ai/board-template` endpoint — done.
+- A dedicated `/api/v1` layer for scoped/read‑only tokens, audit logging, and conditional updates.
+- Realtime: a `list_changes(since)` poll tool and (where clients support it) resource‑update notifications.
+- A Claude Code **plugin** that bundles this server plus slash commands and a transcript‑to‑cards skill.
+
+## License
+
+MIT

package/dist/ai.js

@@ -0,0 +1,37 @@
+import { WEB_BASE_URL } from './config.js';
+/**
+ * Generate a board template from a natural-language prompt by calling the web
+ * app's existing /api/ai/board-template endpoint with the user's access token.
+ * That endpoint runs the AI gateway and enforces the daily free-tier limit, so
+ * we don't reimplement any of that here.
+ */
+export async function generateBoardTemplate(prompt, accessToken) {
+    let res;
+    try {
+        res = await fetch(`${WEB_BASE_URL}/api/ai/board-template`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${accessToken}` },
+            body: JSON.stringify({ prompt }),
+            signal: AbortSignal.timeout(45_000),
+        });
+    }
+    catch (err) {
+        throw new Error(`Could not reach ZeroBoard AI: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (res.status === 401) {
+        throw new Error('Not authorized for AI. Run `zeroboard-mcp login` again.');
+    }
+    if (res.status === 429) {
+        const body = (await res.json().catch(() => ({})));
+        const resets = body.usage?.resetsAt ? ` Resets at ${body.usage.resetsAt}.` : '';
+        throw new Error(`Daily AI limit reached.${resets} Upgrade to ZeroBoard Pro for unlimited AI.`);
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => ({})));
+        throw new Error(`AI board generation failed (${res.status})${body.error ? `: ${body.error}` : ''}`);
+    }
+    const data = (await res.json());
+    if (!data.template)
+        throw new Error('AI returned no template.');
+    return data.template;
+}

package/dist/auth.js

@@ -0,0 +1,192 @@
+import readline from 'node:readline';
+import http from 'node:http';
+import { randomBytes } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { createClient } from '@supabase/supabase-js';
+import { makeClient, getAuthedClient, NotAuthenticatedError } from './supabase.js';
+import { setSupabaseUrl, clearCredentials, hasCredentials } from './credentials.js';
+import { SUPABASE_URL, SUPABASE_ANON_KEY, WEB_BASE_URL } from './config.js';
+function flag(name) {
+    const idx = process.argv.indexOf(`--${name}`);
+    if (idx !== -1 && process.argv[idx + 1] && !process.argv[idx + 1].startsWith('--'))
+        return process.argv[idx + 1];
+    const eq = process.argv.find((a) => a.startsWith(`--${name}=`));
+    return eq ? eq.slice(name.length + 3) : undefined;
+}
+function question(query, mask = false) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    if (mask) {
+        rl._writeToOutput = (s) => {
+            process.stdout.write(s.includes('\n') || s.includes(query) ? s : '*');
+        };
+    }
+    return new Promise((resolve) => {
+        rl.question(query, (answer) => {
+            rl.close();
+            if (mask)
+                process.stdout.write('\n');
+            resolve(answer.trim());
+        });
+    });
+}
+function openBrowser(url) {
+    if (process.env.ZEROBOARD_NO_BROWSER)
+        return; // headless: just print the URL
+    const platform = process.platform;
+    const cmd = platform === 'darwin' ? 'open' : platform === 'win32' ? 'cmd' : 'xdg-open';
+    const args = platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+        child.on('error', () => {
+            /* fall back to the printed URL */
+        });
+        child.unref();
+    }
+    catch {
+        /* user can open the URL manually */
+    }
+}
+/**
+ * Browser sign-in: start a loopback listener, open the ZeroBoard web app's
+ * /auth/cli page (which reuses the app's existing Supabase sign-in — Google or
+ * email), and receive the resulting tokens back on the loopback. A random
+ * `state` (only ever in the URL we opened) gates the callback against other
+ * local processes/tabs. No password ever touches this CLI.
+ */
+async function browserLogin() {
+    const state = randomBytes(16).toString('hex');
+    let resolveDone;
+    let rejectDone;
+    const done = new Promise((res, rej) => {
+        resolveDone = res;
+        rejectDone = rej;
+    });
+    // Validate and store a delivered session. Returns true once a VALID session is
+    // accepted; a stale/invalid delivery is rejected and the loopback keeps
+    // listening (so a premature delivery doesn't abort the whole login).
+    const accept = async (data) => {
+        if (data.state !== state)
+            return { code: 403, body: { ok: false, error: 'state mismatch' } };
+        if (!data.access_token || !data.refresh_token)
+            return { code: 400, body: { ok: false, error: 'missing tokens' } };
+        const tokens = { access_token: data.access_token, refresh_token: data.refresh_token };
+        // Validate with a throwaway, non-persisting client so a bad session never
+        // pollutes the credential store.
+        const probe = createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+            auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
+        });
+        const set = await probe.auth.setSession(tokens);
+        if (set.error || !set.data.session)
+            return { code: 401, body: { ok: false, error: 'session invalid — sign in again' } };
+        const who = await probe.auth.getUser();
+        if (who.error || !who.data.user)
+            return { code: 401, body: { ok: false, error: 'session could not be validated' } };
+        // Persist via the file-backed client (canonical supabase-js storage format).
+        const store = makeClient();
+        const stored = await store.auth.setSession(tokens);
+        if (stored.error || !stored.data.session)
+            return { code: 500, body: { ok: false, error: 'failed to store session' } };
+        setSupabaseUrl(SUPABASE_URL);
+        resolveDone(who.data.user.email ?? 'your account');
+        return { code: 200, body: { ok: true } };
+    };
+    const server = http.createServer((req, res) => {
+        res.setHeader('Access-Control-Allow-Origin', req.headers.origin ?? '*');
+        res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        if (req.method === 'POST' && (req.url ?? '').startsWith('/callback')) {
+            let body = '';
+            req.on('data', (chunk) => {
+                body += chunk;
+                if (body.length > 1_000_000)
+                    req.destroy();
+            });
+            req.on('end', () => {
+                const reply = (code, obj) => {
+                    res.writeHead(code, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify(obj));
+                };
+                let parsed = null;
+                try {
+                    parsed = JSON.parse(body);
+                }
+                catch {
+                    reply(400, { ok: false, error: 'bad request' });
+                    return;
+                }
+                if (!parsed || typeof parsed !== 'object') {
+                    reply(400, { ok: false, error: 'bad request' });
+                    return;
+                }
+                accept(parsed).then(({ code, body: b }) => reply(code, b)).catch(() => reply(500, { ok: false }));
+            });
+            return;
+        }
+        res.writeHead(404);
+        res.end();
+    });
+    await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+    const addr = server.address();
+    const port = typeof addr === 'object' && addr ? addr.port : 0;
+    const url = `${WEB_BASE_URL}/auth/cli?port=${port}&state=${state}`;
+    console.log('Opening your browser to sign in to ZeroBoard…');
+    console.log(`If it does not open automatically, visit:\n  ${url}\n`);
+    openBrowser(url);
+    const timeout = setTimeout(() => rejectDone(new Error('Timed out waiting for sign-in (5 minutes).')), 300_000);
+    let email;
+    try {
+        email = await done;
+    }
+    finally {
+        clearTimeout(timeout);
+        server.close();
+    }
+    console.log(`✅ Signed in as ${email}.`);
+}
+/** Fallback: direct email/password sign-in (flags, env, or interactive prompt). */
+async function passwordLogin() {
+    const email = flag('email') ?? process.env.ZEROBOARD_EMAIL ?? (await question('Email: '));
+    const password = flag('password') ?? process.env.ZEROBOARD_PASSWORD ?? (await question('Password: ', true));
+    if (!email || !password)
+        throw new Error('Email and password are required.');
+    const client = makeClient();
+    const { data, error } = await client.auth.signInWithPassword({ email, password });
+    if (error || !data.session)
+        throw new Error(`Login failed: ${error?.message ?? 'no session returned'}`);
+    setSupabaseUrl(SUPABASE_URL);
+    console.log(`✅ Signed in as ${data.user?.email ?? email}.`);
+}
+export async function login() {
+    // Use password mode when explicitly asked or when credentials are supplied;
+    // otherwise do the browser flow (supports Google OAuth + email).
+    const usePassword = process.argv.includes('--password') ||
+        flag('email') !== undefined ||
+        (!!process.env.ZEROBOARD_EMAIL && !!process.env.ZEROBOARD_PASSWORD);
+    return usePassword ? passwordLogin() : browserLogin();
+}
+export function logout() {
+    clearCredentials();
+    console.log('✅ Signed out — local credentials cleared.');
+}
+export async function status() {
+    if (!hasCredentials()) {
+        console.log('Not signed in. Run `zeroboard-mcp login`.');
+        return;
+    }
+    try {
+        const { user } = await getAuthedClient();
+        console.log(`Signed in as ${user.email ?? user.id}.`);
+    }
+    catch (err) {
+        if (err instanceof NotAuthenticatedError) {
+            console.log(err.message);
+            return;
+        }
+        throw err;
+    }
+}

package/dist/board-data.js

@@ -0,0 +1,384 @@
+import { randomUUID } from 'node:crypto';
+// ---------------------------------------------------------------------------
+// Helpers — these intentionally mirror src/store/useBoardStore.ts so the MCP
+// server and the web UI read/write the boards.data JSONB identically.
+// ---------------------------------------------------------------------------
+const nowIso = () => new Date().toISOString();
+const newId = () => randomUUID();
+function createDefaultColumns() {
+    return [
+        { id: newId(), title: 'To Do', cards: [], order: 0 },
+        { id: newId(), title: 'Blocked', cards: [], order: 1 },
+        { id: newId(), title: 'In Progress', cards: [], order: 2 },
+        { id: newId(), title: 'Resolved', cards: [], order: 3 },
+        { id: newId(), title: 'Closed', cards: [], order: 4 },
+    ];
+}
+function asRecord(data) {
+    if (!data || typeof data !== 'object' || Array.isArray(data))
+        return null;
+    return data;
+}
+export function decodeData(data) {
+    const rec = asRecord(data);
+    const columns = rec && Array.isArray(rec.columns) ? rec.columns : createDefaultColumns();
+    const background = rec && typeof rec.background === 'string' ? rec.background : undefined;
+    const hiddenColumnIds = rec && Array.isArray(rec.hiddenColumnIds)
+        ? rec.hiddenColumnIds.filter((v) => typeof v === 'string')
+        : [];
+    return { columns, background, hiddenColumnIds };
+}
+/** Re-encode columns into the JSONB shape, preserving background/hiddenColumnIds. */
+function encodeData(columns, base) {
+    return {
+        columns,
+        ...(base.background ? { background: base.background } : {}),
+        ...(base.hiddenColumnIds && base.hiddenColumnIds.length > 0
+            ? { hiddenColumnIds: base.hiddenColumnIds }
+            : {}),
+    };
+}
+const SELECT_COLS = 'id,user_id,name,description,data,created_at,updated_at,is_public,embed_enabled';
+function rowToFullBoard(row) {
+    const decoded = decodeData(row.data);
+    return {
+        id: row.id,
+        name: row.name,
+        description: row.description ?? undefined,
+        columns: decoded.columns,
+        background: decoded.background,
+        hiddenColumnIds: decoded.hiddenColumnIds ?? [],
+        isPublic: row.is_public,
+        embedEnabled: row.embed_enabled,
+        createdAt: row.created_at,
+        updatedAt: row.updated_at,
+    };
+}
+function rowToSummary(row) {
+    const { columns } = decodeData(row.data);
+    return {
+        id: row.id,
+        name: row.name,
+        description: row.description ?? undefined,
+        columnCount: columns.length,
+        cardCount: columns.reduce((n, c) => n + c.cards.length, 0),
+        updatedAt: row.updated_at,
+        createdAt: row.created_at,
+    };
+}
+class BoardError extends Error {
+}
+const notFound = (what, id) => {
+    throw new BoardError(`${what} ${id} not found`);
+};
+async function getRow(client, boardId) {
+    const { data, error } = await client.from('boards').select(SELECT_COLS).eq('id', boardId).single();
+    if (error || !data)
+        return notFound('Board', boardId);
+    return data;
+}
+/**
+ * Read-modify-write the columns of a board's JSONB. Reads the freshest row
+ * immediately before writing to narrow the last-write-wins window (the web app
+ * also overwrites the whole columns array on a debounce — concurrent edits are
+ * last-write-wins; see README "Concurrency").
+ */
+async function mutateColumns(client, boardId, mutator) {
+    const row = await getRow(client, boardId);
+    const base = decodeData(row.data);
+    const nextColumns = mutator(structuredClone(base.columns));
+    const nextData = encodeData(nextColumns, base);
+    const { data, error } = await client
+        .from('boards')
+        .update({ data: nextData, updated_at: nowIso() })
+        .eq('id', boardId)
+        .select(SELECT_COLS)
+        .single();
+    if (error || !data)
+        throw new BoardError(error?.message ?? 'Update failed');
+    return rowToFullBoard(data);
+}
+function findColumn(columns, columnId) {
+    const col = columns.find((c) => c.id === columnId);
+    if (!col)
+        notFound('Column', columnId);
+    return col;
+}
+function locateCard(columns, cardId) {
+    for (const column of columns) {
+        const index = column.cards.findIndex((c) => c.id === cardId);
+        if (index !== -1)
+            return { column, card: column.cards[index], index };
+    }
+    return notFound('Card', cardId);
+}
+// ---------------------------------------------------------------------------
+// Boards
+// ---------------------------------------------------------------------------
+export async function listBoards(client) {
+    const { data, error } = await client
+        .from('boards')
+        .select(SELECT_COLS)
+        .order('created_at', { ascending: true });
+    if (error)
+        throw new BoardError(error.message);
+    return data.map(rowToSummary);
+}
+export async function getBoard(client, boardId) {
+    return rowToFullBoard(await getRow(client, boardId));
+}
+export async function createBoard(client, userId, name, description, columns) {
+    const id = newId();
+    const now = nowIso();
+    const data = { columns: columns ?? createDefaultColumns() };
+    const { data: row, error } = await client
+        .from('boards')
+        .insert({
+        id,
+        user_id: userId,
+        name,
+        description: description ?? null,
+        data,
+        created_at: now,
+        updated_at: now,
+    })
+        .select(SELECT_COLS)
+        .single();
+    if (error || !row)
+        throw new BoardError(error?.message ?? 'Insert failed');
+    return rowToFullBoard(row);
+}
+/** Create a board from an AI-generated template (maps template cards to Cards). */
+export function createBoardFromTemplate(client, userId, template) {
+    const now = nowIso();
+    const columns = template.columns.map((col, i) => ({
+        id: newId(),
+        title: col.title,
+        order: i,
+        cards: (col.sampleCards ?? []).map((c) => {
+            const content = c.content?.type === 'checklist'
+                ? {
+                    type: 'checklist',
+                    checklist: (c.content.checklist ?? []).map((it) => ({ id: newId(), text: it.text, completed: false })),
+                }
+                : { type: 'text', text: c.content?.text ?? '' };
+            return {
+                id: newId(),
+                title: c.title,
+                description: c.description,
+                content,
+                labels: c.labels ?? [],
+                isArchived: false,
+                createdAt: now,
+                updatedAt: now,
+            };
+        }),
+    }));
+    return createBoard(client, userId, template.name, template.description, columns);
+}
+export async function updateBoardMeta(client, boardId, patch) {
+    const update = { updated_at: nowIso() };
+    if (patch.name !== undefined)
+        update.name = patch.name;
+    if (patch.description !== undefined)
+        update.description = patch.description;
+    const { data, error } = await client
+        .from('boards')
+        .update(update)
+        .eq('id', boardId)
+        .select(SELECT_COLS)
+        .single();
+    if (error || !data)
+        throw new BoardError(error?.message ?? 'Update failed');
+    return rowToFullBoard(data);
+}
+export async function deleteBoard(client, boardId) {
+    const { error } = await client.from('boards').delete().eq('id', boardId);
+    if (error)
+        throw new BoardError(error.message);
+    return { id: boardId };
+}
+// ---------------------------------------------------------------------------
+// Columns
+// ---------------------------------------------------------------------------
+export function addColumn(client, boardId, title) {
+    return mutateColumns(client, boardId, (columns) => {
+        const maxOrder = columns.reduce((m, c) => Math.max(m, c.order), -1);
+        return [...columns, { id: newId(), title, cards: [], order: maxOrder + 1 }];
+    });
+}
+export function updateColumn(client, boardId, columnId, title) {
+    return mutateColumns(client, boardId, (columns) => {
+        findColumn(columns, columnId).title = title;
+        return columns;
+    });
+}
+export function removeColumn(client, boardId, columnId) {
+    return mutateColumns(client, boardId, (columns) => {
+        findColumn(columns, columnId);
+        return columns.filter((c) => c.id !== columnId);
+    });
+}
+export function reorderColumns(client, boardId, orderedColumnIds) {
+    return mutateColumns(client, boardId, (columns) => {
+        const map = new Map(columns.map((c) => [c.id, c]));
+        if (orderedColumnIds.some((id) => !map.has(id)) || orderedColumnIds.length !== columns.length) {
+            throw new BoardError('orderedColumnIds must list every existing column id exactly once');
+        }
+        return orderedColumnIds.map((id, index) => ({ ...map.get(id), order: index }));
+    });
+}
+export function addCard(client, boardId, columnId, input) {
+    return mutateColumns(client, boardId, (columns) => {
+        const column = findColumn(columns, columnId);
+        const now = nowIso();
+        const card = {
+            id: newId(),
+            title: input.title,
+            description: input.description,
+            content: input.content ?? { type: 'text', text: '' },
+            targetDate: input.targetDate,
+            labels: input.labels ?? [],
+            coverImage: input.coverImage,
+            isArchived: false,
+            createdAt: now,
+            updatedAt: now,
+        };
+        column.cards.push(card);
+        return columns;
+    });
+}
+export function updateCard(client, boardId, cardId, patch) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { card } = locateCard(columns, cardId);
+        Object.assign(card, patch, { updatedAt: nowIso() });
+        return columns;
+    });
+}
+export function moveCard(client, boardId, cardId, targetColumnId, targetIndex) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { column: sourceColumn, card, index } = locateCard(columns, cardId);
+        const target = findColumn(columns, targetColumnId);
+        sourceColumn.cards.splice(index, 1);
+        const insertAt = targetIndex === undefined ? target.cards.length : Math.max(0, Math.min(targetIndex, target.cards.length));
+        target.cards.splice(insertAt, 0, card);
+        card.updatedAt = nowIso();
+        return columns;
+    });
+}
+export function removeCard(client, boardId, cardId) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { column } = locateCard(columns, cardId);
+        column.cards = column.cards.filter((c) => c.id !== cardId);
+        return columns;
+    });
+}
+export function setCardArchived(client, boardId, cardId, archived) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { card } = locateCard(columns, cardId);
+        card.isArchived = archived;
+        card.archivedAt = archived ? nowIso() : undefined;
+        card.updatedAt = nowIso();
+        return columns;
+    });
+}
+export function duplicateCard(client, boardId, cardId) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { column, card } = locateCard(columns, cardId);
+        const now = nowIso();
+        column.cards.push({ ...structuredClone(card), id: newId(), title: `${card.title} (copy)`, createdAt: now, updatedAt: now });
+        return columns;
+    });
+}
+// ---------------------------------------------------------------------------
+// Card detail mutations
+// ---------------------------------------------------------------------------
+export function addChecklistItem(client, boardId, cardId, text) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { card } = locateCard(columns, cardId);
+        const checklist = card.content.type === 'checklist' && card.content.checklist ? card.content.checklist : [];
+        card.content = { ...card.content, type: 'checklist', checklist: [...checklist, { id: newId(), text, completed: false }] };
+        card.updatedAt = nowIso();
+        return columns;
+    });
+}
+export function toggleChecklistItem(client, boardId, cardId, itemId, completed) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { card } = locateCard(columns, cardId);
+        const items = card.content.checklist;
+        if (!items)
+            throw new BoardError(`Card ${cardId} has no checklist`);
+        const item = items.find((i) => i.id === itemId);
+        if (!item)
+            notFound('Checklist item', itemId);
+        item.completed = completed ?? !item.completed;
+        card.updatedAt = nowIso();
+        return columns;
+    });
+}
+export function setLabel(client, boardId, cardId, label, present) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { card } = locateCard(columns, cardId);
+        const labels = new Set(card.labels ?? []);
+        if (present)
+            labels.add(label);
+        else
+            labels.delete(label);
+        card.labels = [...labels];
+        card.updatedAt = nowIso();
+        return columns;
+    });
+}
+export function setTargetDate(client, boardId, cardId, targetDate) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { card } = locateCard(columns, cardId);
+        card.targetDate = targetDate ?? undefined;
+        card.updatedAt = nowIso();
+        return columns;
+    });
+}
+export function setCoverImage(client, boardId, cardId, coverImage) {
+    return mutateColumns(client, boardId, (columns) => {
+        const { card } = locateCard(columns, cardId);
+        card.coverImage = coverImage ?? undefined;
+        card.updatedAt = nowIso();
+        return columns;
+    });
+}
+function cardText(card) {
+    const parts = [card.title, card.description ?? '', card.content.text ?? ''];
+    if (card.content.checklist)
+        parts.push(...card.content.checklist.map((i) => i.text));
+    return parts.join('\n');
+}
+export async function search(client, query, includeArchived = false) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const { data, error } = await client.from('boards').select(SELECT_COLS);
+    if (error)
+        throw new BoardError(error.message);
+    const hits = [];
+    for (const row of data) {
+        const { columns } = decodeData(row.data);
+        for (const column of columns) {
+            for (const card of column.cards) {
+                if (card.isArchived && !includeArchived)
+                    continue;
+                const text = cardText(card);
+                if (text.toLowerCase().includes(q)) {
+                    hits.push({
+                        boardId: row.id,
+                        boardName: row.name,
+                        columnId: column.id,
+                        columnName: column.title,
+                        cardId: card.id,
+                        cardTitle: card.title,
+                        snippet: card.description || card.content.text || undefined,
+                    });
+                }
+            }
+        }
+    }
+    return hits;
+}

package/dist/config.js

@@ -0,0 +1,33 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+// Public ZeroBoard Supabase project defaults so the published package works with
+// zero configuration. Both values are PUBLISHABLE: the anon key is a `role: anon`
+// JWT (the same one shipped in the web app's browser bundle), and Postgres RLS
+// (`auth.uid() = user_id`) enforces per-user access. The service-role key is
+// never included. Override with ZEROBOARD_SUPABASE_URL / ZEROBOARD_SUPABASE_ANON_KEY.
+const DEFAULT_SUPABASE_URL = 'https://lhupamtkfuntxwosogtz.supabase.co';
+const DEFAULT_SUPABASE_ANON_KEY = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZSIsInJlZiI6ImxodXBhbXRrZnVudHh3b3NvZ3R6Iiwicm9sZSI6ImFub24iLCJpYXQiOjE3NjE1OTIwNzEsImV4cCI6MjA3NzE2ODA3MX0.RRzUk5vf5cqvc-gjCua_LMT5UubaM6OJdMJ_LBls88U';
+export const SUPABASE_URL = process.env.ZEROBOARD_SUPABASE_URL ?? process.env.VITE_SUPABASE_URL ?? DEFAULT_SUPABASE_URL;
+export const SUPABASE_ANON_KEY = process.env.ZEROBOARD_SUPABASE_ANON_KEY ?? process.env.VITE_SUPABASE_ANON_KEY ?? DEFAULT_SUPABASE_ANON_KEY;
+/** The ZeroBoard web app, used for the browser sign-in (`/auth/cli`) flow. */
+export const WEB_BASE_URL = (process.env.ZEROBOARD_WEB_URL ?? 'https://board.zeroclickdev.ai').replace(/\/$/, '');
+/** Read-only mode: only non-mutating tools are registered. */
+export const READ_ONLY = process.env.ZEROBOARD_READONLY === '1' || process.argv.includes('--read-only');
+export const CONFIG_DIR = join(homedir(), '.zeroboard');
+export const CREDENTIALS_PATH = join(CONFIG_DIR, 'credentials.json');
+/** supabase-js derives this from the URL; we reproduce it for the storage key. */
+export function storageKeyFor(url) {
+    try {
+        const ref = new URL(url).hostname.split('.')[0];
+        return `sb-${ref}-auth-token`;
+    }
+    catch {
+        return 'sb-zeroboard-auth-token';
+    }
+}
+export function assertConfigured() {
+    if (!SUPABASE_URL || !SUPABASE_ANON_KEY) {
+        throw new Error('ZeroBoard Supabase URL/anon key not configured. Set ZEROBOARD_SUPABASE_URL and ' +
+            'ZEROBOARD_SUPABASE_ANON_KEY (or VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY).');
+    }
+}

package/dist/credentials.js

@@ -0,0 +1,42 @@
+import { mkdirSync, readFileSync, writeFileSync, rmSync, existsSync } from 'node:fs';
+import { CONFIG_DIR, CREDENTIALS_PATH } from './config.js';
+function read() {
+    try {
+        return JSON.parse(readFileSync(CREDENTIALS_PATH, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+function write(next) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    writeFileSync(CREDENTIALS_PATH, JSON.stringify(next, null, 2), { mode: 0o600 });
+}
+export function setSupabaseUrl(url) {
+    write({ ...read(), url });
+}
+export function clearCredentials() {
+    if (existsSync(CREDENTIALS_PATH))
+        rmSync(CREDENTIALS_PATH);
+}
+export function hasCredentials() {
+    return !!read().token;
+}
+/**
+ * A supabase-js storage adapter backed by the credentials file. supabase-js
+ * calls setItem whenever it persists/rotates the session, so refresh tokens stay
+ * current on disk. We keep a single session, so the storage key is ignored.
+ */
+export const fileStorage = {
+    getItem(_key) {
+        return read().token ?? null;
+    },
+    setItem(_key, value) {
+        write({ ...read(), token: value });
+    },
+    removeItem(_key) {
+        const current = read();
+        delete current.token;
+        write(current);
+    },
+};

package/dist/index.js

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+import { login, logout, status } from './auth.js';
+import { runServer } from './server.js';
+const HELP = `zeroboard-mcp — ZeroBoard MCP server
+
+Usage:
+  zeroboard-mcp [serve]      Start the MCP server over stdio (default)
+  zeroboard-mcp --read-only  Start in read-only mode (no write tools)
+  zeroboard-mcp login        Sign in via the browser (Google or email). Use \`--password\`
+                             (or ZEROBOARD_EMAIL/PASSWORD) for headless password sign-in.
+  zeroboard-mcp logout       Clear stored credentials
+  zeroboard-mcp status       Show the signed-in account
+`;
+async function main() {
+    const cmd = process.argv[2];
+    switch (cmd) {
+        case 'login':
+            return login();
+        case 'logout':
+            return logout();
+        case 'status':
+            return status();
+        case 'help':
+        case '--help':
+        case '-h':
+            process.stdout.write(HELP);
+            return;
+        case undefined:
+        case 'serve':
+        default:
+            // Bare invocation or any leading flag (e.g. --read-only) starts the server.
+            if (cmd && cmd !== 'serve' && !cmd.startsWith('--')) {
+                console.error(`Unknown command: ${cmd}\n\n${HELP}`);
+                process.exit(1);
+            }
+            return runServer();
+    }
+}
+main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/server.js

@@ -0,0 +1,172 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { READ_ONLY } from './config.js';
+import { getAuthedClient, NotAuthenticatedError } from './supabase.js';
+import * as db from './board-data.js';
+import { generateBoardTemplate } from './ai.js';
+import { CARD_LABELS } from './types.js';
+const text = (data) => ({
+    content: [{ type: 'text', text: typeof data === 'string' ? data : JSON.stringify(data, null, 2) }],
+});
+const fail = (e) => ({
+    content: [{ type: 'text', text: `Error: ${e instanceof Error ? e.message : String(e)}` }],
+    isError: true,
+});
+const safe = async (fn) => {
+    try {
+        return text(await fn());
+    }
+    catch (e) {
+        return fail(e);
+    }
+};
+const labelEnum = z.enum(CARD_LABELS);
+const textToContent = (t) => t === undefined ? undefined : { type: 'text', text: t };
+function buildServer(client, user) {
+    const server = new McpServer({ name: 'zeroboard-mcp', version: '0.1.0' });
+    const RO = { readOnlyHint: true };
+    const DESTRUCTIVE = { destructiveHint: true };
+    // ----- Read tools -----------------------------------------------------
+    server.registerTool('list_boards', { title: 'List boards', description: 'List all of your ZeroBoard boards (id, name, column/card counts).', inputSchema: {}, annotations: RO }, async () => safe(() => db.listBoards(client)));
+    server.registerTool('get_board', { title: 'Get board', description: 'Get a full board including its columns and cards.', inputSchema: { boardId: z.string().describe('Board id') }, annotations: RO }, async ({ boardId }) => safe(() => db.getBoard(client, boardId)));
+    server.registerTool('list_columns', { title: 'List columns', description: 'List the columns of a board.', inputSchema: { boardId: z.string() }, annotations: RO }, async ({ boardId }) => safe(async () => {
+        const b = await db.getBoard(client, boardId);
+        return b.columns.map((c) => ({ id: c.id, title: c.title, order: c.order, cardCount: c.cards.length }));
+    }));
+    server.registerTool('list_cards', {
+        title: 'List cards',
+        description: 'List cards on a board, optionally filtered to a column. Archived cards excluded unless includeArchived.',
+        inputSchema: {
+            boardId: z.string(),
+            columnId: z.string().optional(),
+            includeArchived: z.boolean().optional(),
+        },
+        annotations: RO,
+    }, async ({ boardId, columnId, includeArchived }) => safe(async () => {
+        const b = await db.getBoard(client, boardId);
+        return b.columns
+            .filter((c) => !columnId || c.id === columnId)
+            .flatMap((c) => c.cards
+            .filter((card) => includeArchived || !card.isArchived)
+            .map((card) => ({ columnId: c.id, columnName: c.title, ...card })));
+    }));
+    server.registerTool('get_card', { title: 'Get card', description: 'Get a single card by id.', inputSchema: { boardId: z.string(), cardId: z.string() }, annotations: RO }, async ({ boardId, cardId }) => safe(async () => {
+        const b = await db.getBoard(client, boardId);
+        for (const c of b.columns) {
+            const card = c.cards.find((x) => x.id === cardId);
+            if (card)
+                return { columnId: c.id, columnName: c.title, ...card };
+        }
+        throw new Error(`Card ${cardId} not found`);
+    }));
+    server.registerTool('search', {
+        title: 'Search cards',
+        description: 'Search across all your boards for cards whose title/description/content match the query.',
+        inputSchema: { query: z.string(), includeArchived: z.boolean().optional() },
+        annotations: RO,
+    }, async ({ query, includeArchived }) => safe(() => db.search(client, query, includeArchived ?? false)));
+    if (READ_ONLY)
+        return server;
+    // ----- Write tools ----------------------------------------------------
+    server.registerTool('create_board', { title: 'Create board', description: 'Create a new board with the default columns.', inputSchema: { name: z.string(), description: z.string().optional() } }, async ({ name, description }) => safe(() => db.createBoard(client, user.id, name, description)));
+    server.registerTool('generate_board', {
+        title: 'Generate board (AI)',
+        description: 'Create a new board from a natural-language description using ZeroBoard AI (e.g. "a sprint board for a mobile app launch"). Subject to the daily AI limit on the free plan.',
+        inputSchema: { prompt: z.string().describe('What the board is for') },
+    }, async ({ prompt }) => safe(async () => {
+        const { data } = await client.auth.getSession();
+        const token = data.session?.access_token;
+        if (!token)
+            throw new Error('No active session — run `zeroboard-mcp login`.');
+        const template = await generateBoardTemplate(prompt, token);
+        return db.createBoardFromTemplate(client, user.id, template);
+    }));
+    server.registerTool('update_board', { title: 'Update board', description: 'Rename a board or change its description.', inputSchema: { boardId: z.string(), name: z.string().optional(), description: z.string().optional() } }, async ({ boardId, name, description }) => safe(() => db.updateBoardMeta(client, boardId, { name, description })));
+    server.registerTool('delete_board', { title: 'Delete board', description: 'Permanently delete a board and all its cards.', inputSchema: { boardId: z.string() }, annotations: DESTRUCTIVE }, async ({ boardId }) => safe(() => db.deleteBoard(client, boardId)));
+    server.registerTool('add_column', { title: 'Add column', description: 'Add a column to a board.', inputSchema: { boardId: z.string(), title: z.string() } }, async ({ boardId, title }) => safe(() => db.addColumn(client, boardId, title)));
+    server.registerTool('update_column', { title: 'Rename column', description: 'Rename a column.', inputSchema: { boardId: z.string(), columnId: z.string(), title: z.string() } }, async ({ boardId, columnId, title }) => safe(() => db.updateColumn(client, boardId, columnId, title)));
+    server.registerTool('remove_column', { title: 'Remove column', description: 'Remove a column and its cards.', inputSchema: { boardId: z.string(), columnId: z.string() }, annotations: DESTRUCTIVE }, async ({ boardId, columnId }) => safe(() => db.removeColumn(client, boardId, columnId)));
+    server.registerTool('reorder_columns', { title: 'Reorder columns', description: 'Reorder columns. Provide every existing column id exactly once, in the desired order.', inputSchema: { boardId: z.string(), orderedColumnIds: z.array(z.string()) } }, async ({ boardId, orderedColumnIds }) => safe(() => db.reorderColumns(client, boardId, orderedColumnIds)));
+    server.registerTool('add_card', {
+        title: 'Add card',
+        description: 'Add a card to a column.',
+        inputSchema: {
+            boardId: z.string(),
+            columnId: z.string(),
+            title: z.string(),
+            description: z.string().optional(),
+            text: z.string().optional().describe('Card body text'),
+            targetDate: z.string().optional().describe('ISO date'),
+            labels: z.array(labelEnum).optional(),
+        },
+    }, async ({ boardId, columnId, title, description, text: body, targetDate, labels }) => safe(() => db.addCard(client, boardId, columnId, {
+        title,
+        description,
+        content: textToContent(body),
+        targetDate,
+        labels: labels,
+    })));
+    server.registerTool('update_card', {
+        title: 'Update card',
+        description: 'Update fields of a card.',
+        inputSchema: {
+            boardId: z.string(),
+            cardId: z.string(),
+            title: z.string().optional(),
+            description: z.string().optional(),
+            text: z.string().optional(),
+            targetDate: z.string().optional(),
+        },
+    }, async ({ boardId, cardId, title, description, text: body, targetDate }) => safe(() => db.updateCard(client, boardId, cardId, {
+        ...(title !== undefined ? { title } : {}),
+        ...(description !== undefined ? { description } : {}),
+        ...(body !== undefined ? { content: textToContent(body) } : {}),
+        ...(targetDate !== undefined ? { targetDate } : {}),
+    })));
+    server.registerTool('move_card', { title: 'Move card', description: 'Move a card to another column (and optional index).', inputSchema: { boardId: z.string(), cardId: z.string(), targetColumnId: z.string(), targetIndex: z.number().int().nonnegative().optional() } }, async ({ boardId, cardId, targetColumnId, targetIndex }) => safe(() => db.moveCard(client, boardId, cardId, targetColumnId, targetIndex)));
+    server.registerTool('archive_card', { title: 'Archive card', description: 'Archive a card.', inputSchema: { boardId: z.string(), cardId: z.string() } }, async ({ boardId, cardId }) => safe(() => db.setCardArchived(client, boardId, cardId, true)));
+    server.registerTool('restore_card', { title: 'Restore card', description: 'Restore an archived card.', inputSchema: { boardId: z.string(), cardId: z.string() } }, async ({ boardId, cardId }) => safe(() => db.setCardArchived(client, boardId, cardId, false)));
+    server.registerTool('duplicate_card', { title: 'Duplicate card', description: 'Duplicate a card within its column.', inputSchema: { boardId: z.string(), cardId: z.string() } }, async ({ boardId, cardId }) => safe(() => db.duplicateCard(client, boardId, cardId)));
+    server.registerTool('delete_card', { title: 'Delete card', description: 'Permanently delete a card.', inputSchema: { boardId: z.string(), cardId: z.string() }, annotations: DESTRUCTIVE }, async ({ boardId, cardId }) => safe(() => db.removeCard(client, boardId, cardId)));
+    server.registerTool('add_checklist_item', { title: 'Add checklist item', description: 'Add a checklist item to a card (converts the card content to a checklist).', inputSchema: { boardId: z.string(), cardId: z.string(), text: z.string() } }, async ({ boardId, cardId, text: itemText }) => safe(() => db.addChecklistItem(client, boardId, cardId, itemText)));
+    server.registerTool('toggle_checklist_item', { title: 'Toggle checklist item', description: 'Toggle (or set) a checklist item completed state.', inputSchema: { boardId: z.string(), cardId: z.string(), itemId: z.string(), completed: z.boolean().optional() } }, async ({ boardId, cardId, itemId, completed }) => safe(() => db.toggleChecklistItem(client, boardId, cardId, itemId, completed)));
+    server.registerTool('add_label', { title: 'Add label', description: `Add a color label to a card (${CARD_LABELS.join(', ')}).`, inputSchema: { boardId: z.string(), cardId: z.string(), label: labelEnum } }, async ({ boardId, cardId, label }) => safe(() => db.setLabel(client, boardId, cardId, label, true)));
+    server.registerTool('remove_label', { title: 'Remove label', description: 'Remove a color label from a card.', inputSchema: { boardId: z.string(), cardId: z.string(), label: labelEnum } }, async ({ boardId, cardId, label }) => safe(() => db.setLabel(client, boardId, cardId, label, false)));
+    server.registerTool('set_target_date', { title: 'Set target date', description: 'Set or clear a card target date (ISO string, or null to clear).', inputSchema: { boardId: z.string(), cardId: z.string(), targetDate: z.string().nullable() } }, async ({ boardId, cardId, targetDate }) => safe(() => db.setTargetDate(client, boardId, cardId, targetDate)));
+    server.registerTool('set_cover_image', { title: 'Set cover image', description: 'Set or clear a card cover image URL (or null to clear).', inputSchema: { boardId: z.string(), cardId: z.string(), coverImage: z.string().nullable() } }, async ({ boardId, cardId, coverImage }) => safe(() => db.setCoverImage(client, boardId, cardId, coverImage)));
+    return server;
+}
+function registerResources(server, client, user) {
+    server.registerResource('me', 'zeroboard://me', { title: 'Current user', description: 'The authenticated ZeroBoard account.', mimeType: 'application/json' }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ id: user.id, email: user.email }, null, 2) }],
+    }));
+    server.registerResource('boards', 'zeroboard://boards', { title: 'Boards index', description: 'All of your boards.', mimeType: 'application/json' }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(await db.listBoards(client), null, 2) }],
+    }));
+    server.registerResource('board', new ResourceTemplate('zeroboard://board/{boardId}', { list: undefined }), { title: 'Board', description: 'A full board (columns + cards) as JSON.', mimeType: 'application/json' }, async (uri, variables) => {
+        const boardId = Array.isArray(variables.boardId) ? variables.boardId[0] : variables.boardId;
+        return {
+            contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(await db.getBoard(client, boardId), null, 2) }],
+        };
+    });
+}
+export async function runServer() {
+    let client;
+    let user;
+    try {
+        ({ client, user } = await getAuthedClient());
+    }
+    catch (err) {
+        if (err instanceof NotAuthenticatedError) {
+            console.error(`[zeroboard-mcp] ${err.message}`);
+            process.exit(1);
+        }
+        throw err;
+    }
+    const server = buildServer(client, user);
+    registerResources(server, client, user);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`[zeroboard-mcp] ready as ${user.email ?? user.id}${READ_ONLY ? ' (read-only)' : ''}. Listening on stdio.`);
+}

package/dist/smoke.js

@@ -0,0 +1,89 @@
+// End-to-end smoke test of the board-data layer against REAL Supabase, using the
+// dedicated e2e test user. Uses a direct in-memory client (does NOT touch the
+// ~/.zeroboard credential store). Run: npm run build && npm run smoke
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createClient } from '@supabase/supabase-js';
+import * as db from './board-data.js';
+function loadEnv() {
+    for (const p of [resolve(process.cwd(), '.env.local'), resolve(process.cwd(), '..', '.env.local')]) {
+        try {
+            for (const line of readFileSync(p, 'utf8').split('\n')) {
+                const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*)\s*$/);
+                if (!m || process.env[m[1]] !== undefined)
+                    continue;
+                let v = m[2];
+                if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'")))
+                    v = v.slice(1, -1);
+                process.env[m[1]] = v;
+            }
+        }
+        catch {
+            /* try next path */
+        }
+    }
+}
+let passed = 0;
+function check(label, cond) {
+    if (!cond)
+        throw new Error(`FAILED: ${label}`);
+    passed++;
+    console.log(`  ✓ ${label}`);
+}
+async function main() {
+    loadEnv();
+    const url = process.env.VITE_SUPABASE_URL;
+    const anon = process.env.VITE_SUPABASE_ANON_KEY;
+    const email = process.env.E2E_EMAIL;
+    const password = process.env.E2E_PASSWORD;
+    if (!url || !anon || !email || !password) {
+        throw new Error('Missing VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY / E2E_EMAIL / E2E_PASSWORD (run scripts/e2e/ensure-test-user.mjs).');
+    }
+    const client = createClient(url, anon, {
+        auth: { persistSession: false, autoRefreshToken: false, detectSessionInUrl: false },
+    });
+    const signIn = await client.auth.signInWithPassword({ email, password });
+    if (signIn.error || !signIn.data.user)
+        throw new Error(`sign-in failed: ${signIn.error?.message}`);
+    const userId = signIn.data.user.id;
+    console.log(`Signed in as ${email}\n`);
+    let boardId = '';
+    try {
+        const board = await db.createBoard(client, userId, 'MCP Smoke Board', 'created by smoke test');
+        boardId = board.id;
+        check('create_board returns default columns', board.columns.length === 5);
+        const list = await db.listBoards(client);
+        check('list_boards includes the new board', list.some((b) => b.id === boardId));
+        const withCol = await db.addColumn(client, boardId, 'Review');
+        check('add_column appends a column', withCol.columns.length === 6);
+        const reviewCol = withCol.columns.find((c) => c.title === 'Review');
+        check('add_column sets incremental order', reviewCol.order === 5);
+        const todo = withCol.columns.find((c) => c.title === 'To Do');
+        const afterCard = await db.addCard(client, boardId, todo.id, { title: 'Ship MCP v1', content: { type: 'text', text: 'wire it up' }, labels: ['green'] });
+        const card = afterCard.columns.find((c) => c.id === todo.id).cards[0];
+        check('add_card creates a card with a label', card.title === 'Ship MCP v1' && card.labels?.includes('green') === true);
+        const moved = await db.moveCard(client, boardId, card.id, reviewCol.id);
+        check('move_card moves the card to the target column', moved.columns.find((c) => c.id === reviewCol.id).cards.some((x) => x.id === card.id));
+        check('move_card removes from source column', moved.columns.find((c) => c.id === todo.id).cards.length === 0);
+        const checked = await db.addChecklistItem(client, boardId, card.id, 'subtask 1');
+        const checkedCard = checked.columns.flatMap((c) => c.cards).find((x) => x.id === card.id);
+        check('add_checklist_item converts content to checklist', checkedCard.content.type === 'checklist' && checkedCard.content.checklist?.length === 1);
+        const hits = await db.search(client, 'Ship MCP');
+        check('search finds the card', hits.some((h) => h.cardId === card.id));
+        const fetched = await db.getBoard(client, boardId);
+        check('get_board persists across reads (round-trips boards.data JSONB)', fetched.columns.flatMap((c) => c.cards).some((x) => x.id === card.id));
+        const renamed = await db.updateBoardMeta(client, boardId, { name: 'MCP Smoke Board (renamed)' });
+        check('update_board renames', renamed.name === 'MCP Smoke Board (renamed)');
+    }
+    finally {
+        if (boardId) {
+            await db.deleteBoard(client, boardId);
+            console.log('\n  ✓ cleanup: deleted smoke board');
+        }
+    }
+    console.log(`\n✅ smoke passed (${passed} checks)`);
+}
+main().catch((err) => {
+    console.error(`\n❌ ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+});

package/dist/supabase.js

@@ -0,0 +1,44 @@
+import { createClient } from '@supabase/supabase-js';
+import { SUPABASE_URL, SUPABASE_ANON_KEY, storageKeyFor, assertConfigured } from './config.js';
+import { fileStorage } from './credentials.js';
+/**
+ * Build a Supabase client backed by the on-disk credential store. With
+ * persistSession + autoRefreshToken, supabase-js loads the saved session, keeps
+ * the access token fresh, and rewrites the rotated refresh token to disk — the
+ * server equivalent of the web app's api/_lib/auth.ts authenticated client.
+ * Every request carries a fresh, RLS-scoped JWT (anon key only; never service-role).
+ */
+export function makeClient() {
+    assertConfigured();
+    return createClient(SUPABASE_URL, SUPABASE_ANON_KEY, {
+        auth: {
+            storage: fileStorage,
+            storageKey: storageKeyFor(SUPABASE_URL),
+            persistSession: true,
+            autoRefreshToken: true,
+            detectSessionInUrl: false,
+        },
+    });
+}
+export class NotAuthenticatedError extends Error {
+    constructor(message = 'Not signed in. Run `zeroboard-mcp login` first.') {
+        super(message);
+        this.name = 'NotAuthenticatedError';
+    }
+}
+/**
+ * Return a client whose stored session is valid against the server. Throws
+ * NotAuthenticatedError if there is no session or the token is revoked/expired.
+ */
+export async function getAuthedClient() {
+    const client = makeClient();
+    const { data: sessionData } = await client.auth.getSession();
+    if (!sessionData.session)
+        throw new NotAuthenticatedError();
+    // Validate against the server (also triggers a refresh if needed).
+    const { data, error } = await client.auth.getUser();
+    if (error || !data.user) {
+        throw new NotAuthenticatedError(`Stored session is no longer valid${error ? ` (${error.message})` : ''}. Run \`zeroboard-mcp login\`.`);
+    }
+    return { client, user: data.user };
+}

package/dist/types.js

@@ -0,0 +1,4 @@
+// Types mirrored from the web app (src/types/index.ts). The MCP server reads and
+// writes the SAME boards.data JSONB the app uses, so these shapes MUST stay in
+// sync with the app's Card / Column / CardContent definitions.
+export const CARD_LABELS = ['red', 'yellow', 'green', 'blue', 'purple', 'gray'];

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@zeroclickdev/zeroboard-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for ZeroBoard — manage your boards, columns, and cards from any MCP-compatible agent (Claude Code, Cursor, Zed, Windsurf).",
+  "type": "module",
+  "bin": {
+    "zeroboard-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://board.zeroclickdev.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tmcfarlane/zeroclickboards.git",
+    "directory": "mcp-server"
+  },
+  "bugs": {
+    "url": "https://github.com/tmcfarlane/zeroclickboards/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "smoke": "node dist/smoke.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "kanban",
+    "zeroboard",
+    "supabase"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.18.0",
+    "@supabase/supabase-js": "^2.56.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.0"
+  }
+}