### Install and Run MCP Server (Bash)

Source: https://github.com/tymon3568/well-task/blob/master/mcp-server/README.md

Installs dependencies, builds the project, and starts the MCP server. It also shows how to set the MCP_DOCS_DIR environment variable to specify the documentation directory.

```bash
cd mcp-server
npm install
npm run build
npm start
```

```bash
export MCP_DOCS_DIR="/home/arch/well-task/docs"
node /home/arch/well-task/mcp-server/dist/index.js
```

--------------------------------

### Project Initialization and Agent Context Loading (Bash & JavaScript)

Source: https://context7.com/tymon3568/well-task/llms.txt

Covers the initial setup for a new project or agent onboarding. Includes a bash command for initializing the project context and JavaScript examples for agents to retrieve comprehensive project information, search documentation, list available files, review tasks, and generate an overview.

```bash
# Initialize project context (typically run once)
npm run init

# Output:
# 🚀 Initializing Well-Task Project Context...
# ✅ Project context loaded successfully!
# 
# 📋 Project Summary:
# - Goals: Build a comprehensive task management system with Jira-like features...
# - Active Tasks: 8
# - Documentation: 4 files

```

```javascript
// Agent retrieves full project context on startup
const context = await mcp.call({
  name: "get_project_context",
  arguments: {}
});

// Agent searches for specific information
const authDocs = await mcp.call({
  name: "search_project_docs",
  arguments: { query: "authentication security" }
});

// Agent lists available documentation
const docs = await mcp.call({
  name: "list_docs",
  arguments: { pattern: "**/*.{md,yaml,surql}" }
});

// Agent reviews current task landscape
const allTasks = await mcp.call({
  name: "list_tasks",
  arguments: {}
});

// Agent generates overview summary
await mcp.call({
  name: "sync_overview",
  arguments: {}
});

```

--------------------------------

### Well-Task MCP Client Configuration Examples

Source: https://context7.com/tymon3568/well-task/llms.txt

This section provides JSON examples for configuring the Well-Task MCP client, illustrating how to specify the server command, environment variables, and arguments for both global installations and npx usage. This configuration is essential for integrating AI systems with the MCP server.

```json
// MCP client configuration (e.g., Claude Desktop)
{
  "mcpServers": {
    "well-task": {
      "command": "well-task-mcp",
      "env": {
        "MCP_DOCS_DIR": "/Users/username/projects/my-app/docs"
      }
    }
  }
}
```

```json
// Alternative: Use npx without global installation
{
  "mcpServers": {
    "well-task": {
      "command": "npx",
      "args": ["-y", "@tymon3568/well-task-mcp-server"],
      "env": {
        "MCP_DOCS_DIR": "/Users/username/projects/my-app/docs"
      }
    }
  }
}
```

--------------------------------

### Configure and Run Well-Task MCP Server

Source: https://context7.com/tymon3568/well-task/llms.txt

These examples show how to install, configure environment variables for, and run the Well-Task MCP server using npm and npx. It includes setting a custom documentation directory and running the server in different modes.

```bash
# Install the MCP server
npm install -g @tymon3568/well-task-mcp-server

# Configure environment (optional)
export MCP_DOCS_DIR="/path/to/my/project/docs"

# Run the server
well-task-mcp

# Or run in development mode with auto-reload
npm run dev
```

--------------------------------

### Get Project Context

Source: https://context7.com/tymon3568/well-task/llms.txt

Retrieves comprehensive project context, including goals, architecture, current tasks, and an overview of available documentation.

```APIDOC
## GET /get_project_context

### Description
Get comprehensive project context including goals, architecture, current tasks, and documentation overview.

### Method
GET

### Endpoint
/get_project_context

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "name": "get_project_context",
  "arguments": {}
}
```

### Response
#### Success Response (200)
- **content** (array) - An array of content objects, typically containing text.

#### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "# 📋 Well-Task Project Context\n\n## 🎯 Project Goals\nBuild a comprehensive task management system with Jira-like features.\n\n## 🏗️ Architecture\nBackend:\n  - Rust with Axum framework\n  - SurrealDB for data persistence\nFrontend:\n  - React with TypeScript\n  - Material-UI components\n\n## 📁 Project Structure\n...\n\n## 📋 Current Active Tasks\n- V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md - User Registration Endpoint (Todo)\n- V1_MVP/01_Database_Schema_And_Seed_Data/task_01.01_define_core_schemas.md - Define Core Schemas (InProgress_By_Agent_Alpha)\n\n## 📚 Available Documentation\n- technical: Available for detailed reference\n- api: Available for detailed reference\n- schema: Available for detailed reference\n- prd: Available for detailed reference"
    }
  ]
}
```
```

