# Task Manager MCP Server

AI‑powered task management system for AI agents. Maps tasks, picks daily work, tracks velocity, and integrates with agent‑modes session context.

## Features

- **Task board** with backlog/ready/in‑progress/done columns
- **Daily planning** – pick tasks for today, log completions
- **Velocity tracking** – empirical tasks/day based on recent logs
- **Forecasting** – predict when backlog will be cleared
- **Session integration** – scan recent agent‑modes context notes for work signals
- **Rule‑based AI recommendations** – suggests daily tasks based on priority, dependencies, category balance, and recent completion
- **DeepSeek AI integration** – smarter recommendations, task parsing, session analysis, and summarization

## Tools

### Task Management
- `create_task` – add a new task (title, category, priority, etc.)
- `get_task` – retrieve a single task by ID
- `list_tasks` – list tasks with optional filtering (category, status, tags)
- `update_task` – modify any task field
- `delete_task` – remove a task

### Daily Planning
- `get_daily_log` – get today’s (or any date’s) planned/completed tasks
- `plan_day` – add task IDs to today’s plan
- `complete_tasks` – mark tasks as done (updates daily log and task status)
- `list_daily_logs` – list logs within a date range
- `get_daily_summary` – generate completion rate and category breakdown

### Projections
- `get_projections` – retrieve current velocity and forecast
- `update_velocity` – recalculate velocity from recent completions
- `forecast_completion` – estimate when backlog will be finished

### Session Integration
- `scan_recent_sessions` – scan agent‑modes session context notes from the last N days

### AI‑Assisted Planning
- `recommend_daily_tasks` – rule‑based recommendation for today’s tasks (priority, dependencies, category balance, recent history)
- `recommend_daily_tasks_ai` – DeepSeek-powered recommendations with sophisticated reasoning
- `analyze_session_for_tasks` – parse agent‑modes session notes to detect task completion and progress
- `parse_natural_language_task` – convert informal descriptions into structured tasks
- `summarize_task_description` – create concise, clear summaries of lengthy task descriptions
- `generate_weekly_summary` – AI‑written narrative summary of weekly productivity

## Data Storage

All data is stored in `.opencode/tasks/` as JSON files:
- `tasks.json` – all tasks
- `daily‑logs.json` – daily plans and completions
- `projections.json` – velocity and forecast

## Integration with Agent‑Modes

The server reads `.opencode/sessions/<id>/context.md` files to detect work‑completion signals (future enhancement: auto‑update task status based on session notes).

## Usage in OpenCode

Once registered in `opencode.json`, the tools are available to all agents (subject to agent‑level permissions). Example:

```bash
# Create a coding task
task_manager create_task title="Implement user auth" category=coding priority=1

# Plan today’s work
task_manager plan_day task_ids=["task-id-1","task-id-2"]

# Get recommendations (rule-based)
task_manager recommend_daily_tasks max_tasks=3 category=coding

# Get AI-powered recommendations
task_manager recommend_daily_tasks_ai max_tasks=3 use_ai_reasoning=true

# Parse natural language into structured task
task_manager parse_natural_language_task description="need to fix the login bug that happens on mobile safari"

# Analyze session notes for task completion
task_manager analyze_session_for_tasks session_id="20250304T123456Z_abc123"

# Generate weekly summary
task_manager generate_weekly_summary start_date="2025-03-01" end_date="2025-03-07"

# Mark tasks as done
task_manager complete_tasks task_ids=["task-id-1"]

# Check velocity
task_manager update_velocity days=7
task_manager forecast_completion
```

## Configuration

The server is registered in `opencode.json` under the key `task_manager`. It runs as a local stdio MCP server.

### DeepSeek API Key

For AI features, set the `DEEPSEEK_API_KEY` environment variable. The server includes a default key for testing, but for production use you should:
1. Get your own API key from [DeepSeek Platform](https://platform.deepseek.com/)
2. Set it as environment variable or replace the default in `llm‑bridge.mjs`

```bash
export DEEPSEEK_API_KEY=your_key_here
# or on Windows:
set DEEPSEEK_API_KEY=your_key_here
```

## Development

Files:
- `server.mjs` – MCP transport boilerplate
- `core.mjs` – tool definitions and execution router
- `task‑store.mjs` – persistence layer (JSON files)
- `daily‑planner.mjs` – rule‑based recommendation logic
- `llm‑bridge.mjs` – DeepSeek API integration for AI features
- `README.md` – this file

## Next Steps (Planned)

**✅ Implemented**
1. **LLM bridge** – DeepSeek API integration for smarter recommendations, task parsing, and summarization
2. **Session integration** – scan agent‑modes context notes (manual analysis via `analyze_session_for_tasks`)

**🔄 Remaining**
3. **Auto‑completion** – automatically update task status based on session notes (future enhancement)
4. **Custom OpenCode commands** – e.g., `/task‑board`, `/plan‑today`
5. **Initial seed** – pre‑populate with example tasks from existing projects
6. **Web UI** – optional browser‑based task board visualization