jamischarles/projects-tasks-todos-mcp

Projects-Tasks-Todos (PTT) MCP Server

A hierarchical productivity system built as an MCP server, inspired by your existing markdown-based workflow. Manage projects, tasks, and todos with cross-chat focus tracking and human-readable markdown storage.

Features

Core Hierarchy

• Projects → Tasks → Todos
• Inbox system for quick brain dumps
• Promote/Demote functionality between levels

Focus Management

• Global current task tracking across all chats
• Context switch counting and focus rules
• Primary/secondary project allocation

Storage Format

• Human and machine readable Markdown files
• Matches your existing productivity system structure
• Local project data + global focus state

Key Capabilities

• ✅ Leverage scoring (1-10) for prioritization
• ✅ Time allocation tracking
• ✅ Strategic context documentation
• ✅ Cross-chat memory and focus persistence
• ✅ Inbox → Task → Project promotion flow
• ✅ Weekly objectives and decision points

Installation

1. Clone and build:

cd projects-tasks-todos-mcp
npm install
npm run build

2. Add to your MCP client configuration:

{
  "mcpServers": {
    "ptt": {
      "command": "node",
      "args": ["/path/to/projects-tasks-todos-mcp/dist/index.js"],
      "env": {
        "PTT_LOCAL_DIR": "./.ptt",
        "PTT_GLOBAL_FOCUS_PATH": "~/.ptt/current-focus.yaml"
      }
    }
  }
}

Quick Start

Create your first project:

ptt_create_project
  name: "MCP Development"
  leverage_score: 8
  time_allocation: 70
  strategic_context: "Building AI productivity tools with compound value"

Add items to inbox:

ptt_add_to_inbox
  project_name: "MCP Development"  
  content: "Research Toggl API integration patterns"

Promote inbox item to task:

ptt_promote_to_task
  project_name: "MCP Development"
  item_content: "Research Toggl API"
  task_title: "Implement Toggl Integration"
  leverage_score: 7
  strategic_value: "Enable time tracking for productivity insights"

Start working on a task:

ptt_start_task
  project_name: "MCP Development"
  task_title: "Implement Toggl Integration"

File Structure

Each project creates a folder with these markdown files:

.ptt/
├── project-name/
│   ├── README.md          # Project overview, leverage score, status
│   ├── inbox.md           # Quick brain dumps, unorganized ideas
│   ├── tasks.md           # Organized tasks with todos and deadlines
│   ├── current-context.md # Current work context and notes
│   └── archive.md         # Completed tasks and decisions

Global focus tracking:

~/.ptt/
└── current-focus.yaml     # Current active task across all chats

MCP Tools Reference

Project Management

• ptt_create_project - Create new project
• ptt_list_projects - List all projects
• ptt_get_project - Get project details
• ptt_update_project - Update project properties
• ptt_archive_project - Archive completed project
• ptt_set_primary_project - Set as primary focus

Task Management

• ptt_create_task - Create task in project
• ptt_list_tasks - List project tasks
• ptt_get_task - Get task details
• ptt_start_task - Start working on task (sets focus)
• ptt_update_task_status - Update task status
• ptt_add_todo - Add todo to task
• ptt_complete_todo - Mark todo as completed

Inbox Management

• ptt_add_to_inbox - Quick brain dump to project inbox
• ptt_list_inbox - List inbox items
• ptt_review_inbox - Review unprocessed items
• ptt_promote_to_task - Promote inbox item to task
• ptt_archive_inbox_item - Archive low-value items

Promote/Demote Flow

• ptt_promote_to_task - Inbox → Task
• ptt_promote_to_project - Task → Project (for high-leverage tasks)
• ptt_demote_to_inbox - Task → Inbox (when task loses value)

Focus Management

• ptt_get_current_focus - See what you're working on
• ptt_switch_focus - Switch to different task
• ptt_stop_focus - Take a break
• ptt_focus_stats - Focus statistics and insights
• ptt_add_weekly_objective - Add weekly goal
• ptt_set_project_priority - Set primary/secondary projects

System Status

• ptt_status - Overall system status

Design Philosophy

Leverage-Driven Prioritization

• All tasks scored 1-10 for leverage/impact
• Only 6+/10 leverage items promoted to tasks
• Only 8+/10 leverage tasks become projects

Single-Task Focus Principle

• One active task at a time across all chats
• Context switch tracking for focus awareness
• Global state shared between chat sessions

Human-Readable Storage

• All data stored in markdown format
• Compatible with existing note-taking workflows
• Version controllable and grep-searchable

Inbox-First Workflow

1. Brain dump ideas to project inbox
2. Review inbox periodically
3. Promote high-leverage items to tasks
4. Focus on one task at a time
5. Archive completed work

Later Features (Currently in Inbox)

These advanced features are planned for future releases:

• AI Context & Memory: Cross-chat memory with context summarization
• Status Summaries: Auto-generate standup updates and progress reports
• Blocker Tracking: Identify and report blockers across projects
• Toggl Integration: Bi-directional sync with Toggl time tracking
• Export Capabilities: Generate reports for Jira, meetings, etc.

Environment Variables

• PTT_LOCAL_DIR - Local project data directory (default: ./.ptt)
• PTT_GLOBAL_FOCUS_PATH - Global focus file path (default: ~/.ptt/current-focus.yaml)

Contributing

This project follows the PTT methodology itself! Check the project's own .ptt/ folder to see the system in action managing its own development.