--------------------------------

### Start Task

Source: https://context7.com/tymon3568/well-task/llms.txt

Initiates a task by setting its status to 'InProgress_By_<agent>' if all dependencies are met, otherwise sets it to 'Blocked_By_Dependency'. Logs the action and updates the task file.

```javascript
// MCP Tool Call - Agent Alpha starts a task
{
  "name": "start_task",
  "arguments": {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "agent": "Agent_Alpha"
  }
}

// Response when dependencies are satisfied
{
  "content": [{
    "type": "text",
    "text": "Task started by Agent_Alpha"
  }]
}
// Task file is updated:
// **Trạng thái:** InProgress_By_Agent_Alpha
// **Ngày cập nhật cuối:** 2025-06-15
// ## AI Agent Log
// * 2025-06-15 14:30: Agent_Alpha: Started task

// Response when dependencies are not met
{
  "content": [{
    "type": "text",
    "text": "Task blocked by dependencies: V1_MVP/01_Database_Schema_And_Seed_Data/task_01.01_define_core_schemas.md => Todo"
  }]
}
// Task file is updated:
// **Trạng thái:** Blocked_By_Dependency
// ## AI Agent Log
// * 2025-06-15 14:30: Agent_Alpha: Blocked by dependencies: ...
```

--------------------------------

### Get Project Context using MCP

Source: https://context7.com/tymon3568/well-task/llms.txt

Retrieves comprehensive project context, including goals, architecture, active tasks, and documentation overview. This tool is essential for AI agents to understand the project's current state and available resources.

```javascript
// MCP Tool Call
{
  "name": "get_project_context",
  "arguments": {}
}

// Response
{
  "content": [{
    "type": "text",
    "text": "# 📋 Well-Task Project Context

## 🎯 Project Goals
Build a comprehensive task management system with Jira-like features.

## 🏗️ Architecture
Backend:
  - Rust with Axum framework
  - SurrealDB for data persistence
Frontend:
  - React with TypeScript
  - Material-UI components

## 📁 Project Structure
...

## 📋 Current Active Tasks
- V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md - User Registration Endpoint (Todo)
- V1_MVP/01_Database_Schema_And_Seed_Data/task_01.01_define_core_schemas.md - Define Core Schemas (InProgress_By_Agent_Alpha)

## 📚 Available Documentation
- technical: Available for detailed reference
- api: Available for detailed reference
- schema: Available for detailed reference
- prd: Available for detailed reference"
  }]
}
```

--------------------------------

### Get Task Suggestions

Source: https://context7.com/tymon3568/well-task/llms.txt

The 'get_task_suggestions' command provides intelligent task recommendations based on the project's current context and progress. It can generate general suggestions or phase-specific suggestions when a 'phase' argument is provided. The output includes current active tasks and actionable recommendations for project progression.

```javascript
// MCP Tool Call - Get general suggestions
{
  "name": "get_task_suggestions",
  "arguments": {}
}

// Response
{
  "content": [{
    "type": "text",
    "text": "# 🤖 AI Task Suggestions

## 📋 Based on Current Project Context:

### Current Active Tasks:
- V1_MVP/01_Database_Schema_And_Seed_Data/task_01.01_define_core_schemas.md - Define Core Schemas (InProgress_By_Agent_Beta)
- V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md - User Registration Endpoint (Todo)

### General Suggestions:
- Use 'list_tasks()' to see all current tasks
- Use 'next_ready_task()' to find tasks ready to work on
- Use 'create_task()' to add new tasks following project structure
- Use 'get_project_context()' to understand project goals"
  }]
}

// Get phase-specific suggestions
{
  "name": "get_task_suggestions",
  "arguments": {
    "phase": "02_Backend_Core_Features"
  }
}

// Response includes phase-specific suggestions:
// ### Suggestions for Phase: 02_Backend_Core_Features
// - Implement user authentication
// - Create user profile management
// - Build core API endpoints
```

--------------------------------

### List Tasks

Source: https://context7.com/tymon3568/well-task/llms.txt

Lists all task markdown files with their associated metadata such as status and assignee. This function is crucial for getting an overview of project progress.

```javascript
// MCP Tool Call
{
  "name": "list_tasks",
  "arguments": {}
}

// Response
{
  "content": [{
    "type": "text",
    "text": `[
  {
    "path": "V1_MVP/00_Project_Setup_And_Environment/task_00.01_rust_axum_backend_setup.md",
    "status": "Done",
    "assignee": "Agent_Alpha"
  },
  {
    "path": "V1_MVP/01_Database_Schema_And_Seed_Data/task_01.01_define_core_schemas.md",
    "status": "InProgress_By_Agent_Beta",
    "assignee": "Agent_Beta"
  },
  {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "status": "Todo",
    "assignee": null
  }
]`
  }]
}
```

