MCP server for Damper task management
npm install @damper/mcpMCP server for Damper - enables AI agents to manage roadmap tasks.
``bash`
npm install -g @damper/mcp
Claude Code (~/.claude.json or ~/.config/claude/claude.json):`json`
{
"mcpServers": {
"damper": {
"command": "npx",
"args": ["@damper/mcp"],
"env": { "DAMPER_API_KEY": "dmp_..." }
}
}
}
Cursor (.cursor/mcp.json):`json`
{
"mcpServers": {
"damper": {
"command": "npx",
"args": ["@damper/mcp"],
"env": { "DAMPER_API_KEY": "dmp_..." }
}
}
}
Each API key is tied to one project. For multiple projects, configure separate server entries:
Claude Code (~/.claude.json or ~/.config/claude/claude.json):`json`
{
"mcpServers": {
"damper-frontend": {
"command": "npx",
"args": ["@damper/mcp"],
"env": { "DAMPER_API_KEY": "dmp_frontend_xxx" }
},
"damper-backend": {
"command": "npx",
"args": ["@damper/mcp"],
"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"
| Tool | Description |
|------|-------------|
| list_tasks | Get roadmap tasks (filter by status, type, quarter, sort by importance/newest/votes) |get_task
| | Task details + subtasks + commits + 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). Returns project context index. |add_note
| | Add progress note |add_commit
| | Log a commit (hash + message). Appears in task details. |create_subtask
| | Add subtask to a task |update_subtask
| | Mark subtask done/undone |complete_task
| | Mark done, release lock. Optionally log commits at completion. |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 |get_agent_instructions
| | Get canonical workflow for CLAUDE.md setup |
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 documentationget_context_section
2. Fetch relevant sections with to understand the codebasecomplete_task
3. After completing work, reminds you to update docs if neededupdate_context_section
4. Use 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.
Configure agent-relevant project settings programmatically.
| Tool | Description |
|------|-------------|
| get_project_settings | View current settings (completion checklist, etc.) |update_project_settings
| | Configure completion checklist and other agent-relevant settings |
Completion checklist workflow:
1. update_project_settings with completionChecklist: ["All tests pass", "Build succeeds", "Code reviewed"]start_task
2. Agents see the checklist when they call confirmations
3. Agents must confirm all items via when calling complete_task
``
> View project settings
> Set completion checklist to require tests and builds
> Clear the completion checklist
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.
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.
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.
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.
Filter tasks by type to prioritize work:
``
> List all bugs
> Work on the first feature
> Show me improvement tasks
Types: bug 🐛, feature ✨, improvement 💡, task 📌
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) + votesnewest
- - most recently created firstvotes
- - highest vote score first
``
> List tasks sorted by newest
> Show me the most voted features
Tasks include project management fields visible in list_tasks and get_task:
- Priority: high 🔴, medium 🟡, low ⚪
- Effort: xs, s, m, l, xl
- Quarter: Target quarter (Q1 2025, Q2 2025, etc.)
- Labels: Custom tags
- Due date: Target completion date
Refine task details as you work:
``
> Set priority to high for this task
> Update the implementation plan with what I've learned
> Add labels: backend, api, auth
> Set effort to medium
> Schedule this for Q2 2025
Tasks can have subtasks for tracking incremental progress. Use get_task to see subtasks with their IDs:
``Subtasks (2/5)
- [x] Setup database schema (id: abc123)
- [ ] Implement API endpoints (id: def456)
Create and update subtasks as you work:
``
> Add a subtask "Write unit tests" to this task
> Create subtask for database migrations
> Mark the database schema subtask as done
> Update subtask def456 to done
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
Log commits as you work to track code changes for each task:
``
> Log commit abc1234 with message "Added validation"
> Add commit def5678: "Fixed auth bug"
Commits are stored structurally and displayed in task details:
``Commits (2)
- abc1234: Added validation
- def5678: Fixed auth bug
Two ways to log commits:
1. add_commit - Log commits as you make themcomplete_task
2. with commits - Log final commits at completion
When working on tasks, follow this workflow for best results:
1. Start: start_task → locks the task and returns project contextadd_note
2. Log start: with "Session started: add_commit
3. Work: Make changes, use after each commit, add_note for decisionsadd_note
4. Log end: with "Session end: complete_task
5. Finish: (done) or abandon_task (stopping)
What to log:
- Session start: add_note "Session started: implementing dark mode"add_commit abc123 "Added theme provider"
- Commits: add_note "Decision: Using CSS variables because..."
- Decisions: add_note "Session end: Done theme provider, remaining: toggle UI"
- Session end:
Before completing:
- Push all commits
- Log session end note
- Check if project context docs need updating
Before abandoning:
- Push any WIP commits
- Log session end with progress, blockers, next steps
- Provide summary for handoff
> What tasks are available?
> List bugs I can fix
> Show tasks for Q2 2025
> What's unscheduled? (quarter: none)
> Import my TODO.md into Damper
> Work on the dark mode feature
> Show me the subtasks for this task
> Mark the first subtask as done
> I'm done with the auth task - tests pass
> Abandon the current task, I'm blocked
`$3
`
> 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
`Setting Up a Project
To add Damper workflow instructions to a new project:
`
> Get the agent instructions and add them to my CLAUDE.md
`The agent will call
get_agent_instructions and write to your CLAUDE.md file. This ensures you always have the latest workflow instructions.Formats:
-
section (default): Just the Damper workflow section - append to existing CLAUDE.md
- markdown: Full file with header - use when creating a new CLAUDE.mdAgent Instructions (CLAUDE.md)
Add this to your project's
CLAUDE.md (or .cursorrules for Cursor) to ensure AI agents use Damper consistently:`markdown
Task Management with Damper MCP
This project uses Damper MCP for task tracking. You MUST follow this workflow.
$3
1. get_project_context - READ THIS FIRST. Contains architecture, conventions, and critical project info. Do NOT skip.
2. get_context_section - Fetch full content for sections relevant to your task (e.g., "api", "database", "testing")
3. list_tasks - Check for existing tasks to work on
4. If working on a task: start_task to lock it (returns context index - read relevant sections)$3
- add_commit after each commit with hash and message
- add_note for decisions: "Decision: chose X because Y"
- update_subtask to mark subtask progress
- Follow patterns from project context - Don't reinvent; use existing conventions$3
- ALWAYS call add_note with session summary before stopping
- ALWAYS call complete_task (if done) or abandon_task (if stopping early)
- NEVER leave a started task without completing or abandoning it
- If you learned something about the codebase, consider updating project context$3
- Project context prevents mistakes - Contains architecture decisions, gotchas, and patterns you need to follow
- Locked tasks block other agents from working on them
- Commits and notes help the next agent (or you) continue the work
- Updating context saves future agents from re-analyzing the codebase
`Environment
| Variable | Required | Default |
|----------|----------|---------|
|
DAMPER_API_KEY | Yes | - |
| DAMPER_API_URL` | No | https://api.usedamper.com |MIT