MCP Task Server

A Model Context Protocol (MCP) server for task management with multi-agent coordination. Designed for use with Cursor IDE and other MCP-compatible AI tools.

Quick Publish

publish-mcp

This script (in ~/scripts/) bumps version, builds, and publishes to npm. Requires $NPM_TOKEN in your shell profile.

Cursor IDE Integration

Global Config (Recommended)

Add to ~/.cursor/mcp.json for all projects:

{
  "mcpServers": {
    "task-server": {
      "command": "npx",
      "args": ["-y", "mcp-task-server"]
    }
  }
}

The server auto-detects your workspace. No per-project config needed.

Per-Project Config (Optional)

For explicit control, add to .cursor/mcp.json in your project:

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

Usage

Invoke any tool with call <tool_name>:

| Command | Description | |---------|-------------| | call help | List all 27 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.

flowchart TB
    subgraph Cursor IDE
        A[AI Assistant]
    end
    
    subgraph MCP Task Server
        B[27 Tools]
        C[Preferences Engine]
    end
    
    subgraph Your Machine
        D[~/.cursor/shared-context.json]
        E[memory_bank/tasks/]
        F[memory_bank/execution/progress.md]
    end
    
    A <-->|MCP Protocol| B
    B --> C
    C -->|read/write| D
    B -->|read/write| E
    B -->|auto-sync| F
    D -->|inject into responses| A

Features

• 27 MCP Tools: Comprehensive task management and coordination
• 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 markdown summary
• Prompt-Based Operations: PRD parsing, task expansion, complexity analysis
• Shared Context: Reads user preferences from ~/.cursor/shared-context.json to personalise prompts
• Project Initialisation: Scaffolds 22 template files across agent-kit, memory_bank (architecture, context, execution, reference), and cursor rules

Quick Start

Note: For brand new empty projects, create at least one file first (e.g., touch README.md), then reload Cursor. See Troubleshooting for details.

# Add to a new project and initialise
call init_project({ project_name: "my-app" })

# Add your first task
call add_task({ title: "Set up development environment" })

# Get recommended next task
call next_task

Shared Context & Preferences

The server reads ~/.cursor/shared-context.json for user preferences and automatically injects them into tool responses and prompts.

How Preferences Flow

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]

Agent Workflow for Preferences

Before creating or reviewing content, agents should:

1. Call show_memory to check for user preferences
2. Look for writing_preferences category
3. Apply discovered preferences to all content

This is enforced by the Cursor rules in .cursor/rules/agent-workflow.mdc (per-project) and ~/.cursor/rules/writing-review.mdc (global).

Memory Storage Architecture

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

Managing Memories

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 |

The sync action is recommended because it matches by title, avoiding duplicates:

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:

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.

Why Shared Context Exists

Cursor's memory system has limitations that make shared context necessary:

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

Where Preferences Are Used

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

Compliance Checking

Validate files against your preferences:

# 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

Via npx (recommended)

npx mcp-task-server

Global Install

npm install -g mcp-task-server
mcp-task-server

From Source

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.

Detection Order

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 |

Debugging

Run call get_version to see how the workspace was detected:

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

Explicit Override

If auto-detection isn't working, set TASK_WORKSPACE in per-project config:

{
  "mcpServers": {
    "task-server": {
      "command": "npx",
      "args": ["-y", "mcp-task-server"],
      "env": {
        "TASK_WORKSPACE": "/absolute/path/to/project"
      }
    }
  }
}

Troubleshooting

Tools Not Available in Agent

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

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:

   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

Cached Old Version

Symptom: Server shows old version or missing tools after publishing update.

Fix: Clear the npx cache:

rm -rf ~/.npm/_npx

Then reload Cursor and start a new Agent chat.

Workspace Detected as Home Directory

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

Viewing MCP Logs

Cursor logs MCP server activity. To debug issues:

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

# Look 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 27 tools → Server connected successfully
• Workspace: /path → Shows detected workspace

Configuration

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 |

Storage Architecture

The server uses a scalable storage model with three layers:

1. JSON Registry (memory_bank/tasks/tasks.json)

Machine-readable source of truth containing task IDs, status, dependencies, and subtasks.

{
  "version": "2.0.0",
  "tasks": [
    {
      "id": "1",
      "title": "Project Setup",
      "status": "done",
      "priority": "high",
      "subtasks": [
        { "id": 1, "title": "Init project", "status": "done" }
      ]
    }
  ]
}

2. Task Files (memory_bank/tasks/task_XXX.txt)

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]
### Dependencies: None
### Description: Create initial project structure

3. Progress Summary (memory_bank/execution/progress.md)

High-level overview auto-generated from tasks.json:

# Implementation Progress

## Task Completion Summary

### Completed Tasks (3/5)
- Task 1: Project Setup
- Task 2: Database Schema

This architecture scales well for complex projects with many tasks and subtasks.

Tools

Project Initialisation

| Tool | Description | |------|-------------| | init_project | Initialise project with agent-kit, memory_bank, and cursor rules |

# Initialise with auto-detected project name
call init_project

# Initialise with custom name
call init_project({ project_name: "my-app" })

# Force overwrite existing files
call init_project({ force: true })

Core Tools

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

Multi-Agent Coordination

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

Task Breakdown

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

Prompt-Based Tools

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

Utility Tools

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

# List all tools
call help
# Returns: { server, version, usage, tool_count: 27, 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 checks

# Show all memories
call show_memory

# Search 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_project

# Focus 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:

Planner

• Creates and organizes tasks
• Sets dependencies and priorities
• Analyses complexity
• Cannot execute tasks

Worker

• Claims and executes tasks
• Updates progress
• Adds subtasks during implementation
• Cannot create top-level tasks

Judge

• Reviews completed work
• Approves or rejects with feedback
• Cannot claim or modify tasks

Example

# 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
│   ├── 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  # Cursor agent rules

The full structure includes 22 template files covering architecture, context, and execution tracking.

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 updated

Publishing to npm

Quick Publish (recommended)

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

One-Time Setup

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 immediately

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

echo 'export NPM_TOKEN="npm_xxxxxxxxxxxx"' >> ~/.zshrc
source ~/.zshrc

Manual Publishing

cd /path/to/mcp-task-server
npm version patch   # or minor/major
npm run build
npm publish --//registry.npmjs.org/:_authToken=$NPM_TOKEN

Verify Publication

npm info mcp-task-server

Token Security

• Regenerate tokens before 90-day expiry
• Use IP restrictions for static IPs
• Never commit tokens to git

Development

# Install dependencies
npm install

# Build
npm run build

# Watch mode
npm run dev

# Test locally before publishing
npm pack  # Creates .tgz file for inspection

License

MIT