@lil2good/nubis-mcp-server 1.0.51 → 1.0.53

package/src/index.ts

@@ -4,7 +4,6 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import dotenv from 'dotenv';
-import { json } from "stream/consumers";
 
 dotenv.config();
 
@@ -12,7 +11,7 @@ dotenv.config();
 const cliWorkspaceID: string | undefined = process.env.NUBIS_WORKSPACE_ID;
 const cliApiKey: string | undefined = process.env.NUBIS_API_KEY;
 
-  // Create server instance
+// Create server instance
 const server = new McpServer({
   name: "nubis-mcp-server",
   version: "1.0.0",
@@ -22,8 +21,167 @@ const server = new McpServer({
   },
 });
 
-// Helper to get results from middleware
-async function getResultsFromMiddleware({endpoint, schema}: {endpoint: string, schema: any}) {
+// ============================================================================
+// Types
+// ============================================================================
+
+type Task = {
+  readonly id: string;
+  readonly title: string;
+  readonly task_number: number;
+  readonly board: string;
+  readonly bolt?: { id: string; name: string } | null;
+  readonly description?: string;
+  readonly context?: string;
+  readonly github_item_type?: string;
+  readonly github_file_path?: string;
+  readonly github_repo_name?: string;
+  readonly parent_task_id?: string;
+  readonly pm_task_blockers?: readonly { blocker_task_id: string }[];
+  readonly images?: readonly { url: string }[];
+  readonly subtasks?: readonly Task[];
+  readonly comments?: readonly { id: string; content: string; created_at: string }[];
+};
+
+type Bolt = {
+  readonly id: string;
+  readonly name: string;
+  readonly description?: string;
+};
+
+type ApiUsage = {
+  count: string;
+  remaining_calls: number;
+  total_limit: number;
+};
+
+type McpContentItem =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string }
+  | { type: "audio"; data: string; mimeType: string }
+  | { type: "resource"; resource: { text: string; uri: string; mimeType?: string } | { uri: string; blob: string; mimeType?: string } };
+
+// ============================================================================
+// Formatting Helpers
+// ============================================================================
+
+const BOARD_LABELS: Record<string, string> = {
+  'backlog': '📋 Backlog',
+  'bugs': '🐛 Bugs',
+  'priority': '⚡ Priority',
+  'in-progress': '🔄 In Progress',
+  'reviewing': '👀 Reviewing',
+  'completed': '✅ Completed'
+};
+
+function formatBoard(board: string): string {
+  return BOARD_LABELS[board] || board;
+}
+
+function formatApiUsage(usage: ApiUsage): string {
+  return `📊 **API Usage:** ${usage.remaining_calls}/${usage.total_limit} calls remaining`;
+}
+
+function formatTask(task: Task, options: { detailed?: boolean } = {}): string {
+  const lines: string[] = [
+    `## ${task.title}`,
+    '',
+    `| Property | Value |`,
+    `|----------|-------|`,
+    `| **ID** | \`${task.id}\` |`,
+    `| **Number** | #${task.task_number} |`,
+    `| **Board** | ${formatBoard(task.board)} |`,
+    `| **Bolt** | ${task.bolt?.name || '_Unassigned_'} |`,
+  ];
+
+  if (task.parent_task_id) {
+    lines.push(`| **Parent Task** | \`${task.parent_task_id}\` |`);
+  }
+
+  // Description
+  lines.push('', '### Description', task.description || '_No description provided_');
+
+  // GitHub info
+  if (task.github_file_path || task.github_repo_name) {
+    lines.push(
+      '',
+      '### GitHub',
+      `- **Repo:** ${task.github_repo_name || '_Not set_'}`,
+      `- **Path:** \`${task.github_file_path || '_Not set_'}\``,
+      `- **Type:** ${task.github_item_type || '_Not set_'}`
+    );
+  }
+
+  // Blockers
+  if (task.pm_task_blockers && task.pm_task_blockers.length > 0) {
+    lines.push(
+      '',
+      '### ⚠️ Blockers',
+      ...task.pm_task_blockers.map(b => `- \`${b.blocker_task_id}\``)
+    );
+  }
+
+  // Detailed view includes subtasks and comments
+  if (options.detailed) {
+    if (task.subtasks && task.subtasks.length > 0) {
+      const flatSubtasks = Array.isArray(task.subtasks[0]) ? task.subtasks[0] : task.subtasks;
+      if (flatSubtasks.length > 0) {
+        lines.push('', '### Subtasks');
+        (flatSubtasks as readonly Task[]).forEach((sub: Task) => {
+          lines.push(`- [${sub.board === 'completed' ? 'x' : ' '}] **${sub.title}** (\`${sub.id}\`) - ${formatBoard(sub.board)}`);
+        });
+      }
+    }
+
+    if (task.comments && task.comments.length > 0) {
+      const flatComments = Array.isArray(task.comments[0]) ? task.comments[0] : task.comments;
+      if (flatComments.length > 0) {
+        lines.push('', '### Comments');
+        (flatComments as readonly { id: string; content: string; created_at: string }[]).forEach((c) => {
+          lines.push(`- ${c.content}`);
+        });
+      }
+    }
+
+    if (task.context) {
+      lines.push('', '### Context', task.context);
+    }
+  }
+
+  // Images
+  if (task.images && task.images.length > 0) {
+    lines.push('', '### Images');
+    task.images.forEach((img, i) => {
+      lines.push(`${i + 1}. ${img.url}`);
+    });
+  }
+
+  return lines.join('\n');
+}
+
+function formatTaskCompact(task: Task): string {
+  const blockerNote = task.pm_task_blockers && task.pm_task_blockers.length > 0
+    ? ` ⚠️ ${task.pm_task_blockers.length} blocker(s)`
+    : '';
+
+  return [
+    `### #${task.task_number}: ${task.title}${blockerNote}`,
+    `**ID:** \`${task.id}\` | **Board:** ${formatBoard(task.board)} | **Bolt:** ${task.bolt?.name || '_None_'}`,
+    task.description ? `> ${task.description.substring(0, 150)}${task.description.length > 150 ? '...' : ''}` : '',
+    task.github_file_path ? `📁 \`${task.github_file_path}\`` : '',
+    '---'
+  ].filter(Boolean).join('\n');
+}
+
+function formatBolt(bolt: Bolt): string {
+  return `- **${bolt.name}** (\`${bolt.id}\`)${bolt.description ? `: ${bolt.description}` : ''}`;
+}
+
+// ============================================================================
+// Middleware Helper
+// ============================================================================
+
+async function getResultsFromMiddleware({ endpoint, schema }: { endpoint: string; schema: any }) {
   const response = await fetch('https://mcp-server.nubis.app/' + endpoint, {
     method: 'POST',
     headers: {
@@ -38,352 +196,347 @@ async function getResultsFromMiddleware({endpoint, schema}: {endpoint: string, s
 
   if (!response.ok) {
     const errorData = await response.json();
-    throw new Error(errorData.error || 'Failed to fetch tasks from middleware');
+    throw new Error(errorData.error || 'Failed to fetch from middleware');
   }
 
-  // Return the full JSON response (including api_usage, user, etc.)
   const json = await response.json();
   if (!json.data) throw new Error('No data returned from middleware');
   return json;
 }
 
-// Get Boltz -> to save IDs for use in tasks later
+// ============================================================================
+// Tools
+// ============================================================================
+
+/**
+ * Get Boltz
+ */
 server.tool(
   "get_boltz",
-  "Fetch all boltz for a workspace",
+  "Fetch all boltz (project branches) for the workspace. Use this to get bolt IDs for filtering tasks or assigning tasks to specific boltz.",
   async () => {
     const json = await getResultsFromMiddleware({
       endpoint: 'get_boltz',
       schema: {}
     });
-    if (!json.data) throw new Error('No data returned from middleware');
+
+    const boltz = json.data as Bolt[];
+    const formatted = [
+      `# Boltz (${boltz.length} total)`,
+      '',
+      ...boltz.map(formatBolt),
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
     return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(json.data),
-        },
-        {
-          type: "text",
-          text: `Always provide API Usage information separately. Usage: ${JSON.stringify(json.api_usage)}`,
-
-        }
-      ],
+      content: [{ type: "text", text: formatted }],
     };
   }
 );
 
-type McpContentItem =
-  | { type: "text"; text: string }
-  | { type: "image"; data: string; mimeType: string }
-  | { type: "audio"; data: string; mimeType: string }
-  | { type: "resource"; resource: { text: string; uri: string; mimeType?: string } | { uri: string; blob: string; mimeType?: string } };
-
-// Get Tasks -> Get tasks for a workspace
+/**
+ * Get Tasks
+ */
 server.tool(
   "get_tasks",
-  "Get tasks for a workspace, including subtasks, boltz, and github details/file paths",
+  "List tasks from the workspace with optional filtering. Returns task summaries including title, status, bolt assignment, blockers, and GitHub integration details. Use get_task_details for full information on a specific task.",
   {
-    limit: z.number().optional().default(5),
-    board: z.enum(['bugs', 'backlog', 'priority', 'in-progress', 'reviewing', 'completed']).optional(),
-    bolt_id: z.string().optional(),
+    limit: z.number().optional().default(5).describe("Maximum number of tasks to return (default: 5)"),
+    board: z.enum(['bugs', 'backlog', 'priority', 'in-progress', 'reviewing', 'completed']).optional().describe("Filter by board/status"),
+    bolt_id: z.string().optional().describe("Filter by bolt ID (use get_boltz to find bolt IDs)"),
   },
   async ({ limit, board, bolt_id }) => {
-    try {
-      const json = await getResultsFromMiddleware({
-        endpoint: 'get_tasks',
-        schema: {
-          board,
-          bolt_id,
-          limit
-        }
-      });
-      if (!json.data) throw new Error('No data returned from middleware');
-      /**
-       * Formats a list of tasks into Markdown content.
-       * @param data - Array of Task objects to format.
-       * @returns An object with content as an array of formatted Markdown strings.
-       */
-      type Task = {
-        readonly id: string;
-        readonly title: string;
-        readonly task_number: number;
-        readonly board: string;
-        readonly bolt: any;
-        readonly description?: string;
-        readonly github_item_type?: string;
-        readonly github_file_path?: string;
-        readonly github_repo_name?: string;
-        readonly pm_task_blockers?: readonly { blocker_task_id: string }[];
-        readonly images?: readonly { url: string }[];
-      };
-      const taskContent = (json.data as Task[]).map((task) => ({
-        type: "text",
-        text: [
-          `---`,
-          `### ${task.title}`,
-          `**Task ID:** ${task.id}`,
-          `**Task Number:** ${task.task_number}`,
-          `**Board:** ${task.board}`,
-          `**Bolt:** ${task.bolt && typeof task.bolt === "object" && !Array.isArray(task.bolt) && "name" in task.bolt && task.bolt.name ? task.bolt.name : "_No bolt_"}`,
-          `**Description:** ${task.description ? task.description : "_No description_"}`,
-          `**Path Type:** ${task.github_item_type ? task.github_item_type : "_No file path type_"}`,
-          `**File Path:** ${task.github_file_path ? task.github_file_path : "_No file path_"}`,
-          `**Repo Name:** ${task.github_repo_name ? task.github_repo_name : "_No repo name_"}`,
-          `**Blockers:** ${task.pm_task_blockers && task.pm_task_blockers.length > 0 ? task.pm_task_blockers.map(blocker => blocker.blocker_task_id).join(', ') : "_No blockers_"}`,
-          task.images && task.images.length > 0
-            ? task.images.map((image) => image.url).join('\n')
-            : "_No images_",
-          `---`,
-        ].join('\n\n'),
-      }));
-      // Append quota and user info as additional content
-      taskContent.push({
-        type: "text",
-        text: `Always provide API Usage information separately. Usage: ${JSON.stringify(json.api_usage)}`,
-      });
-      return {
-        content: taskContent as McpContentItem[],
-      };
-    } catch (error: unknown) {
-      const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
-      throw new Error(errorMessage);
-    }
+    const json = await getResultsFromMiddleware({
+      endpoint: 'get_tasks',
+      schema: { board, bolt_id, limit }
+    });
+
+    const tasks = json.data as Task[];
+    const filterInfo = [
+      board ? `Board: ${formatBoard(board)}` : null,
+      bolt_id ? `Bolt: ${bolt_id}` : null,
+    ].filter(Boolean).join(' | ');
+
+    const formatted = [
+      `# Tasks (${tasks.length}${limit ? ` of max ${limit}` : ''})`,
+      filterInfo ? `**Filters:** ${filterInfo}` : '',
+      '',
+      ...tasks.map(formatTaskCompact),
+      '',
+      formatApiUsage(json.api_usage)
+    ].filter(Boolean).join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
   }
 );
 
 /**
- * Get Task Details -> Get a task by ID
+ * Get Task Details
  */
 server.tool(
   "get_task_details",
-  "Get a task by ID",
+  "Get comprehensive details for a specific task including description, status, bolt assignment, GitHub integration, blockers, subtasks, comments, and context. Use this when you need full information about a single task.",
   {
-    taskID: z.string(),
+    taskID: z.string().describe("The UUID of the task to retrieve"),
   },
   async ({ taskID }) => {
     const json = await getResultsFromMiddleware({
       endpoint: 'get_task',
-      schema: {
-        taskID
-      }
+      schema: { taskID }
     });
-    if (!json.data) throw new Error('No data returned from middleware');
+
+    const task = json.data as Task;
+    const formatted = [
+      formatTask(task, { detailed: true }),
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
     return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(json.data),
-        },
-        {
-          type: "text",
-          text: `Always provide API Usage information separately. Usage: ${JSON.stringify(json.api_usage)}`,
-        }
-      ],
+      content: [{ type: "text", text: formatted }],
     };
   }
 );
 
-//add_context_to_pm_task
 /**
- * Always ADD CONTEXT TO PM TASK
+ * Get Task Context
+ */
+server.tool(
+  "get_task_context",
+  "Retrieve the context/notes stored for a specific task. Context contains additional information, implementation notes, or progress updates added during task work.",
+  {
+    taskID: z.string().describe("The UUID of the task"),
+  },
+  async ({ taskID }) => {
+    const json = await getResultsFromMiddleware({
+      endpoint: 'get_task_context',
+      schema: { taskID }
+    });
+
+    const context = json.data?.context;
+    const formatted = [
+      `# Task Context`,
+      `**Task ID:** \`${taskID}\``,
+      '',
+      '---',
+      '',
+      context || '_No context has been added to this task yet._',
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
+  }
+);
+
+/**
+ * Add Context to Task
  */
 server.tool(
   "add_context_to_task",
-  "Add context to a task",
+  "Add or update context/notes for a task. Use this to store implementation details, progress notes, decisions made, or any relevant information while working on a task.",
   {
-    taskID: z.string(),
-    context: z.string(),
+    taskID: z.string().describe("The UUID of the task"),
+    context: z.string().describe("The context/notes to add (replaces existing context)"),
   },
   async ({ taskID, context }) => {
     const json = await getResultsFromMiddleware({
       endpoint: 'add_context_to_task',
-      schema: {
-        taskID,
-        context
-      }
+      schema: { taskID, context }
     });
-    if (!json.data) throw new Error('No data returned from middleware');
+
+    const formatted = [
+      `✅ **Context Updated Successfully**`,
+      '',
+      `**Task ID:** \`${taskID}\``,
+      '',
+      '**Context:**',
+      context,
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
     return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({ taskID, context }),
-        },
-        {
-          type: "text",
-          text: `Always provide API Usage information separately. Usage: ${JSON.stringify({ taskID, context })}`,
-        }
-      ],
+      content: [{ type: "text", text: formatted }],
     };
   }
 );
 
-// Get Task Images -> Get images for a task
+/**
+ * Get Task Images
+ */
 server.tool(
   "get_task_images",
-  "Get/View images for a task",
+  "Retrieve all images/attachments associated with a task. Returns image URLs that can be viewed or referenced.",
   {
-    taskID: z.string(),
+    taskID: z.string().describe("The UUID of the task"),
   },
   async ({ taskID }) => {
     const json = await getResultsFromMiddleware({
       endpoint: 'get_task_images',
-      schema: {
-        taskID
-      }
+      schema: { taskID }
     });
-    if (!json.data) throw new Error('No data returned from middleware');
+
+    const images = json.data?.images || [];
+    const formatted = [
+      `# Task Images`,
+      `**Task ID:** \`${taskID}\``,
+      '',
+      images.length > 0
+        ? images.map((img: { url: string }, i: number) => `${i + 1}. ${img.url}`).join('\n')
+        : '_No images attached to this task._',
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
     return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(json.data),
-        },
-        {
-          type: "text",
-          text: `Always provide API Usage information separately. Usage: ${JSON.stringify(json.api_usage)}`,
-        }
-      ],
+      content: [{ type: "text", text: formatted }],
     };
   }
 );
 
