codecks-mcp

Instructions

Implementation Reference

• src/tools/read.ts:67-146 (registration)

  Registration of the 'list_cards' tool with MCP server, including schema definition and handler that calls client.listCards() with pagination, sanitization, and response formatting.

  server.registerTool(
    "list_cards",
    {
      title: "List Cards",
      description: "List cards. Filters combine with AND.",
      inputSchema: z.object({
        deck: z.string().optional().describe("Filter by deck name"),
        status: z
          .string()
          .optional()
          .describe("Comma-separated: not_started, started, done, blocked, in_review"),
        project: z.string().optional().describe("Filter by project name"),
        search: z.string().optional().describe("Search in title and content"),
        milestone: z.string().optional().describe("Filter by milestone name"),
        tag: z.string().optional().describe("Filter by tag name"),
        owner: z.string().optional().describe("Owner name, or 'none' for unassigned"),
        priority: z.string().optional().describe("Comma-separated: a, b, c, null"),
        sort: z
          .enum(["status", "priority", "effort", "deck", "title", "owner", "updated", "created"])
          .optional(),
        card_type: z.enum(["hero", "doc"]).optional(),
        hero: z.string().optional().describe("Filter by hero card UUID"),
        hand_only: z.boolean().default(false),
        stale_days: z.number().optional().describe("Cards not updated in N days"),
        updated_after: z.string().optional().describe("YYYY-MM-DD"),
        updated_before: z.string().optional().describe("YYYY-MM-DD"),
        archived: z.boolean().default(false),
        include_stats: z.boolean().default(false),
        limit: z.number().default(50),
        offset: z.number().default(0),
      }),
    },
    async (args) => {
      try {
        const result = await client.listCards({
          deck: args.deck,
          status: args.status,
          project: args.project,
          search: args.search,
          milestone: args.milestone,
          tag: args.tag,
          owner: args.owner,
          priority: args.priority,
          sort: args.sort,
          cardType: args.card_type,
          hero: args.hero,
          handOnly: args.hand_only,
          staleDays: args.stale_days,
          updatedAfter: args.updated_after,
          updatedBefore: args.updated_before,
          archived: args.archived,
          includeStats: args.include_stats,
        });
  
        const allCards = (result.cards ?? []) as Record<string, unknown>[];
        const total = allCards.length;
        const page = allCards.slice(args.offset, args.offset + args.limit);
        const payload = {
          cards: page.map((c) => sanitizeCard(slimCard(c))),
          stats: result.stats,
          total_count: total,
          has_more: args.offset + args.limit < total,
          limit: args.limit,
          offset: args.offset,
        };
        return {
          content: [{ type: "text", text: JSON.stringify(finalizeToolResult(payload)) }],
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(finalizeToolResult(handleError(err))),
            },
          ],
        };
      }
    },
  );

• src/tools/read.ts:68-97 (schema)

  Input schema definition for list_cards tool using zod, specifying all filter options (deck, status, project, search, milestone, tag, owner, priority, sort, card_type, hero, hand_only, stale_days, updated_after, updated_before, archived, include_stats, limit, offset).

  "list_cards",
  {
    title: "List Cards",
    description: "List cards. Filters combine with AND.",
    inputSchema: z.object({
      deck: z.string().optional().describe("Filter by deck name"),
      status: z
        .string()
        .optional()
        .describe("Comma-separated: not_started, started, done, blocked, in_review"),
      project: z.string().optional().describe("Filter by project name"),
      search: z.string().optional().describe("Search in title and content"),
      milestone: z.string().optional().describe("Filter by milestone name"),
      tag: z.string().optional().describe("Filter by tag name"),
      owner: z.string().optional().describe("Owner name, or 'none' for unassigned"),
      priority: z.string().optional().describe("Comma-separated: a, b, c, null"),
      sort: z
        .enum(["status", "priority", "effort", "deck", "title", "owner", "updated", "created"])
        .optional(),
      card_type: z.enum(["hero", "doc"]).optional(),
      hero: z.string().optional().describe("Filter by hero card UUID"),
      hand_only: z.boolean().default(false),
      stale_days: z.number().optional().describe("Cards not updated in N days"),
      updated_after: z.string().optional().describe("YYYY-MM-DD"),
      updated_before: z.string().optional().describe("YYYY-MM-DD"),
      archived: z.boolean().default(false),
      include_stats: z.boolean().default(false),
      limit: z.number().default(50),
      offset: z.number().default(0),
    }),

• src/tools/read.ts:99-145 (handler)

  The tool handler function that processes list_cards requests, calls client.listCards(), applies pagination (offset/limit), sanitizes results with slimCard and sanitizeCard, and returns formatted response with cards array, stats, total_count, has_more, limit, and offset.

  async (args) => {
    try {
      const result = await client.listCards({
        deck: args.deck,
        status: args.status,
        project: args.project,
        search: args.search,
        milestone: args.milestone,
        tag: args.tag,
        owner: args.owner,
        priority: args.priority,
        sort: args.sort,
        cardType: args.card_type,
        hero: args.hero,
        handOnly: args.hand_only,
        staleDays: args.stale_days,
        updatedAfter: args.updated_after,
        updatedBefore: args.updated_before,
        archived: args.archived,
        includeStats: args.include_stats,
      });
  
      const allCards = (result.cards ?? []) as Record<string, unknown>[];
      const total = allCards.length;
      const page = allCards.slice(args.offset, args.offset + args.limit);
      const payload = {
        cards: page.map((c) => sanitizeCard(slimCard(c))),
        stats: result.stats,
        total_count: total,
        has_more: args.offset + args.limit < total,
        limit: args.limit,
        offset: args.offset,
      };
      return {
        content: [{ type: "text", text: JSON.stringify(finalizeToolResult(payload)) }],
      };
    } catch (err) {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(finalizeToolResult(handleError(err))),
          },
        ],
      };
    }
  },

