@damper/mcp

MCP server for Damper - enables AI agents to manage roadmap tasks.

Install

``bash
npm install -g @damper/mcp
`

Setup

$3

Damper → Settings → API Keys → Generate

$3

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_..." }
}
}
}
`

$3

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"

Tools

$3

| 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 |

$3

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.

$3

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"]
2. Agents see the checklist when they call start_task
3. Agents must confirm all items via confirmations when calling complete_task

`
> View project settings
> Set completion checklist to require tests and builds
> Clear the completion checklist
`

$3

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.

$3

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.

$3

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.

$3

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.

$3

Filter tasks by type to prioritize work:

`
> List all bugs
> Work on the first feature
> Show me improvement tasks
`

Types: bug 🐛, feature ✨, improvement 💡, task 📌

$3

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
`

$3

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

$3

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
`

$3

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
`

$3

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

$3

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 them
2. complete_task with commits - Log final commits at completion

$3

When working on tasks, follow this workflow for best results:

1. Start: start_task → locks the task and returns project context
2. Log start: add_note with "Session started: "
3. Work: Make changes, use add_commit after each commit, add_note for decisions
4. Log end: add_note with "Session end: "
5. Finish: complete_task (done) or abandon_task (stopping)

What to log:
- Session start: add_note "Session started: implementing dark mode"
- Commits: add_commit abc123 "Added theme provider"
- Decisions: add_note "Decision: Using CSS variables because..."
- Session end: add_note "Session end: Done theme provider, remaining: toggle UI"

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

Usage Examples

$3


`
> 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.md

Agent 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 |

License

MIT