codecks-mcp

Instructions

Implementation Reference

• src/tools/read.ts:148-191 (handler)

  MCP tool registration and handler for 'get_card'. Registers the tool with its schema (card_id, include_content, include_conversations, archived) and implements the async handler that validates the UUID, calls client.getCard(), and returns sanitized results.

  server.registerTool(
    "get_card",
    {
      title: "Get Card",
      description:
        "Get full card details (content, checklist, sub-cards, conversations, hand status).",
      inputSchema: z.object({
        card_id: z.string().describe("Full 36-char UUID"),
        include_content: z
          .boolean()
          .default(true)
          .describe("False to strip body for metadata-only checks"),
        include_conversations: z.boolean().default(true).describe("False to skip comment threads"),
        archived: z.boolean().default(false),
      }),
    },
    async (args) => {
      try {
        validateUuid(args.card_id);
        const result = await client.getCard(args.card_id, {
          includeContent: args.include_content,
          includeConversations: args.include_conversations,
          archived: args.archived,
        });
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(finalizeToolResult(sanitizeCard(result))),
            },
          ],
        };
      } catch (err) {
        return {
          content: [
            {
              type: "text",
              text: JSON.stringify(finalizeToolResult(handleError(err))),
            },
          ],
        };
      }
    },
  );

• src/client.ts:160-194 (handler)

  Client implementation of getCard method. Constructs GraphQL query fields based on options, executes the query, validates the card exists, and enriches the card with additional fields before returning.

  async getCard(
    cardId: string,
    options: {
      includeContent?: boolean;
      includeConversations?: boolean;
      archived?: boolean;
    } = {},
  ): Promise<Record<string, unknown>> {
    const { includeContent = true, includeConversations = true } = options;
  
    const fields: unknown[] = [
      "id",
      "title",
      "status",
      "priority",
      "effort",
      "createdAt",
      "lastUpdatedAt",
      { assignee: ["name"] },
      { deck: ["title"] },
      { milestone: ["title"] },
      { masterTags: ["name"] },
      { childCards: ["id", "title", "status"] },
    ];
    if (includeContent) fields.push("content");
  
    const result = await query({
      card: { _args: { id: cardId }, _fields: fields },
    });
  
    const card = (result.card ?? result[cardId]) as Record<string, unknown>;
    if (!card) throw new CliError(`[ERROR] Card not found: ${cardId}`);
  
    return this.enrichCard(card, { includeContent, includeConversations });
  }

• src/client.ts:687-711 (helper)

  enrichCard helper method that flattens nested relation objects (assignee→owner_name, deck→deck_name, milestone→milestone_name, masterTags→tags, childCards→sub_cards) for easier client consumption.

  private enrichCard(
    card: Record<string, unknown>,
    _options: {
      includeContent?: boolean;
      includeConversations?: boolean;
    },
  ): Record<string, unknown> {
    // Flatten nested relations
    if (card.assignee && typeof card.assignee === "object") {
      card.owner_name = (card.assignee as Record<string, unknown>).name;
    }
    if (card.deck && typeof card.deck === "object") {
      card.deck_name = (card.deck as Record<string, unknown>).title;
    }
    if (card.milestone && typeof card.milestone === "object") {
      card.milestone_name = (card.milestone as Record<string, unknown>).title;
    }
    if (Array.isArray(card.masterTags)) {
      card.tags = (card.masterTags as Record<string, unknown>[]).map((t) => t.name);
    }
    if (Array.isArray(card.childCards)) {
      card.sub_cards = card.childCards;
    }
    return card;
  }

• src/security.ts:173-180 (helper)

  validateUuid helper that validates a UUID string must be 36 characters with 4 hyphens, throwing CliError if invalid. Called by get_card handler to validate the card_id input.

  export function validateUuid(value: string, field = "card_id"): string {
    if (typeof value !== "string" || value.length !== 36 || (value.match(/-/g) ?? []).length !== 4) {
      throw new CliError(
        `[ERROR] ${field} must be a full 36-char UUID, got: ${JSON.stringify(value)}`,
      );
    }
    return value;
  }

• src/security.ts:46-96 (helper)

  sanitizeCard helper that performs security sanitization on card objects. Tags user text fields (title, content, etc.) with [USER_DATA] markers, checks for injection patterns, and recursively sanitizes sub_cards and conversations.

  export function sanitizeCard(card: Record<string, unknown>): Record<string, unknown> {
    const out = { ...card };
    const warnings: string[] = [];
  
    for (const field of USER_TEXT_FIELDS) {
      if (field in out && typeof out[field] === "string") {
        for (const desc of checkInjection(out[field] as string)) {
          warnings.push(`${field}: ${desc}`);
        }
        out[field] = tagUserText(out[field] as string);
      }
    }
  
    if (Array.isArray(out.sub_cards)) {
      out.sub_cards = (out.sub_cards as Record<string, unknown>[]).map((sc) => {
        const tagged = { ...sc };
        if (typeof tagged.title === "string") {
          for (const desc of checkInjection(tagged.title as string)) {
            warnings.push(`sub_card.title: ${desc}`);
          }
          tagged.title = tagUserText(tagged.title as string);
        }
        return tagged;
      });
    }
  
    if (Array.isArray(out.conversations)) {
      out.conversations = (out.conversations as Record<string, unknown>[]).map((conv) => {
        const tagged = { ...conv };
        if (Array.isArray(tagged.messages)) {
          tagged.messages = (tagged.messages as Record<string, unknown>[]).map((msg) => {
            const m = { ...msg };
            if (typeof m.content === "string") {
              for (const desc of checkInjection(m.content as string)) {
                warnings.push(`conversation.message: ${desc}`);
              }
              m.content = tagUserText(m.content as string);
            }
            return m;
          });
        }
        return tagged;
      });
    }
  
    if (warnings.length > 0) {
      out._safety_warnings = warnings;
    }
  
    return out;
  }