Tasks.md MCP Server

# Tasks.md MCP Server - Usage Guide ## Getting Started ### 1. Start the MCP Server **Option A: Using npm** ```bash npm start ``` **Option B: Using npx directly** ```bash npx mcp-tasks ``` **Option C: With environment variables** ```bash TRANSPORT=http PORT=3211 TASKS_DIR=./demo-project npx mcp-tasks ``` ### 2. Connect Claude The MCP server runs in the background and Claude connects to it automatically when configured in `.claude/settings.json` or `.kilocode/mcp.json`. ## Common Tasks ### View All Tasks ```bash cd demo-project npx mcp-tasks summary ``` Output shows: - Total tasks by status - Tasks in progress - Reminders - Project statistics ### Search Tasks ```bash npx mcp-tasks search "In Progress,To Do" "auth,signup" ``` Search by: - **Statuses**: `"Backlog,To Do,In Progress,Done,Notes,Deleted"` - **Keywords**: Any text in task title or description ### Add New Task ```bash npx mcp-tasks add "Implement password reset endpoint" "To Do" 0 ``` Parameters: - **Text**: Task description - **Status**: Backlog, To Do, In Progress, Done, Notes, or Deleted - **Index**: Position in the status section (0 = top) ### Update Task Status ```bash npx mcp-tasks update OLzw "Done" ``` Parameters: - **Task IDs**: Comma-separated list of task IDs (e.g., `OLzw,mBPw`) - **Status**: New status to set ### Refresh Status Board ```bash ./scripts/refresh-status.sh ``` Generates `demo-project/status-board.md` with current task overview. ## Using with Claude ### Creating Tasks **Example 1: Create an Epic** ``` User: "Create a new epic for admin dashboard features" Claude: Creates epic-03-admin.md with: - EPIC: ADMIN-01 — Admin Dashboard - Proper description - Server ID - Status: Backlog ``` **Example 2: Create Story under Epic** ``` User: "Add a story to the authentication epic for password reset" Claude: Creates story-01-02.md with: - STORY: AUTH-01-2 — Password reset flow - Links to parent epic - Server ID - Status: To Do ``` **Example 3: Create Task under Story** ``` User: "Create a task for implementing the password reset email" Claude: Creates task-01-02-01.md with: - TASK: AUTH-01-2-1 — Send password reset email - Detailed description - Server ID - Status: To Do ``` ### Querying Tasks **Example 1: View In Progress Tasks** ``` User: "What tasks are currently in progress?" Claude: Queries and returns: - TASK: AUTH-01-1-1 — Implement signup endpoint ``` **Example 2: Search by Epic** ``` User: "Show me all tasks in the authentication epic" Claude: Lists all AUTH-01 epics, stories, and tasks ``` **Example 3: Generate Progress Report** ``` User: "Create a weekly progress report" Claude: Analyzes tasks and generates: - Completed tasks - In progress tasks - Blocked tasks - Velocity metrics ``` ### Updating Tasks **Example 1: Move Task to Done** ``` User: "Mark the signup endpoint task as complete" Claude: Updates task-01-01-01.md: - Changes Status: In Progress → Done - Updates tasks.md index ``` **Example 2: Add Task Details** ``` User: "Add acceptance criteria to the signup story" Claude: Updates story-01-01.md with: - Acceptance criteria section - Technical notes - Dependencies ``` ## File Organization ### Task Hierarchy ``` EPIC (epic-01-auth.md) ├── STORY (story-01-01.md) │ ├── TASK (task-01-01-01.md) │ ├── TASK (task-01-01-02.md) │ └── TASK (task-01-01-03.md) ├── STORY (story-01-02.md) │ └── TASK (task-01-02-01.md) └── MILESTONE (milestone-v1-0.md) ``` ### Status Flow ``` Backlog → To Do → In Progress → Done ↓ Notes ↓ Deleted ``` ## Advanced Features ### Git Integration Track task changes in version control: ```bash # View task changes git diff demo-project/tasks.md # Commit task updates git add demo-project/*.md git commit -m "feat: add password reset story and tasks" # Create branch per epic git checkout -b epic/auth-01 ``` ### Automation with Hooks **Pre-commit hook** (`.git/hooks/pre-commit`): ```bash #!/bin/bash ./scripts/refresh-status.sh git add demo-project/status-board.md ``` Make it executable: ```bash chmod +x .git/hooks/pre-commit ``` ### Task Templates Create reusable templates in `scripts/`: **API Endpoint Template** (`scripts/api-endpoint-template.md`): ```markdown # TASK: [EPIC]-[STORY]-[NUM] — Implement [endpoint] endpoint Create [METHOD] /api/[path] endpoint that [description]. Server ID: [generated] Status: To Do ## Acceptance Criteria - [ ] Endpoint accepts correct input parameters - [ ] Input validation implemented - [ ] Error handling for all edge cases - [ ] Response format matches API spec - [ ] Unit tests written - [ ] Integration tests passing - [ ] API documentation updated ## Technical Notes - Use express.js router - Validate with joi/zod - Return proper HTTP status codes - Log all errors ## Dependencies - Depends on: [prerequisite task] ``` Usage: ```bash cp scripts/api-endpoint-template.md demo-project/task-01-01-02.md # Edit and customize ``` ### Bulk Operations **Update multiple tasks**: ```bash # Get task IDs npx mcp-tasks search "To Do" "auth" # Update multiple at once npx mcp-tasks update OLzw,mBPw,cI9A "In Progress" ``` **Move epic to new status**: ```bash # Find all tasks in epic grep -l "AUTH-01" demo-project/*.md # Update each file's status using sed for file in demo-project/*AUTH-01*.md; do sed -i 's/Status: Backlog/Status: To Do/' "$file" done ``` ## Troubleshooting ### MCP Server Won't Start **Check Node.js version**: ```bash node --version # Should be 18+ ``` **Verify installation**: ```bash ls node_modules/.bin/mcp-tasks npm list mcp-tasks ``` **Check configuration**: ```bash cat .claude/settings.json cat .kilocode/mcp.json ``` ### Tasks Not Showing Up **Verify tasks.md format**: - Tasks must start with `- [ ]` or `- [x]` - Format: `- [ ] TYPE: ID — Title` - Must be under correct status section (## In Progress, ## To Do, etc.) **Re-setup tasks file**: ```bash cd demo-project npx mcp-tasks setup tasks.md . npx mcp-tasks summary ``` ### Server IDs Not Working **Server IDs are auto-generated**: - Don't create manually - Generated when using `npx mcp-tasks add` - Check summary.json for task IDs **Find task ID**: ```bash npx mcp-tasks summary | jq '.inProgress[].id' ``` ## Best Practices ### 1. Consistent Naming - **Epics**: `epic-[ID]-[slug].md` (e.g., `epic-01-auth.md`) - **Stories**: `story-[EPIC]-[NUM].md` (e.g., `story-01-01.md`) - **Tasks**: `task-[EPIC]-[STORY]-[NUM].md` (e.g., `task-01-01-01.md`) ### 2. Status Discipline - Start tasks in **Backlog** - Move to **To Do** when prioritized - Set to **In Progress** when starting work - Mark **Done** when complete - Use **Notes** for ideas and planning - Set **Deleted** for cancelled tasks (keep for history) ### 3. Task Descriptions Write clear, actionable descriptions: ✅ **Good**: ```markdown Create POST /api/signup endpoint that accepts email and password, validates input with zod, hashes password with bcrypt, stores user in PostgreSQL, and returns JWT token on success. ``` ❌ **Bad**: ```markdown Signup stuff ``` ### 4. Acceptance Criteria Add clear criteria for task completion: ```markdown ## Acceptance Criteria - [ ] Endpoint validates email format - [ ] Password must be 8+ characters - [ ] Duplicate emails return 409 error - [ ] Success returns JWT token - [ ] All tests passing ``` ### 5. Link Dependencies Document task relationships: ```markdown ## Dependencies - Depends on: AUTH-01-1-1 (user model must exist) - Blocks: AUTH-01-1-3 (email verification needs signup) ``` ## Integration Examples ### CI/CD Pipeline **GitHub Actions** (`.github/workflows/tasks.yml`): ```yaml name: Task Validation on: [push, pull_request] jobs: validate-tasks: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - uses: actions/setup-node@v2 with: node-version: '18' - run: npm install - run: npx mcp-tasks summary - run: ./scripts/refresh-status.sh ``` ### Slack Notifications **Webhook script** (`scripts/notify-slack.sh`): ```bash #!/bin/bash SUMMARY=$(npx mcp-tasks summary) IN_PROGRESS=$(echo $SUMMARY | jq '."In Progress"') curl -X POST $SLACK_WEBHOOK -H 'Content-type: application/json' -d "{ \"text\": \"📊 Task Update: $IN_PROGRESS tasks in progress\" }" ``` ### VS Code Integration **tasks.json** for VS Code: ```json { "version": "2.0.0", "tasks": [ { "label": "Task Summary", "type": "shell", "command": "npx mcp-tasks summary | jq", "problemMatcher": [] }, { "label": "Refresh Status Board", "type": "shell", "command": "./scripts/refresh-status.sh", "problemMatcher": [] } ] } ``` ## Resources - **MCP Tasks Documentation**: https://github.com/modelcontextprotocol/servers/tree/main/src/tasks - **Model Context Protocol**: https://modelcontextprotocol.io - **Claude Documentation**: https://docs.anthropic.com/claude/docs --- **Need help?** Open an issue or check the README.md for more examples.