@damper/mcp 0.3.22 → 0.4.0

package/dist/formatters.d.ts

@@ -8,6 +8,7 @@ export interface StartTaskResult {
     id: string;
     status: string;
     message: string;
+    completionChecklist?: string[];
     context?: {
         isEmpty: boolean;
         index: Array<{

package/dist/formatters.js

@@ -16,6 +16,14 @@ export function formatStartTaskResponse(result) {
             lines.push(`• ${rule}`);
         }
     }
+    // Completion checklist - shown after critical rules so agent knows upfront
+    if (result.completionChecklist && result.completionChecklist.length > 0) {
+        lines.push('\n📋 **COMPLETION CHECKLIST (required for complete_task):**');
+        lines.push('You MUST verify each item and pass them as `confirmations` when calling `complete_task`:');
+        for (const item of result.completionChecklist) {
+            lines.push(`  □ ${item}`);
+        }
+    }
     // Context section - emphatic about reading it first
     if (result.context) {
         if (result.context.isEmpty) {
@@ -43,7 +51,7 @@ export function formatStartTaskResponse(result) {
     lines.push('1. `add_note`: "Session started: <goal>"');
     lines.push('2. Work: use `add_commit` for commits, `add_note` for decisions');
     lines.push('3. `add_note`: "Session end: <summary>"');
-    lines.push('4. `complete_task` or `abandon_task`');
+    lines.push('4. `complete_task` (with `confirmations` if checklist exists) or `abandon_task`');
     return lines.join('\n');
 }
 /**

package/dist/index.js

@@ -28,6 +28,12 @@ async function api(method, path, body) {
             lockErr.lockInfo = err;
             throw lockErr;
         }
+        // Preserve checklist info for 400 checklist failures
+        if (res.status === 400 && err.missingItems) {
+            const checklistErr = new Error(err.error || `HTTP ${res.status}`);
+            checklistErr.checklistInfo = err;
+            throw checklistErr;
+        }
         throw new Error(err.error || `HTTP ${res.status}`);
     }
     return res.json();
@@ -35,7 +41,7 @@ async function api(method, path, body) {
 // Server
 const server = new McpServer({
     name: 'damper',
-    version: '0.3.0',
+    version: '0.4.0',
 });
 // Output schemas
 const SubtaskProgressSchema = z.object({
@@ -403,6 +409,7 @@ server.registerTool('start_task', {
         lockedBy: z.string().optional(),
         lockedAt: z.string().optional(),
         context: ContextIndexSchema.optional(),
+        completionChecklist: z.array(z.string()).optional(),
     }),
     annotations: {
         readOnlyHint: false,
@@ -587,6 +594,9 @@ server.registerTool('complete_task', {
         '**Before calling:**\n' +
         '1. Push all commits\n' +
         '2. Check if project context docs need updating\n\n' +
+        '**Completion checklist:** If the project has a completion checklist (shown in `start_task` response), ' +
+        'you MUST pass `confirmations` — an array echoing back each checklist item you\'ve verified. ' +
+        'The server will reject completion if any items are missing.\n\n' +
         '**Commits:** Pass commits array to log them at completion (convenience for final commits).\n\n' +
         'Returns documentation update suggestions.',
     inputSchema: z.object({
@@ -596,6 +606,7 @@ server.registerTool('complete_task', {
             hash: z.string().describe('Commit hash (short or full)'),
             message: z.string().describe('Commit message'),
         })).optional().describe('Optional: commits to log at completion'),
+        confirmations: z.array(z.string()).optional().describe('Completion checklist confirmations — echo back each item from the checklist shown in start_task'),
     }),
     outputSchema: z.object({
         id: z.string(),
@@ -608,12 +619,33 @@ server.registerTool('complete_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId, summary, commits }) => {
-    const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary, commits });
-    return {
-        content: [{ type: 'text', text: formatCompleteTaskResponse(result) }],
-        structuredContent: result,
-    };
+}, async ({ taskId, summary, commits, confirmations }) => {
+    try {
+        const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary, commits, confirmations });
+        return {
+            content: [{ type: 'text', text: formatCompleteTaskResponse(result) }],
+            structuredContent: result,
+        };
+    }
+    catch (err) {
+        const error = err;
+        if (error.checklistInfo) {
+            const { missingItems, checklist } = error.checklistInfo;
+            const lines = [
+                '❌ Completion blocked — checklist not fully confirmed.',
+                '',
+                `**Missing ${missingItems.length} of ${checklist.length} items:**`,
+                ...missingItems.map(item => `  • ${item}`),
+                '',
+                'Pass ALL checklist items in `confirmations` to complete the task.',
+            ];
+            return {
+                content: [{ type: 'text', text: lines.join('\n') }],
+                isError: true,
+            };
+        }
+        throw error;
+    }
 });
 // Tool: Abandon task
 server.registerTool('abandon_task', {
@@ -724,6 +756,7 @@ This project uses Damper MCP for task tracking. **You MUST follow this workflow.
 ### At Session End (MANDATORY)
 - ALWAYS call \`complete_task\` (if done) or \`abandon_task\` (if stopping early)
 - NEVER leave a started task without completing or abandoning it
+- If the project has a **completion checklist** (shown in \`start_task\` response), you MUST pass all items as \`confirmations\` when calling \`complete_task\`
 - If you learned something about the codebase, consider updating project context
 
 ### Why This Matters

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damper/mcp",
-  "version": "0.3.22",
+  "version": "0.4.0",
   "description": "MCP server for Damper task management",
   "author": "Damper <hello@usedamper.com>",
   "repository": {

package/dist/formatters.test.d.ts

@@ -1,4 +0,0 @@
-/**
- * Tests for MCP response formatters
- */
-export {};

package/dist/formatters.test.js

@@ -1,126 +0,0 @@
-/**
- * Tests for MCP response formatters
- */
-import { describe, it, expect } from 'bun:test';
-import { formatStartTaskResponse, formatCompleteTaskResponse, formatAbandonTaskResponse, } from './formatters';
-describe('formatStartTaskResponse', () => {
-    it('includes workflow steps', () => {
-        const result = formatStartTaskResponse({
-            id: 'TASK-1',
-            status: 'in_progress',
-            message: 'Task started',
-        });
-        expect(result).toContain('**📋 Workflow:**');
-        expect(result).toContain('`add_note`: "Session started: <goal>"');
-        expect(result).toContain('`add_note`: "Session end: <summary, next steps>"');
-        expect(result).toContain('`complete_task` or `abandon_task`');
-    });
-    it('shows empty context hint when context is empty', () => {
-        const result = formatStartTaskResponse({
-            id: 'TASK-1',
-            status: 'in_progress',
-            message: 'Task started',
-            context: {
-                isEmpty: true,
-                index: [],
-                hint: 'No docs available yet',
-            },
-        });
-        expect(result).toContain('📚 No docs available yet');
-    });
-    it('lists context sections with star for relevant ones', () => {
-        const result = formatStartTaskResponse({
-            id: 'TASK-1',
-            status: 'in_progress',
-            message: 'Task started',
-            context: {
-                isEmpty: false,
-                index: [
-                    { section: 'overview', preview: 'Project overview', updatedAt: '2024-01-01' },
-                    { section: 'api', preview: 'API docs', updatedAt: '2024-01-01' },
-                    { section: 'testing', preview: 'Testing guide', updatedAt: '2024-01-01' },
-                ],
-                relevantSections: ['api', 'testing'],
-            },
-        });
-        expect(result).toContain('**Project context available:**');
-        expect(result).toContain('• overview');
-        expect(result).toContain('• api ⭐');
-        expect(result).toContain('• testing ⭐');
-        expect(result).toContain('Relevant for this task: api, testing');
-        expect(result).toContain('Use get_context_section to fetch full content.');
-    });
-    it('shows basic message and task ID', () => {
-        const result = formatStartTaskResponse({
-            id: 'TASK-123',
-            status: 'in_progress',
-            message: 'Locked successfully',
-        });
-        expect(result).toContain('Started TASK-123: Locked successfully');
-    });
-});
-describe('formatCompleteTaskResponse', () => {
-    it('shows completion message', () => {
-        const result = formatCompleteTaskResponse({
-            id: 'TASK-1',
-            status: 'done',
-        });
-        expect(result).toContain('✅ Completed TASK-1');
-    });
-    it('shows documentation section with affected sections', () => {
-        const result = formatCompleteTaskResponse({
-            id: 'TASK-1',
-            status: 'done',
-            documentation: {
-                hasContext: true,
-                affectedSections: ['api', 'overview'],
-                reminder: 'Please review and update docs',
-            },
-        });
-        expect(result).toContain('**📚 Documentation:**');
-        expect(result).toContain('May need updates: api, overview');
-        expect(result).toContain('Please review and update docs');
-    });
-    it('skips affected sections line when empty', () => {
-        const result = formatCompleteTaskResponse({
-            id: 'TASK-1',
-            status: 'done',
-            documentation: {
-                hasContext: true,
-                affectedSections: [],
-                reminder: 'No changes needed',
-            },
-        });
-        expect(result).toContain('**📚 Documentation:**');
-        expect(result).not.toContain('May need updates:');
-        expect(result).toContain('No changes needed');
-    });
-    it('handles missing documentation gracefully', () => {
-        const result = formatCompleteTaskResponse({
-            id: 'TASK-1',
-            status: 'done',
-        });
-        expect(result).not.toContain('**📚 Documentation:**');
-        expect(result).toBe('✅ Completed TASK-1');
-    });
-});
-describe('formatAbandonTaskResponse', () => {
-    it('shows tip when no summary provided', () => {
-        const result = formatAbandonTaskResponse({ id: 'TASK-1', status: 'planned', message: 'Task abandoned' }, false);
-        expect(result).toContain('⏸️ Abandoned TASK-1: Task abandoned');
-        expect(result).toContain('⚠️ Tip: Include a summary next time for better handoff.');
-        expect(result).toContain('💡 Task returned to "planned". Notes preserved for next agent.');
-    });
-    it('does not show tip when summary provided', () => {
-        const result = formatAbandonTaskResponse({ id: 'TASK-1', status: 'planned', message: 'Task abandoned with handoff' }, true);
-        expect(result).toContain('⏸️ Abandoned TASK-1');
-        expect(result).not.toContain('⚠️ Tip:');
-        expect(result).toContain('💡 Task returned to "planned"');
-    });
-    it('always shows notes preserved message', () => {
-        const withSummary = formatAbandonTaskResponse({ id: 'TASK-1', status: 'planned', message: 'Done' }, true);
-        const withoutSummary = formatAbandonTaskResponse({ id: 'TASK-1', status: 'planned', message: 'Done' }, false);
-        expect(withSummary).toContain('Notes preserved for next agent');
-        expect(withoutSummary).toContain('Notes preserved for next agent');
-    });
-});