@damper/mcp 0.2.0 → 0.3.0

package/README.md

@@ -85,6 +85,14 @@ The AI will see tools from both servers and can distinguish between them:
 | `abandon_task` | Release lock, return to planned |
 | `list_feedback` | Browse user feedback |
 | `get_feedback` | Feedback details + votes |
+| `list_templates` | List available code templates |
+| `get_template` | Get template content |
+| `update_template` | Create/update a template |
+| `sync_templates` | Bulk upload templates |
+| `list_modules` | List monorepo modules |
+| `get_module` | Get module details |
+| `update_module` | Register/update a module |
+| `sync_modules` | Bulk upload module registry |
 
 ### Project Context
 
@@ -94,8 +102,8 @@ AI agents can store and retrieve project documentation to help future agents wor
 |------|-------------|
 | `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) |
+| `get_context_section` | Get full content of a specific section. Supports glob patterns (`api/*`, `api/**`). |
+| `update_context_section` | Upload/update a context section with optional tags (requires user permission) |
 | `sync_project_context` | Bulk upload multiple sections at once (requires user permission) |
 
 **How it works:**
@@ -108,6 +116,75 @@ AI agents can store and retrieve project documentation to help future agents wor
 
 ⚠️ **Security:** Never include sensitive data (API keys, secrets, credentials, connection strings) in context uploads. Users can review and delete context from Settings → AI Context.
 
+### Hierarchical Sections
+
+For monorepos or large projects, organize sections hierarchically:
+
+```
+> Update the api/architecture section
+> Get all api sections: api/**
+> Get direct children only: api/*
+```
+
+**When to use**: When a project has many related sections that benefit from organization (e.g., `api/architecture`, `api/endpoints`, `api/testing`).
+
+**When to skip**: For simple projects, flat section names like `overview`, `api`, `testing` are sufficient.
+
+### Section Tags
+
+Add tags to sections for better automatic matching with task labels:
+
+```
+> Update api section with tags: backend, critical
+> Sections tagged "backend" will auto-surface for tasks labeled "backend"
+```
+
+**When to use**: When you have multiple related sections that should surface together (e.g., all docs tagged "backend" for backend tasks).
+
+**When to skip**: For simple projects with few sections. Tags add complexity without much benefit.
+
+### Code Templates
+
+Store and retrieve code templates for maintaining consistency.
+
+| Tool | Description |
+|------|-------------|
+| `list_templates` | List available templates with previews |
+| `get_template` | Get full template content |
+| `update_template` | Create/update a template |
+| `sync_templates` | Bulk upload templates |
+
+```
+> List available templates
+> Get the service-module template
+> Create a template for API controllers
+```
+
+**When to use**: Check for templates before creating new service files, components, or test files. If you notice repetitive patterns, extract them into templates.
+
+**When to skip**: If the project doesn't have templates defined, create files using patterns you observe in the existing codebase.
+
+### Module Registry
+
+Track monorepo package structure for better cross-package awareness.
+
+| Tool | Description |
+|------|-------------|
+| `list_modules` | List registered modules with paths and ports |
+| `get_module` | Get module details including dependencies |
+| `update_module` | Register/update a module |
+| `sync_modules` | Bulk upload module registry |
+
+```
+> List all modules in this monorepo
+> What port does the dashboard run on?
+> Register the new shared package
+```
+
+**When to use**: For monorepos with multiple packages. Helps understand package structure and dependencies before making cross-package changes.
+
+**When to skip**: For single-package projects, the module registry isn't needed.
+
 ### Task Types
 
 Filter tasks by type to prioritize work:

package/dist/index.js

@@ -34,7 +34,7 @@ async function api(method, path, body) {
 // Server
 const server = new McpServer({
     name: 'damper',
-    version: '0.2.0',
+    version: '0.3.0',
 });
 // Output schemas
 const SubtaskProgressSchema = z.object({
@@ -571,6 +571,8 @@ server.registerTool('list_context_sections', {
             updatedAt: z.string(),
             source: z.string(),
             preview: z.string(),
+            tags: z.array(z.string()).optional(),
+            appliesTo: z.array(z.string()).optional(),
         })),
         isEmpty: z.boolean(),
     }),
@@ -588,7 +590,10 @@ server.registerTool('list_context_sections', {
             structuredContent: data,
         };
     }
-    const lines = data.sections.map((s) => `• ${s.section} (${s.source}, updated ${s.updatedAt.split('T')[0]})`);
+    const lines = data.sections.map((s) => {
+        const tags = s.tags && s.tags.length > 0 ? ` [${s.tags.join(', ')}]` : '';
+        return `• ${s.section}${tags} (${s.source}, updated ${s.updatedAt.split('T')[0]})`;
+    });
     return {
         content: [{ type: 'text', text: `Context sections:\n${lines.join('\n')}` }],
         structuredContent: data,
@@ -597,16 +602,35 @@ server.registerTool('list_context_sections', {
 // Tool: Get context section
 server.registerTool('get_context_section', {
     title: 'Get Context Section',
-    description: 'Get full content of a specific context section.',
+    description: 'Get full content of a specific context section. Supports glob patterns for hierarchical sections.\n\n' +
+        '**Hierarchical paths**: For monorepos or large projects, sections can be organized hierarchically ' +
+        '(e.g., "api/architecture", "api/endpoints/auth"). Use glob patterns to fetch multiple:\n' +
+        '- `api/*` - direct children only (api/architecture, api/testing)\n' +
+        '- `api/**` - all descendants (api/architecture, api/endpoints/auth)',
     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(),
+        section: z.string().describe('Section name or glob pattern (e.g., "overview", "api/architecture", "api/*", "api/**")'),
     }),
+    outputSchema: z.union([
+        z.object({
+            section: z.string(),
+            content: z.string(),
+            updatedAt: z.string(),
+            source: z.string(),
+            tags: z.array(z.string()).optional(),
+            appliesTo: z.array(z.string()).optional(),
+        }),
+        z.object({
+            pattern: z.string(),
+            sections: z.array(z.object({
+                section: z.string(),
+                content: z.string(),
+                updatedAt: z.string(),
+                source: z.string(),
+                tags: z.array(z.string()).optional(),
+                appliesTo: z.array(z.string()).optional(),
+            })),
+        }),
+    ]),
     annotations: {
         readOnlyHint: true,
         destructiveHint: false,
@@ -614,7 +638,19 @@ server.registerTool('get_context_section', {
         openWorldHint: false,
     },
 }, async ({ section }) => {
-    const data = await api('GET', `/api/agent/context/${section}`);
+    const data = await api('GET', `/api/agent/context/${encodeURIComponent(section)}`);
+    // Handle glob pattern response (multiple sections)
+    if (data.pattern && data.sections) {
+        const lines = [`**Sections matching "${data.pattern}":**\n`];
+        for (const s of data.sections) {
+            lines.push(`# ${s.section}\n\n${s.content}\n\n---\n`);
+        }
+        return {
+            content: [{ type: 'text', text: lines.join('\n') }],
+            structuredContent: data,
+        };
+    }
+    // Single section response
     return {
         content: [{ type: 'text', text: `# ${data.section}\n\n${data.content}` }],
         structuredContent: data,
@@ -625,6 +661,11 @@ 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' +
+        '**When to use hierarchical names**: For monorepos or large projects, use paths like ' +
+        '`api/architecture`, `api/testing` to organize by module. For simple projects, flat ' +
+        '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' +
         '⚠️ SECURITY WARNING: Do NOT include sensitive information:\n' +
         '- API keys, secrets, passwords, tokens\n' +
         '- Database connection strings\n' +
@@ -633,13 +674,17 @@ server.registerTool('update_context_section', {
         '- .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'),
+            .regex(/^[a-z][a-z0-9-]{0,49}(\/[a-z][a-z0-9-]{0,49}){0,2}$/)
+            .describe('Section name or path (e.g., "overview", "api/architecture"). Max 3 levels.'),
         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"]).'),
     }),
     outputSchema: z.object({
         success: z.boolean(),
         section: z.string(),
+        tags: z.array(z.string()).optional(),
+        appliesTo: z.array(z.string()).optional(),
         warnings: z.array(z.string()).optional(),
     }),
     annotations: {
@@ -648,9 +693,12 @@ server.registerTool('update_context_section', {
         idempotentHint: true,
         openWorldHint: false,
     },
-}, async ({ section, content }) => {
-    const result = await api('POST', `/api/agent/context/${section}`, { content });
+}, async ({ section, content, tags, appliesTo }) => {
+    const result = await api('POST', `/api/agent/context/${encodeURIComponent(section)}`, { content, tags, appliesTo });
     let text = `📝 Updated context section: ${result.section}`;
+    if (result.tags && result.tags.length > 0) {
+        text += ` [${result.tags.join(', ')}]`;
+    }
     if (result.warnings && result.warnings.length > 0) {
         text += `\n⚠️ Warnings: ${result.warnings.join(', ')}`;
     }
@@ -673,9 +721,11 @@ server.registerTool('sync_project_context', {
     inputSchema: z.object({
         sections: z.array(z.object({
             section: z.string()
-                .regex(/^[a-z][a-z0-9-]{0,49}$/)
-                .describe('Section name'),
+                .regex(/^[a-z][a-z0-9-]{0,49}(\/[a-z][a-z0-9-]{0,49}){0,2}$/)
+                .describe('Section name or path (e.g., "overview", "api/architecture")'),
             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'),
         })).describe('Array of sections to upload'),
     }),
     outputSchema: z.object({
@@ -709,6 +759,8 @@ server.registerTool('get_project_context', {
             section: z.string(),
             preview: z.string(),
             updatedAt: z.string(),
+            tags: z.array(z.string()).optional(),
+            appliesTo: z.array(z.string()).optional(),
         })),
         relevantSections: z.array(z.string()).optional(),
         hint: z.string().optional(),
@@ -731,7 +783,8 @@ server.registerTool('get_project_context', {
     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}`);
+        const tags = s.tags && s.tags.length > 0 ? ` [${s.tags.join(', ')}]` : '';
+        lines.push(`• ${s.section}${relevant}${tags} - ${s.preview}`);
     }
     if (data.relevantSections && data.relevantSections.length > 0) {
         lines.push(`\n**Relevant for this task:** ${data.relevantSections.join(', ')}`);
@@ -821,6 +874,294 @@ server.registerTool('get_feedback', {
         structuredContent: f,
     };
 });
+// ==================== Template Tools ====================
+// Tool: List templates
+server.registerTool('list_templates', {
+    title: 'List Templates',
+    description: 'List available code templates for this project. Templates help maintain consistency ' +
+        'when creating new files.\n\n' +
+        '**When to use**: Check for templates before creating new service files, components, ' +
+        'or test files. If no templates exist, create files using patterns you observe in the codebase.\n\n' +
+        '**When to skip**: If the list is empty, the project doesn\'t use templates - that\'s fine.',
+    inputSchema: z.object({}),
+    outputSchema: z.object({
+        templates: z.array(z.object({
+            name: z.string(),
+            description: z.string().nullable().optional(),
+            filePattern: z.string().nullable().optional(),
+            tags: z.array(z.string()).optional(),
+            preview: z.string(),
+            updatedAt: z.string(),
+        })),
+        isEmpty: z.boolean(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async () => {
+    const data = await api('GET', '/api/agent/templates');
+    if (data.isEmpty) {
+        return {
+            content: [{ type: 'text', text: 'No templates available for this project.' }],
+            structuredContent: data,
+        };
+    }
+    const lines = data.templates.map((t) => {
+        const pattern = t.filePattern ? ` → ${t.filePattern}` : '';
+        const desc = t.description ? `: ${t.description}` : '';
+        return `• ${t.name}${pattern}${desc}`;
+    });
+    return {
+        content: [{ type: 'text', text: `Templates:\n${lines.join('\n')}` }],
+        structuredContent: data,
+    };
+});
+// Tool: Get template
+server.registerTool('get_template', {
+    title: 'Get Template',
+    description: 'Get full content of a specific code template.',
+    inputSchema: z.object({
+        name: z.string().describe('Template name'),
+    }),
+    outputSchema: z.object({
+        name: z.string(),
+        description: z.string().nullable().optional(),
+        content: z.string(),
+        filePattern: z.string().nullable().optional(),
+        tags: z.array(z.string()).optional(),
+        updatedAt: z.string(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ name }) => {
+    const t = await api('GET', `/api/agent/templates/${name}`);
+    const header = t.description ? `${t.name}: ${t.description}` : t.name;
+    const pattern = t.filePattern ? `\nFile pattern: ${t.filePattern}` : '';
+    return {
+        content: [{ type: 'text', text: `# Template: ${header}${pattern}\n\n\`\`\`\n${t.content}\n\`\`\`` }],
+        structuredContent: t,
+    };
+});
+// Tool: Update template
+server.registerTool('update_template', {
+    title: 'Update Template',
+    description: 'Create or update a code template. Templates help maintain consistency across similar files.\n\n' +
+        '**When to create templates**: When you notice repetitive file patterns in a project ' +
+        '(e.g., all services follow same structure). Extract the pattern and store it.\n\n' +
+        '**File patterns**: Use `{name}` as a placeholder in the file pattern ' +
+        '(e.g., "src/services/{name}.ts").',
+    inputSchema: z.object({
+        name: z.string().regex(/^[a-z][a-z0-9-]{0,49}$/).describe('Template name (lowercase, alphanumeric, hyphens)'),
+        content: z.string().describe('Template content (can include placeholders like {name}, {description})'),
+        description: z.string().optional().describe('Brief description of when to use this template'),
+        filePattern: z.string().optional().describe('File path pattern (e.g., "src/services/{name}.ts")'),
+        tags: z.array(z.string()).optional().describe('Categorization tags'),
+    }),
+    outputSchema: z.object({
+        success: z.boolean(),
+        name: z.string(),
+        description: z.string().nullable().optional(),
+        filePattern: z.string().nullable().optional(),
+        tags: z.array(z.string()).optional(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ name, content, description, filePattern, tags }) => {
+    const result = await api('POST', `/api/agent/templates/${name}`, { content, description, filePattern, tags });
+    return {
+        content: [{ type: 'text', text: `📝 Updated template: ${result.name}` }],
+        structuredContent: result,
+    };
+});
+// Tool: Sync templates
+server.registerTool('sync_templates', {
+    title: 'Sync Templates',
+    description: 'Bulk upload multiple templates at once.',
+    inputSchema: z.object({
+        templates: z.array(z.object({
+            name: z.string().regex(/^[a-z][a-z0-9-]{0,49}$/).describe('Template name'),
+            content: z.string().describe('Template content'),
+            description: z.string().optional().describe('Description'),
+            filePattern: z.string().optional().describe('File path pattern'),
+            tags: z.array(z.string()).optional().describe('Tags'),
+        })).describe('Array of templates to upload'),
+    }),
+    outputSchema: z.object({
+        success: z.boolean(),
+        templatesUpdated: z.number(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ templates }) => {
+    const result = await api('POST', '/api/agent/templates/sync', { templates });
+    return {
+        content: [{ type: 'text', text: `📚 Synced ${result.templatesUpdated} templates` }],
+        structuredContent: result,
+    };
+});
+// ==================== Module Tools ====================
+// Tool: List modules
+server.registerTool('list_modules', {
+    title: 'List Modules',
+    description: 'List registered modules in this monorepo. Shows package structure, ports, and dependencies.\n\n' +
+        '**When to use**: For monorepos with multiple packages. Helps understand which packages ' +
+        'exist and how they relate before making cross-package changes.\n\n' +
+        '**When to skip**: For single-package projects or when you already understand the structure.',
+    inputSchema: z.object({}),
+    outputSchema: z.object({
+        modules: z.array(z.object({
+            name: z.string(),
+            path: z.string(),
+            port: z.number().nullable().optional(),
+            dependsOn: z.array(z.string()).optional(),
+            description: z.string().nullable().optional(),
+            tags: z.array(z.string()).optional(),
+            updatedAt: z.string(),
+        })),
+        isEmpty: z.boolean(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async () => {
+    const data = await api('GET', '/api/agent/modules');
+    if (data.isEmpty) {
+        return {
+            content: [{ type: 'text', text: 'No modules registered. This may be a single-package project.' }],
+            structuredContent: data,
+        };
+    }
+    const lines = data.modules.map((m) => {
+        const port = m.port ? ` :${m.port}` : '';
+        const deps = m.dependsOn && m.dependsOn.length > 0 ? ` → ${m.dependsOn.join(', ')}` : '';
+        return `• ${m.name}${port} (${m.path})${deps}`;
+    });
+    return {
+        content: [{ type: 'text', text: `Modules:\n${lines.join('\n')}` }],
+        structuredContent: data,
+    };
+});
+// Tool: Get module
+server.registerTool('get_module', {
+    title: 'Get Module',
+    description: 'Get details of a specific module.',
+    inputSchema: z.object({
+        name: z.string().describe('Module name'),
+    }),
+    outputSchema: z.object({
+        name: z.string(),
+        path: z.string(),
+        port: z.number().nullable().optional(),
+        dependsOn: z.array(z.string()).optional(),
+        description: z.string().nullable().optional(),
+        tags: z.array(z.string()).optional(),
+        updatedAt: z.string(),
+    }),
+    annotations: {
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ name }) => {
+    const m = await api('GET', `/api/agent/modules/${name}`);
+    const parts = [`# Module: ${m.name}`, `Path: ${m.path}`];
+    if (m.port)
+        parts.push(`Port: ${m.port}`);
+    if (m.dependsOn && m.dependsOn.length > 0)
+        parts.push(`Depends on: ${m.dependsOn.join(', ')}`);
+    if (m.description)
+        parts.push(`\n${m.description}`);
+    return {
+        content: [{ type: 'text', text: parts.join('\n') }],
+        structuredContent: m,
+    };
+});
+// Tool: Update module
+server.registerTool('update_module', {
+    title: 'Update Module',
+    description: 'Register or update a module in the registry. Use to track monorepo structure.\n\n' +
+        '**When to use**: After analyzing a monorepo, register each package so future agents ' +
+        'understand the structure without re-analyzing.',
+    inputSchema: z.object({
+        name: z.string().regex(/^[a-z][a-z0-9-]{0,49}$/).describe('Module name (e.g., "server", "dashboard")'),
+        path: z.string().describe('Path to module (e.g., "packages/server")'),
+        port: z.number().nullable().optional().describe('Dev server port if applicable'),
+        dependsOn: z.array(z.string()).optional().describe('Names of modules this depends on'),
+        description: z.string().optional().describe('Brief description of the module'),
+        tags: z.array(z.string()).optional().describe('Categorization tags'),
+    }),
+    outputSchema: z.object({
+        success: z.boolean(),
+        name: z.string(),
+        path: z.string(),
+        port: z.number().nullable().optional(),
+        dependsOn: z.array(z.string()).optional(),
+        description: z.string().nullable().optional(),
+        tags: z.array(z.string()).optional(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ name, path, port, dependsOn, description, tags }) => {
+    const result = await api('POST', `/api/agent/modules/${name}`, { path, port, dependsOn, description, tags });
+    return {
+        content: [{ type: 'text', text: `📦 Updated module: ${result.name} (${result.path})` }],
+        structuredContent: result,
+    };
+});
+// Tool: Sync modules
+server.registerTool('sync_modules', {
+    title: 'Sync Modules',
+    description: 'Bulk upload multiple modules at once. Use after analyzing a monorepo.',
+    inputSchema: z.object({
+        modules: z.array(z.object({
+            name: z.string().regex(/^[a-z][a-z0-9-]{0,49}$/).describe('Module name'),
+            path: z.string().describe('Path to module'),
+            port: z.number().nullable().optional().describe('Dev server port'),
+            dependsOn: z.array(z.string()).optional().describe('Dependencies'),
+            description: z.string().optional().describe('Description'),
+            tags: z.array(z.string()).optional().describe('Tags'),
+        })).describe('Array of modules to upload'),
+    }),
+    outputSchema: z.object({
+        success: z.boolean(),
+        modulesUpdated: z.number(),
+    }),
+    annotations: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ modules }) => {
+    const result = await api('POST', '/api/agent/modules/sync', { modules });
+    return {
+        content: [{ type: 'text', text: `📦 Synced ${result.modulesUpdated} modules` }],
+        structuredContent: result,
+    };
+});
 // Start
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

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