-// Work on Task -> Work on a task
+/**
+ * Work on Task
+ */
 server.tool(
   "work_on_task",
-  "Work on a task",
+  "Start working on a task. This checks for blockers and returns full task details. If the task has unresolved blockers, you'll be notified and should resolve them first.",
   {
-    taskID: z.string(),
+    taskID: z.string().describe("The UUID of the task to work on"),
   },
   async ({ taskID }) => {
-    // Step 1: Fetch task details
+    // Step 1: Fetch task details to check blockers
     const taskData = await getResultsFromMiddleware({
       endpoint: 'get_task',
       schema: { taskID }
     });
-    if (!taskData.data) throw new Error('No data returned from middleware');
+
+    const task = taskData.data as Task;
+
     // Step 2: Check for blockers
-    if (Array.isArray(taskData.data.pm_task_blockers) && taskData.data.pm_task_blockers.length > 0) {
+    if (Array.isArray(task.pm_task_blockers) && task.pm_task_blockers.length > 0) {
+      const blockerIds = task.pm_task_blockers.map(b => `\`${b.blocker_task_id}\``).join(', ');
+      const formatted = [
+        `⚠️ **Cannot Work on Task - Blockers Detected**`,
+        '',
+        `**Task:** ${task.title}`,
+        `**Task ID:** \`${taskID}\``,
+        '',
+        `### Blocking Tasks`,
+        `The following tasks must be completed first: ${blockerIds}`,
+        '',
+        '**Suggested Actions:**',
+        '- Use `get_task_details` on each blocker to understand what needs to be done',
+        '- Complete or remove the blocking tasks before proceeding',
+        '',
+        '---',
+        formatApiUsage(taskData.api_usage)
+      ].join('\n');
+
       return {
-        content: [
-          {
-            type: "text",
-            text: `Task ${taskID} cannot be worked on because it has blockers: ${taskData.data.pm_task_blockers.map((b: { blocker_task_id: string }) => b.blocker_task_id).join(', ')}. Please resolve all blockers before proceeding.`,
-          },
-          {
-            type: "text",
-            text: `API Usage: ${JSON.stringify(taskData.api_usage)}`,
-          }
-        ],
+        content: [{ type: "text", text: formatted }],
       };
-    };
+    }
 
+    // Step 3: No blockers, proceed with work
     const json = await getResultsFromMiddleware({
       endpoint: 'work_on_task',
-      schema: {
-        taskID
-      }
+      schema: { taskID }
     });
-  
-    return {
-      content: [
-        {
-          type: "text",
-          text: `You are assisting with task management in Nubis. Your task is to work on the user's requested task based on the following details:\n\n**Task Instruction**: Process and update the task with the provided information.\n\n**Task ID**: ${taskID}\n\n**Task Details**: \n      ${JSON.stringify(json.data, null, 2).replace(/"/g, '').replace(/:/g, ': ').replace(/},/g, ',\n')}\n      \n      Please analyze the details, perform the requested action (e.g., update description, add subtask), and return a response indicating the action taken.`,
-        },
-        {
-          type: "text",
-          user: "NUBIS",
-          text: `Prompt user to move this task to 'in-progress' if it is not already in progress.`,
-        },
-        
-        {
-          type: "text",
-          user: "NUBIS",
-          text: `API Usage: ${JSON.stringify(json.api_usage)}`,
-        }
-      ],
-    };
-  }
-);
 
