@damper/mcp 0.1.12 → 0.2.0

package/README.md

@@ -69,21 +69,45 @@ The AI will see tools from both servers and can distinguish between them:
 
 ## Tools
 
+### Task Management
+
 | Tool | Description |
 |------|-------------|
-| `list_tasks` | Get roadmap tasks (filter by `status`, `type`, `quarter`) |
+| `list_tasks` | Get roadmap tasks (filter by `status`, `type`, `quarter`, sort by `importance`/`newest`/`votes`) |
 | `get_task` | Task details + subtasks + 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) |
+| `start_task` | Lock and start task (use `force` to take over). Returns project context index. |
 | `add_note` | Add progress note |
 | `create_subtask` | Add subtask to a task |
 | `update_subtask` | Mark subtask done/undone |
-| `complete_task` | Mark done, release lock |
+| `complete_task` | Mark done, release lock. Suggests context updates if needed. |
 | `abandon_task` | Release lock, return to planned |
 | `list_feedback` | Browse user feedback |
 | `get_feedback` | Feedback details + votes |
 
+### Project Context
+
+AI agents can store and retrieve project documentation to help future agents work more effectively.
+
+| Tool | Description |
+|------|-------------|
+| `get_project_context` | Get context index with section previews. Optionally highlights sections relevant to a task. |
+| `list_context_sections` | List all available context sections |
+| `get_context_section` | Get full content of a specific section |
+| `update_context_section` | Upload/update a context section (requires user permission) |
+| `sync_project_context` | Bulk upload multiple sections at once (requires user permission) |
+
+**How it works:**
+1. When you `start_task`, you receive a context index showing available documentation
+2. Fetch relevant sections with `get_context_section` to understand the codebase
+3. After completing work, `complete_task` reminds you to update docs if needed
+4. Use `update_context_section` to share knowledge for future agents
+
+**Common sections:** `overview`, `api`, `database`, `services`, `components`, `testing`, `auth`, `deployment`
+
+⚠️ **Security:** Never include sensitive data (API keys, secrets, credentials, connection strings) in context uploads. Users can review and delete context from Settings → AI Context.
+
 ### Task Types
 
 Filter tasks by type to prioritize work:
@@ -96,6 +120,19 @@ Filter tasks by type to prioritize work:
 
 Types: `bug` 🐛, `feature` ✨, `improvement` 💡, `task` 📌
 
+### Sorting
+
+Tasks are sorted by **weighted importance** by default (priority weight + vote score), so high-priority items surface first even without votes. Override with `sort`:
+
+- `importance` (default) - priority weight (high=100, medium=50, low=10) + votes
+- `newest` - most recently created first
+- `votes` - highest vote score first
+
+```
+> List tasks sorted by newest
+> Show me the most voted features
+```
+
 ### Task Metadata
 
 Tasks include project management fields visible in `list_tasks` and `get_task`:
@@ -147,6 +184,7 @@ When you start a task, it's locked to prevent other agents from working on it si
 
 ## Usage Examples
 
+### Tasks
 ```
 > What tasks are available?
 > List bugs I can fix
@@ -160,6 +198,15 @@ When you start a task, it's locked to prevent other agents from working on it si
 > Abandon the current task, I'm blocked
 ```
 
+### Project Context
+```
+> What documentation is available for this project?
+> Get the API context section
+> After analyzing this codebase, upload an overview
+> Update the database section with the new schema
+> Sync all my documentation to Damper
+```
+
 ## Environment
 
 | Variable | Required | Default |

package/dist/index.js

