TaskFlow MCP

A local Model Context Protocol (MCP) server that gives AI agents structured task planning, execution tracking, and guided research workflows.

Quick Start • Client Setup • Tools • Documentation

Table of Contents 📌

• Overview
• Why Use It
• How It Augments Modern AI Tools
• What Is MCP?
• How TaskFlow Works
• Quick Start
• Installation
• Basic Usage
• Client Setup
• Tools Overview
• Example: Agent-in-the-Loop (ReBAC Feature)
• Documentation
• Development
• Versioning
• Release and Git-Based Usage
• License
• Credit

Overview ✨

TaskFlow MCP helps agents turn vague goals into concrete, trackable work. It provides a persistent task system plus research and reasoning tools so agents can plan, execute, and verify tasks without re‑sending long context every time.

Why Use It ✅

• Lower token use: retrieve structured task summaries instead of restating context.
• Smarter workflows: dependency‑aware planning reduces rework.
• Better handoffs: tasks, notes, and research state persist across sessions.
• More reliable execution: schemas validate tool inputs.
• Auditability: clear task history, verification, and scores.

How It Augments Modern AI Tools 🧭

TaskFlow MCP complements modern AI tooling. Tools like GitHub CLI and Skills help with repo workflows and onboarding, while TaskFlow MCP focuses on durable task state, structured planning/execution, and repeatable workflows across sessions. Use it to add persistent task memory and structured agent prompts on top of your existing toolchain.

What Is MCP? 🤔

MCP is a standard way for AI tools to call external capabilities over JSON‑RPC (usually STDIO). This server exposes tools that an agent can invoke to plan work, track progress, and keep context consistent across long sessions.

How TaskFlow Works 🧭

TaskFlow MCP adds a structured workflow layer on top of normal LLM chat. The server validates tool inputs and returns deterministic, structured prompts for planning and research, while persisting task state on disk so agents can resume without re‑sending long context.

flowchart LR
  subgraph Host["MCP Host: VS Code"]
    subgraph Client["MCP Client"]
      Agent["Agent / Model"]
    end
  end

  Agent -- "JSON-RPC (STDIO)" --> Server["MCP Server (taskflow)"]
  Server -- "Structured prompts / results" --> Agent
  Server --> Store["Data Store (DATA_DIR/.mcp-tasks)"]

In practice:

• The host runs the MCP client and the model.
• The client calls MCP tools over JSON‑RPC via STDIO.
• The server validates inputs, builds structured prompts, and returns them to the client.
• The data store keeps task state across sessions so the agent can resume without context loss.

Quick Start 🚀

pnpm install
pnpm build
pnpm start

Installation 📦

# npm
npm install

# yarn
yarn install

# pnpm
pnpm install

Basic Usage ▶️

Start the server

pnpm start

Configure data directory (optional)

# PowerShell
$env:DATA_DIR="${PWD}\.mcp-tasks"

Client Setup 📎

Use npx to run the MCP server directly from GitHub. Replace <DATA_DIR> with your preferred data path.

Path examples:

• Windows: <DATA_DIR> = C:\repos\mcp-taskflow\.mcp-tasks
• macOS/Linux: <DATA_DIR> = /Users/you/repos/mcp-taskflow/.mcp-tasks

VS Code (.vscode/mcp.json)

{
  "servers": {
    "mcp-taskflow": {
      "type": "stdio",
      "command": "npx",
      "args": ["mcp-taskflow"],
      "env": {
        "DATA_DIR": "<DATA_DIR>"
      }
    }
  }
}

Claude Desktop (settings JSON)

{
  "mcpServers": {
    "mcp-taskflow": {
      "command": "npx",
      "args": ["mcp-taskflow"],
      "env": { "DATA_DIR": "<DATA_DIR>" }
    }
  }
}

Codex (config.toml)

[mcp_servers.mcp-taskflow]
type = "stdio"
command = "npx"
args = ["mcp-taskflow"]
env = { DATA_DIR="<DATA_DIR>" }
startup_timeout_sec = 120

Tools Overview 🧰

TaskFlow MCP exposes a focused toolset. Most clients surface these as callable actions for your agent.

Planning

• plan_task: turn a goal into a structured plan
• split_tasks: split a plan into discrete tasks with dependencies
• analyze_task: capture analysis and rationale
• reflect_task: record reflections and improvements

Task Management

• list_tasks: list tasks by status
• get_task_detail: show full details for a task
• query_task: search tasks by keyword or ID
• create_task: create a task directly
• update_task: update status, notes, dependencies, or metadata
• delete_task: remove a task by ID
• clear_all_tasks: clear the task list

Workflow

• execute_task: mark a task in progress and generate an execution prompt
• verify_task: score and mark a task complete

Research & Project

