@damper/mcp 0.3.3 → 0.3.4

package/dist/formatters.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Response formatters for MCP tools
+ *
+ * Extracted for testability - these pure functions format API responses
+ * into user-friendly text output.
+ */
+export interface StartTaskResult {
+    id: string;
+    status: string;
+    message: string;
+    context?: {
+        isEmpty: boolean;
+        index: Array<{
+            section: string;
+            preview: string;
+            updatedAt: string;
+        }>;
+        relevantSections?: string[];
+        hint?: string;
+    };
+}
+export interface CompleteTaskResult {
+    id: string;
+    status: string;
+    documentation?: {
+        hasContext: boolean;
+        affectedSections: string[];
+        reminder: string;
+    };
+}
+export interface AbandonTaskResult {
+    id: string;
+    status: string;
+    message: string;
+}
+/**
+ * Format start_task response
+ */
+export declare function formatStartTaskResponse(result: StartTaskResult): string;
+/**
+ * Format complete_task response
+ */
+export declare function formatCompleteTaskResponse(result: CompleteTaskResult): string;
+/**
+ * Format abandon_task response
+ */
+export declare function formatAbandonTaskResponse(result: AbandonTaskResult, hasSummary: boolean): string;

package/dist/formatters.js

@@ -0,0 +1,63 @@
+/**
+ * Response formatters for MCP tools
+ *
+ * Extracted for testability - these pure functions format API responses
+ * into user-friendly text output.
+ */
+/**
+ * Format start_task response
+ */
+export function formatStartTaskResponse(result) {
+    const lines = [`Started ${result.id}: ${result.message}`];
+    if (result.context) {
+        if (result.context.isEmpty) {
+            lines.push(`\n📚 ${result.context.hint || 'No project context available.'}`);
+        }
+        else {
+            lines.push('\n**Project context available:**');
+            for (const s of result.context.index) {
+                const relevant = result.context.relevantSections?.includes(s.section) ? ' ⭐' : '';
+                lines.push(`• ${s.section}${relevant}`);
+            }
+            if (result.context.relevantSections && result.context.relevantSections.length > 0) {
+                lines.push(`\nRelevant for this task: ${result.context.relevantSections.join(', ')}`);
+                lines.push('Use get_context_section to fetch full content.');
+            }
+        }
+    }
+    lines.push('\n---');
+    lines.push('**📋 Workflow:**');
+    lines.push('1. `add_note`: "Session started: <goal>"');
+    lines.push('2. Work + log commits/decisions with `add_note`');
+    lines.push('3. `add_note`: "Session end: <summary, next steps>"');
+    lines.push('4. `complete_task` or `abandon_task`');
+    return lines.join('\n');
+}
+/**
+ * Format complete_task response
+ */
+export function formatCompleteTaskResponse(result) {
+    const lines = [`✅ Completed ${result.id}`];
+    if (result.documentation) {
+        lines.push('\n---');
+        lines.push('**📚 Documentation:**');
+        if (result.documentation.affectedSections?.length > 0) {
+            lines.push(`May need updates: ${result.documentation.affectedSections.join(', ')}`);
+        }
+        if (result.documentation.reminder) {
+            lines.push(result.documentation.reminder);
+        }
+    }
+    return lines.join('\n');
+}
+/**
+ * Format abandon_task response
+ */
+export function formatAbandonTaskResponse(result, hasSummary) {
+    const lines = [`⏸️ Abandoned ${result.id}: ${result.message}`];
+    if (!hasSummary) {
+        lines.push('\n⚠️ Tip: Include a summary next time for better handoff.');
+    }
+    lines.push('\n💡 Task returned to "planned". Notes preserved for next agent.');
+    return lines.join('\n');
+}

package/dist/formatters.test.d.ts

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

package/dist/formatters.test.js

