backlog-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Goga Koreli
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# backlog-mcp
+
+Minimal task backlog as an MCP server. Records state, doesn't enforce workflow.
+
+## Task Schema
+
+```typescript
+{
+  id: string;           // TASK-0001
+  title: string;
+  description?: string;
+  status: 'open' | 'in_progress' | 'blocked' | 'done' | 'cancelled';
+  created_at: string;   // ISO8601
+  updated_at: string;   // ISO8601
+  blocked_reason?: string;
+  evidence?: string[];
+}
+```
+
+## MCP Tools
+
+| Tool | Description |
+|------|-------------|
+| `backlog_list` | List tasks. Filter by status. Use `summary=true` for counts. |
+| `backlog_get` | Get task by ID |
+| `backlog_create` | Create task |
+| `backlog_update` | Update any field (title, description, status, blocked_reason, evidence) |
+
+## Installation
+
+Add to your MCP config (`.mcp.json` or Claude Desktop config):
+
+```json
+{
+  "mcpServers": {
+    "backlog": {
+      "command": "npx",
+      "args": ["-y", "backlog-mcp"]
+    }
+  }
+}
+```
+
+Or build from source:
+
+```bash
+git clone https://github.com/gkoreli/backlog-mcp.git
+cd backlog-mcp
+npm install && npm run build
+npm start
+```
+
+Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "backlog": {
+      "command": "node",
+      "args": ["/path/to/backlog-mcp/dist/server.js"]
+    }
+  }
+}
+```
+
+## Storage
+
+Single file: `data/backlog.json` (atomic writes via temp + rename)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { isValidTaskId, parseTaskId, formatTaskId, nextTaskId, STATUSES, type Status, type Task, type CreateTaskInput, createTask, } from './schema.js';
+export { type Backlog, type StorageOptions, loadBacklog, saveBacklog, getTask, listTasks, addTask, saveTask, deleteTask, taskExists, getTaskCounts, } from './storage.js';

package/dist/index.js

@@ -0,0 +1,5 @@
+// Schema
+export { isValidTaskId, parseTaskId, formatTaskId, nextTaskId, STATUSES, createTask, } from './schema.js';
+// Storage
+export { loadBacklog, saveBacklog, getTask, listTasks, addTask, saveTask, deleteTask, taskExists, getTaskCounts, } from './storage.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,SAAS;AACT,OAAO,EACL,aAAa,EACb,WAAW,EACX,YAAY,EACZ,UAAU,EACV,QAAQ,EAIR,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,UAAU;AACV,OAAO,EAGL,WAAW,EACX,WAAW,EACX,OAAO,EACP,SAAS,EACT,OAAO,EACP,QAAQ,EACR,UAAU,EACV,UAAU,EACV,aAAa,GACd,MAAM,cAAc,CAAC"}

package/dist/schema.d.ts

@@ -0,0 +1,26 @@
+export declare function isValidTaskId(id: unknown): id is string;
+export declare function parseTaskId(id: string): number | null;
+export declare function formatTaskId(num: number): string;
+export declare function nextTaskId(existingTasks: ReadonlyArray<{
+    id: string;
+}>): string;
+export declare const STATUSES: readonly ["open", "in_progress", "blocked", "done", "cancelled"];
+export type Status = (typeof STATUSES)[number];
+export interface Task {
+    id: string;
+    title: string;
+    description?: string;
+    status: Status;
+    created_at: string;
+    updated_at: string;
+    blocked_reason?: string;
+    evidence?: string[];
+}
+export interface CreateTaskInput {
+    id?: string;
+    title: string;
+    description?: string;
+}
+export declare function createTask(input: CreateTaskInput, existingTasks?: ReadonlyArray<{
+    id: string;
+}>): Task;

package/dist/schema.js

@@ -0,0 +1,42 @@
+// ============================================================================
+// Task ID
+// ============================================================================
+const TASK_ID_PATTERN = /^TASK-(\d{4,})$/;
+export function isValidTaskId(id) {
+    return typeof id === 'string' && TASK_ID_PATTERN.test(id);
+}
+export function parseTaskId(id) {
+    const match = TASK_ID_PATTERN.exec(id);
+    if (!match?.[1])
+        return null;
+    return parseInt(match[1], 10);
+}
+export function formatTaskId(num) {
+    return `TASK-${num.toString().padStart(4, '0')}`;
+}
+export function nextTaskId(existingTasks) {
+    let maxNum = 0;
+    for (const task of existingTasks) {
+        const num = parseTaskId(task.id);
+        if (num !== null && num > maxNum) {
+            maxNum = num;
+        }
+    }
+    return formatTaskId(maxNum + 1);
+}
+// ============================================================================
+// Status
+// ============================================================================
+export const STATUSES = ['open', 'in_progress', 'blocked', 'done', 'cancelled'];
+export function createTask(input, existingTasks = []) {
+    const now = new Date().toISOString();
+    return {
+        id: input.id ?? nextTaskId(existingTasks),
+        title: input.title,
+        description: input.description,
+        status: 'open',
+        created_at: now,
+        updated_at: now,
+    };
+}
+//# sourceMappingURL=schema.js.map

package/dist/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,MAAM,eAAe,GAAG,iBAAiB,CAAC;AAE1C,MAAM,UAAU,aAAa,CAAC,EAAW;IACvC,OAAO,OAAO,EAAE,KAAK,QAAQ,IAAI,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC5D,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,EAAU;IACpC,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACvC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC7B,OAAO,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAChC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,GAAW;IACtC,OAAO,QAAQ,GAAG,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,UAAU,CAAC,aAA4C;IACrE,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjC,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,GAAG,MAAM,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,YAAY,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,EAAE,WAAW,CAAU,CAAC;AA4BzF,MAAM,UAAU,UAAU,CACxB,KAAsB,EACtB,gBAA+C,EAAE;IAEjD,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IACrC,OAAO;QACL,EAAE,EAAE,KAAK,CAAC,EAAE,IAAI,UAAU,CAAC,aAAa,CAAC;QACzC,KAAK,EAAE,KAAK,CAAC,KAAK;QAClB,WAAW,EAAE,KAAK,CAAC,WAAW;QAC9B,MAAM,EAAE,MAAM;QACd,UAAU,EAAE,GAAG;QACf,UAAU,EAAE,GAAG;KAChB,CAAC;AACJ,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+import { createTask, STATUSES } from './schema.js';
+import { loadBacklog, getTask, listTasks, addTask, saveTask, getTaskCounts } from './storage.js';
+// ============================================================================
+// Server
+// ============================================================================
+const server = new McpServer({
+    name: 'backlog-mcp',
+    version: '0.1.0',
+});
+const storageOptions = {
+    dataDir: process.env.BACKLOG_DATA_DIR ?? 'data',
+};
+// ============================================================================
+// Tools
+// ============================================================================
+server.registerTool('backlog_list', {
+    description: 'List tasks, optionally filtered by status. Use summary=true for counts.',
+    inputSchema: {
+        status: z.array(z.enum(STATUSES)).optional().describe('Filter by status'),
+        summary: z.boolean().optional().describe('Return counts instead of list'),
+    },
+}, async ({ status, summary }) => {
+    const tasks = listTasks(status ? { status } : undefined, storageOptions);
+    if (summary) {
+        const counts = getTaskCounts(storageOptions);
+        return { content: [{ type: 'text', text: JSON.stringify(counts, null, 2) }] };
+    }
+    const list = tasks.map((t) => ({ id: t.id, title: t.title, status: t.status }));
+    return { content: [{ type: 'text', text: JSON.stringify(list, null, 2) }] };
+});
+server.registerTool('backlog_get', {
+    description: 'Get a task by ID',
+    inputSchema: { id: z.string().describe('Task ID') },
+}, async ({ id }) => {
+    const task = getTask(id, storageOptions);
+    if (!task) {
+        return { content: [{ type: 'text', text: `Not found: ${id}` }], isError: true };
+    }
+    return { content: [{ type: 'text', text: JSON.stringify(task, null, 2) }] };
+});
+server.registerTool('backlog_create', {
+    description: 'Create a new task',
+    inputSchema: {
+        title: z.string().describe('Task title'),
+        description: z.string().optional().describe('Task description'),
+    },
+}, async ({ title, description }) => {
+    const backlog = loadBacklog(storageOptions);
+    const task = createTask({ title, description }, backlog.tasks);
+    addTask(task, storageOptions);
+    return { content: [{ type: 'text', text: `Created ${task.id}` }] };
+});
+server.registerTool('backlog_update', {
+    description: 'Update a task (any field)',
+    inputSchema: {
+        id: z.string().describe('Task ID'),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        status: z.enum(STATUSES).optional(),
+        blocked_reason: z.string().optional(),
+        evidence: z.array(z.string()).optional(),
+    },
+}, async ({ id, ...updates }) => {
+    const task = getTask(id, storageOptions);
+    if (!task) {
+        return { content: [{ type: 'text', text: `Not found: ${id}` }], isError: true };
+    }
+    const updated = {
+        ...task,
+        ...Object.fromEntries(Object.entries(updates).filter(([_, v]) => v !== undefined)),
+        updated_at: new Date().toISOString(),
+    };
+    saveTask(updated, storageOptions);
+    return { content: [{ type: 'text', text: `Updated ${id}` }] };
+});
+// ============================================================================
+// Main
+// ============================================================================
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":";AAEA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAa,MAAM,aAAa,CAAC;AAC9D,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAuB,MAAM,cAAc,CAAC;AAEtH,+EAA+E;AAC/E,SAAS;AACT,+EAA+E;AAE/E,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;IAC3B,IAAI,EAAE,aAAa;IACnB,OAAO,EAAE,OAAO;CACjB,CAAC,CAAC;AAEH,MAAM,cAAc,GAAmB;IACrC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,MAAM;CAChD,CAAC;AAEF,+EAA+E;AAC/E,QAAQ;AACR,+EAA+E;AAE/E,MAAM,CAAC,YAAY,CACjB,cAAc,EACd;IACE,WAAW,EAAE,yEAAyE;IACtF,WAAW,EAAE;QACX,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;QACzE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;KAC1E;CACF,EACD,KAAK,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE;IAC5B,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;IAEzE,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,MAAM,GAAG,aAAa,CAAC,cAAc,CAAC,CAAC;QAC7C,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACzF,CAAC;IAED,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAChF,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACvF,CAAC,CACF,CAAC;AAEF,MAAM,CAAC,YAAY,CACjB,aAAa,EACb;IACE,WAAW,EAAE,kBAAkB;IAC/B,WAAW,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE;CACpD,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,EAAE;IACf,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC;IACzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3F,CAAC;IACD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;AACvF,CAAC,CACF,CAAC;AAEF,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;IACE,WAAW,EAAE,mBAAmB;IAChC,WAAW,EAAE;QACX,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,CAAC;QACxC,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,kBAAkB,CAAC;KAChE;CACF,EACD,KAAK,EAAE,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,EAAE;IAC/B,MAAM,OAAO,GAAG,WAAW,CAAC,cAAc,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC/D,OAAO,CAAC,IAAI,EAAE,cAAc,CAAC,CAAC;IAC9B,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,WAAW,IAAI,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;AAC9E,CAAC,CACF,CAAC;AAEF,MAAM,CAAC,YAAY,CACjB,gBAAgB,EAChB;IACE,WAAW,EAAE,2BAA2B;IACxC,WAAW,EAAE;QACX,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,SAAS,CAAC;QAClC,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAC5B,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QAClC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,QAAQ,EAAE;QACnC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;QACrC,QAAQ,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,EAAE;KACzC;CACF,EACD,KAAK,EAAE,EAAE,EAAE,EAAE,GAAG,OAAO,EAAE,EAAE,EAAE;IAC3B,MAAM,IAAI,GAAG,OAAO,CAAC,EAAE,EAAE,cAAc,CAAC,CAAC;IACzC,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IAC3F,CAAC;IAED,MAAM,OAAO,GAAS;QACpB,GAAG,IAAI;QACP,GAAG,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,SAAS,CAAC,CAAC;QAClF,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;KACrC,CAAC;IAEF,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC,CAAC;IAClC,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;AACzE,CAAC,CACF,CAAC;AAEF,+EAA+E;AAC/E,OAAO;AACP,+EAA+E;AAE/E,KAAK,UAAU,IAAI;IACjB,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;AAClC,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/storage.d.ts

@@ -0,0 +1,51 @@
+import type { Task } from './schema.js';
+export interface Backlog {
+    version: '1';
+    tasks: Task[];
+}
+export interface StorageOptions {
+    dataDir?: string;
+}
+/**
+ * Load backlog from disk. Returns empty backlog if file doesn't exist.
+ */
+export declare function loadBacklog(options?: StorageOptions): Backlog;
+/**
+ * Save backlog to disk atomically (write to temp, then rename).
+ */
+export declare function saveBacklog(backlog: Backlog, options?: StorageOptions): void;
+/**
+ * Load archive from disk. Returns empty backlog if file doesn't exist.
+ */
+export declare function loadArchive(options?: StorageOptions): Backlog;
+/**
+ * Get a task by ID. Returns undefined if not found.
+ */
+export declare function getTask(id: string, options?: StorageOptions): Task | undefined;
+/**
+ * List all tasks. Optionally filter by status.
+ */
+export declare function listTasks(filter?: {
+    status?: Task['status'][];
+}, options?: StorageOptions): Task[];
+/**
+ * Add a new task. Throws if task with same ID already exists.
+ */
+export declare function addTask(task: Task, options?: StorageOptions): void;
+/**
+ * Update an existing task. Throws if task doesn't exist.
+ * Automatically archives tasks with terminal status (done, cancelled).
+ */
+export declare function saveTask(task: Task, options?: StorageOptions): void;
+/**
+ * Delete a task by ID. Throws if task doesn't exist.
+ */
+export declare function deleteTask(id: string, options?: StorageOptions): void;
+/**
+ * Check if a task exists.
+ */
+export declare function taskExists(id: string, options?: StorageOptions): boolean;
+/**
+ * Get count of tasks by status.
+ */
+export declare function getTaskCounts(options?: StorageOptions): Record<Task['status'], number>;

package/dist/storage.js

@@ -0,0 +1,194 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync, renameSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+// ============================================================================
+// Storage
+// ============================================================================
+const DEFAULT_DATA_DIR = 'data';
+const BACKLOG_FILE = 'backlog.json';
+const ARCHIVE_FILE = 'archive.json';
+const TERMINAL_STATUSES = ['done', 'cancelled'];
+function ensureDir(dir) {
+    if (!existsSync(dir)) {
+        mkdirSync(dir, { recursive: true });
+    }
+}
+function getBacklogPath(dataDir) {
+    return join(dataDir, BACKLOG_FILE);
+}
+function getArchivePath(dataDir) {
+    return join(dataDir, ARCHIVE_FILE);
+}
+function emptyBacklog() {
+    return {
+        version: '1',
+        tasks: [],
+    };
+}
+/**
+ * Load backlog from disk. Returns empty backlog if file doesn't exist.
+ */
+export function loadBacklog(options = {}) {
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    const path = getBacklogPath(dataDir);
+    if (!existsSync(path)) {
+        return emptyBacklog();
+    }
+    const content = readFileSync(path, 'utf-8');
+    const data = JSON.parse(content);
+    // Basic version check
+    if (data.version !== '1') {
+        throw new Error(`Unsupported backlog version: ${data.version}`);
+    }
+    return data;
+}
+/**
+ * Save backlog to disk atomically (write to temp, then rename).
+ */
+export function saveBacklog(backlog, options = {}) {
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    ensureDir(dataDir);
+    const path = getBacklogPath(dataDir);
+    const tempPath = join(dataDir, `.backlog.${randomUUID()}.tmp`);
+    const content = JSON.stringify(backlog, null, 2);
+    // Write to temp file first
+    writeFileSync(tempPath, content, 'utf-8');
+    // Atomic rename
+    renameSync(tempPath, path);
+}
+/**
+ * Load archive from disk. Returns empty backlog if file doesn't exist.
+ */
+export function loadArchive(options = {}) {
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    const path = getArchivePath(dataDir);
+    if (!existsSync(path)) {
+        return emptyBacklog();
+    }
+    const content = readFileSync(path, 'utf-8');
+    const data = JSON.parse(content);
+    if (data.version !== '1') {
+        throw new Error(`Unsupported archive version: ${data.version}`);
+    }
+    return data;
+}
+/**
+ * Save archive to disk atomically.
+ */
+function saveArchive(archive, options = {}) {
+    const dataDir = options.dataDir ?? DEFAULT_DATA_DIR;
+    ensureDir(dataDir);
+    const path = getArchivePath(dataDir);
+    const tempPath = join(dataDir, `.archive.${randomUUID()}.tmp`);
+    const content = JSON.stringify(archive, null, 2);
+    writeFileSync(tempPath, content, 'utf-8');
+    renameSync(tempPath, path);
+}
+/**
+ * Move a task from backlog to archive.
+ */
+function archiveTask(task, options = {}) {
+    const backlog = loadBacklog(options);
+    const archive = loadArchive(options);
+    // Remove from backlog
+    const index = backlog.tasks.findIndex((t) => t.id === task.id);
+    if (index !== -1) {
+        backlog.tasks.splice(index, 1);
+    }
+    // Add to archive (replace if exists)
+    const archiveIndex = archive.tasks.findIndex((t) => t.id === task.id);
+    if (archiveIndex !== -1) {
+        archive.tasks[archiveIndex] = task;
+    }
+    else {
+        archive.tasks.push(task);
+    }
+    saveBacklog(backlog, options);
+    saveArchive(archive, options);
+}
+// ============================================================================
+// Task Operations
+// ============================================================================
+/**
+ * Get a task by ID. Returns undefined if not found.
+ */
+export function getTask(id, options = {}) {
+    const backlog = loadBacklog(options);
+    return backlog.tasks.find((t) => t.id === id);
+}
+/**
+ * List all tasks. Optionally filter by status.
+ */
+export function listTasks(filter, options = {}) {
+    const backlog = loadBacklog(options);
+    if (filter?.status && filter.status.length > 0) {
+        return backlog.tasks.filter((t) => filter.status.includes(t.status));
+    }
+    return backlog.tasks;
+}
+/**
+ * Add a new task. Throws if task with same ID already exists.
+ */
+export function addTask(task, options = {}) {
+    const backlog = loadBacklog(options);
+    if (backlog.tasks.some((t) => t.id === task.id)) {
+        throw new Error(`Task with ID '${task.id}' already exists`);
+    }
+    backlog.tasks.push(task);
+    saveBacklog(backlog, options);
+}
+/**
+ * Update an existing task. Throws if task doesn't exist.
+ * Automatically archives tasks with terminal status (done, cancelled).
+ */
+export function saveTask(task, options = {}) {
+    const backlog = loadBacklog(options);
+    const index = backlog.tasks.findIndex((t) => t.id === task.id);
+    if (index === -1) {
+        throw new Error(`Task with ID '${task.id}' not found`);
+    }
+    // Archive if terminal status
+    if (TERMINAL_STATUSES.includes(task.status)) {
+        archiveTask(task, options);
+        return;
+    }
+    backlog.tasks[index] = task;
+    saveBacklog(backlog, options);
+}
+/**
+ * Delete a task by ID. Throws if task doesn't exist.
+ */
+export function deleteTask(id, options = {}) {
+    const backlog = loadBacklog(options);
+    const index = backlog.tasks.findIndex((t) => t.id === id);
+    if (index === -1) {
+        throw new Error(`Task with ID '${id}' not found`);
+    }
+    backlog.tasks.splice(index, 1);
+    saveBacklog(backlog, options);
+}
+/**
+ * Check if a task exists.
+ */
+export function taskExists(id, options = {}) {
+    const backlog = loadBacklog(options);
+    return backlog.tasks.some((t) => t.id === id);
+}
+/**
+ * Get count of tasks by status.
+ */
+export function getTaskCounts(options = {}) {
+    const backlog = loadBacklog(options);
+    const counts = {
+        open: 0,
+        in_progress: 0,
+        blocked: 0,
+        done: 0,
+        cancelled: 0,
+    };
+    for (const task of backlog.tasks) {
+        counts[task.status]++;
+    }
+    return counts;
+}
+//# sourceMappingURL=storage.js.map

package/dist/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":"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"}

package/dist/transitions.d.ts

@@ -0,0 +1,32 @@
+import type { Task, Status, Blocked, Dod, Evidence, ValidationError } from './schema.js';
+export declare const TERMINAL_STATUSES: readonly Status[];
+export interface TransitionToBlocked {
+    to: 'blocked';
+    blocked: Blocked;
+}
+export interface TransitionToVerifying {
+    to: 'verifying';
+    dod: Dod;
+    evidence: Evidence;
+}
+export interface TransitionToDone {
+    to: 'done';
+}
+export interface TransitionToInProgress {
+    to: 'in_progress';
+}
+export interface TransitionToCancelled {
+    to: 'cancelled';
+}
+export type TransitionInput = TransitionToBlocked | TransitionToVerifying | TransitionToDone | TransitionToInProgress | TransitionToCancelled;
+export type TransitionResult = {
+    ok: true;
+    task: Task;
+} | {
+    ok: false;
+    errors: ValidationError[];
+};
+export declare function canTransition(from: Status, to: Status): boolean;
+export declare function getAllowedTransitions(from: Status): readonly Status[];
+export declare function isTerminal(status: Status): boolean;
+export declare function transition(task: Task, input: TransitionInput): TransitionResult;

package/dist/transitions.js

@@ -0,0 +1,174 @@
+// ============================================================================
+// Constants
+// ============================================================================
+export const TERMINAL_STATUSES = ['done', 'cancelled'];
+/**
+ * State machine transitions:
+ *
+ * open ──────► in_progress ──────► verifying ──────► done
+ *   │               │                  │
+ *   │               │                  ├─► in_progress (rejected)
+ *   │               │                  │
+ *   │               │                  └─► cancelled
+ *   │               │
+ *   │               ├────────────────► blocked
+ *   │               │                     │
+ *   │               │                     ├─► in_progress
+ *   │               │                     │
+ *   │               │                     └─► cancelled
+ *   │               │
+ *   │               └────────────────► cancelled
+ *   │
+ *   └────────────────────────────────► cancelled
+ */
+const ALLOWED_TRANSITIONS = {
+    open: ['in_progress', 'cancelled'],
+    in_progress: ['blocked', 'verifying', 'cancelled'],
+    blocked: ['in_progress', 'cancelled'],
+    verifying: ['done', 'in_progress', 'cancelled'],
+    done: [],
+    cancelled: [],
+};
+// ============================================================================
+// Helpers
+// ============================================================================
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isNonEmptyStringArray(value) {
+    return Array.isArray(value) && value.length > 0 && value.every(isNonEmptyString);
+}
+// ============================================================================
+// Query Functions
+// ============================================================================
+export function canTransition(from, to) {
+    return ALLOWED_TRANSITIONS[from].includes(to);
+}
+export function getAllowedTransitions(from) {
+    return ALLOWED_TRANSITIONS[from];
+}
+export function isTerminal(status) {
+    return TERMINAL_STATUSES.includes(status);
+}
+// ============================================================================
+// Transition Validators
+// ============================================================================
+function validateBlockedInput(input, errors) {
+    if (!input.blocked || typeof input.blocked !== 'object') {
+        errors.push({ field: 'blocked', message: 'required for transition to blocked' });
+        return;
+    }
+    if (!isNonEmptyString(input.blocked.reason)) {
+        errors.push({ field: 'blocked.reason', message: 'must be a non-empty string' });
+    }
+    if (input.blocked.dependency !== undefined && typeof input.blocked.dependency !== 'string') {
+        errors.push({ field: 'blocked.dependency', message: 'must be a string if present' });
+    }
+}
+function validateVerifyingInput(input, errors) {
+    // Validate dod
+    if (!input.dod || typeof input.dod !== 'object') {
+        errors.push({ field: 'dod', message: 'required for transition to verifying' });
+    }
+    else if (!isNonEmptyStringArray(input.dod.checklist)) {
+        errors.push({ field: 'dod.checklist', message: 'must be a non-empty array of non-empty strings' });
+    }
+    // Validate evidence
+    if (!input.evidence || typeof input.evidence !== 'object') {
+        errors.push({ field: 'evidence', message: 'required for transition to verifying' });
+        return;
+    }
+    if (!isNonEmptyStringArray(input.evidence.artifacts)) {
+        errors.push({ field: 'evidence.artifacts', message: 'must have at least 1 non-empty artifact' });
+    }
+    if (input.evidence.commands !== undefined) {
+        if (!Array.isArray(input.evidence.commands)) {
+            errors.push({ field: 'evidence.commands', message: 'must be an array if present' });
+        }
+        else if (!input.evidence.commands.every((c) => typeof c === 'string')) {
+            errors.push({ field: 'evidence.commands', message: 'all items must be strings' });
+        }
+    }
+    if (input.evidence.notes !== undefined && typeof input.evidence.notes !== 'string') {
+        errors.push({ field: 'evidence.notes', message: 'must be a string if present' });
+    }
+}
+function validateDoneTransition(task, errors) {
+    // Structural verification: task must already have dod and evidence from verifying state
+    if (!task.dod || !Array.isArray(task.dod.checklist) || task.dod.checklist.length === 0) {
+        errors.push({ field: 'dod.checklist', message: 'must be non-empty to complete verification' });
+    }
+    if (!task.evidence || !Array.isArray(task.evidence.artifacts) || task.evidence.artifacts.length === 0) {
+        errors.push({ field: 'evidence.artifacts', message: 'must have at least 1 artifact to complete verification' });
+    }
+}
+// ============================================================================
+// Transition Function
+// ============================================================================
+export function transition(task, input) {
+    const errors = [];
+    const from = task.status;
+    const to = input.to;
+    // Check if transition is allowed by state machine
+    if (!canTransition(from, to)) {
+        const allowed = getAllowedTransitions(from);
+        const allowedStr = allowed.length > 0 ? allowed.join(', ') : 'none (terminal state)';
+        errors.push({
+            field: 'status',
+            message: `cannot transition from '${from}' to '${to}'. Allowed: ${allowedStr}`,
+        });
+        return { ok: false, errors };
+    }
+    // Validate transition-specific requirements
+    switch (input.to) {
+        case 'blocked':
+            validateBlockedInput(input, errors);
+            break;
+        case 'verifying':
+            validateVerifyingInput(input, errors);
+            break;
+        case 'done':
+            validateDoneTransition(task, errors);
+            break;
+    }
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    // Build the updated task
+    const now = new Date().toISOString();
+    const updatedTask = {
+        ...task,
+        status: to,
+        updated_at: now,
+    };
+    // Apply transition-specific changes
+    switch (input.to) {
+        case 'blocked':
+            updatedTask.blocked = input.blocked;
+            break;
+        case 'verifying':
+            updatedTask.dod = input.dod;
+            updatedTask.evidence = input.evidence;
+            updatedTask.blocked = null;
+            break;
+        case 'done':
+            // No changes needed - dod and evidence already set from verifying
+            updatedTask.blocked = null;
+            break;
+        case 'in_progress':
+            if (from === 'blocked') {
+                // Clear blocked field when unblocking
+                updatedTask.blocked = null;
+            }
+            else if (from === 'verifying') {
+                // Rejection: clear evidence, keep dod for retry
+                updatedTask.evidence = undefined;
+            }
+            break;
+        case 'cancelled':
+            updatedTask.blocked = null;
+            break;
+    }
+    return { ok: true, task: updatedTask };
+}
+//# sourceMappingURL=transitions.js.map

package/dist/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../src/transitions.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "backlog-mcp",
+  "version": "0.1.0",
+  "description": "Minimal, boring, correct core for persistent backlog state",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "backlog-mcp": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "start": "node dist/server.js",
+    "test": "tsx --test src/**/*.test.ts",
+    "dev": "tsx watch src/server.ts"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1"
+  }
+}