--------------------------------

### Find Next Ready Task (JavaScript)

Source: https://github.com/tymon3568/well-task/blob/master/mcp-server/README.md

Locates the next available task in a specified scope (version, phase, module) that has all its dependencies met. It can optionally start the task immediately if an agent is provided.

```javascript
next_ready_task(version?, phase?, module?, agent?, autoStart?)
```

--------------------------------

### Start Task with Soft-Lock (JavaScript)

Source: https://github.com/tymon3568/well-task/blob/master/mcp-server/README.md

Initiates a task by soft-locking it. If dependencies are met (Done), it sets the status to 'InProgress_By_<agent>'; otherwise, it sets 'Blocked_By_Dependency' and logs the reason.

```javascript
start_task(path, agent)
```

--------------------------------

### Sync Task Overview (JavaScript)

Source: https://github.com/tymon3568/well-task/blob/master/mcp-server/README.md

Scans all task files to generate an up-to-date summary section for the TASKS_OVERVIEW.md file. If TASKS_OVERVIEW.md is not found, it looks for task-overview.md.

```javascript
sync_overview(overviewPath?)
```

--------------------------------

### Find Next Ready Task (MCP Tool)

Source: https://context7.com/tymon3568/well-task/llms.txt

Finds the next task with 'Todo' status whose dependencies are met. It can optionally scope the search by version, phase, and module, and can auto-start the task for a specified agent. The response provides the path to the ready task or indicates if none are found.

```javascript
// MCP Tool Call - Find any ready task and auto-start
{
  "name": "next_ready_task",
  "arguments": {
    "agent": "Agent_Alpha",
    "autoStart": true
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.02_login_endpoint.md"
  }]
}
// If autoStart is true, task is automatically updated to InProgress_By_Agent_Alpha

// Find ready task in specific phase without auto-starting
{
  "name": "next_ready_task",
  "arguments": {
    "version": "V1_MVP",
    "phase": "02_Backend_Core_Features",
    "autoStart": false
  }
}

// Find ready task in specific module
{
  "name": "next_ready_task",
  "arguments": {
    "version": "V1_MVP",
    "phase": "02_Backend_Core_Features",
    "module": "02.01_Authentication",
    "agent": "Agent_Beta",
    "autoStart": true
  }
}

// Response when no ready tasks found
{
  "content": [{
    "type": "text",
    "text": "No ready tasks found in scope."
  }]
}
```

--------------------------------

### Create Task

Source: https://context7.com/tymon3568/well-task/llms.txt

Creates a new task markdown file from a template within a specified version, phase, and module directory. It takes detailed arguments to define the new task.

```javascript
// MCP Tool Call - Create authentication task
{
  "name": "create_task",
  "arguments": {
    "version": "V1_MVP",
    "phase": "02_Backend_Core_Features",
    "module": "02.01_Authentication",
    "id": "02.01.02",
    "slug": "login_endpoint",
    "title": "User Login Endpoint",
    "priority": "High",
    "assignee": "Agent_Alpha",
    "status": "Todo",
    "description": "Implement POST /api/v1/auth/login endpoint that authenticates users and returns JWT token."
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": "Created task: V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.02_login_endpoint.md"
  }]
}

// The created file contains:
// # Task: User Login Endpoint
//
// **ID Task:** `V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.02_login_endpoint.md`
// **Version:** V1_MVP
// **Giai đoạn:** 02_Backend_Core_Features
// **Module:** 02.01_Authentication
// **Ưu tiên:** High
// **Trạng thái:** Todo
// **Người thực hiện (Nếu có):** Agent_Alpha
// **Ngày tạo:** 2025-06-15
// **Ngày cập nhật cuối:** 2025-06-15
//
// ## Mô tả chi tiết:
// Implement POST /api/v1/auth/login endpoint that authenticates users and returns JWT token.
// ...
```

--------------------------------

### Search Project Documentation

Source: https://context7.com/tymon3568/well-task/llms.txt

Searches through all project documentation using keywords or phrases to find relevant information.

