@damper/mcp 0.1.2 → 0.1.4

package/README.md

@@ -40,25 +40,73 @@ Damper → Settings → API Keys → Generate
 }
 ```
 
+### Multiple Projects
+
+Each API key is tied to one project. For multiple projects, configure separate server entries:
+
+**Claude Code** (`~/.claude.json`):
+```json
+{
+  "mcpServers": {
+    "damper-frontend": {
+      "command": "damper",
+      "env": { "DAMPER_API_KEY": "dmp_frontend_xxx" }
+    },
+    "damper-backend": {
+      "command": "damper",
+      "env": { "DAMPER_API_KEY": "dmp_backend_xxx" }
+    }
+  }
+}
+```
+
+The AI will see tools from both servers and can distinguish between them:
+- "list tasks from damper-frontend"
+- "start the auth bug in damper-backend"
+
 ## Tools
 
 | Tool | Description |
 |------|-------------|
-| `list_tasks` | Get roadmap tasks |
-| `get_task` | Task details + feedback |
-| `create_task` | Create task (for TODO imports) |
-| `start_task` | Mark in-progress |
+| `list_tasks` | Get roadmap tasks (filter by `status`, `type`) |
+| `get_task` | Task details + linked feedback |
+| `create_task` | Create task with type (bug, feature, improvement, task) |
+| `start_task` | Lock and start task (use `force` to take over) |
 | `add_note` | Add progress note |
-| `complete_task` | Mark done |
+| `complete_task` | Mark done, release lock |
+| `abandon_task` | Release lock, return to planned |
 | `list_feedback` | Browse user feedback |
-| `get_feedback` | Feedback details |
+| `get_feedback` | Feedback details + votes |
+
+### Task Types
+
+Filter tasks by type to prioritize work:
+
+```
+> List all bugs
+> Work on the first feature
+> Show me improvement tasks
+```
+
+Types: `bug` 🐛, `feature` ✨, `improvement` 💡, `task` 📌
+
+### Task Locking
+
+When you start a task, it's locked to prevent other agents from working on it simultaneously:
+
+- Same agent starting again → success (idempotent)
+- Different agent starting → fails with 409 (use `force: true` to take over)
+- Complete or abandon → releases lock
 
-## Usage
+## Usage Examples
 
 ```
 > What tasks are available?
+> List bugs I can fix
 > Import my TODO.md into Damper
-> Work on the dark mode task
+> Work on the dark mode feature
+> I'm done with the auth task - tests pass
+> Abandon the current task, I'm blocked
 ```
 
 ## Environment

package/dist/index.js

@@ -21,6 +21,12 @@ async function api(method, path, body) {
     });
     if (!res.ok) {
         const err = await res.json().catch(() => ({}));
+        // Preserve lock info for 409 conflicts
+        if (res.status === 409 && err.lockedBy) {
+            const lockErr = new Error(err.error || `HTTP ${res.status}`);
+            lockErr.lockInfo = err;
+            throw lockErr;
+        }
         throw new Error(err.error || `HTTP ${res.status}`);
     }
     return res.json();
@@ -34,6 +40,7 @@ const server = new McpServer({
 const TaskSummarySchema = z.object({
     id: z.string(),
     title: z.string(),
+    type: z.string(),
     status: z.string(),
     priority: z.string(),
     feedbackCount: z.number(),
@@ -43,6 +50,7 @@ const TaskDetailSchema = z.object({
     id: z.string(),
     title: z.string(),
     description: z.string().optional(),
+    type: z.string(),
     implementationPlan: z.string().optional(),
     status: z.string(),
     voteScore: z.number(),
@@ -75,9 +83,11 @@ const FeedbackDetailSchema = z.object({
 // Tool: List tasks
 server.registerTool('list_tasks', {
     title: 'List Tasks',
-    description: 'Get roadmap tasks. Returns planned/in-progress by default.',
+    description: 'Get roadmap tasks. Returns planned/in-progress by default. ' +
+        'Filter by type to get bugs, features, etc.',
     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'),
         limit: z.number().optional(),
     }),
     outputSchema: z.object({
@@ -90,23 +100,26 @@ server.registerTool('list_tasks', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ status, limit }) => {
+}, async ({ status, type, limit }) => {
     const params = new URLSearchParams();
     if (status)
         params.set('status', status);
+    if (type)
+        params.set('type', type);
     if (limit)
         params.set('limit', String(limit));
     const query = params.toString();
     const data = await api('GET', `/api/agent/tasks${query ? `?${query}` : ''}`);
     if (!data.tasks.length) {
         return {
-            content: [{ type: 'text', text: `No tasks in "${data.project.name}"` }],
+            content: [{ type: 'text', text: `No tasks in "${data.project.name}"${type ? ` (type: ${type})` : ''}` }],
             structuredContent: { project: data.project.name, tasks: [] },
         };
     }
     const lines = data.tasks.map((t) => {
         const p = t.priority === 'high' ? '🔴' : t.priority === 'medium' ? '🟡' : '⚪';
-        return `• ${t.id}: ${t.title} [${t.status}] ${p}${t.hasImplementationPlan ? ' 📋' : ''}`;
+        const typeIcon = t.type === 'bug' ? '🐛' : t.type === 'feature' ? '✨' : t.type === 'improvement' ? '💡' : '📌';
+        return `• ${t.id}: ${typeIcon} ${t.title} [${t.status}] ${p}${t.hasImplementationPlan ? ' 📋' : ''}`;
     });
     return {
         content: [{ type: 'text', text: `Tasks in "${data.project.name}":\n${lines.join('\n')}` }],
@@ -129,9 +142,10 @@ server.registerTool('get_task', {
     },
 }, async ({ taskId }) => {
     const t = await api('GET', `/api/agent/tasks/${taskId}`);
+    const typeIcon = t.type === 'bug' ? '🐛' : t.type === 'feature' ? '✨' : t.type === 'improvement' ? '💡' : '📌';
     const parts = [
-        `# ${t.title}`,
-        `Status: ${t.status} | Score: ${t.voteScore}`,
+        `# ${typeIcon} ${t.title}`,
+        `Type: ${t.type} | Status: ${t.status} | Score: ${t.voteScore}`,
     ];
     if (t.description)
         parts.push(`\n## Description\n${t.description}`);
