MCP server for task management with multi-agent coordination
npm install mcp-task-serverA Model Context Protocol (MCP) server for task management with multi-agent coordination. Designed for use with Cursor IDE and other MCP-compatible AI tools.
``bash`
publish-mcp
This script (in ~/scripts/) bumps version, builds, and publishes to npm. Requires $NPM_TOKEN in your shell profile.
Add to ~/.cursor/mcp.json for all projects:
`json`
{
"mcpServers": {
"task-server": {
"command": "npx",
"args": ["-y", "mcp-task-server"]
}
}
}
The server auto-detects your workspace. No per-project config needed.
For explicit control, add to .cursor/mcp.json in your project:
`json`
{
"mcpServers": {
"task-server": {
"command": "npx",
"args": ["-y", "mcp-task-server"],
"env": {
"TASK_WORKSPACE": "/absolute/path/to/your/project"
}
}
}
}
After adding, reload Cursor: Cmd+Shift+P → "Developer: Reload Window"
Invoke any tool with call :
| Command | Description |
|---------|-------------|
| call help | List all 44 available tools |call list_tasks
| | Show all tasks |call next_task
| | Get recommended next task |call diagnose
| | Check server configuration |call show_memory
| | View shared context memories |call init_project
| | Initialise project structure |
Why call? Using just help may trigger Cursor's generic help. The call prefix ensures the MCP tool is invoked.
---
`mermaid`
flowchart TB
subgraph Cursor IDE
A[AI Assistant]
end
subgraph MCP Task Server
B[44 Tools]
C[Preferences Engine]
P[Project Context]
end
subgraph Your Machine
D[~/.cursor/shared-context.json]
E[memory_bank/tasks/]
F[memory_bank/execution/progress*.md]
G[~/.cursor/content-context.md]
end
A <-->|MCP Protocol| B
B --> C
B --> P
C -->|read/write| D
P -->|filter tasks| E
B -->|read/write| E
B -->|auto-sync| F
B -->|read/write| G
D -->|inject into responses| A
- 44 MCP Tools: Comprehensive task management and coordination
- Multi-Project Support: Manage tasks across multiple projects from one workspace with automatic filtering
- Auto Workspace Detection: Works globally without per-project config
- Multi-Agent Coordination: Support for Planner, Worker, and Judge roles
- Dependency Tracking: Tasks can depend on other tasks
- Priority Levels: Critical, High, Medium, Low
- Scalable Storage: Individual task files with JSON registry and per-project markdown summaries
- Prompt-Based Operations: PRD parsing, task expansion, complexity analysis
- Shared Context: Reads user preferences from ~/.cursor/shared-context.json to personalise prompts~/.cursor/content-context.md
- Content Context: Global content inventory at for content creators
- Project Initialisation: Scaffolds 28 template files across agent-kit, memory_bank, and cursor rules
- Wellness Tracking: Break reminder system via cursor rules, using session tracking in shared memory
- Flow Dashboard Integration: Fetch activity data from Flow Control dashboard for work/break recommendations
> Note: For brand new empty projects, create at least one file first (e.g., touch README.md), then reload Cursor. See Troubleshooting for details.
`bashAdd to a new project and initialise
call init_project({ project_name: "my-app" })
Multi-Project Workflow
$3
When working in a project's own folder, bind it once:
`bash
First time in this workspace - bind project to folder
call set_project({ project: "coach-platform", workspace: "/Users/andy/Projects/coaching/platform" })Future sessions auto-detect via workspace binding
call get_project({ workspace: "/Users/andy/Projects/coaching/platform" })
Returns: { current_project: "coach-platform", source: "workspace" }
`$3
When managing multiple projects from one workspace (like Obsidian):
Option A: Global context switching (one project at a time)
`bash
call set_project({ project: "coach-platform" })
call list_tasks # Shows coach-platform taskscall set_project({ project: "mcp-task-server" })
call list_tasks # Now shows mcp-task-server tasks
`Note: Global context is shared across all agent chats in the same workspace.
Option B: Explicit project parameter (parallel work)
`bash
Don't set context - pass project directly
call list_tasks({ project: "coach-platform" })
call list_tasks({ project: "mcp-task-server" })
call add_task({ title: "Fix bug", project: "coach-platform" })
`This is safer when jumping between projects or having multiple chats open.
$3
Progress files are generated per-project:
`
memory_bank/execution/
├── progress.md # Combined view (all projects)
├── progress-coach-platform.md # Coach platform tasks only
└── progress-mcp-task-server.md # MCP task server tasks only
`Shared Context & Preferences
The server reads
~/.cursor/shared-context.json for user preferences and automatically injects them into tool responses and prompts.$3
`mermaid
flowchart LR
A[~/.cursor/shared-context.json] -->|read at runtime| B[MCP Task Server]
B -->|inject into| C[Tool Responses]
B -->|inject into| D[Generated Prompts]
C -->|AI sees| E[preferences hint]
D -->|AI uses| F[full context]
`$3
Before creating or reviewing content, agents should:
1. Call
show_memory to check for user preferences
2. Look for recognised memory categories (see below)
3. Apply discovered preferences to all contentThis is enforced by the Cursor rules created by
init_project:
- .cursor/rules/agent-workflow.mdc - Task management protocol
- .cursor/rules/wellness-check.mdc - Break reminders based on time/duration
- .cursor/rules/shared-context-sync.mdc - Memory sync guidance$3
`mermaid
flowchart TB
subgraph Your Machine
A[shared-context.json]
end
subgraph MCP Server
B[show_memory] -->|read| A
C[update_memory] -->|write| A
D[Tool Responses] -->|include hint from| A
end
subgraph AI Assistant
E[Sees preferences in responses]
F[Applies to content creation]
end
D --> E --> F
`$3
Memories use simple sequential IDs (1, 2, 3...) managed by the server:
| Action | What it does |
|--------|--------------|
|
create | Add new memory with next available ID |
| update | Update existing memory by ID |
| delete | Remove memory by ID |
| sync | Create or update by title match (recommended) |
| migrate | One-time conversion of old IDs to sequential |$3
| Title (case-insensitive) | Purpose |
|--------------------------|---------|
|
identity or values | User context for prompts |
| writing preferences | Formatting, style, avoided words |
| workflow or memory bank | Task management preferences |
| wellness preferences | Break reminder settings and thresholds |
| current_project | Active project for multi-project filtering |The
sync action is recommended because it matches by title, avoiding duplicates:`bash
call update_memory({
action: "sync",
title: "Writing preferences",
content: "British English, no emojis..."
})
Returns: { status: "synced_new", memory: { id: "1", ... } }
`Migrating from old IDs: If you have memories with old-style IDs (like
mem_1737900000_abc123 or Cursor IDs), run migrate once:`bash
call update_memory({ action: "migrate" })
Returns: { status: "migrated", changes: [{ old_id: "mem_...", new_id: "1", title: "..." }] }
Or: { status: "already_migrated" } if already sequential
`> Why not Cursor IDs? Cursor's memory system is unreliable - agents cannot always create memories, and when they can, the ID is not always accessible. Sequential IDs managed by the server are simpler and more reliable.
$3
Cursor's memory system has limitations that make shared context necessary:
`mermaid
flowchart TB
subgraph cursor [Cursor IDE]
A[AI Assistant]
B[Internal Memory DB]
end
subgraph mcp [MCP Server]
C[Task Tools]
D[Memory Tools]
end
subgraph problem [The Problem]
E["AI can READ Cursor memories"]
F["MCP cannot ACCESS Cursor memories"]
end
A -->|can see| B
A -->|can call| C
C -.-x|no access| B
E --> G[Need bridge]
F --> G
`| Cursor Memory Limitation | Impact | Solution |
|-------------------------|--------|----------|
| No API access | MCP tools can't read Cursor's memory database |
~/.cursor/shared-context.json as shared store |
| Isolated per conversation | Memories don't persist across all contexts | Shared file accessible to all MCP servers |
| Unreliable memory creation | Agents cannot always create Cursor memories | Server-managed sequential IDs |Workflow:
1. Ask the agent to sync your preferences:
update_memory({ action: "sync", title: "Writing preferences", content: "..." })
2. Memory saved to ~/.cursor/shared-context.json with sequential ID
3. All MCP servers can now read it via show_memory$3
| Tool Type | How Preferences Are Applied |
|-----------|----------------------------|
|
list_tasks, get_task, add_task, update_task, next_task | Brief hint in response |
| parse_prd, expand_task, research_task | Full context in generated prompt |
| check_compliance | All preferences for validation |
| Wellness cursor rule | Session tracking and break reminders |$3
Validate files against your preferences:
`bash
Review only
call check_compliance({ path: "README.md" })Review a folder
call check_compliance({ path: "docs/" })Review and fix issues
call check_compliance({ path: "README.md", fix: true })
`See agent-kit/SHARED_CONTEXT.md for full setup and usage.
Installation
$3
`bash
npx mcp-task-server
`$3
`bash
npm install -g mcp-task-server
mcp-task-server
`$3
`bash
git clone https://github.com/yourusername/mcp-task-server.git
cd mcp-task-server
npm install
npm run build
npm start
`Workspace Path Configuration
The server automatically detects your project's root directory using multiple strategies.
$3
`mermaid
flowchart TD
A[Start] --> B{TASK_WORKSPACE set?}
B -->|Yes| C[Use TASK_WORKSPACE]
B -->|No| D{WORKSPACE_FOLDER_PATHS set?}
D -->|Yes| E[Use Cursor workspace path]
D -->|No| F{Project markers found?}
F -->|Yes| G["Use directory with .git, package.json, or memory_bank"]
F -->|No| H[Fall back to cwd]
`| Priority | Method | When Used |
|----------|--------|-----------|
| 1 |
TASK_WORKSPACE env | Explicit per-project override |
| 2 | WORKSPACE_FOLDER_PATHS env | Auto-set by Cursor (undocumented) |
| 3 | Project marker detection | Walks up from cwd looking for .git, package.json, memory_bank |
| 4 | process.cwd() | Final fallback |$3
Run
call get_version to see how the workspace was detected:`bash
call get_version
Returns: { workspace: { root: "/path/to/project", source: "found .git" } }
`Possible sources:
-
"TASK_WORKSPACE env" - Explicit override
- "WORKSPACE_FOLDER_PATHS env" - Detected from Cursor
- "found .git" / "found package.json" / "found memory_bank" - Project marker
- "process.cwd() fallback" - No detection, using current directory$3
If auto-detection isn't working, set
TASK_WORKSPACE in per-project config:`json
{
"mcpServers": {
"task-server": {
"command": "npx",
"args": ["-y", "mcp-task-server"],
"env": {
"TASK_WORKSPACE": "/absolute/path/to/project"
}
}
}
}
`Troubleshooting
$3
Symptom: Cursor Settings shows the MCP server connected with tools, but the Agent says it can only see
cursor-browser-extension and cursor-ide-browser.Cause: Cursor has a limitation where MCP tools don't work in empty workspaces (folders with no files).
`mermaid
flowchart LR
A[Empty Folder] --> B["No workspace folders"]
B --> C[MCP connects]
C --> D[Tools registered]
D --> E["Agent can't access"]
F[Folder with files] --> G[Workspace registered]
G --> H[MCP connects]
H --> I[Tools work]
`Fix:
1. Create at least one file in the project:
`bash
touch README.md
# or
npm init -y
`
2. Reload Cursor: Cmd+Shift+P → "Developer: Reload Window"
3. Start a new Agent chat
4. Try call help$3
Symptom: Server shows old version or missing tools after publishing update.
Fix: Clear the npx cache:
`bash
rm -rf ~/.npm/_npx
`Then reload Cursor and start a new Agent chat.
$3
Symptom:
call get_version shows workspace as /Users/yourname instead of your project.Cause: No project markers found (
.git, package.json, memory_bank).Fix: Either:
- Initialise git:
git init
- Create package.json: npm init -y
- Use explicit override with TASK_WORKSPACE env var$3
Cursor logs MCP server activity. To debug issues:
`bash
Find latest logs
ls -t ~/Library/Application\ Support/Cursor/logs/*/View task-server specific logs (replace YYYYMMDD with date)
cat ~/Library/Application\ Support/Cursor/logs//window/exthost/anysphere.cursor-mcp/MCP\ user-task-server.log | tail -50Look for warnings
grep -r "warning\|error" ~/Library/Application\ Support/Cursor/logs//window/exthost/anysphere.cursor-mcp/
`Key log messages:
-
No workspace folders found → Empty workspace issue
- Found 44 tools → Server connected successfully
- Workspace: /path → Shows detected workspaceConfiguration
Configure via environment variables:
| Variable | Default | Description |
|----------|---------|-------------|
|
TASK_MD_PATH | memory_bank/execution/progress.md | Path to markdown summary |
| TASK_JSON_PATH | memory_bank/tasks/tasks.json | Path to JSON registry |
| TASK_DIR | memory_bank/tasks | Directory for task files |
| FLOW_API_URL | https://flow.reids.net.au | Flow Control dashboard API URL (falls back to STATS_API_URL) |
| SLACK_BOT_TOKEN | - | Slack bot OAuth token (xoxb-...) |
| SLACK_CHANNEL_ID | - | Default Slack channel for notifications |
| SLACK_TEAM_ID | - | Optional Slack workspace ID |Storage Architecture
The server uses a scalable storage model with three layers:
$3
Machine-readable source of truth containing task IDs, status, dependencies, and subtasks.
`json
{
"version": "2.0.0",
"tasks": [
{
"id": "1",
"title": "Project Setup",
"status": "done",
"priority": "high",
"subtasks": [
{ "id": 1, "title": "Init project", "status": "done" }
]
}
]
}
`$3
Human-readable detailed task files for each top-level task:
`
Task ID: 1
Title: Project Setup and Configuration
Status: done
Dependencies: None
Priority: high
Description: Initialise the project with required tooling.
Details:
Full implementation details here...Subtasks:
1. Init project [done]
$3
$3
`$3
The server generates progress summaries automatically:
-
memory_bank/execution/progress.md - Combined view of all projects
- memory_bank/execution/progress-{project}.md - Per-project progress filesCombined Progress (shows all projects):
`markdown
Implementation Progress
Task Completion Summary
$3
- Task 1: Project Setup
- Task 2: Database Schema
`This architecture scales well for complex projects with many tasks and subtasks.
Tools
$3
| Tool | Description |
|------|-------------|
|
init_project | Initialise project with agent-kit, memory_bank, and cursor rules |
| sync_rules | Sync .cursor/rules/ to latest templates (for existing projects) |`bash
Initialise with auto-detected project name
call init_projectInitialise with custom name
call init_project({ project_name: "my-app" })Force overwrite existing files
call init_project({ force: true })Sync rules to existing project (add missing only)
call sync_rulesPreview what would change
call sync_rules({ dry_run: true })Update existing rules to latest templates
call sync_rules({ update_existing: true })
`$3
| Tool | Description | Preferences |
|------|-------------|-------------|
|
list_tasks | List all tasks, optionally filtered by status or assignee | ✓ hint |
| get_task | Get a specific task by ID with subtasks | ✓ hint |
| add_task | Create a new task | ✓ hint |
| update_task | Update task title, description, status, priority, or metadata | ✓ hint |
| complete_task | Mark a task as completed | |
| next_task | Get the next recommended task based on priority/dependencies | ✓ hint |$3
| Tool | Description |
|------|-------------|
|
claim_task | Claim a task for the calling agent |
| release_task | Release a claimed task |
| handoff_task | Transfer task to another role |
| review_task | Review a task (Judge role) |
| approve_task | Approve completed task (Judge role) |
| reject_task | Reject with feedback (Judge role) |$3
| Tool | Description |
|------|-------------|
|
expand_task | Get prompt to break task into subtasks |
| add_subtask | Add a subtask to existing task |
| set_dependencies | Set task dependencies |
| remove_task | Remove a task |$3
| Tool | Description | Preferences |
|------|-------------|-------------|
|
parse_prd | Get prompt to parse PRD into tasks | ✓ full |
| research_task | Get prompt to research a task | ✓ full |
| analyse_complexity | Get prompt to analyse task complexity | ✓ full |
| check_compliance | Check file/folder against user preferences from shared context | ✓ full |
| analyse_project | Analyse project structure and suggest memory_bank updates | ✓ full |$3
| Tool | Description |
|------|-------------|
|
set_project | Set project context (global or workspace-specific) |
| get_project | Get current project (checks workspace first, then global) |
| tag_all_tasks | Bulk tag tasks with a project name (for migration) |#### Hybrid Workspace Support
Project context supports two modes:
1. Global context - For hub workflows (like Obsidian) where you manage multiple projects from one workspace
2. Workspace-specific binding - For dedicated project workspaces that should always use a specific project
`bash
Hub workflow: Set global project (switchable)
call set_project({ project: "mcp-task-server" })
Returns: { project: "mcp-task-server", binding: "global" }
call set_project({ project: "coach-platform" })
Switches global context to coach-platform
Dedicated workspace: Bind project to workspace path
call set_project({ project: "mcp-task-server", workspace: "/Users/andy/Projects/tools/mcp-task-server" })
Returns: { project: "mcp-task-server", binding: "workspace", workspace: "..." }
Get project: Checks workspace mapping first, then global
call get_project({ workspace: "/Users/andy/Projects/tools/mcp-task-server" })
Returns: { current_project: "mcp-task-server", source: "workspace" }
call get_project()
Returns: { current_project: "coach-platform", source: "global" }
Bulk tag all unassigned tasks with a project
call tag_all_tasks({ project: "coach-platform" })
Returns: { tagged: 100, skipped: 0, message: "Tagged 100 tasks..." }
`#### Storage Structure
Project context is stored in
~/.cursor/shared-context.json:`json
{
"cursor_memories": [...],
"metadata": {
"current_project": "coach-platform",
"workspace_projects": {
"/Users/andy/Projects/tools/mcp-task-server": "mcp-task-server",
"/Users/andy/Projects/coaching/platform": "coach-platform"
}
}
}
`All task operations (
list_tasks, add_task, next_task) automatically filter by the current project context.$3
| Tool | Description |
|------|-------------|
|
show_content_context | Read global content context file |
| update_content_context | Update a section of the content context |`bash
Read content context
call show_content_context
Returns: { exists: true, path: "~/.cursor/content-context.md", content: "..." }
Update a section
call update_content_context({ section: "Published Content", content: "- Post 1\n- Post 2" })
`The content context file (
~/.cursor/content-context.md) stores content inventory, themes, and locations for content creators.$3
| Tool | Description |
|------|-------------|
|
stats | Fetch work activity statistics from Flow Control dashboard |
| usage | Fetch Cursor AI billing and spend limit info |
| flow | Get current flow state (score 0-10, zone, signals, nudge) |`bash
Quick check - today's hours and recommendation
call stats
Returns: { today: { hours: 3.5 }, recommendation: { status: "continue", message: "..." } }
Detailed with costs and billing period
call stats({ detailed: true })
Returns: Full stats including costs, period, and totals
Cursor billing - spend limit and usage
call usage
Returns: { plan: "Ultra", onDemand: { used: 909.21, limit: 1000, remaining: 90.79, percentUsed: 91 } }
Current flow state
call flow
Returns: { score: 7.2, zone: "flow", status: "flowing", signals: { parallelism: 8, velocity: 9, ... },
sleepDebt: 25, sessionHours: 4.5, nudge: "In flow at 7.2/10. Keep going while it lasts." }
`$3
| Tool | Description |
|------|-------------|
|
slack_notify | Post a message to Slack (returns thread_ts for follow-up) |
| slack_check_replies | Get replies to a specific thread |
| slack_wait_reply | Block and poll until reply received or timeout |
| slack_ask | Post message + wait for reply in one call (for conversations) |
| slack_list_channels | List available channels |
| slack_add_reaction | Add emoji reaction to a message |
| slack_get_user | Get user profile information |
| slack_channel_history | Get recent channel messages |`bash
Post to default channel
call slack_notify({ message: "[QUESTION] Need input on auth approach" })
Returns: { ok: true, ts: "1234567890.123456", thread_ts: "1234567890.123456" }
Check for replies
call slack_check_replies({ channel_id: "C...", thread_ts: "1234567890.123456" })
Returns: { reply_count: 2, replies: [{ user: "U...", text: "Use OAuth" }] }
React to acknowledge
call slack_add_reaction({ channel_id: "C...", timestamp: "1234567890.123456", emoji: "thumbsup" })Wait for reply (blocks until reply or timeout)
call slack_wait_reply({ thread_ts: "1234567890.123456", timeout: 1800 })
Returns when user replies, or after 30 min timeout
{ status: "reply_received", replies: [{ user: "U...", text: "Use OAuth" }], waited_seconds: 45 }
Conversation mode - post + wait in one call
call slack_ask({ message: "Should we use OAuth or JWT?" })
Returns: { reply: "Use OAuth", thread_ts: "..." }
Continue the conversation in same thread
call slack_ask({ message: "What about refresh tokens?", thread_ts: "..." })
Returns: { reply: "Use rotating refresh tokens" }
`Configuration: Set these environment variables in
~/.cursor/mcp.json:`json
{
"mcpServers": {
"task-server": {
"command": "npx",
"args": ["-y", "mcp-task-server"],
"env": {
"SLACK_BOT_TOKEN": "xoxb-...",
"SLACK_CHANNEL_ID": "C..."
}
}
}
}
`Required Slack Bot Scopes:
channels:history, channels:read, chat:write, reactions:write, users:readAuto-notifications: The
handoff_task tool automatically posts to Slack when configured.Returns data from your Flow Control dashboard (
FLOW_API_URL env var, defaults to flow.reids.net.au):| Field | Description |
|-------|-------------|
|
today | Hours, commits, pipelines for today |
| thisWeek | Weekly totals |
| streak | Current and longest streak |
| recommendation | continue/pause/stop with message |
| costs (detailed) | Usage and subscription costs |
| period (detailed) | Billing cycle start/end dates |
| totals (detailed) | Active days, estimated hours, projects |File Format:
`markdown
Content Context
Current State
| Property | Value |
|----------|-------|
| Last update | 2026-02-01 |Published Content
- Post 1: Title (2026-01-15)
- Post 2: Title (2026-01-20)Themes Covered
- Theme A
- Theme BContent Locations
| Type | Location |
|------|----------|
| Draft posts | ~/drafts |
| Published | ~/published |
`$3
| Tool | Description |
|------|-------------|
|
help | List all available tools with descriptions and parameters |
| get_version | Get server version and workspace detection info |
| diagnose | Diagnose MCP configuration, paths, and workspace detection |
| show_memory | Show shared context memories from ~/.cursor/shared-context.json |
| update_memory | Create, update, sync, or delete memories (sync matches by title) |`bash
List all tools
call help
Returns: { server, version, usage, tool_count: 44, tools: [...] }
Get help for specific tool
call help({ tool: "update_memory" })
Returns: { name, description, usage: "call update_memory", parameters: {...} }
Check version and workspace
call get_version
Returns: { version: "x.x.x", workspace: { root: "/path", source: "found .git" } }
Diagnose configuration
call diagnose # Basic info
call diagnose({ verbose: true }) # Include env vars and file checksShow all memories
call show_memorySearch for specific memories
call show_memory({ search: "writing" })Force reload from file (clears cache)
call show_memory({ reload: true })Sync a memory by title (recommended - avoids duplicates)
call update_memory({
action: "sync",
title: "Writing preferences",
content: "British English, ISO dates, no emojis..."
})Create a new memory (generates sequential ID)
call update_memory({
action: "create",
title: "Project conventions",
content: "Use TypeScript strict mode."
})Update an existing memory by ID
call update_memory({
action: "update",
id: "1",
title: "Writing preferences",
content: "Updated content..."
})Delete a memory
call update_memory({ action: "delete", id: "1" })Migrate old IDs to sequential (one-time)
call update_memory({ action: "migrate" })Analyse project and get suggestions for memory_bank
call analyse_projectFocus on specific area
call analyse_project({ focus: "tech" }) # Just tech stack
call analyse_project({ focus: "brief" }) # Just project brief
call analyse_project({ focus: "active" }) # Just current focus
call analyse_project({ focus: "architecture" }) # Just architecture
`Multi-Agent Mode
The server supports three agent roles:
$3
- Creates and organizes tasks
- Sets dependencies and priorities
- Analyses complexity
- Cannot execute tasks$3
- Claims and executes tasks
- Updates progress
- Adds subtasks during implementation
- Cannot create top-level tasks$3
- Reviews completed work
- Approves or rejects with feedback
- Cannot claim or modify tasks$3
`bash
Solo mode (no role required)
call add_task({ title: "Build login page" })Multi-agent mode (explicit identification)
call add_task({
title: "Build login page",
description: "Create a secure login page with form validation",
agent_id: "planner-1",
role: "planner"
})call claim_task({
task_id: "5",
agent_id: "worker-1",
role: "worker"
})
`Project Structure
After running
init_project:`
your-project/
├── agent-kit/
│ ├── AGENT_RULES.md # Role definitions and permissions
│ ├── KICKOFF.md # Session startup checklist
│ ├── TASKS.md # Task reference (points to memory_bank)
│ ├── HANDOFF.md # Handoff protocol reference
│ └── SHARED_CONTEXT.md # Shared context documentation
├── memory_bank/
│ ├── architecture/
│ │ ├── architecture.md # High-level architecture overview
│ │ ├── tech.md # Technical stack and context
│ │ ├── models.md # Data models
│ │ ├── services.md # System services
│ │ ├── deployment.md # Deployment guide
│ │ ├── kubernetes.md # Kubernetes deployment (if applicable)
│ │ └── webhooks.md # Webhooks implementation (if applicable)
│ ├── context/
│ │ ├── context.md # Context index
│ │ ├── brief.md # Project overview
│ │ ├── active.md # Current focus
│ │ ├── product.md # Product context
│ │ ├── canvas.md # Lean canvas
│ │ └── changelog.md # Change log
│ ├── execution/
│ │ ├── execution.md # Execution overview
│ │ ├── progress.md # Task summary (auto-synced)
│ │ ├── decisions.md # Decision log
│ │ ├── debug.md # Debug diary
│ │ └── git.md # Git setup and code quality
│ ├── reference/
│ │ └── README.md # Reference materials folder
│ └── tasks/
│ ├── tasks.json # Task registry (source of truth)
│ ├── task_001.txt # Detailed task file
│ ├── task_002.txt # ...
│ └── ...
└── .cursor/
└── rules/
├── agent-workflow.mdc # Task management protocol
├── wellness-check.mdc # Break reminders
└── shared-context-sync.mdc # Memory sync guidance
`The full structure includes 28 template files covering architecture, context, execution tracking, and cursor rules.
Migration from v1.x
If you have existing
.taskmaster/tasks.json:1. Run any task command (e.g.,
list_tasks)
2. The server auto-migrates to memory_bank/tasks/
3. Individual task files are generated
4. Progress summary is updatedPublishing to npm
$3
`bash
publish-mcp
`The
publish-mcp script (in ~/scripts/) handles everything:
1. Prompts for version bump (patch/minor/none)
2. Updates VERSION constant in source
3. Builds the project
4. Publishes to npm$3
#### 1. Create npm Token
1. Go to npmjs.com/settings/~/tokens
2. Click Generate New Token → Granular Access Token
3. Configure:
- Token name:
mcp-task-server-publish
- Bypass two-factor authentication (2FA): ✓ Check this (required for CLI)
- Allowed IP ranges: Optional - add your IP as x.x.x.x/32
- Packages and scopes: Read and write → All packages
- Expiration: 90 days (maximum)
4. Copy the token immediatelyNote: npm no longer supports TOTP authenticator apps for new 2FA setups. Automation tokens with "Bypass 2FA" are required for scripted publishing.
#### 2. Add Token to Shell
`bash
echo 'export NPM_TOKEN="npm_xxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc
`$3
`bash
cd /path/to/mcp-task-server
npm version patch # or minor/major
npm run build
npm publish --//registry.npmjs.org/:_authToken=$NPM_TOKEN
`$3
`bash
npm info mcp-task-server
`$3
- Regenerate tokens before 90-day expiry
- Use IP restrictions for static IPs
- Never commit tokens to git
Development
`bash
Install dependencies
npm installBuild
npm run buildWatch mode
npm run devTest locally before publishing
npm pack # Creates .tgz file for inspection
`$3
To test changes without publishing, create a per-project MCP config that points to your local build:
`json
// .cursor/mcp.json (in this project)
{
"mcpServers": {
"task-server": {
"command": "node",
"args": ["/Users/andy/Projects/tools/mcp-task-server/dist/index.js"]
}
}
}
`This overrides the global config only for this workspace. Other projects continue using the npm version.
After making changes:
1. Run
npm run build
2. Reload Cursor (Cmd+Shift+P → "Developer: Reload Window")
3. Test with call help` to verify tools are availableMIT