```APIDOC
## GET /search_project_docs

### Description
Search through all project documentation using keywords or phrases.

### Method
GET

### Endpoint
/search_project_docs

### Parameters
#### Path Parameters
None

#### Query Parameters
- **query** (string) - Required - The keywords or phrases to search for in the project documentation.

#### Request Body
None

### Request Example
```json
{
  "name": "search_project_docs",
  "arguments": {
    "query": "authentication JWT"
  }
}
```

### Response
#### Success Response (200)
- **content** (array) - An array of content objects, typically containing text, representing search results.

#### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "## Search Results for \"authentication JWT\"\n\n## API_SPEC.yaml\nopenapi: 3.1.0\ninfo:\n  title: CoupleConnect API (Stub)\n  version: 0.1.0\npaths:\n  /api/v1/auth/register:\n    post:\n      summary: Register new user (stub)...\n\n---\n\n## task_02.01.01_user_registration_endpoint.md\n# Task: User Registration Endpoint\n...\n- [ ] Return user info (without password hash) and JWT on success..."
    }
  ]
}
```
```

--------------------------------

### Search Project Documentation using MCP

Source: https://context7.com/tymon3568/well-task/llms.txt

Enables searching through all project documentation using keywords or phrases. This tool helps AI agents find relevant information within the project's knowledge base, such as API specifications or task details.

```javascript
// MCP Tool Call - Search for authentication-related documentation
{
  "name": "search_project_docs",
  "arguments": {
    "query": "authentication JWT"
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": "## Search Results for \"authentication JWT\"

## API_SPEC.yaml
openapi: 3.1.0
info:
  title: CoupleConnect API (Stub)
  version: 0.1.0
paths:
  /api/v1/auth/register:
    post:
      summary: Register new user (stub)...

---

## task_02.01.01_user_registration_endpoint.md
# Task: User Registration Endpoint
...
- [ ] Return user info (without password hash) and JWT on success..."
  }]
}
```

--------------------------------

### Create and Manage Project Tasks with Well-Task MCP

Source: https://context7.com/tymon3568/well-task/llms.txt

This JavaScript snippet demonstrates how a project manager uses the MCP client to create tasks within a project module, including suggesting task IDs, creating tasks with detailed descriptions, and manually adding dependencies. It utilizes the `mcp.call` method for interacting with the MCP server.

```javascript
// Project manager creates a new authentication module with multiple tasks

// 1. Suggest next task ID for the module
const taskIdResponse = await mcp.call({
  name: "suggest_task_id",
  arguments: {
    version: "V1_MVP",
    phase: "02_Backend_Core_Features",
    module: "02.01_Authentication"
  }
});
// Returns: "02.01.01" (or next available)

// 2. Create registration task
await mcp.call({
  name: "create_task",
  arguments: {
    version: "V1_MVP",
    phase: "02_Backend_Core_Features",
    module: "02.01_Authentication",
    id: "02.01.01",
    slug: "user_registration_endpoint",
    title: "User Registration Endpoint",
    priority: "High",
    assignee: "",
    status: "Todo",
    description: "Implement POST /api/v1/auth/register endpoint with email validation, password hashing using Argon2, and JWT token generation. Must integrate with SurrealDB users table."
  }
});

// 3. Create login task (depends on registration)
const loginIdResponse = await mcp.call({
  name: "suggest_task_id",
  arguments: {
    version: "V1_MVP",
    phase: "02_Backend_Core_Features",
    module: "02.01_Authentication"
  }
});
// Returns: "02.01.02"

await mcp.call({
  name: "create_task",
  arguments: {
    version: "V1_MVP",
    phase: "02_Backend_Core_Features",
    module: "02.01_Authentication",
    id: "02.01.02",
    slug: "login_endpoint",
    title: "User Login Endpoint",
    priority: "High",
    assignee: "",
    status: "Todo",
    description: "Implement POST /api/v1/auth/login endpoint that validates credentials and returns JWT token."
  }
});

// 4. Manually edit task file to add dependency
// In task_02.01.02_login_endpoint.md:
// ## Dependencies (Các task cần hoàn thành trước):
// - `V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md`

// 5. Get phase-specific suggestions for more tasks
const suggestions = await mcp.call({
  name: "get_task_suggestions",
  arguments: {
    phase: "02_Backend_Core_Features"
  }
});
```

--------------------------------

### List Documentation Files

Source: https://context7.com/tymon3568/well-task/llms.txt

Lists files within the 'docs' directory, with optional filtering using glob patterns.

```APIDOC
## GET /list_docs

### Description
List files under the docs directory with optional glob pattern filtering.

### Method
GET

### Endpoint
/list_docs

### Parameters
#### Path Parameters
None

#### Query Parameters
- **pattern** (string) - Optional - A glob pattern to filter the files listed (e.g., "**/*.md"). Defaults to listing all files if not provided.

#### Request Body
None