-// Explain setup and what user needs to do for feature to be implemented
-/* server.tool(
-  "explain_setup",
-  "Explain setup and what needs to be done for feature to be implemented",
-  {
-    taskID: z.string(),
-  },
-  async ({ taskID }) => {
-    const json = await getResultsFromMiddleware({
-      endpoint: 'explain_setup',
-      schema: {
-        taskID
-      }
-    });
+    const workTask = json.data as Task;
+    const suggestedActions: string[] = [];
+
+    if (workTask.board !== 'in-progress') {
+      suggestedActions.push(`- Move task to "in-progress" using \`move_task\``);
+    }
+    if (workTask.subtasks && workTask.subtasks.length > 0) {
+      suggestedActions.push(`- Review ${workTask.subtasks.length} subtask(s)`);
+    }
+    suggestedActions.push(
+      '- Add context with `add_context_to_task` as you make progress',
+      '- When done, move to "reviewing" or "completed"'
+    );
+
+    const formatted = [
+      `🚀 **Ready to Work**`,
+      '',
+      formatTask(workTask, { detailed: true }),
+      '',
+      '### 💡 Suggested Actions',
+      ...suggestedActions,
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
 
-    if (!json.data) throw new Error('No data returned from middleware');
     return {
-      content: [
-        {
-          type: "text",
-          text: `You are assisting with task management in Nubis. Your task is to explain the setup and what needs to be done for feature to be implemented.\n      \n      **Task Instruction**: Explain the setup and what needs to be done for feature to be implemented.\n      **Task Details**: \n      ${JSON.stringify(json.data, null, 2).replace(/"/g, '').replace(/:/g, ': ').replace(/},/g, ',\n')}\n      \n      Please analyze the feature and return a response indicating the action that needs to be taken.`,
-        },
-        {
-          type: "text",
-          text: `Always provide API Usage information separately. Usage: ${JSON.stringify(json.api_usage)}`,
-        }
-      ],
+      content: [{ type: "text", text: formatted }],
     };
   }
-); */
+);
 
