codecks-mcp

Instructions

Implementation Reference

• src/tools/comments.ts:140-172 (registration)

  Tool registration with input schema (card_id: UUID) and handler function that validates input, calls client.listConversations, sanitizes results, and returns formatted output.

  server.registerTool(
    "list_conversations",
    {
      title: "List Conversations",
      description: "List all comment threads on a card with messages and thread IDs.",
      inputSchema: z.object({
        card_id: z.string().describe("Full 36-char UUID"),
      }),
    },
    async (args) => {
      try {
        validateUuid(args.card_id);
        const result = await client.listConversations(args.card_id);
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(finalizeToolResult(sanitizeConversations(result))),
            },
          ],
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(finalizeToolResult(handleError(err))),
            },
          ],
        };
      }
    },
  );

• src/client.ts:633-649 (handler)

  Core implementation: uses query API to fetch conversations for a card, including thread ID, status, and messages (id, content, createdAt, user.name).

  async listConversations(cardId: string): Promise<Record<string, unknown>> {
    const result = await query({
      card: {
        _args: { id: cardId },
        _fields: [
          {
            conversations: [
              "id",
              "status",
              { messages: ["id", "content", "createdAt", { user: ["name"] }] },
            ],
          },
        ],
      },
    });
    return result;
  }

• src/security.ts:115-143 (helper)

  Security helper that sanitizes conversation data by tagging user text in message content for proper output formatting.

  export function sanitizeConversations(data: Record<string, unknown>): Record<string, unknown> {
    const out = { ...data };
    for (const [key, val] of Object.entries(out)) {
      if (Array.isArray(val)) {
        out[key] = val.map((item) => {
          if (typeof item === "object" && item !== null) {
            const m = { ...item } as Record<string, unknown>;
            if (typeof m.content === "string") {
              m.content = tagUserText(m.content as string);
            }
            return m;
          }
          return item;
        });
      } else if (typeof val === "object" && val !== null) {
        const entries = val as Record<string, Record<string, unknown>>;
        const tagged: Record<string, Record<string, unknown>> = {};
        for (const [id, entry] of Object.entries(entries)) {
          const e = { ...entry };
          if (typeof e.content === "string") {
            e.content = tagUserText(e.content as string);
          }
          tagged[id] = e;
        }
        out[key] = tagged;
      }
    }
    return out;
  }