@damper/mcp 0.8.7 → 0.10.0

package/dist/formatters.d.ts

@@ -35,6 +35,11 @@ export interface CompleteTaskResult {
         reminder: string;
     };
 }
+export interface ReviewTaskResult {
+    id: string;
+    status: string;
+    completionChecklist?: string[];
+}
 export interface AbandonTaskResult {
     id: string;
     status: string;
@@ -49,11 +54,16 @@ export declare function formatStartTaskResponse(result: StartTaskResult): string
  * Guides the agent to propose improvements to the user with rationale.
  */
 export declare function formatSelfAssessmentActions(assessment: SelfAssessment): string;
+/**
+ * Format review_task response.
+ * Shows self-assessment follow-up actions and reminds about next steps.
+ */
+export declare function formatReviewTaskResponse(result: ReviewTaskResult, assessment: SelfAssessment): string;
 /**
  * Format complete_task response
  */
-export declare function formatCompleteTaskResponse(result: CompleteTaskResult, assessment?: SelfAssessment): string;
+export declare function formatCompleteTaskResponse(result: CompleteTaskResult): string;
 /**
  * Format abandon_task response
  */
-export declare function formatAbandonTaskResponse(result: AbandonTaskResult, hasSummary: boolean, assessment?: SelfAssessment): string;
+export declare function formatAbandonTaskResponse(result: AbandonTaskResult, hasSummary: boolean): string;

package/dist/formatters.js

@@ -52,7 +52,8 @@ 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` (with `confirmations` and `selfAssessment`) or `abandon_task`');
+    lines.push('4. `review_task` (with `selfAssessment`) — required self-review before completion');
+    lines.push('5. `complete_task` (with `confirmations`) or `abandon_task`');
     return lines.join('\n');
 }
 /**
@@ -91,31 +92,38 @@ export function formatSelfAssessmentActions(assessment) {
     }
     return lines.join('\n');
 }
+/**
+ * Format review_task response.
+ * Shows self-assessment follow-up actions and reminds about next steps.
+ */
+export function formatReviewTaskResponse(result, assessment) {
+    const lines = [`🔍 Review recorded for ${result.id}.`];
+    // Self-assessment follow-up actions
+    const actions = formatSelfAssessmentActions(assessment);
+    if (actions) {
+        lines.push(actions);
+    }
+    if (!actions) {
+        lines.push('\nNo friction points reported — nice!');
+    }
+    // Remind about completion checklist
+    if (result.completionChecklist && result.completionChecklist.length > 0) {
+        lines.push('\n📋 **Completion checklist (pass as `confirmations` in `complete_task`):**');
+        for (const item of result.completionChecklist) {
+            lines.push(`  □ ${item}`);
+        }
+    }
+    lines.push('\n**Next:** Push commits, then call `complete_task` with summary and `reviewInstructions` (what to test/verify).');
+    return lines.join('\n');
+}
 /**
  * Format complete_task response
  */
-export function formatCompleteTaskResponse(result, assessment) {
+export function formatCompleteTaskResponse(result) {
     const statusMessage = result.status === 'done'
         ? `✅ Task ${result.id} marked as done`
         : `✅ Task ${result.id} moved to review`;
     const lines = [statusMessage];
-    // Self-assessment follow-up actions (shown first if provided)
-    if (assessment) {
-        const actions = formatSelfAssessmentActions(assessment);
-        if (actions) {
-            lines.push(actions);
-        }
-    }
-    if (!assessment) {
-        // No assessment provided — nudge the agent to reflect
-        lines.push('\n---');
-        lines.push('**🔍 Before you finish — quick self-assessment:**');
-        lines.push('Reflect on your session. If you encountered any of these, propose improvements to the user:');
-        lines.push('• Missing project docs → offer to call `update_context_section`');
-        lines.push('• Confusing tools → offer to call `report_issue`');
-        lines.push('• Spec/process gaps → offer to update docs or report');
-        lines.push('Explain briefly why each improvement would help future tasks.');
-    }
     if (result.documentation) {
         if (result.documentation.affectedSections?.length > 0) {
             lines.push(`\nSections that may need updates: ${result.documentation.affectedSections.join(', ')}`);
@@ -129,26 +137,11 @@ export function formatCompleteTaskResponse(result, assessment) {
 /**
  * Format abandon_task response
  */
-export function formatAbandonTaskResponse(result, hasSummary, assessment) {
+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" (from in_progress or in_review). Notes preserved for next agent.');
-    // Self-assessment follow-up actions
-    if (assessment) {
-        const actions = formatSelfAssessmentActions(assessment);
-        if (actions) {
-            lines.push(actions);
-        }
-    }
-    if (!assessment) {
-        lines.push('\n---');
-        lines.push('**🔍 Before you finish — quick self-assessment:**');
-        lines.push('Something caused this task to be abandoned. Propose improvements to the user:');
-        lines.push('• Missing project docs that would have helped → offer to call `update_context_section`');
-        lines.push('• Tool issues that blocked progress → offer to call `report_issue`');
-        lines.push('Explain briefly why each fix would help the next agent pick this up smoothly.');
-    }
     return lines.join('\n');
 }

package/dist/index.js

@@ -2,7 +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';
+import { formatStartTaskResponse, formatReviewTaskResponse, 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';
@@ -28,6 +28,12 @@ async function api(method, path, body) {
             lockErr.lockInfo = err;
             throw lockErr;
         }
+        // Preserve review-required info for 400 review gate
+        if (res.status === 400 && err.reviewRequired) {
+            const reviewErr = new Error(err.error || `HTTP ${res.status}`);
+            reviewErr.reviewRequired = true;
+            throw reviewErr;
+        }
         // Preserve checklist info for 400 checklist failures
         if (res.status === 400 && (err.missingItems || err.invalidEvidence)) {
             const checklistErr = new Error(err.error || `HTTP ${res.status}`);
@@ -101,6 +107,7 @@ const FeedbackSummarySchema = z.object({
     title: z.string(),
     type: z.string(),
     voterCount: z.number(),
+    isPublic: z.boolean(),
     linkedTaskId: z.string().nullish(),
 });
 const FeedbackDetailSchema = z.object({
@@ -110,6 +117,7 @@ const FeedbackDetailSchema = z.object({
     type: z.string(),
     status: z.string(),
     voteScore: z.number(),
+    isPublic: z.boolean(),
     metadata: z.unknown().optional(),
     linkedTaskId: z.string().nullish(),
     voters: z.array(z.object({ email: z.string(), plan: z.string() })),
@@ -275,6 +283,8 @@ server.registerTool('update_task', {
         description: z.string().optional().describe('Task description (shown on public roadmap). Write for end users: 1-3 sentences on what changes and why it matters. ' +
             'No code references, file paths, or jargon.'),
         implementationPlan: z.string().optional().describe('Implementation plan (markdown, internal only - never shown publicly)'),
+        reviewInstructions: z.string().optional().describe('Review instructions (markdown, internal only). What the reviewer should test, verify, or check. ' +
+            'Write specific, actionable steps — not a restatement of what was done.'),
         priority: z.enum(['high', 'medium', 'low']).nullable().optional().describe('Task priority'),
         effort: z.enum(['xs', 's', 'm', 'l', 'xl']).nullable().optional().describe('Estimated effort'),
         quarter: z.string().nullable().optional().describe('Target quarter (e.g., "Q1 2025", "Q2 2025")'),
@@ -286,6 +296,7 @@ server.registerTool('update_task', {
         title: z.string(),
         description: z.string().nullable().optional(),
         implementationPlan: z.string().nullable().optional(),
+        reviewInstructions: z.string().nullable().optional(),
         priority: z.string().nullable().optional(),
         effort: z.string().nullable().optional(),
         quarter: z.string().nullable().optional(),
@@ -298,7 +309,7 @@ server.registerTool('update_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId, title, description, implementationPlan, priority, effort, quarter, labels, isPublic }) => {
+}, async ({ taskId, title, description, implementationPlan, reviewInstructions, priority, effort, quarter, labels, isPublic }) => {
     const body = {};
     if (title !== undefined)
         body.title = title;
@@ -306,6 +317,8 @@ server.registerTool('update_task', {
         body.description = description;
     if (implementationPlan !== undefined)
         body.implementationPlan = implementationPlan;
+    if (reviewInstructions !== undefined)
+        body.reviewInstructions = reviewInstructions;
     if (priority !== undefined)
         body.priority = priority;
     if (effort !== undefined)
@@ -324,6 +337,8 @@ server.registerTool('update_task', {
         updates.push('description');
     if (implementationPlan !== undefined)
         updates.push('plan');
+    if (reviewInstructions !== undefined)
+        updates.push('reviewInstructions');
     if (priority !== undefined)
         updates.push(`priority=${priority || 'none'}`);
     if (effort !== undefined)
@@ -341,6 +356,7 @@ server.registerTool('update_task', {
             title: result.title,
             description: result.description,
             implementationPlan: result.implementationPlan,
+            reviewInstructions: result.reviewInstructions,
             priority: result.priority,
             effort: result.effort,
             quarter: result.quarter,
@@ -600,6 +616,38 @@ const SelfAssessmentSchema = z.object({
     toolIssues: z.array(z.string()).optional().describe('MCP tools or workflow steps that were confusing, broken, or could be improved'),
     processGaps: z.array(z.string()).optional().describe('Gaps in specs, checklists, or conventions that caused friction or mistakes'),
 });
+// Tool: Review task (self-assessment gate before completion)
+server.registerTool('review_task', {
+    title: 'Review Task',
+    description: 'Self-review gate — MUST be called before `complete_task`.\n\n' +
+        'Reflect on your session: what project knowledge was missing, what tools were confusing, ' +
+        'what process gaps caused friction. This drives project improvements.\n\n' +
+        '**Flow:** `start_task` → work → `review_task` → `complete_task`\n\n' +
+        'If you have findings, propose improvements to the user after this call ' +
+        '(e.g., `update_context_section` for missing docs, `report_issue` for tool problems).',
+    inputSchema: z.object({
+        taskId: z.string(),
+        selfAssessment: SelfAssessmentSchema.describe('Reflect on your session: what went well, what knowledge was missing, what caused friction. ' +
+            'Be honest — this drives project improvements. Pass empty object if nothing to report.'),
+    }),
+    outputSchema: z.object({
+        id: z.string(),
+        status: z.string(),
+        completionChecklist: z.array(z.string()).optional(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ taskId, selfAssessment }) => {
+    const result = await api('POST', `/api/agent/tasks/${taskId}/review`, { selfAssessment });
+    return {
+        content: [{ type: 'text', text: formatReviewTaskResponse(result, selfAssessment) }],
+        structuredContent: result,
+    };
+});
 // Documentation reminder schema for complete_task response
 const DocumentationSchema = z.object({
     hasContext: z.boolean(),
@@ -611,22 +659,22 @@ server.registerTool('complete_task', {
     title: 'Complete Task',
     description: 'Mark task as ready for review (in_review). A human will verify and move it to done. ' +
         'Pass `skipReview: true` to mark as done immediately (use when the human explicitly asks).\n\n' +
+        '**Requires `review_task` first** — completion will be rejected if you haven\'t called `review_task`.\n\n' +
         '**Before calling:**\n' +
-        '1. Push all commits\n' +
-        '2. Check if project context docs need updating\n\n' +
-        '**Self-assessment:** Reflect on your session — what project knowledge was missing, what tools were confusing, ' +
-        'what process gaps caused friction. If you identify improvements, propose them to the user with a brief explanation.\n\n' +
-        '**Completion checklist:** If the project has a completion checklist (shown in `start_task` response), ' +
+        '1. Call `review_task` (self-assessment)\n' +
+        '2. Push all commits\n' +
+        '3. Check if project context docs need updating\n\n' +
+        '**Completion checklist:** If the project has a completion checklist (shown in `start_task` and `review_task` responses), ' +
         'you MUST pass `confirmations` — an array of `{item, evidence}` objects. Each confirmation needs the checklist item text ' +
         'and concrete evidence proving you verified it (e.g., test output, build log snippet). ' +
         'Empty evidence or evidence identical to the item text will be rejected.\n\n' +
         '**Commits:** Pass commits array to log them at completion (convenience for final commits).\n\n' +
+        '**Review instructions:** When sending to review (default), provide `reviewInstructions` — specific steps ' +
+        'for the reviewer: what to test in UI, edge cases, areas of risk. Not a restatement of what was done.\n\n' +
         'Returns documentation update suggestions.',
     inputSchema: z.object({
         taskId: z.string(),
         summary: z.string().describe('Brief one-line summary of what was done, written for end users. Focus on the outcome, not the implementation.'),
-        selfAssessment: SelfAssessmentSchema.optional().describe('Reflect on your session: what went well, what knowledge was missing, what caused friction. ' +
-            'Be honest — this drives project improvements.'),
         commits: z.array(z.object({
             hash: z.string().describe('Commit hash (short or full)'),
             message: z.string().describe('Commit message'),
@@ -636,6 +684,9 @@ server.registerTool('complete_task', {
             evidence: z.string().describe('Concrete proof of verification (e.g., "bun test: 47 passed, 0 failed")'),
         })).optional().describe('Completion checklist confirmations — echo back each item from the checklist shown in start_task'),
         skipReview: z.boolean().optional().describe('Skip human review and mark task as done immediately (default: false, task goes to in_review)'),
+        reviewInstructions: z.string().optional().describe('What the reviewer should test or verify (markdown). Recommended when sending to review (default behavior). ' +
+            'Write specific, actionable steps: what to test in the UI, what edge cases to check, ' +
+            'what areas might break. Not a restatement of the summary.'),
     }),
     outputSchema: z.object({
         id: z.string(),
@@ -648,43 +699,22 @@ server.registerTool('complete_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId, summary, selfAssessment, commits, confirmations, skipReview }) => {
+}, async ({ taskId, summary, commits, confirmations, skipReview, reviewInstructions }) => {
     try {
-        const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary, commits, confirmations, skipReview });
-        // Log self-assessment as a structured note if provided
-        if (selfAssessment) {
-            const assessmentLines = ['Self-Assessment:'];
-            if (selfAssessment.missingContext?.length) {
-                assessmentLines.push('Missing context:');
-                for (const item of selfAssessment.missingContext)
-                    assessmentLines.push(`  - ${item}`);
-            }
-            if (selfAssessment.toolIssues?.length) {
-                assessmentLines.push('Tool issues:');
-                for (const item of selfAssessment.toolIssues)
-                    assessmentLines.push(`  - ${item}`);
-            }
-            if (selfAssessment.processGaps?.length) {
-                assessmentLines.push('Process gaps:');
-                for (const item of selfAssessment.processGaps)
-                    assessmentLines.push(`  - ${item}`);
-            }
-            if (assessmentLines.length > 1) {
-                try {
-                    await api('POST', `/api/agent/tasks/${taskId}/notes`, { note: assessmentLines.join('\n') });
-                }
-                catch {
-                    // Don't fail completion if note logging fails
-                }
-            }
-        }
+        const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary, commits, confirmations, skipReview, reviewInstructions });
         return {
-            content: [{ type: 'text', text: formatCompleteTaskResponse(result, selfAssessment) }],
+            content: [{ type: 'text', text: formatCompleteTaskResponse(result) }],
             structuredContent: result,
         };
     }
     catch (err) {
         const error = err;
+        if (error.reviewRequired) {
+            return {
+                content: [{ type: 'text', text: '❌ Completion blocked — self-review required.\n\nCall `review_task` before `complete_task`. This is a required step for reflecting on your session.' }],
+                isError: true,
+            };
+        }
         if (error.checklistInfo) {
             const { missingItems, invalidEvidence, checklist } = error.checklistInfo;
             const lines = [
@@ -719,14 +749,10 @@ server.registerTool('abandon_task', {
     description: 'Release lock and return task to planned status. Works for in_progress and in_review tasks.\n\n' +
         '**Before calling:**\n' +
         '1. Push any WIP commits\n\n' +
-        '**Summary parameter:** What was done, what remains, blockers. Helps the next agent.\n\n' +
-        '**Self-assessment:** Especially important when abandoning — reflect on what blocked you ' +
-        'or what knowledge was missing so the next agent has a smoother experience.',
+        '**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'),
-        selfAssessment: SelfAssessmentSchema.optional().describe('Reflect on your session: what went well, what knowledge was missing, what caused friction. ' +
-            'Be honest — this drives project improvements.'),
     }),
     outputSchema: z.object({
         id: z.string(),
@@ -739,37 +765,10 @@ server.registerTool('abandon_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId, summary, selfAssessment }) => {
+}, async ({ taskId, summary }) => {
     const result = await api('POST', `/api/agent/tasks/${taskId}/abandon`, summary ? { summary } : undefined);
-    // Log self-assessment as a structured note if provided
-    if (selfAssessment) {
-        const assessmentLines = ['Self-Assessment (abandoned):'];
-        if (selfAssessment.missingContext?.length) {
-            assessmentLines.push('Missing context:');
-            for (const item of selfAssessment.missingContext)
-                assessmentLines.push(`  - ${item}`);
-        }
-        if (selfAssessment.toolIssues?.length) {
-            assessmentLines.push('Tool issues:');
-            for (const item of selfAssessment.toolIssues)
-                assessmentLines.push(`  - ${item}`);
-        }
-        if (selfAssessment.processGaps?.length) {
-            assessmentLines.push('Process gaps:');
-            for (const item of selfAssessment.processGaps)
-                assessmentLines.push(`  - ${item}`);
-        }
-        if (assessmentLines.length > 1) {
-            try {
-                await api('POST', `/api/agent/tasks/${taskId}/notes`, { note: assessmentLines.join('\n') });
-            }
-            catch {
-                // Don't fail abandonment if note logging fails
-            }
-        }
-    }
     return {
-        content: [{ type: 'text', text: formatAbandonTaskResponse(result, !!summary, selfAssessment) }],
+        content: [{ type: 'text', text: formatAbandonTaskResponse(result, !!summary) }],
         structuredContent: result,
     };
 });
@@ -862,7 +861,7 @@ This project uses Damper MCP for task tracking. **You MUST follow this workflow.
   2. **Abandon and hand off** - Call \`abandon_task\` with a detailed handoff summary for the next agent.
 - 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\`
-- **Self-assessment:** Include \`selfAssessment\` when calling \`complete_task\` or \`abandon_task\`. Reflect honestly on:
+- **Self-review (required):** Call \`review_task\` before \`complete_task\`. Pass \`selfAssessment\` reflecting on:
   - \`missingContext\` — What project knowledge was missing or wrong?
   - \`toolIssues\` — Which tools or workflow steps were confusing or broken?
   - \`processGaps\` — What specs or conventions were missing?
@@ -902,6 +901,12 @@ All content you generate — titles, descriptions, changelogs, notes — should
 - Types: feat, fix, refactor, test, docs, chore, style, perf
 - Imperative mood: "add feature" not "added feature"
 
+**Review instructions** (provided at task completion via \`reviewInstructions\`):
+- Write for a human reviewer who hasn't seen the code changes
+- List specific things to test: UI flows, edge cases, regressions
+- Mention files/areas that were changed and what to verify
+- Include any setup steps needed to test (e.g., "run migrations first")
+
 **Notes:**
 - Prefix with category: "Decision: …", "Blocked: …", "Context: …"
 - Only log non-obvious decisions and blockers — skip routine progress
@@ -1335,7 +1340,8 @@ server.registerTool('list_feedback', {
     }
     const lines = data.feedback.map((f) => {
         const link = f.linkedTaskId ? ` → ${f.linkedTaskId}` : '';
-        return `• ${f.id}: ${f.title} [${f.type}] (${f.voterCount} votes)${link}`;
+        const hidden = !f.isPublic ? ' [hidden]' : '';
+        return `• ${f.id}: ${f.title} [${f.type}] (${f.voterCount} votes)${hidden}${link}`;
     });
     return {
         content: [{ type: 'text', text: `Feedback:\n${lines.join('\n')}` }],
@@ -1412,12 +1418,14 @@ server.registerTool('get_feedback', {
 // Tool: Update feedback
 server.registerTool('update_feedback', {
     title: 'Update Feedback',
-    description: 'Update feedback status. Use to triage, close, or mark feedback as done.',
+    description: 'Update feedback status or visibility. Use to triage, close, mark as done, or hide from public page.',
     inputSchema: z.object({
         feedbackId: z.string().describe('Feedback ID'),
         status: z
             .enum(['new', 'under_review', 'planned', 'in_progress', 'done', 'closed'])
+            .optional()
             .describe('New status'),
+        isPublic: z.boolean().optional().describe('Whether feedback is visible on public page'),
     }),
     outputSchema: z.object({
         id: z.string(),
@@ -1431,8 +1439,13 @@ server.registerTool('update_feedback', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ feedbackId, status }) => {
-    const result = await api('PATCH', `/api/agent/feedback/${feedbackId}`, { status });
+}, async ({ feedbackId, status, isPublic }) => {
+    const body = {};
+    if (status)
+        body.status = status;
+    if (isPublic !== undefined)
+        body.isPublic = isPublic;
+    const result = await api('PATCH', `/api/agent/feedback/${feedbackId}`, body);
     return {
         content: [
             {
@@ -2064,6 +2077,31 @@ server.registerTool('publish_changelog', {
         },
     };
 });
+// Tool: Delete changelog
+server.registerTool('delete_changelog', {
+    title: 'Delete Changelog',
+    description: 'Permanently delete a changelog entry.',
+    inputSchema: z.object({
+        changelogId: z.string().describe('Changelog ID'),
+    }),
+    outputSchema: z.object({
+        success: z.boolean(),
+        id: z.string(),
+        title: z.string(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: true,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ changelogId }) => {
+    const result = await api('DELETE', `/api/agent/changelogs/${changelogId}`);
+    return {
+        content: [{ type: 'text', text: `Deleted changelog: "${result.title}"` }],
+        structuredContent: result,
+    };
+});
 // ==================== Project Settings Tools ====================
 // Tool: Get project settings
 server.registerTool('get_project_settings', {

package/package.json

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