-// Move Task -> Move a task to ['backlog', 'priority', 'in-progress','reviewing', 'completed']
+/**
+ * Move Task
+ */
 server.tool(
   "move_task",
-  "Move a task to ['backlog', 'priority', 'in-progress','reviewing', 'completed']",
+  "Move a task to a different board/status. Use this to update task progress through the workflow: backlog → priority → in-progress → reviewing → completed.",
   {
-    taskID: z.string(),
-    board: z.enum(['backlog', 'priority', 'in-progress','reviewing', 'completed']),
+    taskID: z.string().describe("The UUID of the task to move"),
+    board: z.enum(['backlog', 'priority', 'in-progress', 'reviewing', 'completed']).describe("Target board/status"),
   },
   async ({ taskID, board }) => {
     const json = await getResultsFromMiddleware({
       endpoint: 'move_task',
-      schema: {
-        taskID,
-        board
-      }
+      schema: { taskID, board }
     });
-    if (!json.data) throw new Error('No data returned from middleware');
+
+    const task = json.data as Task;
+    const formatted = [
+      `✅ **Task Moved Successfully**`,
+      '',
+      `| Property | Value |`,
+      `|----------|-------|`,
+      `| **Task** | ${task.title} |`,
+      `| **ID** | \`${taskID}\` |`,
+      `| **New Status** | ${formatBoard(board)} |`,
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
     return {
-      content: [
-        {
-          type: "text",
-          text: `Task ${taskID} has been moved to ${board}`,
-        },
-        {
-          type: "text",
-          text: `API Usage: ${JSON.stringify(json.api_usage)}`,
-        }
-      ],
+      content: [{ type: "text", text: formatted }],
     };
   }
 );
 
-// Create Task -> Create a new task
+/**
+ * Create Task
+ */
 server.tool(
   "create_task",
-  "Create a new task or subtask (parent_task_id is required for subtasks)",
+  "Create a new task or subtask. For subtasks, provide parent_task_id. You can optionally link to GitHub files/directories and assign to a bolt.",
   {
-    title: z.string(),
-    description: z.string().optional(),
-    board: z.enum(['backlog', 'bugs', 'in-progress', 'priority', 'reviewing', 'completed']).optional().default('backlog'),
-    parent_task_id: z.string().optional(),
-    github_item_type: z.string().optional(), // file or dir
-    github_file_path: z.string().optional(), // src/components/modal
-    github_repo_name: z.string().optional(), // Atomlaunch/atom_frontend
-    bolt_id: z.string().optional()
+    title: z.string().describe("Task title"),
+    description: z.string().optional().describe("Task description with details"),
+    board: z.enum(['backlog', 'bugs', 'in-progress', 'priority', 'reviewing', 'completed']).optional().default('backlog').describe("Initial board/status (default: backlog)"),
+    parent_task_id: z.string().optional().describe("Parent task ID to create this as a subtask"),
+    github_item_type: z.enum(['file', 'dir']).optional().describe("Type of GitHub item: 'file' or 'dir'"),
+    github_file_path: z.string().optional().describe("Path to file or directory (e.g., src/components/Modal.tsx)"),
+    github_repo_name: z.string().optional().describe("Repository name (e.g., owner/repo)"),
+    bolt_id: z.string().optional().describe("Bolt ID to assign (use get_boltz to find IDs)")
   },
   async ({ title, description, board, parent_task_id, github_item_type, github_file_path, github_repo_name, bolt_id }) => {
     const json = await getResultsFromMiddleware({
@@ -399,36 +552,53 @@ server.tool(
         bolt_id
       }
     });
-    if (!json.data) throw new Error('No data returned from middleware');
+
+    const task = json.data as Task;
+    const lines = [
+      `✅ **Task Created Successfully**`,
+      '',
+      `| Property | Value |`,
+      `|----------|-------|`,
+      `| **Title** | ${task.title} |`,
+      `| **ID** | \`${task.id}\` |`,
+      `| **Number** | #${task.task_number} |`,
+      `| **Board** | ${formatBoard(task.board)} |`,
+    ];
+
+    if (parent_task_id) {
+      lines.push(`| **Parent Task** | \`${parent_task_id}\` |`);
+    }
+    if (bolt_id) {
+      lines.push(`| **Bolt** | \`${bolt_id}\` |`);
+    }
+    if (github_file_path) {
+      lines.push(`| **GitHub Path** | \`${github_file_path}\` |`);
+    }
+
+    lines.push('', '---', formatApiUsage(json.api_usage));
+
     return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(json.data),
-        },
-        {
-          type: "text",
-          text: `API Usage: ${JSON.stringify(json.api_usage)}`,
-        }
-      ],
+      content: [{ type: "text", text: lines.join('\n') }],
     };
   }
 );
 
