@damper/mcp 0.1.13 → 0.3.0

package/README.md

@@ -69,20 +69,121 @@ 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`, 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 |
+| `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
+
+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. 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:**
+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.
+
+### 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
 
@@ -160,6 +261,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
@@ -173,6 +275,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.3.0',
 });
 // Output schemas
 const SubtaskProgressSchema = z.object({
@@ -315,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'),
@@ -330,6 +342,7 @@ server.registerTool('start_task', {
         message: z.string(),
         lockedBy: z.string().optional(),
         lockedAt: z.string().optional(),
+        context: ContextIndexSchema.optional(),
     }),
     annotations: {
         readOnlyHint: false,
@@ -340,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,
         };
     }
@@ -466,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'),
@@ -477,6 +514,7 @@ server.registerTool('complete_task', {
     outputSchema: z.object({
         id: z.string(),
         status: z.string(),
+        documentation: DocumentationSchema.optional(),
     }),
     annotations: {
         readOnlyHint: false,
@@ -486,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,
     };
 });
@@ -517,6 +559,241 @@ 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(),
+            tags: z.array(z.string()).optional(),
+            appliesTo: z.array(z.string()).optional(),
+        })),
+        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) => {
+        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,
+    };
+});
+// Tool: Get context section
+server.registerTool('get_context_section', {
+    title: 'Get 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 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,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, async ({ 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,
+    };
+});
+// 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' +
+        '**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' +
+        '- 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}(\/[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: {
+        readOnlyHint: false,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    },
+}, 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(', ')}`;
+    }
+    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}(\/[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({
+        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(),
+            tags: z.array(z.string()).optional(),
+            appliesTo: z.array(z.string()).optional(),
+        })),
+        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) ? ' ⭐' : '';
+        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(', ')}`);
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        structuredContent: data,
+    };
+});
 // Tool: List feedback
 server.registerTool('list_feedback', {
     title: 'List Feedback',
@@ -597,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.1.13",
+  "version": "0.3.0",
   "description": "MCP server for Damper task management",
   "author": "Damper <hello@usedamper.com>",
   "repository": {