mcp-taskflow 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+### Minor Changes
+
+### [0.1.0](https://www.npmjs.com/package/taskflow-mcp/v/0.1.0) - 2026-02-05
+
+Initial package release
+
+This project uses Changesets to generate release notes.
+
+For a new release, run the Changesets workflow to create a release PR with version bumps and changelog updates.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TaskFlow MCP contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,275 @@
+# TaskFlow MCP
+
+[![npm version](https://badge.fury.io/js/mcp-taskflow.svg)](https://badge.fury.io/js/mcp-taskflow)
+
+
+
+## Table of Contents 📌
+
+- [Overview](#overview-)
+- [What Is MCP?](#what-is-mcp-)
+- [Quick Start](#quick-start-)
+- [Installation](#installation-)
+- [Basic Usage](#basic-usage-)
+- [Tools Overview](#tools-overview-)
+- [Example: Agent-in-the-Loop (ReBAC Feature)](#example-agent-in-the-loop-rebac-feature-)
+- [Documentation](#documentation-)
+- [Development](#development-)
+- [Versioning](#versioning-)
+- [License](#license-)
+
+A local Model Context Protocol (MCP) server that gives AI agents structured task planning, execution tracking, and guided research workflows.
+
+## 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.
+
+## 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.
+
+## 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.
+
+**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
+```
+

package/dist/config/pathResolver.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Path resolution and sanitization utilities.
+ */
+/**
+ * Resolve workspace root directory.
+ */
+export declare function resolveWorkspaceRoot(): string;
+/**
+ * Resolve data directory path
+ * Uses DATA_DIR environment variable or defaults to .mcp-tasks
+ */
+export declare function resolveDataDir(): string;
+/**
+ * Sanitize a user-provided file path.
+ */
+export declare function sanitizePath(userPath: string, baseDir: string): string;
+/**
+ * Get sanitized path within data directory.
+ */
+export declare function getDataPath(relativePath: string, dataDirOverride?: string): string;
+/**
+ * Ensure directory exists, creating it if necessary.
+ */
+export declare function ensureDirectory(dirPath: string): Promise<void>;
+/**
+ * Validate that a path exists and is within allowed directory.
+ */
+export declare function isValidPath(filePath: string, allowedDir: string): Promise<boolean>;
+/**
+ * Resolve template file path.
+ */
+export declare function resolveTemplatePath(templatePath: string): string;
+//# sourceMappingURL=pathResolver.d.ts.map

package/dist/config/pathResolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathResolver.d.ts","sourceRoot":"","sources":["../../src/config/pathResolver.ts"],"names":[],"mappings":"AAAA;;GAEG;AAYH;;GAEG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAqC7C;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI,MAAM,CAWvC;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAyBtE;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlF;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CASpE;AAED;;GAEG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAelB;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAShE"}

package/dist/config/pathResolver.js

@@ -0,0 +1,130 @@
+/**
+ * Path resolution and sanitization utilities.
+ */
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+/**
+ * Get the current file's directory (ESM equivalent of __dirname)
+ */
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Resolve workspace root directory.
+ */
+export function resolveWorkspaceRoot() {
+    // Priority 1: Environment variable
+    if (process.env['MCP_WORKSPACE_ROOT']) {
+        return path.resolve(process.env['MCP_WORKSPACE_ROOT']);
+    }
+    // Priority 2: Current working directory
+    const cwd = process.cwd();
+    // Protected directories check (don't use system directories)
+    const protectedDirs = [
+        '/etc',
+        '/usr',
+        '/bin',
+        '/sbin',
+        '/sys',
+        '/proc',
+        'C:\\Windows',
+        'C:\\Program Files',
+    ];
+    const isProtected = protectedDirs.some(dir => cwd.toLowerCase().startsWith(dir.toLowerCase()));
+    if (!isProtected) {
+        return cwd;
+    }
+    // Priority 3: User home directory (fallback)
+    const homeDir = process.env['HOME'] || process.env['USERPROFILE'];
+    if (homeDir) {
+        return homeDir;
+    }
+    // Last resort: current directory
+    return cwd;
+}
+/**
+ * Resolve data directory path
+ * Uses DATA_DIR environment variable or defaults to .mcp-tasks
+ */
+export function resolveDataDir() {
+    const workspaceRoot = resolveWorkspaceRoot();
+    const dataDirName = process.env['DATA_DIR'] || '.mcp-tasks';
+    // If DATA_DIR is absolute, use it directly
+    if (path.isAbsolute(dataDirName)) {
+        return dataDirName;
+    }
+    // Otherwise, relative to workspace root
+    return path.join(workspaceRoot, dataDirName);
+}
+/**
+ * Sanitize a user-provided file path.
+ */
+export function sanitizePath(userPath, baseDir) {
+    // Ensure baseDir is absolute
+    const absoluteBaseDir = path.resolve(baseDir);
+    // Normalize separators to avoid mixed-separator traversal bypasses
+    const normalizedUserPath = userPath.replace(/[\\/]+/g, path.sep);
+    // Resolve user path relative to base directory
+    const resolvedPath = path.resolve(absoluteBaseDir, normalizedUserPath);
+    // Verify path is within baseDir
+    const relativePath = path.relative(absoluteBaseDir, resolvedPath);
+    const isOutside = relativePath === '' ? false :
+        relativePath.startsWith(`..${path.sep}`) ||
+            relativePath === '..' ||
+            path.isAbsolute(relativePath);
+    if (isOutside) {
+        throw new Error(`Access denied: path '${userPath}' resolves outside allowed directory`);
+    }
+    return resolvedPath;
+}
+/**
+ * Get sanitized path within data directory.
+ */
+export function getDataPath(relativePath, dataDirOverride) {
+    const dataDir = dataDirOverride ?? resolveDataDir();
+    return sanitizePath(relativePath, dataDir);
+}
+/**
+ * Ensure directory exists, creating it if necessary.
+ */
+export async function ensureDirectory(dirPath) {
+    const fs = await import('fs/promises');
+    try {
+        await fs.access(dirPath);
+    }
+    catch {
+        // Directory doesn't exist, create it
+        await fs.mkdir(dirPath, { recursive: true });
+    }
+}
+/**
+ * Validate that a path exists and is within allowed directory.
+ */
+export async function isValidPath(filePath, allowedDir) {
+    try {
+        // Check containment
+        const absoluteAllowedDir = path.resolve(allowedDir);
+        if (!filePath.startsWith(absoluteAllowedDir)) {
+            return false;
+        }
+        // Check existence
+        const fs = await import('fs/promises');
+        await fs.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Resolve template file path.
+ */
+export function resolveTemplatePath(templatePath) {
+    // Get the dist directory
+    const distDir = path.resolve(__dirname, '..');
+    // Templates are in dist/prompts/templates/v1/templates_en/
+    const templatesBaseDir = path.join(distDir, 'prompts', 'templates', 'v1', 'templates_en');
+    // Sanitize to prevent directory traversal
+    return sanitizePath(templatePath, templatesBaseDir);
+}
+//# sourceMappingURL=pathResolver.js.map

package/dist/config/pathResolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pathResolver.js","sourceRoot":"","sources":["../../src/config/pathResolver.ts"],"names":[],"mappings":"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"}

package/dist/data/fileOperations.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Atomic JSON File Operations
+ *
+ * Implements atomic write using temp file + fsync + rename.
+ */
+import { z } from 'zod';
+/**
+ * File operation errors with detailed context
+ */
+export declare class FileOperationError extends Error {
+    readonly filePath: string;
+    readonly operation: 'read' | 'write' | 'delete';
+    readonly originalError?: unknown | undefined;
+    constructor(message: string, filePath: string, operation: 'read' | 'write' | 'delete', originalError?: unknown | undefined);
+}
+/**
+ * Read and parse JSON file with Zod schema validation.
+ */
+export declare function readJsonFile<T>(filePath: string, schema: z.ZodSchema<T>): Promise<T>;
+/**
+ * Write JSON file atomically using temp file + rename pattern.
+ */
+export declare function writeJsonFile<T>(filePath: string, data: T, schema: z.ZodSchema<T>): Promise<void>;
+/**
+ * Check if a file exists
+ *
+ * @param filePath - Absolute file path
+ * @returns true if file exists, false otherwise
+ */
+export declare function fileExists(filePath: string): Promise<boolean>;
+/**
+ * Read JSON file or return default value if file doesn't exist.
+ */
+export declare function readJsonFileOrDefault<T>(filePath: string, schema: z.ZodSchema<T>, defaultValue: T): Promise<T>;
+/**
+ * List all files in a directory.
+ */
+export declare function listFiles(dirPath: string): Promise<string[]>;
+/**
+ * Delete a file with retry logic.
+ */
+export declare function deleteFile(filePath: string): Promise<void>;
+//# sourceMappingURL=fileOperations.d.ts.map

package/dist/data/fileOperations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileOperations.d.ts","sourceRoot":"","sources":["../../src/data/fileOperations.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAaxB;;GAEG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;aAGzB,QAAQ,EAAE,MAAM;aAChB,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ;aACtC,aAAa,CAAC,EAAE,OAAO;gBAHvC,OAAO,EAAE,MAAM,EACC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,EACtC,aAAa,CAAC,EAAE,OAAO,YAAA;CAK1C;AAgDD;;GAEG;AACH,wBAAsB,YAAY,CAAC,CAAC,EAClC,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,CAAC,CAAC,CAmDZ;AAED;;GAEG;AACH,wBAAsB,aAAa,CAAC,CAAC,EACnC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,CAAC,EACP,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GACrB,OAAO,CAAC,IAAI,CAAC,CAsDf;AAkCD;;;;;GAKG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOnE;AAED;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,CAAC,EAC3C,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EACtB,YAAY,EAAE,CAAC,GACd,OAAO,CAAC,CAAC,CAAC,CAgBZ;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAelE;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CA+BhE"}