@damper/mcp 0.3.8 → 0.3.10

package/README.md

@@ -74,14 +74,15 @@ The AI will see tools from both servers and can distinguish between them:
 | Tool | Description |
 |------|-------------|
 | `list_tasks` | Get roadmap tasks (filter by `status`, `type`, `quarter`, sort by `importance`/`newest`/`votes`) |
-| `get_task` | Task details + subtasks + linked feedback |
+| `get_task` | Task details + subtasks + commits + linked feedback |
 | `create_task` | Create task with type (bug, feature, improvement, task) |
 | `update_task` | Update description, plan, priority, effort, quarter, labels |
 | `start_task` | Lock and start task (use `force` to take over). Returns project context index. |
 | `add_note` | Add progress note |
+| `add_commit` | Log a commit (hash + message). Appears in task details. |
 | `create_subtask` | Add subtask to a task |
 | `update_subtask` | Mark subtask done/undone |
-| `complete_task` | Mark done, release lock. Suggests context updates if needed. |
+| `complete_task` | Mark done, release lock. Optionally log commits at completion. |
 | `abandon_task` | Release lock, return to planned |
 | `list_feedback` | Browse user feedback |
 | `get_feedback` | Feedback details + votes |
@@ -93,6 +94,7 @@ The AI will see tools from both servers and can distinguish between them:
 | `get_module` | Get module details |
 | `update_module` | Register/update a module |
 | `sync_modules` | Bulk upload module registry |
+| `get_agent_instructions` | Get canonical workflow for CLAUDE.md setup |
 
 ### Project Context
 
@@ -259,21 +261,42 @@ When you start a task, it's locked to prevent other agents from working on it si
 - Different agent starting → fails with 409 (use `force: true` to take over)
 - Complete or abandon → releases lock
 
+### Commit Tracking
+
+Log commits as you work to track code changes for each task:
+
+```
+> Log commit abc1234 with message "Added validation"
+> Add commit def5678: "Fixed auth bug"
+```
+
+Commits are stored structurally and displayed in task details:
+
+```
+## Commits (2)
+- abc1234: Added validation
+- def5678: Fixed auth bug
+```
+
+**Two ways to log commits:**
+1. `add_commit` - Log commits as you make them
+2. `complete_task` with `commits` - Log final commits at completion
+
 ### Recommended Workflow
 
 When working on tasks, follow this workflow for best results:
 
 1. **Start**: `start_task` → locks the task and returns project context
 2. **Log start**: `add_note` with "Session started: <your goal>"
-3. **Work**: Make changes, logging commits and decisions with `add_note`
+3. **Work**: Make changes, use `add_commit` after each commit, `add_note` for decisions
 4. **Log end**: `add_note` with "Session end: <summary, next steps>"
 5. **Finish**: `complete_task` (done) or `abandon_task` (stopping)
 
-**Note types to log:**
-- Session start: `"Session started: implementing dark mode"`
-- Commits: `"Committed abc123: Added theme provider"`
-- Decisions: `"Decision: Using CSS variables because..."`
-- Session end: `"Session end: Done theme provider, remaining: toggle UI"`
+**What to log:**
+- Session start: `add_note "Session started: implementing dark mode"`
+- Commits: `add_commit abc123 "Added theme provider"`
+- Decisions: `add_note "Decision: Using CSS variables because..."`
+- Session end: `add_note "Session end: Done theme provider, remaining: toggle UI"`
 
 **Before completing:**
 - Push all commits