### Request Example
```json
{
  "name": "list_docs",
  "arguments": {
    "pattern": "**/*.md"
  }
}
```

### Response
#### Success Response (200)
- **content** (array) - An array of content objects, typically containing a JSON string array of file paths.

#### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "[\n  \"TASKS_OVERVIEW.md\",\n  \"task-overview.md\",\n  \"deployment-guide.md\",\n  \"directory-structure.md\",\n  \"prd-en.md\",\n  \"task-template.md\",\n  \"V1_MVP/00_Project_Setup_And_Environment/task_00.01_rust_axum_backend_setup.md\",\n  \"V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md\"\n]"
    }
  ]
}
```

#### Example with different pattern
```json
{
  "name": "list_docs",
  "arguments": {
    "pattern": "**/*.{yaml,surql}"
  }
}
```
```

--------------------------------

### General Docs Tools (JavaScript)

Source: https://github.com/tymon3568/well-task/blob/master/mcp-server/README.md

A set of general utility functions for interacting with documentation files, including listing files, reading content, listing tasks, and updating task metadata like status and assignee.

```javascript
list_docs(pattern?)
```

```javascript
read_doc(path)
```

```javascript
list_tasks()
```

```javascript
update_task_status(path, status)
```

```javascript
set_assignee(path, assignee)
```

```javascript
add_agent_log(path, message, agent?)
```

--------------------------------

### Multi-Agent Task Workflow with Status Locking (JavaScript)

Source: https://context7.com/tymon3568/well-task/llms.txt

Demonstrates the step-by-step process an AI agent follows to pick up, execute, and complete a task within the Well-Task system. It includes querying for tasks, claiming ownership with status checks, loading project context, reading documentation, executing work with logging, and completing tasks. Dependencies are managed via status-based locking to prevent conflicts.

```javascript
// Agent_Alpha's workflow for a task cycle

// 1. Query available work
const tasksResponse = await mcp.call({
  name: "list_tasks",
  arguments: {}
});
// Agent identifies task assigned to itself or unclaimed Todo tasks

// 2. Check if task is ready and claim it
const startResponse = await mcp.call({
  name: "start_task",
  arguments: {
    path: "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    agent: "Agent_Alpha"
  }
});
// If dependencies not met, system sets status to Blocked_By_Dependency
// If ready, status becomes InProgress_By_Agent_Alpha

// 3. Load project context for implementation
const contextResponse = await mcp.call({
  name: "get_project_context",
  arguments: {}
});

// 4. Read relevant documentation
const schemaResponse = await mcp.call({
  name: "read_doc",
  arguments: { path: "SCHEMA.surql" }
});

// 5. Execute work and log progress
await mcp.call({
  name: "mark_subtask",
  arguments: {
    path: "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    match: "Define Request and Response structs",
    checked: true
  }
});

await mcp.call({
  name: "add_agent_log",
  arguments: {
    path: "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    message: "Implemented RegisterUserRequest and UserResponse structs with validation attributes",
    agent: "Agent_Alpha"
  }
});

// 6. Complete task when all acceptance criteria met
await mcp.call({
  name: "complete_task",
  arguments: {
    path: "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    finalStatus: "NeedsReview"
  }
});

// 7. Find next ready task and auto-start
const nextTaskResponse = await mcp.call({
  name: "next_ready_task",
  arguments: {
    version: "V1_MVP",
    phase: "02_Backend_Core_Features",
    agent: "Agent_Alpha",
    autoStart: true
  }
});
// Agent continues with next task in its assigned phase

```

--------------------------------

### Synchronize Task Overview

Source: https://context7.com/tymon3568/well-task/llms.txt

The 'sync_overview' command scans project task files to generate a summary section and updates a specified 'TASKS_OVERVIEW.md' file. It supports a default overview file path or a custom path specified via arguments. The synchronization process includes counts of tasks by status (Todo, InProgress, Blocked, NeedsReview, Done) and lists specific tasks in 'InProgress' or 'Blocked' states.

