@damper/mcp 0.3.9 → 0.3.11

package/README.md

@@ -94,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
 
@@ -332,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:

package/dist/index.js

@@ -631,6 +631,77 @@ 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(),
+        lastModified: z.string().describe('ISO date when instructions were last updated'),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ format = 'section' }) => {
+    const lastModified = '2025-02-04';
+    const section = `## Task Management with Damper MCP
+
+> Last updated: ${lastModified}
+
+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
+
+### Feedback & Changelog Integration
+- \`link_feedback_to_task\` - Link user feedback IDs to your task (helps track what customer requests led to the feature)
+- When completing a **public** task, it auto-adds to the project's draft changelog
+- \`list_changelogs\` - View existing changelogs and drafts
+- \`create_changelog\` / \`update_changelog\` - Create or edit changelog entries
+- \`add_to_changelog\` - Manually add completed tasks to a changelog
+
+### 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
+- Linking feedback connects customer requests to shipped features`;
+    if (format === 'markdown') {
+        return {
+            content: [{ type: 'text', text: `# CLAUDE.md\n\n${section}` }],
+            structuredContent: { format: 'markdown', content: `# CLAUDE.md\n\n${section}`, lastModified },
+        };
+    }
+    return {
+        content: [{ type: 'text', text: section }],
+        structuredContent: { format: 'section', content: section, lastModified },
+    };
+});
 // ==================== Context Tools ====================
 // Tool: List context sections
 server.registerTool('list_context_sections', {
@@ -1307,6 +1378,205 @@ server.registerTool('sync_modules', {
         structuredContent: result,
     };
 });
+// ==================== Changelog Tools ====================
+// Tool: Link feedback to task
+server.registerTool('link_feedback_to_task', {
+    title: 'Link Feedback to Task',
+    description: 'Link feedback items to a roadmap task. Links the specified feedback IDs to the task.\n\n' +
+        '**When to use:**\n' +
+        '- After seeing relevant feedback in `list_feedback`\n' +
+        '- When user mentions feedback that should be tracked with a task',
+    inputSchema: z.object({
+        taskId: z.string().describe('Task ID to link feedback to'),
+        feedbackIds: z.array(z.string()).describe('Feedback IDs to link'),
+    }),
+    outputSchema: z.object({
+        taskId: z.string(),
+        linkedFeedbackIds: z.array(z.string()),
+        totalLinkedFeedback: z.number(),
+        feedbackTitles: z.array(z.string()),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ taskId, feedbackIds }) => {
+    const result = await api('POST', `/api/agent/tasks/${taskId}/feedback`, { feedbackIds });
+    const linkedCount = result.linkedFeedbackIds.length;
+    if (linkedCount === 0) {
+        return {
+            content: [{ type: 'text', text: `No new feedback linked (already linked or not found)` }],
+            structuredContent: result,
+        };
+    }
+    return {
+        content: [{ type: 'text', text: `🔗 Linked ${linkedCount} feedback to task: ${result.feedbackTitles.join(', ')}` }],
+        structuredContent: result,
+    };
+});
+// Tool: List changelogs
+server.registerTool('list_changelogs', {
+    title: 'List Changelogs',
+    description: 'List changelogs for the project. Filter by status (draft, published).\n\n' +
+        '**Draft changelogs:** Automatically created when completing public roadmap items. ' +
+        'Review and publish them to announce releases.',
+    inputSchema: z.object({
+        status: z.enum(['draft', 'published']).optional().describe('Filter by status'),
+        limit: z.number().optional(),
+    }),
+    outputSchema: z.object({
+        changelogs: z.array(z.object({
+            id: z.string(),
+            title: z.string(),
+            version: z.string().nullable().optional(),
+            status: z.string(),
+            publishedAt: z.string().nullable().optional(),
+            roadmapItemCount: z.number(),
+            contentPreview: z.string(),
+        })),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ status, limit }) => {
+    const params = new URLSearchParams();
+    if (status)
+        params.set('status', status);
+    if (limit)
+        params.set('limit', String(limit));
+    const query = params.toString();
+    const data = await api('GET', `/api/agent/changelogs${query ? `?${query}` : ''}`);
+    if (!data.changelogs.length) {
+        return {
+            content: [{ type: 'text', text: 'No changelogs found' }],
+            structuredContent: { changelogs: [] },
+        };
+    }
+    const lines = data.changelogs.map((c) => {
+        const status = c.status === 'draft' ? '📝' : '✅';
+        const version = c.version ? ` v${c.version}` : '';
+        const items = c.roadmapItemCount > 0 ? ` (${c.roadmapItemCount} items)` : '';
+        return `• ${c.id}: ${status} ${c.title}${version}${items}`;
+    });
+    return {
+        content: [{ type: 'text', text: `Changelogs:\n${lines.join('\n')}` }],
+        structuredContent: data,
+    };
+});
+// Tool: Create changelog
+server.registerTool('create_changelog', {
+    title: 'Create Changelog',
+    description: 'Create a new changelog entry. Usually starts as draft.\n\n' +
+        '**Note:** Draft changelogs are auto-created when completing public roadmap items. ' +
+        'Use this to create additional changelogs if needed.',
+    inputSchema: z.object({
+        title: z.string().describe('Changelog title (e.g., "v2.1.0" or "January 2025 Release")'),
+        content: z.string().optional().describe('Initial changelog content (markdown)'),
+        version: z.string().optional().describe('Version number'),
+        status: z.enum(['draft', 'published']).optional().describe('Status (default: draft)'),
+    }),
+    outputSchema: z.object({
+        id: z.string(),
+        title: z.string(),
+        version: z.string().nullable().optional(),
+        status: z.string(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
+}, async (args) => {
+    const result = await api('POST', '/api/agent/changelogs', args);
+    const status = result.status === 'draft' ? '📝' : '✅';
+    return {
+        content: [{ type: 'text', text: `${status} Created changelog: ${result.id} "${result.title}"` }],
+        structuredContent: result,
+    };
+});
+// Tool: Update changelog
+server.registerTool('update_changelog', {
+    title: 'Update Changelog',
+    description: 'Update a changelog entry. Can update title, content, version, or status.\n\n' +
+        '**Publishing:** Set status to "published" to make the changelog public.',
+    inputSchema: z.object({
+        changelogId: z.string().describe('Changelog ID'),
+        title: z.string().optional().describe('New title'),
+        content: z.string().optional().describe('New content (markdown)'),
+        version: z.string().optional().describe('Version number'),
+        status: z.enum(['draft', 'published']).optional().describe('Status'),
+    }),
+    outputSchema: z.object({
+        id: z.string(),
+        title: z.string(),
+        version: z.string().nullable().optional(),
+        status: z.string(),
+        publishedAt: z.string().nullable().optional(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ changelogId, title, content, version, status }) => {
+    const body = {};
+    if (title !== undefined)
+        body.title = title;
+    if (content !== undefined)
+        body.content = content;
+    if (version !== undefined)
+        body.version = version;
+    if (status !== undefined)
+        body.status = status;
+    const result = await api('PATCH', `/api/agent/changelogs/${changelogId}`, body);
+    const statusIcon = result.status === 'published' ? '✅' : '📝';
+    const published = result.status === 'published' && result.publishedAt ? ' (just published)' : '';
+    return {
+        content: [{ type: 'text', text: `${statusIcon} Updated changelog: "${result.title}"${published}` }],
+        structuredContent: result,
+    };
+});
+// Tool: Add roadmap items to changelog
+server.registerTool('add_to_changelog', {
+    title: 'Add to Changelog',
+    description: 'Add completed roadmap items to a changelog. Links the items and appends formatted entries to content.\n\n' +
+        '**When to use:**\n' +
+        '- After completing multiple items that should be in one release\n' +
+        '- To manually add items to a draft changelog',
+    inputSchema: z.object({
+        changelogId: z.string().describe('Changelog ID'),
+        roadmapItemIds: z.array(z.string()).describe('Roadmap item IDs to add'),
+    }),
+    outputSchema: z.object({
+        id: z.string(),
+        title: z.string(),
+        roadmapItemCount: z.number(),
+        addedItems: z.array(z.object({
+            id: z.string(),
+            title: z.string(),
+        })),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ changelogId, roadmapItemIds }) => {
+    const result = await api('POST', `/api/agent/changelogs/${changelogId}/items`, { roadmapItemIds });
+    const addedTitles = result.addedItems.map((i) => i.title).join(', ');
+    return {
+        content: [{ type: 'text', text: `📋 Added ${result.addedItems.length} items to "${result.title}": ${addedTitles}` }],
+        structuredContent: result,
+    };
+});
 // Start
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

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