@damper/mcp 0.3.22 → 0.5.0

package/README.md

@@ -118,6 +118,26 @@ AI agents can store and retrieve project documentation to help future agents wor
 
 ⚠️ **Security:** Never include sensitive data (API keys, secrets, credentials, connection strings) in context uploads. Users can review and delete context from Settings → AI Context.
 
+### Project Settings
+
+Configure agent-relevant project settings programmatically.
+
+| Tool | Description |
+|------|-------------|
+| `get_project_settings` | View current settings (completion checklist, etc.) |
+| `update_project_settings` | Configure completion checklist and other agent-relevant settings |
+
+**Completion checklist workflow:**
+1. `update_project_settings` with `completionChecklist: ["All tests pass", "Build succeeds"]`
+2. Agents see the checklist when they call `start_task`
+3. Agents must confirm all items via `confirmations` when calling `complete_task`
+
+```
+> View project settings
+> Set completion checklist to require tests and builds
+> Clear the completion checklist
+```
+
 ### Hierarchical Sections
 
 For monorepos or large projects, organize sections hierarchically:

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.5.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', {
@@ -690,7 +722,7 @@ server.registerTool('get_agent_instructions', {
         openWorldHint: false,
     },
 }, async ({ format = 'section' }) => {
-    const lastModified = '2025-02-05';
+    const lastModified = '2025-02-06';
     const section = `## Task Management with Damper MCP
 
 > Last updated: ${lastModified}
@@ -721,9 +753,14 @@ This project uses Damper MCP for task tracking. **You MUST follow this workflow.
 - \`add_to_changelog\` - Manually add completed tasks to a changelog
 - \`publish_changelog\` - Publish with optional email notifications and Twitter posting
 
+### Project Settings
+- \`get_project_settings\` - View current settings (completion checklist, etc.)
+- \`update_project_settings\` - Configure completion checklist and other agent-relevant settings
+
 ### 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
@@ -1842,6 +1879,74 @@ server.registerTool('publish_changelog', {
         },
     };
 });
+// ==================== Project Settings Tools ====================
+// Tool: Get project settings
+server.registerTool('get_project_settings', {
+    title: 'Get Project Settings',
+    description: 'View current project settings relevant to agents (completion checklist, etc.).\n\n' +
+        '**When to use**: Check what completion checklist items are configured, or verify settings before updating them.',
+    inputSchema: z.object({}),
+    outputSchema: z.object({
+        completionChecklist: z.array(z.string()),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async () => {
+    const data = await api('GET', '/api/agent/project/settings');
+    if (!data.completionChecklist || data.completionChecklist.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'No completion checklist configured.' }],
+            structuredContent: data,
+        };
+    }
+    const lines = data.completionChecklist.map((item, i) => `${i + 1}. ${item}`);
+    return {
+        content: [{ type: 'text', text: `Completion checklist:\n${lines.join('\n')}` }],
+        structuredContent: data,
+    };
+});
+// Tool: Update project settings
+server.registerTool('update_project_settings', {
+    title: 'Update Project Settings',
+    description: 'Configure agent-relevant project settings.\n\n' +
+        '**completionChecklist**: Items agents must confirm before completing tasks. ' +
+        'Pass an empty array to clear the checklist.\n\n' +
+        'Example items: "All tests pass", "Build succeeds", "Migration created if schema changed"',
+    inputSchema: z.object({
+        completionChecklist: z.array(z.string()).optional()
+            .describe('Checklist items agents must confirm when completing tasks. Pass [] to clear.'),
+    }),
+    outputSchema: z.object({
+        completionChecklist: z.array(z.string()),
+        message: z.string(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ completionChecklist }) => {
+    const body = {};
+    if (completionChecklist !== undefined)
+        body.completionChecklist = completionChecklist;
+    const result = await api('PATCH', '/api/agent/project/settings', body);
+    if (result.completionChecklist.length === 0) {
+        return {
+            content: [{ type: 'text', text: 'Completion checklist cleared.' }],
+            structuredContent: result,
+        };
+    }
+    const lines = result.completionChecklist.map((item, i) => `${i + 1}. ${item}`);
+    return {
+        content: [{ type: 'text', text: `${result.message}\n${lines.join('\n')}` }],
+        structuredContent: result,
+    };
+});
 // Start
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@damper/mcp",
-  "version": "0.3.22",
+  "version": "0.5.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');
-    });
-});