```javascript
// MCP Tool Call - Sync overview with default path
{
  "name": "sync_overview",
  "arguments": {}
}

// Response
{
  "content": [{
    "type": "text",
    "text": "Overview synchronized at TASKS_OVERVIEW.md"
  }]
}

// Updates TASKS_OVERVIEW.md with auto-generated section:
// <!-- well-task:overview:start -->
//
// ## Well-Task Auto Summary
//
// ### V1_MVP
// - 00_Project_Setup_And_Environment: Todo 0, InProgress 0, Blocked 0, NeedsReview 0, Done 1
// - 01_Database_Schema_And_Seed_Data: Todo 2, InProgress 1, Blocked 0, NeedsReview 0, Done 0
// - 02_Backend_Core_Features: Todo 5, InProgress 2, Blocked 1, NeedsReview 0, Done 0
//
// #### In Progress
// - V1_MVP/01_Database_Schema_And_Seed_Data/task_01.01_define_core_schemas.md (InProgress_By_Agent_Beta)
// - V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md (InProgress_By_Agent_Alpha)
//
// #### Blocked
// - V1_MVP/02_Backend_Core_Features/02.02_Profile/task_02.02.01_profile_crud.md (Blocked_By_Dependency)
//
// <!-- well-task:overview:end -->

// Sync to custom overview file
{
  "name": "sync_overview",
  "arguments": {
    "overviewPath": "task-overview.md"
  }
}
```

--------------------------------

### POST /api/v1/auth/register

Source: https://github.com/tymon3568/well-task/blob/master/docs/task-template.md

Allows new users to register an account. The endpoint accepts user details, validates them, hashes the password, and stores the user in the database. A JWT is returned upon successful registration.

