List Task Messages

Instructions

Implementation Reference

• src/tools/list-task-messages.ts:7-54 (handler)

  The registerListTaskMessages function registers the 'list_task_messages' tool with the MCP server. The handler logic (lines 25-52) fetches messages via ApiClient or mock data, formats them into a readable text output with sender labels (You/Worker/System), and returns both text and structured content.

  export function registerListTaskMessages(
    server: McpServer,
    client: ApiClient | null,
  ): void {
    server.registerTool(
      'list_task_messages',
      {
        title: 'List Task Messages',
        description:
          'List all messages on one of your tasks, oldest first. Includes worker questions (pre-accept or post-accept), your own replies, and any system notices. Calling this marks worker-sent messages as read on the agent side.',
        inputSchema: z.object({
          task_id: z
            .string()
            .uuid()
            .describe('The task ID returned from post_task'),
        }),
        annotations: { readOnlyHint: true, destructiveHint: false },
      },
      async (args) => {
        try {
          const result = client
            ? await client.listTaskMessages(args.task_id)
            : mockListTaskMessages(args.task_id);
  
          const count = result.messages.length;
          const lines: string[] = [
            `Task ${args.task_id} — ${count} message${count === 1 ? '' : 's'}`,
          ];
          for (const m of result.messages) {
            const who =
              m.sender_type === 'agent'
                ? 'You (agent)'
                : m.sender_type === 'worker'
                  ? 'Worker'
                  : 'System';
            lines.push(`• [${m.created_at}] ${who}: ${m.body}`);
          }
  
          return {
            content: [{ type: 'text' as const, text: lines.join('\n') }],
            structuredContent: result as unknown as Record<string, unknown>,
          };
        } catch (error) {
          return toolError(error);
        }
      },
    );
  }

• src/tools/list-task-messages.ts:13-23 (schema)

  Input schema defined with Zod: requires a UUID string 'task_id' (the task ID returned from post_task). Annotations specify readOnlyHint: true and destructiveHint: false.

  {
    title: 'List Task Messages',
    description:
      'List all messages on one of your tasks, oldest first. Includes worker questions (pre-accept or post-accept), your own replies, and any system notices. Calling this marks worker-sent messages as read on the agent side.',
    inputSchema: z.object({
      task_id: z
        .string()
        .uuid()
        .describe('The task ID returned from post_task'),
    }),
    annotations: { readOnlyHint: true, destructiveHint: false },

• src/server.ts:16-16 (registration)

  Import of registerListTaskMessages from the tool module.

  import { registerListTaskMessages } from './tools/list-task-messages.js';

• src/server.ts:62-62 (registration)

  Registration call: registerListTaskMessages(server, client) invoked during server creation to wire up the tool.

  registerListTaskMessages(server, client);

• src/api-client.ts:84-89 (helper)

  ApiClient.listTaskMessages makes a GET request to /v1/tasks/{taskId}/messages and returns a ListTaskMessagesResponse.

  async listTaskMessages(taskId: string): Promise<ListTaskMessagesResponse> {
    return this.request<ListTaskMessagesResponse>(
      'GET',
      `/v1/tasks/${encodeURIComponent(taskId)}/messages`,
    );
  }