@vibetasks/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,310 @@
+# TaskFlow MCP Server
+
+Model Context Protocol (MCP) server for TaskFlow integration with Claude Code, Cursor, and other AI coding tools.
+
+## Features
+
+- **8 MCP Tools** for full task management (create, read, update, delete, search, complete, batch create with subtasks, log sessions)
+- **3 MCP Resources** for context-aware AI (active tasks, today's tasks, upcoming tasks)
+- **Claude Code Hooks** for automatic session logging
+- **TodoWrite Integration** for automatic task syncing from Claude's todo lists
+- **STDIO Transport** for reliable communication
+- **Direct Supabase Integration** with Row-Level Security
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18+ installed
+- TaskFlow CLI installed and configured (`taskflow login`)
+- Claude Code or Cursor installed
+
+### Quick Install
+
+```bash
+# From the apps/mcp-server directory
+npm install
+npm run build
+bash scripts/install.sh
+```
+
+The installation script will:
+1. Build the MCP server
+2. Create Claude Code configuration
+3. Set up hooks for automatic session logging
+
+### Manual Installation
+
+1. **Build the server:**
+```bash
+npm run build
+```
+
+2. **Get your Supabase anon key:**
+   - Go to https://supabase.com/dashboard/project/_/settings/api
+   - Copy the `anon` public key
+
+3. **Configure Claude Code:**
+
+Edit `~/.config/claude-code/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "taskflow": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/taskflow/apps/mcp-server/dist/index.js"
+      ],
+      "env": {
+        "TASKFLOW_SUPABASE_URL": "https://cbkkztbcoitrfcleghfd.supabase.co",
+        "TASKFLOW_SUPABASE_KEY": "your_anon_key_here"
+      }
+    }
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "node",
+        "args": ["/absolute/path/to/dist/index.js"],
+        "env": {
+          "CLAUDE_HOOK_TYPE": "SessionStart",
+          "TASKFLOW_SUPABASE_URL": "https://cbkkztbcoitrfcleghfd.supabase.co"
+        }
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "node",
+        "args": ["/absolute/path/to/dist/index.js"],
+        "env": {
+          "CLAUDE_HOOK_TYPE": "SessionEnd",
+          "TASKFLOW_SUPABASE_URL": "https://cbkkztbcoitrfcleghfd.supabase.co"
+        }
+      }
+    ]
+  }
+}
+```
+
+4. **Restart Claude Code**
+
+## Usage
+
+### MCP Tools
+
+Access tools by typing `@` in Claude Code:
+
+#### create_task
+Create a new task:
+```
+@taskflow create_task
+  title: "Add authentication"
+  notes: "Implement OAuth with Supabase"
+  priority: "high"
+  due_date: "2026-01-15"
+  tags: ["backend", "security"]
+```
+
+#### get_tasks
+Get filtered tasks:
+```
+@taskflow get_tasks filter: "today"
+```
+
+Filters: `all`, `today`, `upcoming`, `completed`
+
+#### complete_task
+Mark a task complete:
+```
+@taskflow complete_task task_id: "abc-123..."
+```
+
+#### update_task
+Update task properties:
+```
+@taskflow update_task
+  task_id: "abc-123..."
+  title: "Updated title"
+  priority: "medium"
+```
+
+#### delete_task
+Delete a task:
+```
+@taskflow delete_task task_id: "abc-123..."
+```
+
+#### search_tasks
+Search by title:
+```
+@taskflow search_tasks query: "authentication" limit: 10
+```
+
+#### create_task_with_subtasks
+Create a parent task with subtasks in one call (perfect for TodoWrite integration):
+```
+@taskflow create_task_with_subtasks
+  title: "Implement user authentication"
+  subtasks: ["Create login form", "Add API endpoints", "Implement JWT handling"]
+  priority: "high"
+  due_date: "2026-01-15"
+  tags: ["backend", "auth"]
+```
+
+**Use case:** When using Claude's TodoWrite feature, automatically mirror your todo list to TaskFlow for persistent tracking beyond the session.
+
+#### log_ai_session
+Manually log a session:
+```
+@taskflow log_ai_session
+  summary: "Implemented user authentication"
+  files: ["auth.ts", "login.tsx"]
+  duration_minutes: 45
+```
+
+### MCP Resources
+
+Resources provide automatic context to AI:
+
+- `taskflow://tasks/active` - All incomplete tasks
+- `taskflow://tasks/today` - Tasks due today
+- `taskflow://tasks/upcoming` - Future tasks
+
+The AI can access these without explicit tool calls.
+
+### Automatic Session Logging
+
+When Claude Code hooks are configured:
+
+1. **SessionStart**: Loads today's tasks as context
+2. **SessionEnd**: Automatically creates a completed task summarizing your work
+
+No manual intervention required!
+
+### TodoWrite Integration
+
+When Claude uses its built-in TodoWrite feature for multi-step tasks, it can automatically sync to TaskFlow:
+
+**How it works:**
+1. Claude creates a TodoWrite list for planning (ephemeral, session-only)
+2. Claude calls `create_task_with_subtasks` to mirror the list in TaskFlow
+3. Each todo becomes a persistent subtask
+4. As Claude completes todos, it marks TaskFlow subtasks complete
+5. Your tasks survive beyond the session and sync across all platforms
+
+**Example:**
+```
+User: "Implement user authentication"
+
+Claude creates TodoWrite:
+1. Create login form component
+2. Add authentication API endpoints
+3. Implement JWT token handling
+4. Add protected route middleware
+
+Claude also calls create_task_with_subtasks:
+{
+  title: "Implement user authentication",
+  subtasks: [
+    "Create login form component",
+    "Add authentication API endpoints",
+    "Implement JWT token handling",
+    "Add protected route middleware"
+  ]
+}
+
+Result: Session todos + persistent TaskFlow task with subtasks
+```
+
+## Development
+
+### Running Locally
+
+```bash
+npm run dev
+```
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+```bash
+# Test STDIO communication
+echo '{"method":"list_tools"}' | node dist/index.js
+
+# Test SessionStart hook
+CLAUDE_HOOK_TYPE=SessionStart node dist/index.js
+
+# Test SessionEnd hook
+CLAUDE_HOOK_TYPE=SessionEnd node dist/index.js
+```
+
+## Troubleshooting
+
+### Server Not Appearing in Claude Code
+
+1. Check config file: `~/.config/claude-code/config.json`
+2. Verify dist/index.js exists: `ls apps/mcp-server/dist/`
+3. Check logs: Restart Claude Code with verbose logging
+4. Verify authentication: `taskflow config`
+
+### Authentication Errors
+
+```bash
+# Re-login to TaskFlow
+taskflow login
+
+# Verify tokens are stored
+taskflow config
+```
+
+### Hooks Not Working
+
+1. Check hook configuration in `config.json`
+2. Verify file paths are absolute
+3. Test hooks manually:
+```bash
+CLAUDE_HOOK_TYPE=SessionStart node dist/index.js
+```
+
+## Architecture
+
+```
+┌─────────────────┐
+│  Claude Code    │
+│   or Cursor     │
+└────────┬────────┘
+         │ STDIO
+         │
+┌────────▼────────┐
+│   MCP Server    │
+│  - Tools        │
+│  - Resources    │
+│  - Hooks        │
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│  @taskflow/     │
+│   mcp-core      │
+└────────┬────────┘
+         │
+┌────────▼────────┐
+│    Supabase     │
+│   PostgreSQL    │
+└─────────────────┘
+```
+
+## Contributing
+
+See [main README](../../README.md) for contribution guidelines.
+
+## License
+
+MIT

package/config/claude-code.json

@@ -0,0 +1,38 @@
+{
+  "mcpServers": {
+    "taskflow": {
+      "command": "node",
+      "args": [
+        "REPLACE_WITH_PATH_TO_DIST/index.js"
+      ],
+      "env": {
+        "TASKFLOW_SUPABASE_URL": "https://cbkkztbcoitrfcleghfd.supabase.co",
+        "TASKFLOW_SUPABASE_KEY": "REPLACE_WITH_ANON_KEY"
+      }
+    }
+  },
+  "hooks": {
+    "SessionStart": [
+      {
+        "type": "command",
+        "command": "node",
+        "args": ["REPLACE_WITH_PATH_TO_DIST/index.js"],
+        "env": {
+          "CLAUDE_HOOK_TYPE": "SessionStart",
+          "TASKFLOW_SUPABASE_URL": "https://cbkkztbcoitrfcleghfd.supabase.co"
+        }
+      }
+    ],
+    "Stop": [
+      {
+        "type": "command",
+        "command": "node",
+        "args": ["REPLACE_WITH_PATH_TO_DIST/index.js"],
+        "env": {
+          "CLAUDE_HOOK_TYPE": "SessionEnd",
+          "TASKFLOW_SUPABASE_URL": "https://cbkkztbcoitrfcleghfd.supabase.co"
+        }
+      }
+    ]
+  }
+}