• src/client.ts:44-158 (handler)

  Implementation of CodecksClient.listCards() method - builds GraphQL query, handles server-side filters (status, priority, cardType, archived), performs client-side filtering (deck, search, owner, staleDays), applies sorting, computes optional stats, and returns cards array.

  async listCards(
    options: {
      deck?: string;
      status?: string;
      project?: string;
      search?: string;
      milestone?: string;
      tag?: string;
      owner?: string;
      priority?: string;
      sort?: string;
      cardType?: string;
      hero?: string;
      handOnly?: boolean;
      staleDays?: number;
      updatedAfter?: string;
      updatedBefore?: string;
      archived?: boolean;
      includeStats?: boolean;
    } = {},
  ): Promise<Record<string, unknown>> {
    // Build query filters
    const filters: Record<string, unknown> = {};
    if (options.status) {
      const statuses = options.status.split(",").map((s) => s.trim());
      filters.status = statuses.length === 1 ? statuses[0] : statuses;
    }
    if (options.priority) {
      const pris = options.priority.split(",").map((p) => p.trim());
      filters.priority = pris.length === 1 ? pris[0] : pris;
    }
    if (options.cardType === "hero") filters.cardType = "hero";
    if (options.cardType === "doc") filters.cardType = "doc";
    if (options.archived) filters.visibility = "archived";
  
    const cardFields = [
      "id",
      "title",
      "status",
      "priority",
      "effort",
      "createdAt",
      "lastUpdatedAt",
      { assignee: ["name"] },
      { deck: ["title"] },
      { milestone: ["title"] },
      { masterTags: ["name"] },
    ];
  
    const q: Record<string, unknown> = {
      _root: [
        {
          account: [
            {
              [`${options.archived ? "archivedCards" : "cards"}`]: cardFields,
            },
          ],
        },
      ],
    };
  
    const result = await query(q);
    let cards = this.extractCards(result);
  
    // Client-side filtering
    if (options.deck) {
      cards = cards.filter(
        (c) =>
          String(getField(c, "deck_name", "deckName") ?? "").toLowerCase() ===
          options.deck!.toLowerCase(),
      );
    }
    if (options.search) {
      const term = options.search.toLowerCase();
      cards = cards.filter(
        (c) =>
          String(c.title ?? "")
            .toLowerCase()
            .includes(term) ||
          String(c.content ?? "")
            .toLowerCase()
            .includes(term),
      );
    }
    if (options.owner) {
      if (options.owner === "none") {
        cards = cards.filter((c) => !c.owner_name);
      } else {
        const name = options.owner.toLowerCase();
        cards = cards.filter((c) => String(c.owner_name ?? "").toLowerCase() === name);
      }
    }
    if (options.staleDays) {
      const cutoff = new Date();
      cutoff.setDate(cutoff.getDate() - options.staleDays);
      cards = cards.filter((c) => {
        const updated = parseIsoTimestamp(getField(c, "last_updated_at", "lastUpdatedAt"));
        return updated && updated < cutoff;
      });
    }
  
    // Sort
    if (options.sort) {
      const sortField = options.sort;
      const reverse = sortField === "updated" || sortField === "created";
      cards.sort((a, b) => {
        const va = String(getField(a, sortField) ?? "");
        const vb = String(getField(b, sortField) ?? "");
        return reverse ? vb.localeCompare(va) : va.localeCompare(vb);
      });
    }
  
    const stats = options.includeStats ? this.computeStats(cards) : null;
    return { cards, stats };
  }

• src/tools/read.ts:26-32 (helper)

  Helper function slimCard() that removes redundant raw IDs (deckId, milestoneId, assignee, projectId, childCardInfo, masterTags) from card objects for token efficiency.

  function slimCard(card: Record<string, unknown>): Record<string, unknown> {
    const out: Record<string, unknown> = {};
    for (const [k, v] of Object.entries(card)) {
      if (!SLIM_DROP.has(k)) out[k] = v;
    }
    return out;
  }