@@ -151,16 +165,18 @@ server.registerTool('get_task', {
 // Tool: Create task
 server.registerTool('create_task', {
     title: 'Create Task',
-    description: 'Create a new roadmap task. Use for importing from TODO files.',
+    description: 'Create a new roadmap task. Use for importing from TODO files or creating work items.',
     inputSchema: z.object({
         title: z.string(),
         description: z.string().optional(),
+        type: z.enum(['bug', 'feature', 'improvement', 'task']).optional().describe('Task type (default: feature)'),
         status: z.enum(['planned', 'in_progress']).optional(),
         implementationPlan: z.string().optional(),
     }),
     outputSchema: z.object({
         id: z.string(),
         title: z.string(),
+        type: z.string(),
         status: z.string(),
     }),
     annotations: {
@@ -171,22 +187,27 @@ server.registerTool('create_task', {
     },
 }, async (args) => {
     const result = await api('POST', '/api/agent/tasks', args);
+    const typeIcon = result.type === 'bug' ? '🐛' : result.type === 'feature' ? '✨' : result.type === 'improvement' ? '💡' : '📌';
     return {
-        content: [{ type: 'text', text: `Created: ${result.id} "${result.title}" [${result.status}]` }],
+        content: [{ type: 'text', text: `Created: ${result.id} ${typeIcon} "${result.title}" [${result.status}]` }],
         structuredContent: result,
     };
 });
 // Tool: Start task
 server.registerTool('start_task', {
     title: 'Start Task',
-    description: 'Mark task as in-progress. Call before working on it.',
+    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).',
     inputSchema: z.object({
         taskId: z.string(),
+        force: z.boolean().optional().describe('Take over lock from another agent'),
     }),
     outputSchema: z.object({
         id: z.string(),
         status: z.string(),
         message: z.string(),
+        lockedBy: z.string().optional(),
+        lockedAt: z.string().optional(),
     }),
     annotations: {
         readOnlyHint: false,
@@ -194,12 +215,38 @@ server.registerTool('start_task', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ taskId }) => {
-    const result = await api('POST', `/api/agent/tasks/${taskId}/start`);
-    return {
-        content: [{ type: 'text', text: `Started ${result.id}: ${result.message}` }],
-        structuredContent: result,
-    };
+}, async ({ taskId, force }) => {
+    try {
+        const result = await api('POST', `/api/agent/tasks/${taskId}/start`, force ? { force: true } : undefined);
+        return {
+            content: [{ type: 'text', text: `Started ${result.id}: ${result.message}` }],
+            structuredContent: result,
+        };
+    }
+    catch (err) {
+        const error = err;
+        if (error.lockInfo) {
+            // Return lock info so AI can decide whether to force takeover
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `⚠️ Task is locked by "${error.lockInfo.lockedBy}" since ${error.lockInfo.lockedAt}. ` +
+                            'Use force=true to take over the lock.',
+                    },
+                ],
+                structuredContent: {
+                    id: taskId,
+                    status: 'locked',
+                    message: error.message,
+                    lockedBy: error.lockInfo.lockedBy,
+                    lockedAt: error.lockInfo.lockedAt,
+                },
+                isError: true,
+            };
+        }
+        throw error;
+    }
 });
 // Tool: Add note
 server.registerTool('add_note', {
@@ -251,6 +298,32 @@ server.registerTool('complete_task', {
         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.',
+    inputSchema: z.object({
+        taskId: z.string(),
+    }),
+    outputSchema: z.object({
+        id: z.string(),
+        status: z.string(),
+        message: z.string(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ taskId }) => {
+    const result = await api('POST', `/api/agent/tasks/${taskId}/abandon`);
+    return {
+        content: [{ type: 'text', text: `Abandoned ${result.id}: ${result.message}` }],
+        structuredContent: result,
+    };
+});
 // Tool: List feedback
 server.registerTool('list_feedback', {
     title: 'List Feedback',

package/package.json

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