@@ -310,6 +333,20 @@ When working on tasks, follow this workflow for best results:
 > Sync all my documentation to Damper
 ```
 
+## Setting Up a Project
+
+To add Damper workflow instructions to a new project:
+
+```
+> Get the agent instructions and add them to my CLAUDE.md
+```
+
+The agent will call `get_agent_instructions` and write to your CLAUDE.md file. This ensures you always have the latest workflow instructions.
+
+**Formats:**
+- `section` (default): Just the Damper workflow section - append to existing CLAUDE.md
+- `markdown`: Full file with header - use when creating a new CLAUDE.md
+
 ## Agent Instructions (CLAUDE.md)
 
 Add this to your project's `CLAUDE.md` (or `.cursorrules` for Cursor) to ensure AI agents use Damper consistently:
@@ -319,25 +356,29 @@ Add this to your project's `CLAUDE.md` (or `.cursorrules` for Cursor) to ensure
 
 This project uses Damper MCP for task tracking. **You MUST follow this workflow.**
 
-### At Session Start
-1. `get_project_context` - Read available project documentation
-2. `list_tasks` - Check for existing tasks to work on
-3. If working on a task: `start_task` to lock it
+### At Session Start (MANDATORY)
+1. `get_project_context` - **READ THIS FIRST.** Contains architecture, conventions, and critical project info. Do NOT skip.
+2. `get_context_section` - Fetch full content for sections relevant to your task (e.g., "api", "database", "testing")
+3. `list_tasks` - Check for existing tasks to work on
+4. If working on a task: `start_task` to lock it (returns context index - read relevant sections)
 
 ### While Working
-- `add_note` after each commit: "Committed abc123: description"
+- `add_commit` after each commit with hash and message
 - `add_note` for decisions: "Decision: chose X because Y"
 - `update_subtask` to mark subtask progress
+- **Follow patterns from project context** - Don't reinvent; use existing conventions
 
 ### At Session End (MANDATORY)
 - ALWAYS call `add_note` with session summary before stopping
 - ALWAYS call `complete_task` (if done) or `abandon_task` (if stopping early)
 - NEVER leave a started task without completing or abandoning it
+- If you learned something about the codebase, consider updating project context
 
 ### Why This Matters
+- **Project context prevents mistakes** - Contains architecture decisions, gotchas, and patterns you need to follow
 - Locked tasks block other agents from working on them
-- Notes help the next agent (or you) continue the work
-- Project context saves future agents from re-analyzing the codebase
+- Commits and notes help the next agent (or you) continue the work
+- Updating context saves future agents from re-analyzing the codebase
 ```
 
 ## Environment

package/dist/formatters.js