@@ -0,0 +1,126 @@
+/**
+ * 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');
+    });
+});

package/dist/index.js

@@ -2,6 +2,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { z } from 'zod';
+import { formatStartTaskResponse, formatCompleteTaskResponse, formatAbandonTaskResponse, } from './formatters.js';
 // Config
 const API_KEY = process.env.DAMPER_API_KEY;
 const API_URL = process.env.DAMPER_API_URL || 'https://api.usedamper.com';
@@ -331,8 +332,12 @@ server.registerTool('start_task', {
     title: 'Start Task',
     description: 'Lock and start a task. Fails if locked by another agent unless force=true. ' +
         'Use force=true to take over a task from another agent (e.g., if they abandoned it). ' +
-        'Returns project context index with relevant sections for the task. ' +
-        'Use add_note for session start/end and commits.',
+        'Returns project context index with relevant sections for the task.\n\n' +
+        '**Workflow after starting:**\n' +
+        '1. add_note: "Session started: <your goal>"\n' +
+        '2. Do work, log commits/decisions with add_note\n' +
+        '3. add_note: "Session end: <summary, next steps>"\n' +
+        '4. complete_task (done) or abandon_task (stopping)',
     inputSchema: z.object({
         taskId: z.string(),
         force: z.boolean().optional().describe('Take over lock from another agent'),
@@ -354,27 +359,8 @@ server.registerTool('start_task', {
 }, async ({ taskId, force }) => {
     try {
         const result = await api('POST', `/api/agent/tasks/${taskId}/start`, force ? { force: true } : undefined);
-        // Build response text
-        const lines = [`Started ${result.id}: ${result.message}`];
-        if (result.context) {
-            if (result.context.isEmpty) {
-                lines.push(`\n📚 ${result.context.hint || 'No project context available.'}`);
-            }
-            else {
-                lines.push('\n**Project context available:**');
-                for (const s of result.context.index) {
-                    const relevant = result.context.relevantSections?.includes(s.section) ? ' ⭐' : '';
-                    lines.push(`• ${s.section}${relevant}`);
-                }
-                if (result.context.relevantSections && result.context.relevantSections.length > 0) {
-                    lines.push(`\nRelevant for this task: ${result.context.relevantSections.join(', ')}`);
-                    lines.push('Use get_context_section to fetch full content.');
-                }
-            }
-        }
-        lines.push('\n💡 Use add_note to log session start, commits, and session end with next steps.');
         return {
-            content: [{ type: 'text', text: lines.join('\n') }],
+            content: [{ type: 'text', text: formatStartTaskResponse(result) }],
             structuredContent: result,
         };
     }
@@ -406,8 +392,13 @@ server.registerTool('start_task', {
 // Tool: Add note
 server.registerTool('add_note', {
     title: 'Add Note',
-    description: 'Add progress note to task. Log session start, commits (with hashes), decisions, ' +
-        'and session end with next steps. Notes help future agents continue your work.',
+    description: 'Add progress note to task. Notes help future agents continue your work.\n\n' +
+        '**When to use:**\n' +
+        '- Session start: "Session started: implementing X"\n' +
+        '- Commits: "Committed abc123: Added validation"\n' +
+        '- Decisions: "Decision: Using X because Y"\n' +
+        '- Session end: "Session end: Done X, remaining Y, blockers Z"\n\n' +
+        '**Important:** Always log session end before complete_task or abandon_task.',
     inputSchema: z.object({
         taskId: z.string(),
         note: z.string(),
@@ -509,7 +500,11 @@ const DocumentationSchema = z.object({
 // Tool: Complete task
 server.registerTool('complete_task', {
     title: 'Complete Task',
-    description: 'Mark task done with summary. Include commit hashes and any follow-up work. ' +
+    description: 'Mark task done with summary. Include commit hashes and any follow-up work.\n\n' +
+        '**Before calling:**\n' +
+        '1. Push all commits\n' +
+        '2. add_note: "Session end: <what was done>"\n' +
+        '3. Check if project context docs need updating\n\n' +
         'Returns documentation update suggestions.',
     inputSchema: z.object({
         taskId: z.string(),
@@ -528,20 +523,19 @@ server.registerTool('complete_task', {
     },
 }, async ({ taskId, summary }) => {
     const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary });
-    const lines = [`✅ Completed ${result.id}`];
-    if (result.documentation?.reminder) {
-        lines.push(`\n📝 ${result.documentation.reminder}`);
-    }
     return {
-        content: [{ type: 'text', text: lines.join('\n') }],
+        content: [{ type: 'text', text: formatCompleteTaskResponse(result) }],
         structuredContent: result,
     };
 });
 // Tool: Abandon task
 server.registerTool('abandon_task', {
     title: 'Abandon Task',
-    description: 'Release lock and return task to planned status. Use when you cannot complete the task ' +
-        'or need to stop working on it. Optionally provide summary (what done, what remains, blockers) for handoff.',
+    description: 'Release lock and return task to planned status. Use when stopping work.\n\n' +
+        '**Before calling:**\n' +
+        '1. Push any WIP commits\n' +
+        '2. add_note: "Session end: <progress, blockers, next steps>"\n\n' +
+        '**Summary parameter:** What was done, what remains, blockers. Helps the next agent.',
     inputSchema: z.object({
         taskId: z.string(),
         summary: z.string().optional().describe('Handoff summary: what was done, what remains, any blockers'),
@@ -560,7 +554,7 @@ server.registerTool('abandon_task', {
 }, async ({ taskId, summary }) => {
     const result = await api('POST', `/api/agent/tasks/${taskId}/abandon`, summary ? { summary } : undefined);
     return {
-        content: [{ type: 'text', text: `Abandoned ${result.id}: ${result.message}` }],
+        content: [{ type: 'text', text: formatAbandonTaskResponse(result, !!summary) }],
         structuredContent: result,
     };
 });

package/package.json

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