# TaskFlow MCP

<div align="center">

[![npm version](https://badge.fury.io/js/mcp-taskflow.svg)](https://badge.fury.io/js/mcp-taskflow)

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

**[Quick Start](#quick-start-)** • **[Client Setup](#client-setup-)** • **[Tools](#tools-overview-)** • **[Documentation](#documentation-)**

</div>

## Table of Contents 📌

- [Overview](#overview-)
- [Why Use It](#why-use-it-)
- [How It Augments Modern AI Tools](#how-it-augments-modern-ai-tools-)
- [What Is MCP?](#what-is-mcp-)
- [How TaskFlow Works](#how-taskflow-works-)
- [Quick Start](#quick-start-)
- [Installation](#installation-)
- [Basic Usage](#basic-usage-)
- [Client Setup](#client-setup-)
- [Tools Overview](#tools-overview-)
- [Example: Agent-in-the-Loop (ReBAC Feature)](#example-agent-in-the-loop-rebac-feature-)
- [Documentation](#documentation-)
- [Development](#development-)
- [Versioning](#versioning-)
- [Release and Git-Based Usage](#release-and-git-based-usage-)
- [License](#license-)
- [Credit](#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.

```mermaid
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 🚀

```bash
pnpm install
pnpm build
pnpm start
```

## Installation 📦

```bash
# npm
npm install

# yarn
yarn install

# pnpm
pnpm install
```

## Basic Usage ▶️

### Start the server

```bash
pnpm start
```

### Configure data directory (optional)

```bash
# 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`)

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

### Claude Desktop (settings JSON)

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

### Codex (config.toml)

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

```text
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:

```text
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](./docs/API.md)** | Tool overview and API surface |
| **[docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)** | High-level architecture |
| **[docs/PERFORMANCE.md](./docs/PERFORMANCE.md)** | Benchmarks and performance targets |
| **[AI_AGENT_QUICK_REFERENCE.md](./AI_AGENT_QUICK_REFERENCE.md)** | Agent workflow reference |
| **[SECURITY.md](./SECURITY.md)** | Threat model and controls |
| **[CONTRIBUTING.md](./CONTRIBUTING.md)** | Contribution workflow and changesets |
| **[CHANGELOG.md](./CHANGELOG.md)** | Release notes |

## Development 🛠️

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

```bash
# 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](./LICENSE.md)**.

## Credit 🙏

Inspired by:

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

Also informed by related MCP server patterns and workflows:

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