@@ -8,29 +8,36 @@
  * Format start_task response
  */
 export function formatStartTaskResponse(result) {
-    const lines = [`Started ${result.id}: ${result.message}`];
+    const lines = [`✅ Started ${result.id}: ${result.message}`];
+    // Context section - emphatic about reading it first
     if (result.context) {
         if (result.context.isEmpty) {
             lines.push(`\n📚 ${result.context.hint || 'No project context available.'}`);
         }
         else {
-            lines.push('\n**Project context available:**');
+            lines.push('\n⚠️ **BEFORE YOU START:** Read project context to understand patterns and conventions.');
+            lines.push('');
+            if (result.context.relevantSections && result.context.relevantSections.length > 0) {
+                lines.push(`**Required reading for this task:**`);
+                for (const section of result.context.relevantSections) {
+                    lines.push(`→ \`get_context_section("${section}")\``);
+                }
+                lines.push('');
+            }
+            lines.push('**All available sections:**');
             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`');
+    lines.push('**📋 Required workflow:**');
+    lines.push('1. **Read context sections above** (contains patterns you must follow)');
+    lines.push('2. `add_note`: "Session started: <goal>"');
+    lines.push('3. Work: use `add_commit` for commits, `add_note` for decisions');
+    lines.push('4. `add_note`: "Session end: <summary>"');
+    lines.push('5. `complete_task` or `abandon_task` (NEVER skip this)');
     return lines.join('\n');
 }
 /**
@@ -38,11 +45,13 @@ export function formatStartTaskResponse(result) {
  */
 export function formatCompleteTaskResponse(result) {
     const lines = [`✅ Completed ${result.id}`];
+    lines.push('\n---');
+    lines.push('**📚 Before you finish:**');
+    lines.push('Did you learn something about this codebase that would help future agents?');
+    lines.push('→ Use `update_context_section` to share architecture, patterns, or gotchas.');
     if (result.documentation) {
-        lines.push('\n---');
-        lines.push('**📚 Documentation:**');
         if (result.documentation.affectedSections?.length > 0) {
-            lines.push(`May need updates: ${result.documentation.affectedSections.join(', ')}`);
+            lines.push(`\nSections that may need updates: ${result.documentation.affectedSections.join(', ')}`);
         }
         if (result.documentation.reminder) {
             lines.push(result.documentation.reminder);

package/dist/index.js

@@ -61,6 +61,10 @@ const SubtaskSchema = z.object({
     title: z.string(),
     done: z.boolean(),
 });
+const CommitSchema = z.object({
+    hash: z.string(),
+    message: z.string(),
+});
 const TaskDetailSchema = z.object({
     id: z.string(),
     title: z.string(),
@@ -76,6 +80,7 @@ const TaskDetailSchema = z.object({
     voteScore: z.number(),
     subtasks: z.array(SubtaskSchema).optional(),
     agentNotes: z.string().nullable().optional(),
+    commits: z.array(CommitSchema).optional(),
     feedback: z.array(z.object({
         id: z.string(),
         title: z.string(),
@@ -105,7 +110,8 @@ const FeedbackDetailSchema = z.object({
 server.registerTool('list_tasks', {
     title: 'List Tasks',
     description: 'Get roadmap tasks. Returns planned/in-progress by default. ' +
-        'Filter by type, quarter, etc.',
+        'Filter by type, quarter, etc.\n\n' +
+        '**Recommended:** Call `get_project_context` before starting work to understand codebase patterns.',
     inputSchema: z.object({
         status: z.enum(['planned', 'in_progress', 'done', 'all']).optional(),
         type: z.enum(['bug', 'feature', 'improvement', 'task']).optional().describe('Filter by task type'),
@@ -151,15 +157,21 @@ server.registerTool('list_tasks', {
         const quarterInfo = t.quarter ? ` 📅${t.quarter}` : '';
         return `• ${t.id}: ${typeIcon} ${t.title} [${t.status}] ${p}${quarterInfo}${t.hasImplementationPlan ? ' 📋' : ''}${subtaskInfo}`;
     });
+    const output = [
+        `Tasks in "${data.project.name}":`,
+        lines.join('\n'),
+        '',
+        '💡 **Tip:** Run `get_project_context` first to understand codebase patterns before starting work.',
+    ].join('\n');
     return {
-        content: [{ type: 'text', text: `Tasks in "${data.project.name}":\n${lines.join('\n')}` }],
+        content: [{ type: 'text', text: output }],
         structuredContent: { project: data.project.name, tasks: data.tasks },
     };
 });
 // Tool: Get task
 server.registerTool('get_task', {
     title: 'Get Task',
-    description: 'Get task details including description, plan, and linked feedback.',
+    description: 'Get task details including description, plan, commits, and linked feedback.',
     inputSchema: z.object({
         taskId: z.string().describe('Task ID'),
     }),
@@ -202,12 +214,24 @@ server.registerTool('get_task', {
         parts.push(`\n## Subtasks (${done}/${t.subtasks.length})`);
         t.subtasks.forEach((s) => parts.push(`- [${s.done ? 'x' : ' '}] ${s.title} (id: ${s.id})`));
     }
+    // Show commits
+    if (t.commits && t.commits.length) {
+        parts.push(`\n## Commits (${t.commits.length})`);
+        t.commits.forEach((c) => parts.push(`- ${c.hash.slice(0, 7)}: ${c.message}`));
+    }
     if (t.agentNotes)
         parts.push(`\n## Notes\n${t.agentNotes}`);
     if (t.feedback.length) {
         parts.push(`\n## Feedback (${t.feedback.length})`);
         t.feedback.forEach((f) => parts.push(`- ${f.title} (${f.voterCount} votes)`));
     }
+    // Add workflow reminder for tasks not yet started
+    if (t.status === 'planned') {
+        parts.push('\n---');
+        parts.push('**To work on this task:**');
+        parts.push('1. `get_project_context` → read relevant sections');
+        parts.push('2. `start_task` → locks task and shows context');
+    }
     return {
         content: [{ type: 'text', text: parts.join('\n') }],
         structuredContent: t,
@@ -343,11 +367,14 @@ server.registerTool('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.\n\n' +
+        '**IMPORTANT:** After starting, use get_context_section to read relevant sections. ' +
+        'Project context contains architecture and patterns you MUST follow.\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)',
+        '1. Read relevant context sections (architecture, conventions, etc.)\n' +
+        '2. add_note: "Session started: <your goal>"\n' +
+        '3. Do work, log commits with add_commit, decisions with add_note\n' +
+        '4. add_note: "Session end: <summary, next steps>"\n' +
+        '5. complete_task (done) or abandon_task (stopping)',
     inputSchema: z.object({
         taskId: z.string(),
         force: z.boolean().optional().describe('Take over lock from another agent'),
@@ -405,9 +432,9 @@ server.registerTool('add_note', {
     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' +
+        '**For commits:** Use `add_commit` instead for structured commit tracking.\n\n' +
         '**Important:** Always log session end before complete_task or abandon_task.',
     inputSchema: z.object({
         taskId: z.string(),
@@ -430,6 +457,37 @@ server.registerTool('add_note', {
         structuredContent: { taskId, success: true },
     };
 });
+// Tool: Add commit
+server.registerTool('add_commit', {
+    title: 'Add Commit',
+    description: 'Log a commit for a task. Stores structured commit info that appears in task details.\n\n' +
+        '**When to use:**\n' +
+        '- After making a commit: log hash and message\n' +
+        '- When completing work: optionally pass commits to complete_task instead\n\n' +
+        '**Example:** After `git commit`, call this with the commit hash and message.',
+    inputSchema: z.object({
+        taskId: z.string(),
+        hash: z.string().describe('Commit hash (short or full)'),
+        message: z.string().describe('Commit message'),
+    }),
+    outputSchema: z.object({
+        taskId: z.string(),
+        hash: z.string(),
+        success: z.boolean(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
+}, async ({ taskId, hash, message }) => {
+    const result = await api('POST', `/api/agent/tasks/${taskId}/commits`, { hash, message });
+    return {
+        content: [{ type: 'text', text: `📝 Commit logged: ${hash.slice(0, 7)} - ${message}` }],
+        structuredContent: { taskId, hash: result.hash, success: true },
+    };
+});
 // Tool: Create subtask
 server.registerTool('create_subtask', {
     title: 'Create Subtask',
@@ -510,15 +568,20 @@ 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.\n\n' +
+    description: 'Mark task done with summary. Optionally log final commits at completion.\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' +
+        '**Commits:** Pass commits array to log them at completion (convenience for final commits).\n\n' +
         'Returns documentation update suggestions.',
     inputSchema: z.object({
         taskId: z.string(),
         summary: z.string().describe('What was implemented'),
+        commits: z.array(z.object({
+            hash: z.string().describe('Commit hash (short or full)'),
+            message: z.string().describe('Commit message'),
+        })).optional().describe('Optional: commits to log at completion'),
     }),
     outputSchema: z.object({
         id: z.string(),
@@ -531,8 +594,8 @@ server.registerTool('complete_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId, summary }) => {
-    const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary });
+}, 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,
@@ -568,6 +631,65 @@ server.registerTool('abandon_task', {
         structuredContent: result,
     };
 });
+// ==================== Agent Instructions ====================
+// Tool: Get agent instructions
+server.registerTool('get_agent_instructions', {
+    title: 'Get Agent Instructions',
+    description: 'Get the canonical Damper workflow instructions. ' +
+        'Use this to set up or update CLAUDE.md in a project.',
+    inputSchema: z.object({
+        format: z.enum(['markdown', 'section']).optional()
+            .describe('markdown = full file, section = just the Damper section (default: section)'),
+    }),
+    outputSchema: z.object({
+        format: z.enum(['markdown', 'section']),
+        content: z.string(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ format = 'section' }) => {
+    const section = `## Task Management with Damper MCP
+
+This project uses Damper MCP for task tracking. **You MUST follow this workflow.**
+
+### At Session Start (MANDATORY)
+1. \`get_project_context\` - **READ THIS FIRST.** Contains architecture, conventions, and critical project info.
+2. \`get_context_section\` - Fetch full content for sections relevant to your task
+3. \`list_tasks\` - Check for existing tasks to work on
+4. If working on a task: \`start_task\` to lock it
+
+### While Working
+- \`add_commit\` after each commit with hash and message
+- \`add_note\` for decisions: "Decision: chose X because Y"
+- \`update_subtask\` to mark subtask progress
+- **Follow patterns from project context** - Don't reinvent; use existing conventions
+
+### At Session End (MANDATORY)
+- ALWAYS call \`add_note\` with session summary before stopping
+- ALWAYS call \`complete_task\` (if done) or \`abandon_task\` (if stopping early)
+- NEVER leave a started task without completing or abandoning it
+- If you learned something about the codebase, consider updating project context
+
+### Why This Matters
+- **Project context prevents mistakes** - Contains architecture decisions, gotchas, and patterns
+- Locked tasks block other agents from working on them
+- Commits and notes help the next agent continue the work
+- Updating context saves future agents from re-analyzing the codebase`;
+    if (format === 'markdown') {
+        return {
+            content: [{ type: 'text', text: `# CLAUDE.md\n\n${section}` }],
+            structuredContent: { format: 'markdown', content: `# CLAUDE.md\n\n${section}` },
+        };
+    }
+    return {
+        content: [{ type: 'text', text: section }],
+        structuredContent: { format: 'section', content: section },
+    };
+});
 // ==================== Context Tools ====================
 // Tool: List context sections
 server.registerTool('list_context_sections', {
@@ -786,7 +908,9 @@ server.registerTool('sync_project_context', {
 server.registerTool('get_project_context', {
     title: 'Get Project Context',
     description: 'Get project context index (token-efficient). Returns section list with previews. ' +
-        'Use get_context_section to fetch full content for sections you need.',
+        'Use get_context_section to fetch full content for sections you need.\n\n' +
+        '**IMPORTANT:** Call this at session start. Contains architecture, conventions, and ' +
+        'patterns you MUST follow. Skipping this leads to mistakes and inconsistent code.',
     inputSchema: z.object({
         taskId: z.string().optional().describe('If provided, highlights sections relevant to this task'),
     }),

package/package.json

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