```APIDOC
## POST /api/v1/auth/register

### Description
This endpoint allows new users to register an account. It accepts user credentials, validates the input, securely hashes the password, and persists the user information to the database. A JSON Web Token (JWT) is returned upon successful registration.

### Method
POST

### Endpoint
`/api/v1/auth/register`

### Parameters
#### Request Body
- **email** (string) - Required - The user's email address. Must be a valid format and unique.
- **password** (string) - Required - The user's password. Must meet minimum length and complexity requirements.
- **full_name** (string) - Required - The user's full name.

### Request Example
```json
{
  "email": "user@example.com",
  "password": "securePassword123",
  "full_name": "John Doe"
}
```

### Response
#### Success Response (200 OK)
- **user** (object) - Contains the registered user's information (excluding password hash).
  - **id** (string) - The unique identifier for the user.
  - **email** (string) - The user's email address.
  - **full_name** (string) - The user's full name.
  - **created_at** (string) - The timestamp when the user was created.
- **token** (string) - The JWT issued for the newly registered user.

#### Response Example (Success)
```json
{
  "user": {
    "id": "users:abc123xyz",
    "email": "user@example.com",
    "full_name": "John Doe",
    "created_at": "2025-06-05T10:30:00Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Error Response (400 Bad Request / 409 Conflict / 500 Internal Server Error)
- **error** (string) - A message describing the error (e.g., "Invalid email format", "Email already in use", "Password too short").

#### Response Example (Error)
```json
{
  "error": "Email already in use"
}
```
```

--------------------------------

### Create New Task (JavaScript)

Source: https://github.com/tymon3568/well-task/blob/master/mcp-server/README.md

Creates a new task file within a specified version, phase, and module. It accepts various parameters including ID, slug, title, priority, assignee, status, and description.

```javascript
create_task(version, phase, module?, id, slug, title, priority?, assignee?, status?, description?)
```

--------------------------------

### POST /api/v1/auth/register

Source: https://github.com/tymon3568/well-task/blob/master/docs/V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md

Allows new users to register by providing their email, password, and full name. The endpoint validates the inputs, hashes the password, and saves the user to the database. Upon successful registration, it returns user information and a JWT.

```APIDOC
## POST /api/v1/auth/register

### Description
Creates a new user account. Takes email, password, and full name, validates them, hashes the password, and stores the user in the database. Returns user details and a JWT upon success.

### Method
POST

### Endpoint
/api/v1/auth/register

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **email** (string) - Required - User's email address. Must be a valid format and unique.
- **password** (string) - Required - User's password. Must meet minimum length and complexity requirements.
- **full_name** (string) - Required - User's full name.

### Request Example
```json
{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "full_name": "John Doe"
}
```

### Response
#### Success Response (200)
- **user** (object) - Contains user details.
  - **id** (RecordId) - Unique identifier for the user.
  - **email** (string) - User's email address.
  - **full_name** (string) - User's full name.
  - **created_at** (Datetime) - Timestamp when the user was created.
- **token** (string) - JWT token for authentication.

#### Response Example
```json
{
  "user": {
    "id": "users/some_id",
    "email": "user@example.com",
    "full_name": "John Doe",
    "created_at": "2025-06-05T10:00:00Z"
  },
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

#### Error Response (400, 500)
- **error** (string) - Description of the error (e.g., "Invalid email format", "Password too short", "Email already exists").
```

--------------------------------

### Rust Structs for User Registration Request and Response

Source: https://github.com/tymon3568/well-task/blob/master/docs/V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md

Defines the data structures for handling user registration requests and responses in Rust. This includes request parameters, user details, and authentication tokens.

```rust
#[derive(Debug, Deserialize)]
struct RegisterUserRequest {
    email: String,
    password: String,
    full_name: String,
}

#[derive(Debug, Serialize)]
struct UserResponse {
    id: RecordId,
    email: String,
    full_name: String,
    created_at: DateTime,
}

#[derive(Debug, Serialize)]
struct AuthResponse {
    user: UserResponse,
    token: String,
}
```

--------------------------------

### List Documentation Files using MCP

Source: https://context7.com/tymon3568/well-task/llms.txt

Lists files within the docs directory, with support for glob pattern filtering. This is useful for identifying available documentation files, such as markdown, YAML, or SURQL files.

```javascript
// MCP Tool Call - List all markdown files
{
  "name": "list_docs",
  "arguments": {
    "pattern": "**/*.md"
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": "[
  \"TASKS_OVERVIEW.md\",
  \"task-overview.md\",
  \"deployment-guide.md\",
  \"directory-structure.md\",
  \"prd-en.md\",
  \"task-template.md\",
  \"V1_MVP/00_Project_Setup_And_Environment/task_00.01_rust_axum_backend_setup.md\",
  \"V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md\"
]"
  }]
}

// List only YAML and SURQL files
{
  "name": "list_docs",
  "arguments": {
    "pattern": "**/*.{yaml,surql}"
  }
}
```

--------------------------------

### Read Documentation File

Source: https://context7.com/tymon3568/well-task/llms.txt

Reads a single documentation file by its path, relative to the documentation root directory.

```APIDOC
## GET /read_doc

### Description
Read a single documentation file by path relative to docs root.

### Method
GET

### Endpoint
/read_doc

### Parameters
#### Path Parameters
None

#### Query Parameters
- **path** (string) - Required - The path to the documentation file relative to the docs root.

#### Request Body
None

### Request Example
```json
{
  "name": "read_doc",
  "arguments": {
    "path": "API_SPEC.yaml"
  }
}
```

### Response
#### Success Response (200)
- **content** (array) - An array of content objects, typically containing the text content of the documentation file.

#### Response Example
```json
{
  "content": [
    {
      "type": "text",
      "text": "openapi: 3.1.0\ninfo:\n  title: CoupleConnect API (Stub)\n  version: 0.1.0\npaths:\n  /api/v1/auth/register:\n    post:\n      summary: Register new user (stub)\n      requestBody:\n        required: true\n        content:\n          application/json:\n            schema:\n              type: object\n              properties:\n                email:\n                  type: string\n                password:\n                  type: string\n                full_name:\n                  type: string\n      responses:\n        '201':\n          description: Created"
    }
  ]
}
```
```

--------------------------------

### Read Single Documentation File using MCP

Source: https://context7.com/tymon3568/well-task/llms.txt

Reads the content of a single documentation file using its path relative to the docs root. This allows AI agents to access the full content of specific documentation files, such as API specifications or configuration files.

```javascript
// MCP Tool Call
{
  "name": "read_doc",
  "arguments": {
    "path": "API_SPEC.yaml"
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": "openapi: 3.1.0
info:
  title: CoupleConnect API (Stub)
  version: 0.1.0
paths:
  /api/v1/auth/register:
    post:
      summary: Register new user (stub)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                password:
                  type: string
                full_name:
                  type: string
      responses:
        '201':
          description: Created"
  }]
}
```

--------------------------------

### Suggest Task ID

Source: https://context7.com/tymon3568/well-task/llms.txt

Suggests the next available task ID suffix for a given module directory by analyzing existing tasks. This helps in maintaining sequential task numbering.

```javascript
// MCP Tool Call - Get next task ID for Authentication module
{
  "name": "suggest_task_id",
  "arguments": {
    "version": "V1_MVP",
    "phase": "02_Backend_Core_Features",
    "module": "02.01_Authentication"
  }
}

// Response if directory has task_02.01.01 and task_02.01.02
{
  "content": [{
    "type": "text",
    "text": "02.01.03"
  }]
}

// Response if directory is empty
{
  "content": [{
    "type": "text",
    "text": "02.01.01"
  }]
}
```

--------------------------------

### Define Rust Request/Response Structs for User Registration

Source: https://github.com/tymon3568/well-task/blob/master/docs/task-template.md

Defines the Rust structs for handling user registration requests and responses. Includes request payload, user details for response, and authentication response containing user info and JWT. These structs are essential for data serialization/deserialization and type safety within the Rust application.

```rust
#[derive(Deserialize)]
struct RegisterUserRequest {
    email: String,
    password: String,
    full_name: String,
}

#[derive(Serialize)]
struct UserResponse {
    id: RecordId, // Assuming RecordId is a type from SurrealDB or a similar ORM
    email: String,
    full_name: String,
    created_at: Datetime, // Assuming Datetime is a type for timestamps
}

#[derive(Serialize)]
struct AuthResponse {
    user: UserResponse,
    token: String,
}
```

--------------------------------

### Complete Task (MCP Tool)

Source: https://context7.com/tymon3568/well-task/llms.txt

Marks a task as 'NeedsReview' or 'Done' and updates its last updated date. It takes the file path and the final status as arguments. The response indicates the success of the operation and the task file is updated accordingly.

```javascript
// MCP Tool Call - Mark task as needing review
{
  "name": "complete_task",
  "arguments": {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "finalStatus": "NeedsReview"
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": "Task marked NeedsReview"
  }]
}
// Task file updated:
// **Trạng thái:** NeedsReview
// **Ngày cập nhật cuối:** 2025-06-15
// ## AI Agent Log
// * 2025-06-15 16:45: Marked as NeedsReview

// Mark as fully done
{
  "name": "complete_task",
  "arguments": {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "finalStatus": "Done"
  }
}
```

--------------------------------

### Complete Task (JavaScript)

Source: https://github.com/tymon3568/well-task/blob/master/mcp-server/README.md

Marks a task as completed, updating its status to 'NeedsReview' or 'Done', and automatically updating the 'last-updated' date and logging the action.

```javascript
complete_task(path, finalStatus)
```

--------------------------------

### Add Agent Log (MCP Tool)

Source: https://context7.com/tymon3568/well-task/llms.txt

Appends a line to the 'AI Agent Log' section of a task markdown file. It requires the file path and a message, with an optional agent name. The response confirms the log entry addition, and the task file will include the new timestamped log entry.

```javascript
// MCP Tool Call - Log progress update
{
  "name": "add_agent_log",
  "arguments": {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "message": "Completed email validation implementation. Added regex check and DB uniqueness verification.",
    "agent": "Agent_Alpha"
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": "Appended agent log entry in V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md"
  }]
}
// Appends to task file:
// ## AI Agent Log
// * 2025-06-15 15:23: Agent_Alpha: Completed email validation implementation. Added regex check and DB uniqueness verification.

// Log without agent name
{
  "name": "add_agent_log",
  "arguments": {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "message": "Merged PR #42 into main branch"
  }
}
// Result: * 2025-06-15 16:10: Merged PR #42 into main branch
```

--------------------------------

### Suggest Next Task ID (JavaScript)

Source: https://github.com/tymon3568/well-task/blob/master/mcp-server/README.md

Suggests the next available task ID suffix for a given version, phase, and module. This is useful for creating new tasks sequentially.

```javascript
suggest_task_id(version, phase, module?)
```

--------------------------------

### Set Assignee (MCP Tool)

Source: https://context7.com/tymon3568/well-task/llms.txt

Updates the assignee field of a task markdown file. It takes the file path and the desired assignee's name. An empty assignee string unassigns the task. The response confirms the assignment update in the specified file.

```javascript
// MCP Tool Call - Assign task to agent
{
  "name": "set_assignee",
  "arguments": {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "assignee": "Agent_Beta"
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": "Set assignee to 'Agent_Beta' in V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md"
  }]
}
// Updates: **Người thực hiện (Nếu có):** Agent_Beta

// Unassign task
{
  "name": "set_assignee",
  "arguments": {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "assignee": ""
  }
}
```

--------------------------------

### Mark Subtask (MCP Tool)

Source: https://context7.com/tymon3568/well-task/llms.txt

Marks a sub-task checkbox within a task markdown file. It requires the file path, the text of the sub-task to match, and a boolean 'checked' value to indicate completion. The response confirms the sub-task update, and the task file reflects the changed checkbox state.

```javascript
// MCP Tool Call - Mark first sub-task as complete
{
  "name": "mark_subtask",
  "arguments": {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "match": "Define Request and Response structs",
    "checked": true
  }
}

// Response
{
  "content": [{
    "type": "text",
    "text": "Subtask 'Define Request and Response structs' marked done."
  }]
}
// In task file:
// - [x] 1. Define Request and Response structs in Rust

// Uncheck a subtask
{
  "name": "mark_subtask",
  "arguments": {
    "path": "V1_MVP/02_Backend_Core_Features/02.01_Authentication/task_02.01.01_user_registration_endpoint.md",
    "match": "Define Request and Response structs",
    "checked": false
  }
}
// Result: - [ ] 1. Define Request and Response structs in Rust
```