Change 'request' abstraction to 'project'

Author: chriscarrollsmith

.gitignore

@@ -7,4 +7,9 @@ node_modules
 .env
 .env.local
 .cursor
-artifacts
+artifacts
+repomix-output.txt
+
+# Task files
+tasks.json
+*.tasks.json

README.md

@@ -7,8 +7,10 @@ A Model Context Protocol (MCP) server for AI task management. This tool helps AI
 - Task planning with multiple steps
 - Progress tracking
 - User approval of completed tasks
-- Request completion approval
+- Project completion approval
 - Task details visualization
+- Task status state management
+- Enhanced CLI for task inspection and management
 
 ## Structure
 
@@ -17,6 +19,7 @@ The codebase has been refactored into a modular structure:
 ```
 src/
 ├── index.ts              # Main entry point
+├── cli.ts                # CLI for task approval and listing
 ├── server/
 │   └── TaskManagerServer.ts   # Core server functionality
 └── types/
@@ -26,8 +29,12 @@ src/
 
 ## Data Schema and Storage
 
-The task manager stores data in a JSON file:
-- **Default location**: `~/Documents/tasks.json` (in user's home directory)
+The task manager stores data in a JSON file with platform-specific default locations:
+
+- **Default locations**: 
+  - **Linux**: `~/.local/share/mcp-taskmanager/tasks.json` (following XDG Base Directory specification)
+  - **macOS**: `~/Library/Application Support/mcp-taskmanager/tasks.json`
+  - **Windows**: `%APPDATA%\mcp-taskmanager\tasks.json` (typically `C:\Users\<username>\AppData\Roaming\mcp-taskmanager\tasks.json`)
 - **Custom location**: Set via `TASK_MANAGER_FILE_PATH` environment variable
 
 ```bash
@@ -39,18 +46,18 @@ The data schema is organized as follows:
 
 ```
 TaskManagerFile
-├── requests: RequestEntry[]
-    ├── requestId: string            # Format: "req-{number}"
-    ├── originalRequest: string      # Original user request text
-    ├── splitDetails: string         # Additional request details
-    ├── completed: boolean           # Request completion status
+├── projects: Project[]
+    ├── projectId: string            # Format: "proj-{number}"
+    ├── initialPrompt: string        # Original user request text
+    ├── projectPlan: string          # Additional project details
+    ├── completed: boolean           # Project completion status
     └── tasks: Task[]                # Array of tasks
         ├── id: string               # Format: "task-{number}"
         ├── title: string            # Short task title
         ├── description: string      # Detailed task description
-        ├── done: boolean            # Task completion status
+        ├── status: string           # Task status: "not started", "in progress", or "done"
         ├── approved: boolean        # Task approval status
-        └── completedDetails: string # Completion information
+        └── completedDetails: string # Completion information (required when status is "done")
 ```
 
 The system persists this structure to the JSON file after each operation.
@@ -110,7 +117,7 @@ You can find this through the Claude Desktop menu:
   "tools": {
     "taskmanager": {
       "command": "npx",
-      "args": ["-y", "@kazuph/mcp-taskmanager"]
+      "args": ["-y", "@chriscarrollsmith/mcp-taskmanager"]
     }
   }
 }
