From 139e13486e44fa7e5f7f2f6afd145d1c8f796a6b Mon Sep 17 00:00:00 2001 From: CalebGerman Date: Fri, 6 Feb 2026 08:31:26 -0600 Subject: [PATCH 1/6] updated docs --- mcp-taskflow-brief.md | 62 +++++++++++++ mcp-taskflow-deep-dive.md | 185 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 247 insertions(+) create mode 100644 mcp-taskflow-brief.md create mode 100644 mcp-taskflow-deep-dive.md diff --git a/mcp-taskflow-brief.md b/mcp-taskflow-brief.md new file mode 100644 index 0000000..4176a21 --- /dev/null +++ b/mcp-taskflow-brief.md @@ -0,0 +1,62 @@ +# MCP-Taskflow + +## Summary +MCP-Taskflow adds a structured workflow layer on top of normal LLM chat. It provides **deterministic, structured prompts** for planning and research so the model produces more consistent and efficient output, and it **persists state across sessions** so agents can resume work without re-sending long context. + +## Flow Diagram + +```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)"] +``` + +## What This Means 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. + +## Value Compared to No MCP Server (REBAC Example) +Long‑running work like “create a ReBAC system from scratch” benefits from persistent state and structured workflow. + +**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. +- This makes long efforts like ReBAC safer: design → schema → policy engine → integration → tests becomes an enforced order, not a suggestion. +- 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. diff --git a/mcp-taskflow-deep-dive.md b/mcp-taskflow-deep-dive.md new file mode 100644 index 0000000..b63766a --- /dev/null +++ b/mcp-taskflow-deep-dive.md @@ -0,0 +1,185 @@ +# MCP-Taskflow: Detailed Architecture Notes + +This document is a deeper walkthrough of the major pieces of the repo so you can answer technical questions confidently. + +## 1. System Overview +TaskFlow MCP is a local MCP server that exposes structured workflow tools over JSON-RPC via STDIO. A host (for example, VS Code) runs an MCP client that discovers tools and invokes them with JSON payloads. The server validates inputs, executes logic, and persists task state to disk so work can resume across sessions. + +Core layers: +- MCP Server (protocol handling + tool registration) +- Tools layer (task workflow, research, thought, project metadata) +- Data layer (task persistence, rules, snapshots) +- Prompt layer (templated, consistent output) +- Validation and security (Zod schemas, path sanitization, size limits) + +## 2. MCP Server Layer +**Purpose**: Implements the MCP JSON-RPC interface, registers tools, and manages request/response flow. + +**Key behaviors**: +- Runs locally over STDIO (no network exposure). +- Tool registration is centralized in the server bootstrapping. +- All tool handlers are called through a common execution path that validates inputs and returns structured responses. + +**Where**: +- `src/server/mcpServer.ts` +- `src/index.ts` + +## 3. Tools Layer +**Purpose**: The API surface exposed to the MCP client. Each tool is an operation the agent can call. + +### 3.1 Task Planning and Workflow Tools +- `plan_task`: Turn a goal into a structured plan. +- `split_tasks`: Break the plan into discrete tasks with dependencies. +- `analyze_task`: Capture analysis and rationale. +- `reflect_task`: Record lessons learned or improvements. +- `execute_task`: Mark a task in progress and generate execution context. +- `verify_task`: Score and mark a task complete with summary notes. + +### 3.2 Task Management (CRUD) +- `list_tasks`: List tasks by status. +- `get_task_detail`: Fetch full task details. +- `query_task`: Search tasks by keyword or ID. +- `create_task`: Directly create a task without planning. +- `update_task`: Modify status, dependencies, notes, metadata. +- `delete_task`: Remove a task. +- `clear_all_tasks`: Clear all tasks (with confirmation). + +### 3.3 Research and Thought Tools +- `research_mode`: Guided research workflow with state tracking. +- `process_thought`: Record a structured reasoning step. + +### 3.4 Project Tools +- `init_project_rules`: Create or refresh project rules. +- `get_server_info`: Return server status and task counts. + +**Where**: +- `src/tools/task/` +- `src/tools/research/` +- `src/tools/thought/` +- `src/tools/project/` + +## 4. Data Layer (Persistence) +**Purpose**: Persist tasks, rules, and history across sessions using local JSON files. + +### 4.1 Task Store +- Stores tasks in `tasks.json` under the configured `DATA_DIR`. +- Uses atomic read-modify-write and a write queue for safety. +- Maintains timestamps and status transitions. +- Caches last read to reduce file I/O. + +**Where**: +- `src/data/taskStore.ts` +- `src/data/fileOperations.ts` + +### 4.2 Rules Store +- Stores project-specific rules in `taskflow-rules.md` under `DATA_DIR`. +- Enforces max file size and basic validation. + +**Where**: +- `src/data/rulesStore.ts` + +### 4.3 Memory Store (Snapshots and Backups) +- Supports task snapshots and history in a `memory/` folder. +- Supports completed-task backups in a `backups/` folder. +- Implements filename sanitization and size limits. + +**Where**: +- `src/data/memoryStore.ts` + +**Note**: The `clear_all_tasks` path currently returns no backup in `TaskStore` (there is a TODO to integrate backups), but the `MemoryStore` capability exists. + +## 5. Validation Layer (Zod) +**Purpose**: Enforce runtime safety and protect against malformed inputs or oversized payloads. + +Key protections: +- UUID validation for task IDs. +- String length limits for names, descriptions, notes, summaries. +- Enumerated status values only. +- Pagination limits for queries. + +**Where**: +- `src/data/schemas.ts` + +## 6. Prompt Layer (Template Engine + Builders) +**Purpose**: Produce consistent, readable responses and execution prompts. + +### 6.1 Template Engine +- Simple token replacement (no external dependencies). +- Supports `{{key}}`, `{{ key }}`, and `{key}` formats. + +**Where**: +- `src/prompts/templateEngine.ts` + +### 6.2 Template Loader +- Loads markdown templates from disk and caches them. +- Resolves template paths safely and prevents directory traversal. + +**Where**: +- `src/prompts/templateLoader.ts` +- `src/prompts/templates/v1/templates_en/` + +### 6.3 Prompt Builders +- Compose data into templates for output and tool guidance. + +**Where**: +- `src/prompts/taskPromptBuilders.ts` +- `src/prompts/projectPromptBuilder.ts` +- `src/prompts/researchPromptBuilder.ts` +- `src/prompts/thoughtPromptBuilder.ts` + +## 7. Configuration and Path Security +**Purpose**: Ensure all file access stays within controlled directories. + +Key behavior: +- Workspace root is resolved from `MCP_WORKSPACE_ROOT`, then `cwd`, then home directory. +- `DATA_DIR` defaults to `.mcp-tasks` under workspace root. +- Path sanitization prevents traversal outside allowed directories. + +**Where**: +- `src/config/pathResolver.ts` + +## 8. Security Controls +**Purpose**: Reduce attack surface and prevent misuse from untrusted inputs. + +Controls in codebase: +- Zod validation for all tool inputs. +- Path sanitization and containment checks. +- Size limits on task data and rules files. +- Local STDIO transport (no exposed network port). + +**Where**: +- `SECURITY.md` +- `src/data/schemas.ts` +- `src/config/pathResolver.ts` + +## 9. Logging and Observability +**Purpose**: Structured logging and safe error handling. + +Key points: +- Logs are structured (Pino-based) and avoid leaking sensitive info. +- Errors returned to the user are safe and generic, while server logs contain detail. + +**Where**: +- `src/server/logger.ts` + +## 10. Testing and Benchmarks +**Purpose**: Ensure protocol compliance, tool correctness, and performance baselines. + +Test coverage highlights: +- MCP protocol compliance integration tests. +- Tool behavior tests by category. +- Performance tests in integration suite. + +**Where**: +- `tests/integration/` +- `tests/tools/` +- `benchmarks/` + +## 11. What People Commonly Miss +- The **template engine and cached loader** are important for consistent outputs and performance. +- The **memory/backup system** exists but is not fully wired into task clearing (TODO in TaskStore). +- **Path sanitization** and workspace resolution are key security mechanisms. +- The **rules system** (`taskflow-rules.md`) is part of the persistence story, not just tasks. + +## 12. Practical Takeaway +This repo is not just a set of tools: it is a structured workflow system with strong runtime validation, persistent state, and consistent prompt output. That combination is what makes it more reliable and scalable than a plain chat session. From 747862d6d62566a08a5fa03722bc5105878b1f2b Mon Sep 17 00:00:00 2001 From: CalebGerman Date: Fri, 6 Feb 2026 09:33:09 -0600 Subject: [PATCH 2/6] Fixed errors related with get task details --- src/prompts/taskPromptBuilders.ts | 17 ++++++++++------- .../v1/templates_en/getTaskDetail/completed.md | 5 +++++ .../v1/templates_en/getTaskDetail/index.md | 4 ++-- tests/prompts/templateMigration.test.ts | 2 +- 4 files changed, 18 insertions(+), 10 deletions(-) create mode 100644 src/prompts/templates/v1/templates_en/getTaskDetail/completed.md diff --git a/src/prompts/taskPromptBuilders.ts b/src/prompts/taskPromptBuilders.ts index 61bd0d0..4022cb7 100644 --- a/src/prompts/taskPromptBuilders.ts +++ b/src/prompts/taskPromptBuilders.ts @@ -419,13 +419,16 @@ export class GetTaskDetailPromptBuilder { return render(template, { id: task.id, name: task.name, + status: taskStatusToString(task.status), description: task.description, - dependenciesPrompt: await this.buildDependenciesPrompt(task.dependencies, allTasks), - implementationGuidePrompt: this.buildImplementationGuidePrompt(task.implementationGuide ?? undefined), - verificationCriteriaPrompt: this.buildVerificationCriteriaPrompt(task.verificationCriteria ?? undefined), - notesPrompt: this.buildNotesPrompt(task.notes ?? undefined), - relatedFilesSummaryPrompt: await this.buildRelatedFilesPrompt(task.relatedFiles), - completedSummaryPrompt: await this.buildCompletedSummaryPrompt(task) + dependenciesTemplate: await this.buildDependenciesPrompt(task.dependencies, allTasks), + implementationGuideTemplate: this.buildImplementationGuidePrompt(task.implementationGuide ?? undefined), + verificationCriteriaTemplate: this.buildVerificationCriteriaPrompt(task.verificationCriteria ?? undefined), + notesTemplate: this.buildNotesPrompt(task.notes ?? undefined), + relatedFilesTemplate: await this.buildRelatedFilesPrompt(task.relatedFiles), + createdTime: formatDate(task.createdAt), + updatedTime: formatDate(task.updatedAt), + completedSummaryTemplate: await this.buildCompletedSummaryPrompt(task) }); } @@ -474,7 +477,7 @@ export class GetTaskDetailPromptBuilder { }) .join('\n'); - return render(template, { filesList }); + return render(template, { files: filesList }); } private groupFilesByType( diff --git a/src/prompts/templates/v1/templates_en/getTaskDetail/completed.md b/src/prompts/templates/v1/templates_en/getTaskDetail/completed.md new file mode 100644 index 0000000..4bb67c1 --- /dev/null +++ b/src/prompts/templates/v1/templates_en/getTaskDetail/completed.md @@ -0,0 +1,5 @@ +**Completion Time:** {completedAt} + +**Completion Summary:** + +{completedSummary} diff --git a/src/prompts/templates/v1/templates_en/getTaskDetail/index.md b/src/prompts/templates/v1/templates_en/getTaskDetail/index.md index 4d4e7c6..98bb8fd 100644 --- a/src/prompts/templates/v1/templates_en/getTaskDetail/index.md +++ b/src/prompts/templates/v1/templates_en/getTaskDetail/index.md @@ -6,7 +6,7 @@ **Status:** {status} -**Description:**{description} +**Description:** {description} {notesTemplate} @@ -22,4 +22,4 @@ **Update Time:** {updatedTime} -{complatedSummaryTemplate} +{completedSummaryTemplate} diff --git a/tests/prompts/templateMigration.test.ts b/tests/prompts/templateMigration.test.ts index 3509908..09feb0c 100644 --- a/tests/prompts/templateMigration.test.ts +++ b/tests/prompts/templateMigration.test.ts @@ -102,7 +102,7 @@ describe('Template Loading and Validation', () => { describe('Tool Templates - getTaskDetail', () => { const templates = [ - 'complatedSummary.md', + 'completed.md', 'dependencies.md', 'error.md', 'implementationGuide.md', From 5fe6e26a3f07982cc238bf28e7be5f8509f8e338 Mon Sep 17 00:00:00 2001 From: CalebGerman Date: Fri, 6 Feb 2026 09:33:51 -0600 Subject: [PATCH 3/6] Added changeset --- .changeset/upset-ravens-dance.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/upset-ravens-dance.md diff --git a/.changeset/upset-ravens-dance.md b/.changeset/upset-ravens-dance.md new file mode 100644 index 0000000..39fdedf --- /dev/null +++ b/.changeset/upset-ravens-dance.md @@ -0,0 +1,5 @@ +--- +'mcp-taskflow': patch +--- + +Added fix for missing template for get task details From edf2967a2560f95c54c8bb2e621d7854d608e13e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 6 Feb 2026 15:35:57 +0000 Subject: [PATCH 4/6] Release packages --- .changeset/upset-ravens-dance.md | 5 ----- CHANGELOG.md | 8 ++++++++ package.json | 2 +- 3 files changed, 9 insertions(+), 6 deletions(-) delete mode 100644 .changeset/upset-ravens-dance.md diff --git a/.changeset/upset-ravens-dance.md b/.changeset/upset-ravens-dance.md deleted file mode 100644 index 39fdedf..0000000 --- a/.changeset/upset-ravens-dance.md +++ /dev/null @@ -1,5 +0,0 @@ ---- -'mcp-taskflow': patch ---- - -Added fix for missing template for get task details diff --git a/CHANGELOG.md b/CHANGELOG.md index 70bc869..8c53d65 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Changelog +## 0.1.2 + +### Patch Changes + +### [0.1.2](https://www.npmjs.com/package/taskflow-mcp/v/0.1.2) - 2026-02-06 + +Added fix for missing template for get task details + ## 0.1.1 ### Patch Changes diff --git a/package.json b/package.json index 5d445ce..66eb3c7 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mcp-taskflow", - "version": "0.1.1", + "version": "0.1.2", "description": "MCP server for workflow orchestration, planning, and structured development", "type": "module", "engines": { From 858d3d05ca14a05d32459f45cfc76adbe5b98ff0 Mon Sep 17 00:00:00 2001 From: CalebGerman Date: Mon, 9 Feb 2026 11:05:43 -0600 Subject: [PATCH 5/6] Readme update --- .changeset/sparkly-coats-pick.md | 5 ++ README.md | 93 ++++++++++++++++++++++++++++++-- 2 files changed, 94 insertions(+), 4 deletions(-) create mode 100644 .changeset/sparkly-coats-pick.md diff --git a/.changeset/sparkly-coats-pick.md b/.changeset/sparkly-coats-pick.md new file mode 100644 index 0000000..6a0d7b4 --- /dev/null +++ b/.changeset/sparkly-coats-pick.md @@ -0,0 +1,5 @@ +--- +'mcp-taskflow': patch +--- + +Updated readme diff --git a/README.md b/README.md index 6a594b4..dca6bf0 100644 --- a/README.md +++ b/README.md @@ -1,30 +1,40 @@ # TaskFlow MCP +
+ [![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-)** +
## 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-) - -A local Model Context Protocol (MCP) server that gives AI agents structured task planning, execution tracking, and guided research workflows. +- [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 ✅ +## Why Use It ✅ - **Lower token use**: retrieve structured task summaries instead of restating context. - **Smarter workflows**: dependency‑aware planning reduces rework. @@ -32,10 +42,38 @@ TaskFlow MCP helps agents turn vague goals into concrete, trackable work. It pro - **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 @@ -77,6 +115,7 @@ $env:DATA_DIR="${PWD}\.mcp-tasks" Use `npx` to run the MCP server directly from GitHub. Replace `` with your preferred data path. Path examples: + - Windows: `` = `C:\repos\mcp-taskflow\.mcp-tasks` - macOS/Linux: `` = `/Users/you/repos/mcp-taskflow/.mcp-tasks` @@ -159,6 +198,49 @@ TaskFlow MCP exposes a focused toolset. Most clients surface these as callable a 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.” @@ -188,6 +270,7 @@ Below is a simple, human‑readable script that shows how a user might ask an ag “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” @@ -202,6 +285,7 @@ Below is a simple, human‑readable script that shows how a user might ask an ag - **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. @@ -235,6 +319,7 @@ This project uses **Changesets** for versioning and release notes. See `CONTRIBU 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. @@ -252,6 +337,7 @@ npx git+https://github.com/CalebGerman/mcp-taskflow.git mcp-taskflow ``` **Prerequisites**: + - `bin` entry points to `dist/index.js` - `pnpm build` completes successfully @@ -272,4 +358,3 @@ Also informed by related MCP server patterns and workflows: ```text https://www.nuget.org/packages/Mcp.TaskAndResearch ``` - From cd5bd893876ed116f9a8f60932661b871e1ef62c Mon Sep 17 00:00:00 2001 From: CalebGerman Date: Mon, 9 Feb 2026 11:11:06 -0600 Subject: [PATCH 6/6] Added git ignore --- .gitignore | 2 +- mcp-taskflow-brief.md | 62 ------------- mcp-taskflow-deep-dive.md | 185 -------------------------------------- 3 files changed, 1 insertion(+), 248 deletions(-) delete mode 100644 mcp-taskflow-brief.md delete mode 100644 mcp-taskflow-deep-dive.md diff --git a/.gitignore b/.gitignore index d2d15f8..85c8374 100644 --- a/.gitignore +++ b/.gitignore @@ -27,7 +27,7 @@ Thumbs.db # IDE files .vscode/* -!.vscode/mcp.json +.vscode/mcp.json .idea/ *.swp *.swo diff --git a/mcp-taskflow-brief.md b/mcp-taskflow-brief.md deleted file mode 100644 index 4176a21..0000000 --- a/mcp-taskflow-brief.md +++ /dev/null @@ -1,62 +0,0 @@ -# MCP-Taskflow - -## Summary -MCP-Taskflow adds a structured workflow layer on top of normal LLM chat. It provides **deterministic, structured prompts** for planning and research so the model produces more consistent and efficient output, and it **persists state across sessions** so agents can resume work without re-sending long context. - -## Flow Diagram - -```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)"] -``` - -## What This Means 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. - -## Value Compared to No MCP Server (REBAC Example) -Long‑running work like “create a ReBAC system from scratch” benefits from persistent state and structured workflow. - -**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. -- This makes long efforts like ReBAC safer: design → schema → policy engine → integration → tests becomes an enforced order, not a suggestion. -- 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. diff --git a/mcp-taskflow-deep-dive.md b/mcp-taskflow-deep-dive.md deleted file mode 100644 index b63766a..0000000 --- a/mcp-taskflow-deep-dive.md +++ /dev/null @@ -1,185 +0,0 @@ -# MCP-Taskflow: Detailed Architecture Notes - -This document is a deeper walkthrough of the major pieces of the repo so you can answer technical questions confidently. - -## 1. System Overview -TaskFlow MCP is a local MCP server that exposes structured workflow tools over JSON-RPC via STDIO. A host (for example, VS Code) runs an MCP client that discovers tools and invokes them with JSON payloads. The server validates inputs, executes logic, and persists task state to disk so work can resume across sessions. - -Core layers: -- MCP Server (protocol handling + tool registration) -- Tools layer (task workflow, research, thought, project metadata) -- Data layer (task persistence, rules, snapshots) -- Prompt layer (templated, consistent output) -- Validation and security (Zod schemas, path sanitization, size limits) - -## 2. MCP Server Layer -**Purpose**: Implements the MCP JSON-RPC interface, registers tools, and manages request/response flow. - -**Key behaviors**: -- Runs locally over STDIO (no network exposure). -- Tool registration is centralized in the server bootstrapping. -- All tool handlers are called through a common execution path that validates inputs and returns structured responses. - -**Where**: -- `src/server/mcpServer.ts` -- `src/index.ts` - -## 3. Tools Layer -**Purpose**: The API surface exposed to the MCP client. Each tool is an operation the agent can call. - -### 3.1 Task Planning and Workflow Tools -- `plan_task`: Turn a goal into a structured plan. -- `split_tasks`: Break the plan into discrete tasks with dependencies. -- `analyze_task`: Capture analysis and rationale. -- `reflect_task`: Record lessons learned or improvements. -- `execute_task`: Mark a task in progress and generate execution context. -- `verify_task`: Score and mark a task complete with summary notes. - -### 3.2 Task Management (CRUD) -- `list_tasks`: List tasks by status. -- `get_task_detail`: Fetch full task details. -- `query_task`: Search tasks by keyword or ID. -- `create_task`: Directly create a task without planning. -- `update_task`: Modify status, dependencies, notes, metadata. -- `delete_task`: Remove a task. -- `clear_all_tasks`: Clear all tasks (with confirmation). - -### 3.3 Research and Thought Tools -- `research_mode`: Guided research workflow with state tracking. -- `process_thought`: Record a structured reasoning step. - -### 3.4 Project Tools -- `init_project_rules`: Create or refresh project rules. -- `get_server_info`: Return server status and task counts. - -**Where**: -- `src/tools/task/` -- `src/tools/research/` -- `src/tools/thought/` -- `src/tools/project/` - -## 4. Data Layer (Persistence) -**Purpose**: Persist tasks, rules, and history across sessions using local JSON files. - -### 4.1 Task Store -- Stores tasks in `tasks.json` under the configured `DATA_DIR`. -- Uses atomic read-modify-write and a write queue for safety. -- Maintains timestamps and status transitions. -- Caches last read to reduce file I/O. - -**Where**: -- `src/data/taskStore.ts` -- `src/data/fileOperations.ts` - -### 4.2 Rules Store -- Stores project-specific rules in `taskflow-rules.md` under `DATA_DIR`. -- Enforces max file size and basic validation. - -**Where**: -- `src/data/rulesStore.ts` - -### 4.3 Memory Store (Snapshots and Backups) -- Supports task snapshots and history in a `memory/` folder. -- Supports completed-task backups in a `backups/` folder. -- Implements filename sanitization and size limits. - -**Where**: -- `src/data/memoryStore.ts` - -**Note**: The `clear_all_tasks` path currently returns no backup in `TaskStore` (there is a TODO to integrate backups), but the `MemoryStore` capability exists. - -## 5. Validation Layer (Zod) -**Purpose**: Enforce runtime safety and protect against malformed inputs or oversized payloads. - -Key protections: -- UUID validation for task IDs. -- String length limits for names, descriptions, notes, summaries. -- Enumerated status values only. -- Pagination limits for queries. - -**Where**: -- `src/data/schemas.ts` - -## 6. Prompt Layer (Template Engine + Builders) -**Purpose**: Produce consistent, readable responses and execution prompts. - -### 6.1 Template Engine -- Simple token replacement (no external dependencies). -- Supports `{{key}}`, `{{ key }}`, and `{key}` formats. - -**Where**: -- `src/prompts/templateEngine.ts` - -### 6.2 Template Loader -- Loads markdown templates from disk and caches them. -- Resolves template paths safely and prevents directory traversal. - -**Where**: -- `src/prompts/templateLoader.ts` -- `src/prompts/templates/v1/templates_en/` - -### 6.3 Prompt Builders -- Compose data into templates for output and tool guidance. - -**Where**: -- `src/prompts/taskPromptBuilders.ts` -- `src/prompts/projectPromptBuilder.ts` -- `src/prompts/researchPromptBuilder.ts` -- `src/prompts/thoughtPromptBuilder.ts` - -## 7. Configuration and Path Security -**Purpose**: Ensure all file access stays within controlled directories. - -Key behavior: -- Workspace root is resolved from `MCP_WORKSPACE_ROOT`, then `cwd`, then home directory. -- `DATA_DIR` defaults to `.mcp-tasks` under workspace root. -- Path sanitization prevents traversal outside allowed directories. - -**Where**: -- `src/config/pathResolver.ts` - -## 8. Security Controls -**Purpose**: Reduce attack surface and prevent misuse from untrusted inputs. - -Controls in codebase: -- Zod validation for all tool inputs. -- Path sanitization and containment checks. -- Size limits on task data and rules files. -- Local STDIO transport (no exposed network port). - -**Where**: -- `SECURITY.md` -- `src/data/schemas.ts` -- `src/config/pathResolver.ts` - -## 9. Logging and Observability -**Purpose**: Structured logging and safe error handling. - -Key points: -- Logs are structured (Pino-based) and avoid leaking sensitive info. -- Errors returned to the user are safe and generic, while server logs contain detail. - -**Where**: -- `src/server/logger.ts` - -## 10. Testing and Benchmarks -**Purpose**: Ensure protocol compliance, tool correctness, and performance baselines. - -Test coverage highlights: -- MCP protocol compliance integration tests. -- Tool behavior tests by category. -- Performance tests in integration suite. - -**Where**: -- `tests/integration/` -- `tests/tools/` -- `benchmarks/` - -## 11. What People Commonly Miss -- The **template engine and cached loader** are important for consistent outputs and performance. -- The **memory/backup system** exists but is not fully wired into task clearing (TODO in TaskStore). -- **Path sanitization** and workspace resolution are key security mechanisms. -- The **rules system** (`taskflow-rules.md`) is part of the persistence story, not just tasks. - -## 12. Practical Takeaway -This repo is not just a set of tools: it is a structured workflow system with strong runtime validation, persistent state, and consistent prompt output. That combination is what makes it more reliable and scalable than a plain chat session.