@@ -34,7 +34,7 @@ async function api(method, path, body) {
 // Server
 const server = new McpServer({
     name: 'damper',
-    version: '0.1.11',
+    version: '0.2.0',
 });
 // Output schemas
 const SubtaskProgressSchema = z.object({
@@ -109,6 +109,7 @@ server.registerTool('list_tasks', {
         status: z.enum(['planned', 'in_progress', 'done', 'all']).optional(),
         type: z.enum(['bug', 'feature', 'improvement', 'task']).optional().describe('Filter by task type'),
         quarter: z.string().optional().describe('Filter by quarter (e.g., "Q1 2025") or "none" for unscheduled'),
+        sort: z.enum(['importance', 'newest', 'votes']).optional().describe('Sort order: importance (priority+votes, default), newest, or votes'),
         limit: z.number().optional(),
     }),
     outputSchema: z.object({
@@ -121,7 +122,7 @@ server.registerTool('list_tasks', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ status, type, quarter, limit }) => {
+}, async ({ status, type, quarter, sort, limit }) => {
     const params = new URLSearchParams();
     if (status)
         params.set('status', status);
@@ -129,6 +130,8 @@ server.registerTool('list_tasks', {
         params.set('type', type);
     if (quarter)
         params.set('quarter', quarter);
+    if (sort)
+        params.set('sort', sort);
     if (limit)
         params.set('limit', String(limit));
     const query = params.toString();
@@ -312,11 +315,23 @@ server.registerTool('create_task', {
         structuredContent: result,
     };
 });
+// Context index schema for start_task response
+const ContextIndexSchema = z.object({
+    isEmpty: z.boolean(),
+    index: z.array(z.object({
+        section: z.string(),
+        preview: z.string(),
+        updatedAt: z.string(),
+    })),
+    relevantSections: z.array(z.string()).optional(),
+    hint: z.string().optional(),
+});
 // Tool: Start task
 server.registerTool('start_task', {
     title: '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).',
+        '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.',
     inputSchema: z.object({
         taskId: z.string(),
         force: z.boolean().optional().describe('Take over lock from another agent'),
@@ -327,6 +342,7 @@ server.registerTool('start_task', {
         message: z.string(),
         lockedBy: z.string().optional(),
         lockedAt: z.string().optional(),
+        context: ContextIndexSchema.optional(),
     }),
     annotations: {
         readOnlyHint: false,
@@ -337,8 +353,26 @@ server.registerTool('start_task', {
 }, async ({ taskId, force }) => {
     try {
         const result = await api('POST', `/api/agent/tasks/${taskId}/start`, force ? { force: true } : undefined);
+        // Build response text
+        const lines = [`Started ${result.id}: ${result.message}`];
+        if (result.context) {
+            if (result.context.isEmpty) {
+                lines.push(`\n📚 ${result.context.hint || 'No project context available.'}`);
+            }
+            else {
+                lines.push('\n**Project context available:**');
+                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.');
+                }
+            }
+        }
         return {
-            content: [{ type: 'text', text: `Started ${result.id}: ${result.message}` }],
+            content: [{ type: 'text', text: lines.join('\n') }],
             structuredContent: result,
         };
     }
@@ -463,10 +497,16 @@ server.registerTool('update_subtask', {
         },
     };
 });
+// Documentation reminder schema for complete_task response
+const DocumentationSchema = z.object({
+    hasContext: z.boolean(),
+    affectedSections: z.array(z.string()),
+    reminder: z.string(),
+});
 // Tool: Complete task
 server.registerTool('complete_task', {
     title: 'Complete Task',
-    description: 'Mark task done with summary.',
+    description: 'Mark task done with summary. Returns documentation update suggestions.',
     inputSchema: z.object({
         taskId: z.string(),
         summary: z.string().describe('What was implemented'),
@@ -474,6 +514,7 @@ server.registerTool('complete_task', {
     outputSchema: z.object({
         id: z.string(),
         status: z.string(),
+        documentation: DocumentationSchema.optional(),
     }),
     annotations: {
         readOnlyHint: false,
@@ -483,8 +524,12 @@ server.registerTool('complete_task', {
     },
 }, async ({ taskId, summary }) => {
     const result = await api('POST', `/api/agent/tasks/${taskId}/complete`, { summary });
+    const lines = [`✅ Completed ${result.id}`];
+    if (result.documentation?.reminder) {
+        lines.push(`\n📝 ${result.documentation.reminder}`);
+    }
     return {
-        content: [{ type: 'text', text: `Completed ${result.id}` }],
+        content: [{ type: 'text', text: lines.join('\n') }],
         structuredContent: result,
     };
 });
@@ -514,6 +559,188 @@ server.registerTool('abandon_task', {
         structuredContent: result,
     };
 });
+// ==================== Context Tools ====================
+// Tool: List context sections
+server.registerTool('list_context_sections', {
+    title: 'List Context Sections',
+    description: 'List available project context sections with brief previews.',
+    inputSchema: z.object({}),
+    outputSchema: z.object({
+        sections: z.array(z.object({
+            section: z.string(),
+            updatedAt: z.string(),
+            source: z.string(),
+            preview: z.string(),
+        })),
+        isEmpty: z.boolean(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async () => {
+    const data = await api('GET', '/api/agent/context');
+    if (data.isEmpty) {
+        return {
+            content: [{ type: 'text', text: 'No project context available. Use sync_project_context to upload documentation.' }],
+            structuredContent: data,
+        };
+    }
+    const lines = data.sections.map((s) => `• ${s.section} (${s.source}, updated ${s.updatedAt.split('T')[0]})`);
+    return {
+        content: [{ type: 'text', text: `Context sections:\n${lines.join('\n')}` }],
+        structuredContent: data,
+    };
+});
+// Tool: Get context section
+server.registerTool('get_context_section', {
+    title: 'Get Context Section',
+    description: 'Get full content of a specific context section.',
+    inputSchema: z.object({
+        section: z.string().describe('Section name (e.g., "overview", "api", "database")'),
+    }),
+    outputSchema: z.object({
+        section: z.string(),
+        content: z.string(),
+        updatedAt: z.string(),
+        source: z.string(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ section }) => {
+    const data = await api('GET', `/api/agent/context/${section}`);
+    return {
+        content: [{ type: 'text', text: `# ${data.section}\n\n${data.content}` }],
+        structuredContent: data,
+    };
+});
+// Tool: Update context section
+server.registerTool('update_context_section', {
+    title: 'Update Context Section',
+    description: 'Upload/update a project context section. Use after analyzing local codebase. ' +
+        'This action shares documentation with the Damper project for future AI agents.\n\n' +
+        '⚠️ SECURITY WARNING: Do NOT include sensitive information:\n' +
+        '- API keys, secrets, passwords, tokens\n' +
+        '- Database connection strings\n' +
+        '- Private endpoints or internal URLs\n' +
+        '- Customer data or PII\n' +
+        '- .env file contents or credentials',
+    inputSchema: z.object({
+        section: z.string()
+            .regex(/^[a-z][a-z0-9-]{0,49}$/)
+            .describe('Section name (lowercase, alphanumeric, hyphens). Examples: overview, database, api, services, components, testing, conventions, deployment'),
+        content: z.string().describe('Markdown documentation for this section. Must NOT contain secrets, API keys, or sensitive data.'),
+    }),
+    outputSchema: z.object({
+        success: z.boolean(),
+        section: z.string(),
+        warnings: z.array(z.string()).optional(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ section, content }) => {
+    const result = await api('POST', `/api/agent/context/${section}`, { content });
+    let text = `📝 Updated context section: ${result.section}`;
+    if (result.warnings && result.warnings.length > 0) {
+        text += `\n⚠️ Warnings: ${result.warnings.join(', ')}`;
+    }
+    return {
+        content: [{ type: 'text', text }],
+        structuredContent: result,
+    };
+});
+// Tool: Sync project context (bulk upload)
+server.registerTool('sync_project_context', {
+    title: 'Sync Project Context',
+    description: 'Bulk upload all project context sections at once. Use after analyzing a codebase. ' +
+        'This action shares documentation with the Damper project for future AI agents.\n\n' +
+        '⚠️ SECURITY WARNING: Do NOT include sensitive information:\n' +
+        '- API keys, secrets, passwords, tokens\n' +
+        '- Database connection strings\n' +
+        '- Private endpoints or internal URLs\n' +
+        '- Customer data or PII\n' +
+        '- .env file contents or credentials',
+    inputSchema: z.object({
+        sections: z.array(z.object({
+            section: z.string()
+                .regex(/^[a-z][a-z0-9-]{0,49}$/)
+                .describe('Section name'),
+            content: z.string().describe('Markdown documentation (no secrets!)'),
+        })).describe('Array of sections to upload'),
+    }),
+    outputSchema: z.object({
+        success: z.boolean(),
+        sectionsUpdated: z.number(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ sections }) => {
+    const result = await api('POST', '/api/agent/context/sync', { sections });
+    return {
+        content: [{ type: 'text', text: `📚 Synced ${result.sectionsUpdated} context sections` }],
+        structuredContent: result,
+    };
+});
+// Tool: Get project context (token-efficient index)
+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.',
+    inputSchema: z.object({
+        taskId: z.string().optional().describe('If provided, highlights sections relevant to this task'),
+    }),
+    outputSchema: z.object({
+        isEmpty: z.boolean(),
+        index: z.array(z.object({
+            section: z.string(),
+            preview: z.string(),
+            updatedAt: z.string(),
+        })),
+        relevantSections: z.array(z.string()).optional(),
+        hint: z.string().optional(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ taskId }) => {
+    const params = taskId ? `?task_id=${taskId}` : '';
+    const data = await api('GET', `/api/agent/context/index${params}`);
+    if (data.isEmpty) {
+        return {
+            content: [{ type: 'text', text: data.hint || 'No project context available.' }],
+            structuredContent: data,
+        };
+    }
+    const lines = ['**Available context sections:**'];
+    for (const s of data.index) {
+        const relevant = data.relevantSections?.includes(s.section) ? ' ⭐' : '';
+        lines.push(`• ${s.section}${relevant} - ${s.preview}`);
+    }
+    if (data.relevantSections && data.relevantSections.length > 0) {
+        lines.push(`\n**Relevant for this task:** ${data.relevantSections.join(', ')}`);
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: data,
+    };
+});
 // Tool: List feedback
 server.registerTool('list_feedback', {
     title: 'List Feedback',

package/package.json

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