@@ -126,7 +133,7 @@ You can find this through the Claude Desktop menu:
 ### Installation
 
 ```bash
-git clone https://github.com/kazuph/mcp-taskmanager.git
+git clone https://github.com/chriscarrollsmith/mcp-taskmanager.git
 cd mcp-taskmanager
 npm install
 npm run build
@@ -160,44 +167,137 @@ Add the following to your MCP client's configuration:
 
 ## Available Operations
 
-The TaskManager supports two main phases of operation:
+The TaskManager now uses a consolidated API with two main tools:
+
+### `project` Tool
+Manages high-level projects with multiple tasks.
+
+**Actions:**
+- `list`: List all projects in the system
+- `create`: Create a new project with initial tasks
+- `delete`: Remove a project
+- `add_tasks`: Add new tasks to an existing project
+- `finalize`: Finalize a project after all tasks are done and approved
+
+### `task` Tool
+Manages individual tasks within projects.
+
+**Actions:**
+- `read`: Get details of a specific task
+- `update`: Modify a task's properties (title, description, status)
+- `delete`: Remove a task from a project
+
+### Task Status
+Tasks have a status field that can be one of:
+- `not started`: Task has not been started yet
+- `in progress`: Task is currently being worked on
+- `done`: Task has been completed
+
+#### Status Transition Rules
+The system enforces the following rules for task status transitions:
+- Tasks follow a specific workflow with defined valid transitions:
+  - From `not started`: Can only move to `in progress`
+  - From `in progress`: Can move to either `done` or back to `not started`
+  - From `done`: Can move back to `in progress` if additional work is needed
+- A task cannot skip states (e.g., cannot go directly from "not started" to "done")
+- When a task is marked as "done", the `completedDetails` field is required
+- Approved tasks cannot be modified
+
+These rules help maintain the integrity of task progress and ensure proper documentation of completed work.
+
+### CLI Commands
+
+#### Task Approval
+
+Task approval is controlled exclusively by the human user through a CLI command:
+
+```bash
+npm run approve-task -- <projectId> <taskId>
+```
+
+Options:
+- `-f, --force`: Force approval even if the task is not marked as done
+
+This command sets the `approved` field of a task to `true` after verifying that the task is marked as `done`. Only the human user can approve tasks, ensuring quality control.
+
+#### Listing Tasks and Projects
 
-### Planning Phase
-- Accepts a task list (array of strings) from the user
-- Stores tasks internally as a queue
-- Returns an execution plan (task overview, task ID, current queue status)
+The CLI provides a command to list all projects and tasks:
 
-### Execution Phase
-- Returns the next task from the queue when requested
-- Provides feedback mechanism for task completion
-- Removes completed tasks from the queue
-- Prepares the next task for execution
+```bash
+npm run list-tasks
+```
+
+To view details of a specific project:
 
-### Parameters
+```bash
+npm run list-tasks -- -p <projectId>
+```
 
-- `action`: "plan" | "execute" | "complete"
-- `tasks`: Array of task strings (required for "plan" action)
-- `taskId`: Task identifier (required for "complete" action)
-- `getNext`: Boolean flag to request next task (for "execute" action)
+This command displays information about all projects in the system or a specific project, including:
+- Project ID and initial prompt
+- Completion status
+- Task details (title, description, status, approval)
+- Progress metrics (approved/completed/total tasks)
 
 ## Example Usage
 
-```typescript
-// Planning phase
+### Creating a Project with Tasks
+```json
 {
-  action: "plan",
-  tasks: ["Task 1", "Task 2", "Task 3"]
+  "tool": "project",
+  "action": "create",
+  "arguments": {
+    "initialPrompt": "Write a blog post about cats",
+    "tasks": [
+      { "title": "Research cat breeds", "description": "Find information about 5 popular cat breeds" },
+      { "title": "Create outline", "description": "Organize main points and structure of the blog" },
+      { "title": "Write draft", "description": "Write the first draft of the blog post" },
+      { "title": "Edit and finalize", "description": "Proofread and make final edits to the blog post" }
+    ]
+  }
 }
+```
 
-// Execution phase
+### Updating a Task Status
+```json
 {
-  action: "execute",
-  getNext: true
+  "tool": "task",
+  "action": "update",
+  "arguments": {
+    "projectId": "proj-1",
+    "taskId": "task-1",
+    "status": "in progress"
+  }
 }
+```
 
-// Complete task
+### Finalizing a Project
+```json
 {
-  action: "complete",
-  taskId: "task-123"
+  "tool": "project",
+  "action": "finalize",
+  "arguments": {
+    "projectId": "proj-1"
+  }
 }
 ```
+
+## Status Codes and Responses
+
+All operations return a status code and message in their response:
+
+### Project Tool Statuses
+- `projects_listed`: Successfully listed all projects
+- `planned`: Successfully created a new project
+- `project_deleted`: Successfully deleted a project
+- `tasks_added`: Successfully added tasks to a project
+- `project_finalized`: Successfully finalized a project
+- `error`: An error occurred (with error message)
+
+### Task Tool Statuses
+- `task_details`: Successfully retrieved task details
+- `task_updated`: Successfully updated a task
+- `task_deleted`: Successfully deleted a task
+- `task_not_found`: Task not found
+- `error`: An error occurred (with error message)

package-lock.json

@@ -6,7 +6,8 @@
 	"main": "dist/index.js",
 	"type": "module",
 	"bin": {
-		"mcp-taskmanager": "dist/index.js"
+		"mcp-taskmanager": "dist/index.js",
+		"task-manager-cli": "dist/cli.js"
 	},
 	"files": [
 		"dist"
@@ -15,7 +16,9 @@
 		"build": "tsc",
 		"start": "node dist/index.js",
 		"dev": "tsc && node dist/index.js",
-		"test": "NODE_OPTIONS=--experimental-vm-modules jest"
+		"test": "NODE_OPTIONS=--experimental-vm-modules jest",
+		"approve-task": "node dist/cli.js approve-task",
+		"list-tasks": "node dist/cli.js list"
 	},
 	"repository": {
 		"type": "git",
@@ -33,6 +36,7 @@
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^0.5.0",
 		"chalk": "^5.3.0",
+		"commander": "^11.0.0",
 		"glob": "^10.3.10",
 		"zod": "^3.22.4",
 		"zod-to-json-schema": "^3.23.5"