-// Update Task -> Update an existing task
+/**
+ * Update Task
+ */
 server.tool(
   "update_task",
-  "Update an existing task (title, description, bolt_id, parent_task_id)",
+  "Update an existing task's properties. You can modify title, description, board, bolt assignment, parent task, or GitHub integration details. Only provided fields will be updated.",
   {
-    taskID: z.string(),
-    title: z.string().optional(),
-    description: z.string().optional(),
-    board: z.enum(['backlog', 'bugs', 'in-progress', 'priority', 'reviewing', 'completed']).optional(),
-    bolt_id: z.string().optional(),
-    parent_task_id: z.string().optional(),
-    github_item_type: z.string().optional(),
-    github_file_path: z.string().optional(),
-    github_repo_name: z.string().optional(),
+    taskID: z.string().describe("The UUID of the task to update"),
+    title: z.string().optional().describe("New task title"),
+    description: z.string().optional().describe("New task description"),
+    board: z.enum(['backlog', 'bugs', 'in-progress', 'priority', 'reviewing', 'completed']).optional().describe("New board/status"),
+    bolt_id: z.string().optional().describe("New bolt ID assignment"),
+    parent_task_id: z.string().optional().describe("New parent task ID"),
+    github_item_type: z.enum(['file', 'dir']).optional().describe("Type of GitHub item"),
+    github_file_path: z.string().optional().describe("Path to file or directory"),
+    github_repo_name: z.string().optional().describe("Repository name"),
   },
   async ({ taskID, title, description, board, bolt_id, parent_task_id, github_item_type, github_file_path, github_repo_name }) => {
     const json = await getResultsFromMiddleware({
@@ -445,23 +615,369 @@ server.tool(
         github_repo_name
       }
     });
-    if (!json.data) throw new Error('No data returned from middleware');
+
+    const task = json.data as Task;
+    const updatedFields: string[] = [];
+    if (title) updatedFields.push('title');
+    if (description) updatedFields.push('description');
+    if (board) updatedFields.push('board');
+    if (bolt_id) updatedFields.push('bolt');
+    if (parent_task_id) updatedFields.push('parent task');
+    if (github_file_path || github_repo_name || github_item_type) updatedFields.push('GitHub integration');
+
+    const formatted = [
+      `✅ **Task Updated Successfully**`,
+      '',
+      `**Updated fields:** ${updatedFields.join(', ') || 'none'}`,
+      '',
+      formatTask(task),
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
+  }
+);
+
+/**
+ * Delete Task
+ */
+server.tool(
+  "delete_task",
+  "Permanently delete a task and all its related data (subtasks, comments, blockers, labels, assignments). This action cannot be undone.",
+  {
+    taskID: z.string().describe("The UUID of the task to delete"),
+  },
+  async ({ taskID }) => {
+    const json = await getResultsFromMiddleware({
+      endpoint: 'delete_task',
+      schema: { taskID }
+    });
+
+    const formatted = [
+      `🗑️ **Task Deleted Successfully**`,
+      '',
+      `**Task ID:** \`${taskID}\``,
+      '',
+      'The task and all related data (subtasks, comments, blockers, labels, assignments) have been permanently removed.',
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
+  }
+);
+
+// ============================================================================
+// Comment Tools
+// ============================================================================
+
+type Comment = {
+  readonly id: string;
+  readonly content: string;
+  readonly created_at: string;
+  readonly updated_at?: string;
+  readonly is_edited?: boolean;
+  readonly parent_id?: string;
+  readonly user?: {
+    id: string;
+    full_name?: string;
+    avatar_url?: string;
+  };
+};
+
+function formatComment(comment: Comment): string {
+  const author = comment.user?.full_name || 'Unknown';
+  const editedTag = comment.is_edited ? ' _(edited)_' : '';
+  const date = new Date(comment.created_at).toLocaleString();
+
+  return [
+    `**${author}** · ${date}${editedTag}`,
+    `> ${comment.content}`,
+    `_ID: \`${comment.id}\`_`,
+  ].join('\n');
+}
+
+/**
+ * Get Comments
+ */
+server.tool(
+  "get_comments",
+  "Retrieve all comments for a specific task. Returns comments with author information, timestamps, and edit status.",
+  {
+    taskID: z.string().describe("The UUID of the task"),
+  },
+  async ({ taskID }) => {
+    const json = await getResultsFromMiddleware({
+      endpoint: 'get_comments',
+      schema: { taskID }
+    });
+
+    const comments = json.data as Comment[];
+    const formatted = [
+      `# Task Comments`,
+      `**Task ID:** \`${taskID}\``,
+      `**Total:** ${comments.length} comment(s)`,
+      '',
+      '---',
+      '',
+      comments.length > 0
+        ? comments.map(formatComment).join('\n\n')
+        : '_No comments yet._',
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
+  }
+);
+
+/**
+ * Create Comment
+ */
+server.tool(
+  "create_comment",
+  "Add a comment to a task. Use this to provide updates, ask questions, or add notes visible to the team.",
+  {
+    taskID: z.string().describe("The UUID of the task to comment on"),
+    content: z.string().describe("The comment text"),
+    parent_id: z.string().optional().describe("Parent comment ID for replies (optional)"),
+  },
+  async ({ taskID, content, parent_id }) => {
+    const json = await getResultsFromMiddleware({
+      endpoint: 'create_comment',
+      schema: { taskID, content, parent_id }
+    });
+
+    const comment = json.data as Comment;
+    const formatted = [
+      `✅ **Comment Added**`,
+      '',
+      formatComment(comment),
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
+  }
+);
+
+/**
+ * Update Comment
+ */
+server.tool(
+  "update_comment",
+  "Edit an existing comment. Only the comment author can edit their own comments.",
+  {
+    commentID: z.string().describe("The UUID of the comment to edit"),
+    content: z.string().describe("The new comment text"),
+  },
+  async ({ commentID, content }) => {
+    const json = await getResultsFromMiddleware({
+      endpoint: 'update_comment',
+      schema: { commentID, content }
+    });
+
+    const formatted = [
+      `✅ **Comment Updated**`,
+      '',
+      `**Comment ID:** \`${commentID}\``,
+      `**New content:** ${content}`,
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
+  }
+);
+
+/**
+ * Delete Comment
+ */
+server.tool(
+  "delete_comment",
+  "Delete a comment and all its replies. Only the comment author can delete their own comments.",
+  {
+    commentID: z.string().describe("The UUID of the comment to delete"),
+  },
+  async ({ commentID }) => {
+    const json = await getResultsFromMiddleware({
+      endpoint: 'delete_comment',
+      schema: { commentID }
+    });
+
+    const formatted = [
+      `🗑️ **Comment Deleted**`,
+      '',
+      `**Comment ID:** \`${commentID}\``,
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
+  }
+);
+
+// ============================================================================
+// Blocker Tools
+// ============================================================================
+
+type BlockerInfo = {
+  readonly id: string;
+  readonly blocker_task_id?: string;
+  readonly task_id?: string;
+  readonly blocker?: {
+    id: string;
+    title: string;
+    task_number: number;
+    board: string;
+  };
+  readonly blocked?: {
+    id: string;
+    title: string;
+    task_number: number;
+    board: string;
+  };
+};
+
+function formatBlockerTask(task: { id: string; title: string; task_number: number; board: string }): string {
+  return `#${task.task_number}: ${task.title} (${formatBoard(task.board)}) - \`${task.id}\``;
+}
+
+/**
+ * Get Blockers
+ */
+server.tool(
+  "get_blockers",
+  "Get blocker relationships for a task. Shows both tasks that block this task and tasks that this task blocks.",
+  {
+    taskID: z.string().describe("The UUID of the task"),
+  },
+  async ({ taskID }) => {
+    const json = await getResultsFromMiddleware({
+      endpoint: 'get_blockers',
+      schema: { taskID }
+    });
+
+    const { blockers, blocking } = json.data as { blockers: BlockerInfo[]; blocking: BlockerInfo[] };
+
+    const formatted = [
+      `# Task Blockers`,
+      `**Task ID:** \`${taskID}\``,
+      '',
+      '### ⛔ Blocked By (must complete first)',
+      blockers.length > 0
+        ? blockers.map(b => `- ${formatBlockerTask(b.blocker!)}`).join('\n')
+        : '_No blockers - task is ready to work on_',
+      '',
+      '### 🚧 Blocking (waiting on this task)',
+      blocking.length > 0
+        ? blocking.map(b => `- ${formatBlockerTask(b.blocked!)}`).join('\n')
+        : '_Not blocking any tasks_',
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
     return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(json.data),
-        },
-        {
-          type: "text",
-          text: `API Usage: ${JSON.stringify(json.api_usage)}`,
-        }
-      ],
+      content: [{ type: "text", text: formatted }],
     };
   }
 );
 
-// Start server
+/**
+ * Add Blocker
+ */
+server.tool(
+  "add_blocker",
+  "Create a blocker dependency between tasks. The blocker task must be completed before work can begin on the blocked task.",
+  {
+    taskID: z.string().describe("The UUID of the task that will be blocked"),
+    blockerTaskID: z.string().describe("The UUID of the task that blocks (must be completed first)"),
+  },
+  async ({ taskID, blockerTaskID }) => {
+    const json = await getResultsFromMiddleware({
+      endpoint: 'add_blocker',
+      schema: { taskID, blockerTaskID }
+    });
+
+    const { blocked_task, blocker_task } = json.data as {
+      blocked_task: { id: string; title: string; task_number: number };
+      blocker_task: { id: string; title: string; task_number: number };
+    };
+
+    const formatted = [
+      `✅ **Blocker Added**`,
+      '',
+      `**#${blocker_task.task_number}: ${blocker_task.title}**`,
+      `↓ _blocks_ ↓`,
+      `**#${blocked_task.task_number}: ${blocked_task.title}**`,
+      '',
+      `The blocker task must be completed before work can begin on the blocked task.`,
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
+  }
+);
+
+/**
+ * Remove Blocker
+ */
+server.tool(
+  "remove_blocker",
+  "Remove a blocker dependency between tasks. Use this when a blocker is no longer relevant or was added in error.",
+  {
+    taskID: z.string().describe("The UUID of the blocked task"),
+    blockerTaskID: z.string().describe("The UUID of the blocking task to remove"),
+  },
+  async ({ taskID, blockerTaskID }) => {
+    const json = await getResultsFromMiddleware({
+      endpoint: 'remove_blocker',
+      schema: { taskID, blockerTaskID }
+    });
+
+    const formatted = [
+      `✅ **Blocker Removed**`,
+      '',
+      `Task \`${taskID}\` is no longer blocked by \`${blockerTaskID}\``,
+      '',
+      '---',
+      formatApiUsage(json.api_usage)
+    ].join('\n');
+
+    return {
+      content: [{ type: "text", text: formatted }],
+    };
+  }
+);
+
+// ============================================================================
+// Start Server
+// ============================================================================
+
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);
@@ -472,4 +988,4 @@ main().catch((error: unknown) => {
   const errorMessage = error instanceof Error ? error.message : 'Unknown error occurred';
   console.error("Fatal error in main():", errorMessage);
   process.exit(1);
-});
+});