@damper/mcp 0.1.1

package/README.md

@@ -0,0 +1,73 @@
+# @damper/mcp
+
+MCP server for [Damper](https://usedamper.com) - enables AI agents to manage roadmap tasks.
+
+## Install
+
+```bash
+npm install -g @damper/mcp
+```
+
+## Setup
+
+### 1. Get API Key
+Damper → Settings → API Keys → Generate
+
+### 2. Configure Your AI Agent
+
+**Claude Code** (`~/.claude.json`):
+```json
+{
+  "mcpServers": {
+    "damper": {
+      "command": "damper",
+      "env": { "DAMPER_API_KEY": "dmp_..." }
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "damper": {
+      "command": "npx",
+      "args": ["@damper/mcp"],
+      "env": { "DAMPER_API_KEY": "dmp_..." }
+    }
+  }
+}
+```
+
+## 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 |
+| `add_note` | Add progress note |
+| `complete_task` | Mark done |
+| `list_feedback` | Browse user feedback |
+| `get_feedback` | Feedback details |
+
+## Usage
+
+```
+> What tasks are available?
+> Import my TODO.md into Damper
+> Work on the dark mode task
+```
+
+## Environment
+
+| Variable | Required | Default |
+|----------|----------|---------|
+| `DAMPER_API_KEY` | Yes | - |
+| `DAMPER_API_URL` | No | https://api.usedamper.com |
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { z } from 'zod';
+// Config
+const API_KEY = process.env.DAMPER_API_KEY;
+const API_URL = process.env.DAMPER_API_URL || 'https://api.usedamper.com';
+if (!API_KEY) {
+    console.error('DAMPER_API_KEY required. Get one from Damper → Settings → API Keys');
+    process.exit(1);
+}
+// API Client
+async function api(method, path, body) {
+    const res = await fetch(`${API_URL}${path}`, {
+        method,
+        headers: {
+            Authorization: `Bearer ${API_KEY}`,
+            'Content-Type': 'application/json',
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const err = await res.json().catch(() => ({}));
+        throw new Error(err.error || `HTTP ${res.status}`);
+    }
+    return res.json();
+}
+// Server
+const server = new McpServer({
+    name: 'damper',
+    version: '0.1.0',
+});
+// Tool: List tasks
+server.registerTool('list_tasks', {
+    title: 'List Tasks',
+    description: 'Get roadmap tasks. Returns planned/in-progress by default.',
+    inputSchema: z.object({
+        status: z.enum(['planned', 'in_progress', 'done', 'all']).optional(),
+        limit: z.number().optional(),
+    }),
+}, 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/tasks${query ? `?${query}` : ''}`);
+    if (!data.tasks.length) {
+        return { content: [{ type: 'text', text: `No tasks in "${data.project.name}"` }] };
+    }
+    const lines = data.tasks.map((t) => {
+        const p = t.priority === 'high' ? '🔴' : t.priority === 'medium' ? '🟡' : '⚪';
+        return `• ${t.id}: ${t.title} [${t.status}] ${p}${t.hasImplementationPlan ? ' 📋' : ''}`;
+    });
+    return {
+        content: [{ type: 'text', text: `Tasks in "${data.project.name}":\n${lines.join('\n')}` }],
+    };
+});
+// Tool: Get task
+server.registerTool('get_task', {
+    title: 'Get Task',
+    description: 'Get task details including description, plan, and linked feedback.',
+    inputSchema: z.object({
+        taskId: z.string().describe('Task ID'),
+    }),
+}, async ({ taskId }) => {
+    const t = await api('GET', `/api/agent/tasks/${taskId}`);
+    const parts = [
+        `# ${t.title}`,
+        `Status: ${t.status} | Score: ${t.voteScore}`,
+    ];
+    if (t.description)
+        parts.push(`\n## Description\n${t.description}`);
+    if (t.implementationPlan)
+        parts.push(`\n## Plan\n${t.implementationPlan}`);
+    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)`));
+    }
+    return { content: [{ type: 'text', text: parts.join('\n') }] };
+});
+// Tool: Create task
+server.registerTool('create_task', {
+    title: 'Create Task',
+    description: 'Create a new roadmap task. Use for importing from TODO files.',
+    inputSchema: z.object({
+        title: z.string(),
+        description: z.string().optional(),
+        status: z.enum(['planned', 'in_progress']).optional(),
+        implementationPlan: z.string().optional(),
+    }),
+}, async (args) => {
+    const result = await api('POST', '/api/agent/tasks', args);
+    return {
+        content: [{ type: 'text', text: `Created: ${result.id} "${result.title}" [${result.status}]` }],
+    };
+});
+// Tool: Start task
+server.registerTool('start_task', {
+    title: 'Start Task',
+    description: 'Mark task as in-progress. Call before working on it.',
+    inputSchema: z.object({
+        taskId: z.string(),
+    }),
+}, async ({ taskId }) => {
+    const result = await api('POST', `/api/agent/tasks/${taskId}/start`);
+    return { content: [{ type: 'text', text: `Started ${result.id}: ${result.message}` }] };
+});
+// Tool: Add note
+server.registerTool('add_note', {
+    title: 'Add Note',
+    description: 'Add progress note to task.',
+    inputSchema: z.object({
+        taskId: z.string(),
+        note: z.string(),
+    }),
+}, async ({ taskId, note }) => {
+    await api('POST', `/api/agent/tasks/${taskId}/notes`, { note });
+    return { content: [{ type: 'text', text: `Note added to ${taskId}` }] };
+});
+// Tool: Complete task
+server.registerTool('complete_task', {
+    title: 'Complete Task',
+    description: 'Mark task done with summary.',
+    inputSchema: z.object({
+        taskId: z.string(),
+        summary: z.string().describe('What was implemented'),
+    }),
+}, async ({ taskId, summary }) => {
+    const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary });
+    return { content: [{ type: 'text', text: `Completed ${result.id}` }] };
+});
+// Tool: List feedback
+server.registerTool('list_feedback', {
+    title: 'List Feedback',
+    description: 'Get user feedback. Useful for understanding user needs.',
+    inputSchema: z.object({
+        status: z.enum(['new', 'under_review', 'planned', 'in_progress', 'done', 'closed']).optional(),
+        limit: z.number().optional(),
+    }),
+}, 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/feedback${query ? `?${query}` : ''}`);
+    if (!data.feedback.length) {
+        return { content: [{ type: 'text', text: 'No feedback found' }] };
+    }
+    const lines = data.feedback.map((f) => {
+        const link = f.linkedTaskId ? ` → ${f.linkedTaskId}` : '';
+        return `• ${f.id}: ${f.title} [${f.type}] (${f.voterCount} votes)${link}`;
+    });
+    return { content: [{ type: 'text', text: `Feedback:\n${lines.join('\n')}` }] };
+});
+// Tool: Get feedback
+server.registerTool('get_feedback', {
+    title: 'Get Feedback',
+    description: 'Get feedback details with votes and comments.',
+    inputSchema: z.object({
+        feedbackId: z.string(),
+    }),
+}, async ({ feedbackId }) => {
+    const f = await api('GET', `/api/agent/feedback/${feedbackId}`);
+    const parts = [
+        `# ${f.title}`,
+        `Type: ${f.type} | Status: ${f.status} | Score: ${f.voteScore}`,
+        f.linkedTaskId ? `Linked: ${f.linkedTaskId}` : '',
+        `\n${f.description}`,
+    ].filter(Boolean);
+    if (f.voters.length) {
+        parts.push(`\n## Voters (${f.voters.length})`);
+        f.voters.slice(0, 5).forEach((v) => parts.push(`- ${v.email} (${v.plan})`));
+        if (f.voters.length > 5)
+            parts.push(`... and ${f.voters.length - 5} more`);
+    }
+    if (f.comments.length) {
+        parts.push(`\n## Comments (${f.comments.length})`);
+        f.comments.slice(0, 3).forEach((c) => parts.push(`**${c.author}**: ${c.body}`));
+        if (f.comments.length > 3)
+            parts.push(`... and ${f.comments.length - 3} more`);
+    }
+    return { content: [{ type: 'text', text: parts.join('\n') }] };
+});
+// Start
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((e) => {
+    console.error('Fatal:', e);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@damper/mcp",
+  "version": "0.1.1",
+  "description": "MCP server for Damper task management",
+  "author": "Damper <hello@usedamper.com>",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usedamper/damper.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://usedamper.com",
+  "type": "module",
+  "bin": {
+    "damper": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "bun run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.3.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["mcp", "damper", "ai", "task-management"],
+  "license": "MIT"
+}