• research_mode: guided research with state tracking
• process_thought: capture a structured reasoning step
• init_project_rules: create or refresh project rules
• get_server_info: get server status and task counts

Example: Agent-in-the-Loop (ReBAC Feature) 🧪

Below is a simple, human‑readable script that shows how a user might ask an agent to plan and execute a feature. The agent uses TaskFlow MCP tools behind the scenes, but you don’t need MCP details to follow the flow.

Plain Chat vs TaskFlow (ReBAC Example)

Without TaskFlow (plain chat) Prompt:

Create a ReBAC system from scratch.

Typical outcome:

• The model returns a large, one‑shot answer.
• No durable task list or dependencies.
• Hard to resume later without re‑explaining context.
• Team members have no shared, structured view of progress.

With TaskFlow (structured workflow) Prompt:

Create a ReBAC system from scratch. Plan the work, split tasks, then execute and verify.

Typical outcome:

• The model generates a plan via plan_task.
• Tasks are created and tracked via split_tasks (with dependencies).
• Each task is executed and marked in progress via execute_task.
• Results are verified and scored via verify_task, with adjustments logged.
• State is persisted in the datastore, so anyone can list_tasks and get_task_detail to continue or review.

Why this matters for teams

• The task list, notes, and verification results are stored on disk and can be shared in the repo or a shared data directory.
• A teammate can open the same workspace and immediately see the current task state without reading long chat history.

Dependency management

• Tasks can declare explicit prerequisites, so the agent knows what must happen first.
• Dependencies prevent blocked work: a task can’t be executed until its upstream tasks are complete.
• Dependencies are stored with tasks, so any teammate can see the critical path and pick up the next unblocked item.
• For example: “Integrate with existing auth” cannot start until both “Define ReBAC model” and “Design storage layer” are completed.

User “I want to add a Relationship‑Based system. Create a task list and start working through it.”

Agent “I’ll plan the work, split it into tasks, and track progress as we go.”

Agent (planning summary) “Here’s a structured plan with dependencies and a clear execution order.”

1. Define the ReBAC model
   • Entities, relations, and permission checks
   • Identify critical query patterns
2. Design the storage layer
   • Graph storage schema and indexes
   • Query strategy for path checks
3. Implement the policy engine
   • Relationship evaluation
   • Cached query results
4. Integrate with existing auth
   • Request context mapping
   • Backward compatibility
5. Add tests and benchmarks
   • Unit tests for rules
   • Integration tests for policy decisions

Agent (starts work) “I’ll mark the first task as in progress and add notes as I go.”

Progress updates

• Task 1: In progress — “Drafted entity/relationship schema and example checks”
• Task 1: Completed — “Added model doc and validation rules”
• Task 2: In progress — “Evaluating graph storage options”

Task verification example (with scoring and challenges) Agent “I’ve verified Task 1 and logged a score.”

• Score: 92/100
• Checks passed: model completeness, schema validation, examples included
• Challenges: ambiguous relationship naming in legacy data; resolved by adding a normalization step and a short mapping table
• Next step: start Task 2 with the normalized model in place

Why this helps

• The agent keeps a durable task list and status updates.
• You can stop and resume without losing context.
• Large features become manageable, with explicit dependencies.

Documentation 📚

| Document | Purpose | |---|---| | docs/API.md | Tool overview and API surface | | docs/ARCHITECTURE.md | High-level architecture | | docs/PERFORMANCE.md | Benchmarks and performance targets | | AI_AGENT_QUICK_REFERENCE.md | Agent workflow reference | | SECURITY.md | Threat model and controls | | CONTRIBUTING.md | Contribution workflow and changesets | | CHANGELOG.md | Release notes |

Development 🛠️

pnpm test
pnpm type-check
pnpm lint

Versioning 🏷️

This project uses Changesets for versioning and release notes. See CONTRIBUTING.md for guidance.

Release and Git-Based Usage 🚢

Git-based execution assumes the repository is buildable and includes a valid bin entry in package.json. For production or shared use, prefer a tagged release published via Changesets.

Typical flow:

1. Add a changeset in your PR.
2. CI creates a release PR with version bumps and changelog entries.
3. Merging the release PR publishes to npm and creates a GitHub release.

Use git-based execution for fast testing; use npm releases for stable installs.

Git-based launch (recommended)

# pnpm
pnpm dlx git+https://github.com/CalebGerman/mcp-taskflow.git mcp-taskflow

# npx (fallback)
npx git+https://github.com/CalebGerman/mcp-taskflow.git mcp-taskflow

Prerequisites:

• bin entry points to dist/index.js
• pnpm build completes successfully

License 📄

MIT. See LICENSE.md.

Credit 🙏

Inspired by:

https://github.com/cjo4m06/mcp-shrimp-task-manager

Also informed by related MCP server patterns and workflows:

https://www.nuget.org/packages/Mcp.TaskAndResearch