@damper/mcp 0.3.14 → 0.3.16

package/dist/formatters.d.ts

@@ -17,6 +17,7 @@ export interface StartTaskResult {
         }>;
         relevantSections?: string[];
         hint?: string;
+        criticalRules?: string[];
     };
 }
 export interface CompleteTaskResult {

package/dist/formatters.js

@@ -9,22 +9,29 @@
  */
 export function formatStartTaskResponse(result) {
     const lines = [`✅ Started ${result.id}: ${result.message}`];
+    // Critical rules section - shown first and prominently
+    if (result.context?.criticalRules && result.context.criticalRules.length > 0) {
+        lines.push('\n🚨 **CRITICAL RULES (do not skip):**');
+        for (const rule of result.context.criticalRules) {
+            lines.push(`• ${rule}`);
+        }
+    }
     // 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⚠️ **BEFORE YOU START:** Read project context to understand patterns and conventions.');
+            lines.push('\n📚 **Project context available.** Read sections relevant to your task:');
             lines.push('');
             if (result.context.relevantSections && result.context.relevantSections.length > 0) {
-                lines.push(`**Required reading for this task:**`);
+                lines.push(`**Suggested for this task:**`);
                 for (const section of result.context.relevantSections) {
                     lines.push(`→ \`get_context_section("${section}")\``);
                 }
                 lines.push('');
             }
-            lines.push('**All available sections:**');
+            lines.push('**All sections:**');
             for (const s of result.context.index) {
                 const relevant = result.context.relevantSections?.includes(s.section) ? ' ⭐' : '';
                 lines.push(`• ${s.section}${relevant}`);
@@ -32,12 +39,11 @@ export function formatStartTaskResponse(result) {
         }
     }
     lines.push('\n---');
-    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)');
+    lines.push('**📋 Workflow:**');
+    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`');
     return lines.join('\n');
 }
 /**

package/dist/index.js

@@ -360,6 +360,7 @@ const ContextIndexSchema = z.object({
     })),
     relevantSections: z.array(z.string()).optional(),
     hint: z.string().optional(),
+    criticalRules: z.array(z.string()).optional(),
 });
 // Tool: Start task
 server.registerTool('start_task', {
@@ -371,10 +372,8 @@ server.registerTool('start_task', {
         'Project context contains architecture and patterns you MUST follow.\n\n' +
         '**Workflow after starting:**\n' +
         '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)',
+        '2. Do work, log commits with add_commit\n' +
+        '3. complete_task (done) or abandon_task (stopping)',
     inputSchema: z.object({
         taskId: z.string(),
         force: z.boolean().optional().describe('Take over lock from another agent'),
@@ -429,13 +428,11 @@ server.registerTool('start_task', {
 // Tool: Add note
 server.registerTool('add_note', {
     title: 'Add Note',
-    description: 'Add progress note to task. Notes help future agents continue your work.\n\n' +
+    description: 'Add a note to a task. Use ONLY for non-obvious approach decisions and blockers.\n\n' +
         '**When to use:**\n' +
-        '- Session start: "Session started: implementing X"\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.',
+        '- Blockers: "Blocked: X needs Y before we can proceed"\n\n' +
+        '**Do NOT use for:** Session start/end ceremony, commit logging (use `add_commit`), or restating what code changes do.',
     inputSchema: z.object({
         taskId: z.string(),
         note: z.string(),
@@ -568,16 +565,15 @@ const DocumentationSchema = z.object({
 // Tool: Complete task
 server.registerTool('complete_task', {
     title: 'Complete Task',
-    description: 'Mark task done with summary. Optionally log final commits at completion.\n\n' +
+    description: 'Mark task done with a brief one-line 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' +
+        '2. 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'),
+        summary: z.string().describe('Brief one-line summary of what was done'),
         commits: z.array(z.object({
             hash: z.string().describe('Commit hash (short or full)'),
             message: z.string().describe('Commit message'),
@@ -606,8 +602,7 @@ server.registerTool('abandon_task', {
     title: 'Abandon Task',
     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' +
+        '1. Push any WIP commits\n\n' +
         '**Summary parameter:** What was done, what remains, blockers. Helps the next agent.',
     inputSchema: z.object({
         taskId: z.string(),
@@ -653,7 +648,7 @@ server.registerTool('get_agent_instructions', {
         openWorldHint: false,
     },
 }, async ({ format = 'section' }) => {
-    const lastModified = '2025-02-04';
+    const lastModified = '2025-02-05';
     const section = `## Task Management with Damper MCP
 
 > Last updated: ${lastModified}
@@ -662,7 +657,10 @@ 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
+2. Load relevant architecture context using blocks (token-efficient):
+   - If TASK_CONTEXT.md has an "Available Architecture Context" section, use \`get_section_block_content(section, blockIds)\` to load only the blocks relevant to your task
+   - Otherwise, use \`get_section_blocks(section)\` to see what's available, then fetch specific blocks
+   - Only fall back to \`get_context_section\` if you need an entire section
 3. \`list_tasks\` - Check for existing tasks to work on
 4. If working on a task: \`start_task\` to lock it
 
@@ -671,16 +669,17 @@ This project uses Damper MCP for task tracking. **You MUST follow this workflow.
 - \`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
+- When you need architecture context mid-task, use \`get_section_block_content\` to load specific blocks rather than full sections
 
 ### 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
+- \`create_changelog\` / \`update_changelog\` - Create or edit changelog entries (use \`summary\` for social-friendly posts)
 - \`add_to_changelog\` - Manually add completed tasks to a changelog
+- \`publish_changelog\` - Publish with optional email notifications and Twitter posting
 
 ### 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
@@ -813,6 +812,10 @@ server.registerTool('update_context_section', {
         'names like `overview`, `conventions` are sufficient.\n\n' +
         '**When to add tags**: Only if you have multiple related sections that should surface ' +
         'together (e.g., all "backend" docs). Skip for simple projects.\n\n' +
+        '**criticalRules**: Short, actionable rules that agents MUST follow. These are surfaced ' +
+        'automatically in `start_task` and `get_project_context` responses without requiring ' +
+        'agents to read the full section. Use for rules that, if skipped, cause real problems ' +
+        '(e.g., "Use migrations for DB changes: bunx prisma migrate dev --name <feature>").\n\n' +
         '⚠️ SECURITY WARNING: Do NOT include sensitive information:\n' +
         '- API keys, secrets, passwords, tokens\n' +
         '- Database connection strings\n' +
@@ -826,12 +829,14 @@ server.registerTool('update_context_section', {
         content: z.string().describe('Markdown documentation for this section. Must NOT contain secrets, API keys, or sensitive data.'),
         tags: z.array(z.string()).optional().describe('Categorization tags (e.g., ["backend", "critical"]). Helps match sections to task labels.'),
         appliesTo: z.array(z.string()).optional().describe('Module names this section applies to (e.g., ["server", "dashboard"]).'),
+        criticalRules: z.array(z.string()).optional().describe('Must-follow rules shown in start_task/get_project_context (e.g., ["Use migrations: bunx prisma migrate dev --name <feature>"])'),
     }),
     outputSchema: z.object({
         success: z.boolean(),
         section: z.string(),
         tags: z.array(z.string()).optional(),
         appliesTo: z.array(z.string()).optional(),
+        criticalRules: z.array(z.string()).optional(),
         warnings: z.array(z.string()).optional(),
     }),
     annotations: {
@@ -840,13 +845,13 @@ server.registerTool('update_context_section', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ section, content, tags, appliesTo }) => {
+}, async ({ section, content, tags, appliesTo, criticalRules }) => {
     // Encode each path segment individually but preserve slashes for hierarchical sections
     const encodedSection = section
         .split('/')
         .map(part => encodeURIComponent(part))
         .join('/');
-    const result = await api('POST', `/api/agent/context/${encodedSection}`, { content, tags, appliesTo });
+    const result = await api('POST', `/api/agent/context/${encodedSection}`, { content, tags, appliesTo, criticalRules });
     let text = `📝 Updated context section: ${result.section}`;
     if (result.tags && result.tags.length > 0) {
         text += ` [${result.tags.join(', ')}]`;
@@ -909,6 +914,7 @@ server.registerTool('sync_project_context', {
             content: z.string().describe('Markdown documentation (no secrets!)'),
             tags: z.array(z.string()).optional().describe('Categorization tags'),
             appliesTo: z.array(z.string()).optional().describe('Module names this applies to'),
+            criticalRules: z.array(z.string()).optional().describe('Must-follow rules shown automatically'),
         })).describe('Array of sections to upload'),
     }),
     outputSchema: z.object({
@@ -949,6 +955,7 @@ server.registerTool('get_project_context', {
         })),
         relevantSections: z.array(z.string()).optional(),
         hint: z.string().optional(),
+        criticalRules: z.array(z.string()).optional(),
     }),
     annotations: {
         readOnlyHint: true,
@@ -965,7 +972,16 @@ server.registerTool('get_project_context', {
             structuredContent: data,
         };
     }
-    const lines = ['**Available context sections:**'];
+    const lines = [];
+    // Critical rules first - most important
+    if (data.criticalRules && data.criticalRules.length > 0) {
+        lines.push('🚨 **CRITICAL RULES (do not skip):**');
+        for (const rule of data.criticalRules) {
+            lines.push(`• ${rule}`);
+        }
+        lines.push('');
+    }
+    lines.push('**Available context sections:**');
     for (const s of data.index) {
         const relevant = data.relevantSections?.includes(s.section) ? ' ⭐' : '';
         const tags = s.tags && s.tags.length > 0 ? ` [${s.tags.join(', ')}]` : '';
@@ -979,6 +995,91 @@ server.registerTool('get_project_context', {
         structuredContent: data,
     };
 });
+// Tool: Get section blocks (heading index)
+server.registerTool('get_section_blocks', {
+    title: 'Get Section Blocks',
+    description: 'Get a block index for a context section. Returns a list of headings (## and ###) with their ' +
+        'character counts, without the full content. Use this to see what\'s in a section and then ' +
+        'fetch only the blocks you need with `get_section_block_content`.\n\n' +
+        '**When to use:**\n' +
+        '- Before fetching a large section, check what blocks it contains\n' +
+        '- To selectively load only relevant parts of a section\n' +
+        '- To reduce token usage by skipping irrelevant subsections',
+    inputSchema: z.object({
+        section: z.string().describe('Section name (e.g., "api", "testing")'),
+    }),
+    outputSchema: z.object({
+        section: z.string(),
+        blocks: z.array(z.object({
+            id: z.string(),
+            heading: z.string().nullable(),
+            level: z.number(),
+            charCount: z.number(),
+        })),
+        totalChars: z.number(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ section }) => {
+    const encodedSection = encodeURIComponent(section);
+    const data = await api('GET', `/api/agent/context/${encodedSection}/blocks`);
+    const lines = [`**Blocks in "${data.section}"** (${data.totalChars} chars total):\n`];
+    for (const block of data.blocks) {
+        const heading = block.heading || '(intro)';
+        lines.push(`• ${block.id}: ${heading} (${block.charCount} chars)`);
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: data,
+    };
+});
+// Tool: Get section block content
+server.registerTool('get_section_block_content', {
+    title: 'Get Section Block Content',
+    description: 'Get the full content of specific blocks within a section. Use `get_section_blocks` first ' +
+        'to see available block IDs, then fetch only the ones you need.\n\n' +
+        '**Example workflow:**\n' +
+        '1. `get_section_blocks("api")` → see list of blocks\n' +
+        '2. `get_section_block_content("api", ["authentication", "agent-endpoints"])` → get only relevant blocks',
+    inputSchema: z.object({
+        section: z.string().describe('Section name (e.g., "api", "testing")'),
+        blockIds: z.array(z.string()).describe('Block IDs to fetch (from get_section_blocks)'),
+    }),
+    outputSchema: z.object({
+        section: z.string(),
+        blocks: z.array(z.object({
+            id: z.string(),
+            heading: z.string().nullable(),
+            level: z.number(),
+            content: z.string(),
+            charCount: z.number(),
+        })),
+        totalChars: z.number(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ section, blockIds }) => {
+    const encodedSection = encodeURIComponent(section);
+    const encodedBlockIds = blockIds.map(id => encodeURIComponent(id)).join(',');
+    const data = await api('GET', `/api/agent/context/${encodedSection}/blocks/${encodedBlockIds}`);
+    const lines = [];
+    for (const block of data.blocks) {
+        lines.push(block.content);
+        lines.push('');
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n').trim() }],
+        structuredContent: data,
+    };
+});
 // Tool: List feedback
 server.registerTool('list_feedback', {
     title: 'List Feedback',
@@ -1490,6 +1591,7 @@ server.registerTool('create_changelog', {
         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'),
+        summary: z.string().max(280).optional().describe('Short summary for social sharing and email subject (max 280 chars)'),
         status: z.enum(['draft', 'published']).optional().describe('Status (default: draft)'),
     }),
     outputSchema: z.object({
@@ -1515,13 +1617,14 @@ server.registerTool('create_changelog', {
 // 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.',
+    description: 'Update a changelog entry. Can update title, content, version, summary, or status.\n\n' +
+        '**Publishing:** Use `publish_changelog` instead to publish with email and Twitter options.',
     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'),
+        summary: z.string().max(280).optional().describe('Short summary for social sharing and email subject (max 280 chars)'),
         status: z.enum(['draft', 'published']).optional().describe('Status'),
     }),
     outputSchema: z.object({
@@ -1589,6 +1692,80 @@ server.registerTool('add_to_changelog', {
         structuredContent: result,
     };
 });
+// Tool: Publish changelog
+server.registerTool('publish_changelog', {
+    title: 'Publish Changelog',
+    description: 'Publish a changelog with optional email and Twitter notifications.\n\n' +
+        '**Options:**\n' +
+        '- `sendEmail`: Send to subscribers who opted in (default: true if subscribers exist)\n' +
+        '- `postToTwitter`: Post to connected Twitter account (default: false)\n' +
+        '- `summary`: Short text for email subject and tweet (max 280 chars)\n\n' +
+        '**Example workflow:**\n' +
+        '1. Review draft with `list_changelogs`\n' +
+        '2. Update content with `update_changelog` if needed\n' +
+        '3. Publish with `publish_changelog` and notification options',
+    inputSchema: z.object({
+        changelogId: z.string().describe('Changelog ID to publish'),
+        title: z.string().optional().describe('Update title before publishing'),
+        version: z.string().optional().describe('Set version before publishing'),
+        summary: z.string().max(280).optional().describe('Summary for email subject and tweet (max 280 chars)'),
+        sendEmail: z.boolean().optional().describe('Send email to subscribers (default: true if subscribers exist)'),
+        postToTwitter: z.boolean().optional().describe('Post to Twitter if connected (default: false)'),
+    }),
+    outputSchema: z.object({
+        id: z.string(),
+        title: z.string(),
+        publishedAt: z.string(),
+        emailsSent: z.number().optional(),
+        twitterPost: z.object({
+            success: z.boolean(),
+            postUrl: z.string().optional(),
+            error: z.string().optional(),
+        }).optional(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: false,
+        openWorldHint: false,
+    },
+}, async ({ changelogId, title, version, summary, sendEmail, postToTwitter }) => {
+    const body = {};
+    if (title !== undefined)
+        body.title = title;
+    if (version !== undefined)
+        body.version = version;
+    if (summary !== undefined)
+        body.summary = summary;
+    if (sendEmail !== undefined)
+        body.sendEmail = sendEmail;
+    if (postToTwitter !== undefined)
+        body.postToTwitter = postToTwitter;
+    const result = await api('POST', `/api/agent/changelogs/${changelogId}/publish`, body);
+    // Build response message
+    const parts = [`✅ Published "${result.title}"`];
+    if (result.emailsSent && result.emailsSent > 0) {
+        parts.push(`📧 ${result.emailsSent} email${result.emailsSent !== 1 ? 's' : ''} sent`);
+    }
+    if (result.twitterPost) {
+        if (result.twitterPost.success && result.twitterPost.postUrl) {
+            parts.push(`🐦 Posted to Twitter: ${result.twitterPost.postUrl}`);
+        }
+        else if (!result.twitterPost.success && result.twitterPost.error) {
+            parts.push(`⚠️ Twitter failed: ${result.twitterPost.error}`);
+        }
+    }
+    return {
+        content: [{ type: 'text', text: parts.join('\n') }],
+        structuredContent: {
+            id: result.id,
+            title: result.title,
+            publishedAt: result.publishedAt,
+            emailsSent: result.emailsSent,
+            twitterPost: result.twitterPost,
+        },
+    };
+});
 // Start
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

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