Skip to main content
Glama
lleontor705

forgespec-mcp

by lleontor705
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

tb_update

Update a task's status or append timestamped notes. Transition to 'done' requires prior status of 'in_progress' or 'in_review'.

Instructions

Update a task's status and/or append notes. Moving to 'done' requires 'in_progress' or 'in_review'. Notes are stored as timestamped entries.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
task_idYesTask ID
statusNoNew status (omit to keep current status and only add notes)
notesNoNotes to append (timestamped). Works with or without status change.

Implementation Reference

  • src/tools/task-board.ts:255-363 (handler)
    The handler function for the 'tb_update' tool. Updates a task's status and/or appends timestamped notes. Validates transitions to 'done' (requires 'in_progress' or 'in_review'), auto-unblocks dependent tasks when a task is completed.
    server.tool(
  "tb_update",
  "Update a task's status and/or append notes. Moving to 'done' requires 'in_progress' or 'in_review'. Notes are stored as timestamped entries.",
  {
    task_id: z.string().max(256).describe("Task ID"),
    status: z.enum(TASK_STATUSES).optional().describe("New status (omit to keep current status and only add notes)"),
    notes: z.string().max(65536).optional().describe("Notes to append (timestamped). Works with or without status change."),
  },
  async ({ task_id, status, notes }) => {
    const db = getDb();
    const task = db.prepare(`SELECT * FROM tasks WHERE id = ?`).get(task_id) as Record<string, unknown> | undefined;

    if (!task) {
      return { content: [{ type: "text" as const, text: JSON.stringify({ error: "Task not found" }) }] };
    }

    const now = new Date().toISOString();
    const effectiveStatus = status ?? task.status as string;

    // Validate done transition
    if (status === "done") {
      if (task.status !== "in_progress" && task.status !== "in_review") {
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({ error: `Cannot move to 'done' from '${task.status}'. Must be 'in_progress' or 'in_review' first.` }),
            },
          ],
        };
      }
    }

    // Append notes if provided
    let notesCount: number | undefined;
    if (notes) {
      const existing = JSON.parse((task.notes as string) || "[]") as Array<{ text: string; timestamp: string }>;
      existing.push({ text: notes, timestamp: now });
      db.prepare(`UPDATE tasks SET notes = ?, updated_at = ? WHERE id = ?`).run(
        JSON.stringify(existing),
        now,
        task_id
      );
      notesCount = existing.length;
    }

    // Update status if provided
    if (status) {
      const updates: Record<string, unknown> = { status, updated_at: now };
      if (status === "done") {
        updates.completed_at = now;
      }

      const setClauses = Object.keys(updates).map((k) => `${k} = ?`).join(", ");
      db.prepare(`UPDATE tasks SET ${setClauses} WHERE id = ?`).run(
        ...Object.values(updates),
        task_id
      );

      // Auto-unblock dependent tasks
      if (status === "done") {
        const dependents = db
          .prepare(`SELECT id, dependencies FROM tasks WHERE board_id = ? AND status = 'backlog'`)
          .all(task.board_id as string) as Record<string, unknown>[];

        const unblocked: string[] = [];
        for (const dep of dependents) {
          const depIds = JSON.parse(dep.dependencies as string) as string[];
          if (depIds.includes(task_id)) {
            const remaining = depIds.filter((d) => d !== task_id);
            if (remaining.length === 0) {
              db.prepare(`UPDATE tasks SET status = 'ready', updated_at = ? WHERE id = ?`).run(now, dep.id);
              unblocked.push(dep.id as string);
            }
          }
        }

        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                updated: true,
                task_id,
                status: effectiveStatus,
                unblocked_tasks: unblocked,
                notes_count: notesCount,
              }),
            },
          ],
        };
      }
    }

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            updated: true,
            task_id,
            status: effectiveStatus,
            notes_count: notesCount,
          }),
        },
      ],
    };
  }
);
  • src/tools/task-board.ts:258-262 (schema)
    Input schema for tb_update: task_id (string, required), status (enum from TASK_STATUSES, optional), notes (string, optional).
    {
  task_id: z.string().max(256).describe("Task ID"),
  status: z.enum(TASK_STATUSES).optional().describe("New status (omit to keep current status and only add notes)"),
  notes: z.string().max(65536).optional().describe("Notes to append (timestamped). Works with or without status change."),
},
  • src/tools/task-board.ts:255-363 (registration)
    Registration of the 'tb_update' tool via server.tool() within registerTaskBoardTools(), called from src/server.ts line 19.
    server.tool(
  "tb_update",
  "Update a task's status and/or append notes. Moving to 'done' requires 'in_progress' or 'in_review'. Notes are stored as timestamped entries.",
  {
    task_id: z.string().max(256).describe("Task ID"),
    status: z.enum(TASK_STATUSES).optional().describe("New status (omit to keep current status and only add notes)"),
    notes: z.string().max(65536).optional().describe("Notes to append (timestamped). Works with or without status change."),
  },
  async ({ task_id, status, notes }) => {
    const db = getDb();
    const task = db.prepare(`SELECT * FROM tasks WHERE id = ?`).get(task_id) as Record<string, unknown> | undefined;

    if (!task) {
      return { content: [{ type: "text" as const, text: JSON.stringify({ error: "Task not found" }) }] };
    }

    const now = new Date().toISOString();
    const effectiveStatus = status ?? task.status as string;

    // Validate done transition
    if (status === "done") {
      if (task.status !== "in_progress" && task.status !== "in_review") {
        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({ error: `Cannot move to 'done' from '${task.status}'. Must be 'in_progress' or 'in_review' first.` }),
            },
          ],
        };
      }
    }

    // Append notes if provided
    let notesCount: number | undefined;
    if (notes) {
      const existing = JSON.parse((task.notes as string) || "[]") as Array<{ text: string; timestamp: string }>;
      existing.push({ text: notes, timestamp: now });
      db.prepare(`UPDATE tasks SET notes = ?, updated_at = ? WHERE id = ?`).run(
        JSON.stringify(existing),
        now,
        task_id
      );
      notesCount = existing.length;
    }

    // Update status if provided
    if (status) {
      const updates: Record<string, unknown> = { status, updated_at: now };
      if (status === "done") {
        updates.completed_at = now;
      }

      const setClauses = Object.keys(updates).map((k) => `${k} = ?`).join(", ");
      db.prepare(`UPDATE tasks SET ${setClauses} WHERE id = ?`).run(
        ...Object.values(updates),
        task_id
      );

      // Auto-unblock dependent tasks
      if (status === "done") {
        const dependents = db
          .prepare(`SELECT id, dependencies FROM tasks WHERE board_id = ? AND status = 'backlog'`)
          .all(task.board_id as string) as Record<string, unknown>[];

        const unblocked: string[] = [];
        for (const dep of dependents) {
          const depIds = JSON.parse(dep.dependencies as string) as string[];
          if (depIds.includes(task_id)) {
            const remaining = depIds.filter((d) => d !== task_id);
            if (remaining.length === 0) {
              db.prepare(`UPDATE tasks SET status = 'ready', updated_at = ? WHERE id = ?`).run(now, dep.id);
              unblocked.push(dep.id as string);
            }
          }
        }

        return {
          content: [
            {
              type: "text" as const,
              text: JSON.stringify({
                updated: true,
                task_id,
                status: effectiveStatus,
                unblocked_tasks: unblocked,
                notes_count: notesCount,
              }),
            },
          ],
        };
      }
    }

    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify({
            updated: true,
            task_id,
            status: effectiveStatus,
            notes_count: notesCount,
          }),
        },
      ],
    };
  }
);
  • src/types/index.ts:71-83 (helper)
    TASK_STATUSES constant used as zod enum for the 'status' parameter in tb_update's schema.
    export const TASK_STATUSES = [
  "backlog",
  "ready",
  "in_progress",
  "in_review",
  "done",
  "blocked",
] as const;

export type TaskStatus = (typeof TASK_STATUSES)[number];

export const TASK_PRIORITIES = ["p0", "p1", "p2", "p3"] as const;
export type TaskPriority = (typeof TASK_PRIORITIES)[number];

Tool Definition Quality

A4.6/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description carries full burden. It discloses a key behavioral constraint (transition restriction for 'done') and explains that notes are appended as timestamped entries, implying additive behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff. First sentence immediately conveys purpose; second adds essential behavioral detail. Every sentence is necessary and well-positioned.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema, but the tool is a simple mutation. The description covers behavior and constraints. Lacks return value information, but for a straightforward update+append, the agent can infer success from absence of error.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema covers 100% of parameters. The description adds meaning beyond schema: notes are timestamped, status has a conditional for 'done'. This provides context not obvious from the enum list.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Update a task's status and/or append notes') with specific resources (status and notes). It distinguishes from sibling tools like tb_add_task (which creates tasks) and tb_status (which retrieves status).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides an explicit precondition for moving to 'done' ('in_progress' or 'in_review' required). Does not explicitly mention when not to use or compare to alternatives, but the conditional guidance is helpful for correct usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

Other Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/lleontor705/forgespec-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server