trelly 0.1.0

package/src/index.test.ts

@@ -0,0 +1,117 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { parseTrelloResponse, trelloErrorMessage } from "./api/http.ts";
+import { authLoginUrl } from "./auth/profiles.ts";
+import { parseKvPairs } from "./cli/context.ts";
+import { customFieldChips } from "./cli/ui/custom-fields.ts";
+import { dueStatus, labelHex, listAccentHex } from "./cli/ui/palette.ts";
+import { isBoard, isCard, isLabel, isList } from "./cli/ui/shapes.ts";
+
+describe("parseKvPairs", () => {
+  it("parses key=value pairs", () => {
+    assert.deepEqual(parseKvPairs(["name=foo", "closed=true"]), {
+      name: "foo",
+      closed: "true",
+    });
+  });
+
+  it("rejects invalid pairs", () => {
+    assert.throws(() => parseKvPairs(["invalid"]), /Invalid key=value/);
+  });
+});
+
+describe("authLoginUrl", () => {
+  it("defaults to read,write and 30days", () => {
+    const url = new URL(authLoginUrl("test-key"));
+    assert.equal(url.searchParams.get("key"), "test-key");
+    assert.equal(url.searchParams.get("scope"), "read,write");
+    assert.equal(url.searchParams.get("expiration"), "30days");
+  });
+
+  it("supports callback return_url", () => {
+    const url = new URL(
+      authLoginUrl("test-key", {
+        returnUrl: "http://127.0.0.1:14189/callback",
+      }),
+    );
+    assert.equal(url.searchParams.get("callback_method"), "fragment");
+    assert.equal(url.searchParams.get("return_url"), "http://127.0.0.1:14189/callback");
+  });
+});
+
+describe("trello HTTP helpers", () => {
+  it("parses JSON responses", () => {
+    assert.deepEqual(parseTrelloResponse('{"id":"1"}'), { id: "1" });
+  });
+
+  it("extracts Trello error messages", () => {
+    assert.equal(
+      trelloErrorMessage({ message: "invalid token" }, 401),
+      "invalid token",
+    );
+    assert.equal(trelloErrorMessage(null, 500), "Trello API 500");
+  });
+});
+
+describe("ui palette", () => {
+  it("maps Trello label colors including shades", () => {
+    assert.equal(labelHex("green"), "#61bd4f");
+    assert.equal(labelHex("green_dark"), "#61bd4f");
+    assert.equal(labelHex(null), "#6b778c");
+    assert.equal(labelHex("mauve"), "#6b778c");
+  });
+
+  it("maps list accents, falling back to Trello blue", () => {
+    assert.equal(listAccentHex(null), "#0079bf");
+    assert.equal(listAccentHex(undefined), "#0079bf");
+    assert.equal(listAccentHex("teal"), "#6cc3e0");
+    assert.equal(listAccentHex("purple"), "#0079bf");
+  });
+
+  it("classifies due status", () => {
+    const now = new Date("2026-07-03T12:00:00Z");
+    assert.equal(dueStatus(null, false, now), "none");
+    assert.equal(dueStatus("2026-07-01T00:00:00Z", true, now), "complete");
+    assert.equal(dueStatus("2026-07-01T00:00:00Z", false, now), "overdue");
+    assert.equal(dueStatus("2026-07-03T18:00:00Z", false, now), "soon");
+    assert.equal(dueStatus("2026-08-01T00:00:00Z", false, now), "later");
+  });
+});
+
+describe("custom field chips", () => {
+  const defs = [
+    {
+      id: "f1",
+      name: "Priority",
+      type: "list",
+      cardFront: true,
+      options: [{ id: "o1", text: "Highest", color: "red" }],
+    },
+    { id: "f2", name: "Points", type: "number", cardFront: true, options: [] },
+  ];
+
+  it("resolves list options and raw values, skipping unknown fields", () => {
+    const chips = customFieldChips(defs, [
+      { idCustomField: "f1", idValue: "o1" },
+      { idCustomField: "f2", value: { number: "5" } },
+      { idCustomField: "missing", idValue: "x" },
+    ]);
+    assert.deepEqual(chips, [
+      { id: "f1", label: "Priority: Highest", color: "red" },
+      { id: "f2", label: "Points: 5", color: null },
+    ]);
+  });
+});
+
+describe("ui shapes", () => {
+  it("distinguishes cards, lists, labels, and boards", () => {
+    const card = { id: "c", name: "Card", idList: "l", idBoard: "b", pos: 1 };
+    const list = { id: "l", name: "List", idBoard: "b", pos: 2, closed: false };
+    const label = { id: "lb", name: "bug", color: "red", idBoard: "b" };
+    const board = { id: "b", name: "Board", prefs: {}, idOrganization: "o" };
+    assert.ok(isCard(card) && !isCard(list) && !isCard(board));
+    assert.ok(isList(list) && !isList(card) && !isList(label));
+    assert.ok(isLabel(label) && !isLabel(list) && !isLabel(card));
+    assert.ok(isBoard(board) && !isBoard(card) && !isBoard(list));
+  });
+});

package/src/mcp/handlers.ts

@@ -0,0 +1,61 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
+import { type JsonValue, type TrelloClient, TrelloError } from "../api/client.ts";
+import { getClient } from "../cli/context.ts";
+
+export const toolEnvelopeSchema = z.object({
+  ok: z.boolean(),
+  profile: z.string().optional(),
+  data: z.unknown().optional(),
+  error: z.string().optional(),
+  status: z.number().optional(),
+  details: z.unknown().optional(),
+});
+
+export type ToolEnvelope = z.infer<typeof toolEnvelopeSchema>;
+
+export const profileField = z.string().optional().describe("Auth profile name");
+
+export function toolResult(envelope: ToolEnvelope): CallToolResult {
+  return {
+    structuredContent: envelope,
+    content: [{ type: "text", text: JSON.stringify(envelope, null, 2) }],
+    isError: envelope.ok === false,
+  };
+}
+
+export async function withClient<T>(
+  profile: string | undefined,
+  fn: (client: TrelloClient, profileName: string) => Promise<T>,
+): Promise<CallToolResult> {
+  try {
+    const { profileName, client } = getClient(profile);
+    const data = await fn(client, profileName);
+    return toolResult({ ok: true, profile: profileName, data });
+  } catch (err) {
+    if (err instanceof TrelloError) {
+      return toolResult({
+        ok: false,
+        error: err.message,
+        status: err.status,
+        details: err.body,
+      });
+    }
+    return toolResult({
+      ok: false,
+      error: err instanceof Error ? err.message : String(err),
+    });
+  }
+}
+
+export async function runApi(
+  profile: string | undefined,
+  method: string,
+  path: string,
+  query: Record<string, string> | undefined,
+  body: JsonValue | undefined,
+): Promise<CallToolResult> {
+  return withClient(profile, (client) =>
+    client.request(method.toUpperCase(), path, query ?? {}, body),
+  );
+}

package/src/mcp/server.ts

@@ -0,0 +1,17 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { packageVersion } from "../version.ts";
+import { registerTrelloTools } from "./tools/index.ts";
+
+const server = new McpServer({ name: "trelly", version: packageVersion() });
+registerTrelloTools(server);
+
+async function main(): Promise<void> {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/mcp/tools/api.ts

@@ -0,0 +1,27 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import type { JsonValue } from "../../api/client.ts";
+import { profileField, runApi, toolEnvelopeSchema } from "../handlers.ts";
+
+export function registerApiTools(server: McpServer): void {
+  const outputSchema = toolEnvelopeSchema;
+
+  server.registerTool(
+    "trello_api",
+    {
+      description:
+        "Raw Trello REST escape hatch. path like /boards/{id}. Prefer specific tools when possible.",
+      inputSchema: {
+        profile: profileField,
+        method: z.enum(["GET", "POST", "PUT", "DELETE"]).default("GET"),
+        path: z.string().min(1),
+        query: z.record(z.string(), z.string()).optional(),
+        body: z.unknown().optional(),
+      },
+      annotations: { destructiveHint: true },
+      outputSchema,
+    },
+    async ({ profile, method, path, query, body }) =>
+      runApi(profile, method, path, query, body as JsonValue | undefined),
+  );
+}

package/src/mcp/tools/boards.ts

@@ -0,0 +1,116 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+
+export function registerBoardTools(server: McpServer): void {
+  const outputSchema = toolEnvelopeSchema;
+
+  server.registerTool(
+    "trello_boards_list",
+    {
+      description: "List boards visible to the authenticated member.",
+      inputSchema: {
+        profile: profileField,
+        filter: z
+          .enum([
+            "all",
+            "closed",
+            "memberships",
+            "open",
+            "organization",
+            "pinned",
+            "public",
+            "starred",
+            "unpinned",
+          ])
+          .optional()
+          .default("open"),
+        fields: z.string().optional(),
+      },
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async ({ profile, filter, fields }) =>
+      withClient(profile, (client) => client.memberBoards("me", { filter, fields })),
+  );
+
+  server.registerTool(
+    "trello_board_get",
+    {
+      description: "Get a board by id.",
+      inputSchema: {
+        profile: profileField,
+        boardId: z.string().min(1),
+        fields: z.string().optional(),
+      },
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async ({ profile, boardId, fields }) =>
+      withClient(profile, (client) => client.boardGet(boardId, { fields })),
+  );
+
+  server.registerTool(
+    "trello_board_create",
+    {
+      description: "Create a board.",
+      inputSchema: {
+        profile: profileField,
+        name: z.string().min(1),
+        description: z.string().optional(),
+        organizationId: z.string().optional(),
+        defaultLists: z.boolean().optional(),
+      },
+      outputSchema,
+    },
+    async ({ profile, name, description, organizationId, defaultLists }) =>
+      withClient(profile, (client) =>
+        client.boardCreate({
+          name,
+          desc: description,
+          idOrganization: organizationId,
+          defaultLists,
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "trello_board_archive",
+    {
+      description: "Close (archive) a board. Reversible in the Trello UI.",
+      inputSchema: { profile: profileField, boardId: z.string().min(1) },
+      annotations: { destructiveHint: true },
+      outputSchema,
+    },
+    async ({ profile, boardId }) =>
+      withClient(profile, (client) => client.boardArchive(boardId)),
+  );
+
+  server.registerTool(
+    "trello_board_lists",
+    {
+      description: "List lists on a board.",
+      inputSchema: {
+        profile: profileField,
+        boardId: z.string().min(1),
+        filter: z.string().optional().default("open"),
+      },
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async ({ profile, boardId, filter }) =>
+      withClient(profile, (client) => client.boardLists(boardId, { filter })),
+  );
+
+  server.registerTool(
+    "trello_board_cards",
+    {
+      description: "List all cards on a board.",
+      inputSchema: { profile: profileField, boardId: z.string().min(1) },
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async ({ profile, boardId }) =>
+      withClient(profile, (client) => client.boardCards(boardId)),
+  );
+}

package/src/mcp/tools/cards.ts

@@ -0,0 +1,138 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+
+export function registerCardTools(server: McpServer): void {
+  const outputSchema = toolEnvelopeSchema;
+
+  server.registerTool(
+    "trello_card_get",
+    {
+      description: "Get a card by id or short link.",
+      inputSchema: {
+        profile: profileField,
+        cardId: z.string().min(1),
+        fields: z.string().optional(),
+      },
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async ({ profile, cardId, fields }) =>
+      withClient(profile, (client) => client.cardGet(cardId, { fields })),
+  );
+
+  server.registerTool(
+    "trello_card_create",
+    {
+      description: "Create a card on a list.",
+      inputSchema: {
+        profile: profileField,
+        listId: z.string().min(1),
+        name: z.string().min(1),
+        description: z.string().optional(),
+        due: z.string().optional(),
+        position: z.string().optional(),
+      },
+      outputSchema,
+    },
+    async ({ profile, listId, name, description, due, position }) =>
+      withClient(profile, (client) =>
+        client.cardCreate({
+          idList: listId,
+          name,
+          desc: description,
+          due,
+          pos: position,
+        }),
+      ),
+  );
+
+  server.registerTool(
+    "trello_card_update",
+    {
+      description: "Update card fields (name, desc, due, closed, idList, etc.).",
+      inputSchema: {
+        profile: profileField,
+        cardId: z.string().min(1),
+        fields: z.record(z.string(), z.string()),
+      },
+      outputSchema,
+    },
+    async ({ profile, cardId, fields }) =>
+      withClient(profile, (client) => client.cardUpdate(cardId, fields)),
+  );
+
+  server.registerTool(
+    "trello_card_move",
+    {
+      description: "Move a card to another list.",
+      inputSchema: {
+        profile: profileField,
+        cardId: z.string().min(1),
+        listId: z.string().min(1),
+        position: z.string().optional(),
+      },
+      outputSchema,
+    },
+    async ({ profile, cardId, listId, position }) =>
+      withClient(profile, (client) =>
+        client.cardUpdate(cardId, { idList: listId, pos: position }),
+      ),
+  );
+
+  server.registerTool(
+    "trello_card_comments",
+    {
+      description: "List comments on a card.",
+      inputSchema: {
+        profile: profileField,
+        cardId: z.string().min(1),
+        limit: z.number().int().positive().optional(),
+      },
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async ({ profile, cardId, limit }) =>
+      withClient(profile, (client) => client.cardComments(cardId, { limit })),
+  );
+
+  server.registerTool(
+    "trello_card_comment",
+    {
+      description: "Add a comment to a card.",
+      inputSchema: {
+        profile: profileField,
+        cardId: z.string().min(1),
+        text: z.string().min(1),
+      },
+      outputSchema,
+    },
+    async ({ profile, cardId, text }) =>
+      withClient(profile, (client) => client.cardComment(cardId, text)),
+  );
+
+  server.registerTool(
+    "trello_card_archive",
+    {
+      description: "Close (archive) a card. Reversible in the Trello UI.",
+      inputSchema: { profile: profileField, cardId: z.string().min(1) },
+      annotations: { destructiveHint: true },
+      outputSchema,
+    },
+    async ({ profile, cardId }) =>
+      withClient(profile, (client) => client.cardArchive(cardId)),
+  );
+
+  server.registerTool(
+    "trello_card_delete",
+    {
+      description:
+        "Permanently delete a card. Irreversible — prefer trello_card_archive to close.",
+      inputSchema: { profile: profileField, cardId: z.string().min(1) },
+      annotations: { destructiveHint: true },
+      outputSchema,
+    },
+    async ({ profile, cardId }) =>
+      withClient(profile, (client) => client.cardDelete(cardId)),
+  );
+}

package/src/mcp/tools/checklists.ts

@@ -0,0 +1,40 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+
+export function registerChecklistTools(server: McpServer): void {
+  const outputSchema = toolEnvelopeSchema;
+
+  server.registerTool(
+    "trello_checklist_create",
+    {
+      description: "Create a checklist on a card.",
+      inputSchema: {
+        profile: profileField,
+        cardId: z.string().min(1),
+        name: z.string().min(1),
+      },
+      outputSchema,
+    },
+    async ({ profile, cardId, name }) =>
+      withClient(profile, (client) => client.checklistCreate({ idCard: cardId, name })),
+  );
+
+  server.registerTool(
+    "trello_checklist_add_item",
+    {
+      description: "Add an item to a checklist.",
+      inputSchema: {
+        profile: profileField,
+        checklistId: z.string().min(1),
+        name: z.string().min(1),
+        checked: z.boolean().optional(),
+      },
+      outputSchema,
+    },
+    async ({ profile, checklistId, name, checked }) =>
+      withClient(profile, (client) =>
+        client.checklistAddItem(checklistId, { name, checked }),
+      ),
+  );
+}

package/src/mcp/tools/index.ts

@@ -0,0 +1,22 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { registerApiTools } from "./api.ts";
+import { registerBoardTools } from "./boards.ts";
+import { registerCardTools } from "./cards.ts";
+import { registerChecklistTools } from "./checklists.ts";
+import { registerLabelTools } from "./labels.ts";
+import { registerListTools } from "./lists.ts";
+import { registerProfileTools } from "./profiles.ts";
+import { registerSearchTools } from "./search.ts";
+import { registerWebhookTools } from "./webhooks.ts";
+
+export function registerTrelloTools(server: McpServer): void {
+  registerProfileTools(server);
+  registerBoardTools(server);
+  registerListTools(server);
+  registerCardTools(server);
+  registerChecklistTools(server);
+  registerLabelTools(server);
+  registerSearchTools(server);
+  registerWebhookTools(server);
+  registerApiTools(server);
+}

package/src/mcp/tools/labels.ts

@@ -0,0 +1,40 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+
+export function registerLabelTools(server: McpServer): void {
+  const outputSchema = toolEnvelopeSchema;
+
+  server.registerTool(
+    "trello_label_create",
+    {
+      description: "Create a board label.",
+      inputSchema: {
+        profile: profileField,
+        boardId: z.string().min(1),
+        name: z.string().min(1),
+        color: z.string().min(1),
+      },
+      outputSchema,
+    },
+    async ({ profile, boardId, name, color }) =>
+      withClient(profile, (client) =>
+        client.labelCreate({ idBoard: boardId, name, color }),
+      ),
+  );
+
+  server.registerTool(
+    "trello_card_add_label",
+    {
+      description: "Add a label to a card.",
+      inputSchema: {
+        profile: profileField,
+        cardId: z.string().min(1),
+        labelId: z.string().min(1),
+      },
+      outputSchema,
+    },
+    async ({ profile, cardId, labelId }) =>
+      withClient(profile, (client) => client.cardAddLabel(cardId, labelId)),
+  );
+}

package/src/mcp/tools/lists.ts

@@ -0,0 +1,37 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+
+export function registerListTools(server: McpServer): void {
+  const outputSchema = toolEnvelopeSchema;
+
+  server.registerTool(
+    "trello_list_create",
+    {
+      description: "Create a list on a board.",
+      inputSchema: {
+        profile: profileField,
+        boardId: z.string().min(1),
+        name: z.string().min(1),
+        position: z.string().optional(),
+      },
+      outputSchema,
+    },
+    async ({ profile, boardId, name, position }) =>
+      withClient(profile, (client) =>
+        client.listCreate({ idBoard: boardId, name, pos: position }),
+      ),
+  );
+
+  server.registerTool(
+    "trello_list_cards",
+    {
+      description: "List cards in a list.",
+      inputSchema: { profile: profileField, listId: z.string().min(1) },
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async ({ profile, listId }) =>
+      withClient(profile, (client) => client.listCards(listId)),
+  );
+}

package/src/mcp/tools/profiles.ts

@@ -0,0 +1,40 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+
+export function registerProfileTools(server: McpServer): void {
+  const outputSchema = toolEnvelopeSchema;
+
+  server.registerTool(
+    "trello_profiles_list",
+    {
+      description: "List saved Trello auth profiles and the active default.",
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async () =>
+      withClient(undefined, async (_client, profileName) => {
+        const { loadConfig } = await import("../../auth/profiles.ts");
+        const config = loadConfig();
+        return {
+          activeProfile: profileName,
+          defaultProfile: config.defaultProfile,
+          profiles: Object.entries(config.profiles).map(([name, p]) => ({
+            name,
+            label: p.label,
+            isDefault: name === config.defaultProfile,
+          })),
+        };
+      }),
+  );
+
+  server.registerTool(
+    "trello_member_me",
+    {
+      description: "Get the authenticated Trello member.",
+      inputSchema: { profile: profileField },
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async ({ profile }) => withClient(profile, (client) => client.memberMe()),
+  );
+}

package/src/mcp/tools/search.ts

@@ -0,0 +1,31 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+import { profileField, toolEnvelopeSchema, withClient } from "../handlers.ts";
+
+export function registerSearchTools(server: McpServer): void {
+  const outputSchema = toolEnvelopeSchema;
+
+  server.registerTool(
+    "trello_search",
+    {
+      description: "Search Trello for cards, boards, members, and actions.",
+      inputSchema: {
+        profile: profileField,
+        query: z.string().min(1),
+        modelTypes: z.string().optional(),
+        cardsLimit: z.number().int().positive().optional(),
+        boardsLimit: z.number().int().positive().optional(),
+      },
+      annotations: { readOnlyHint: true },
+      outputSchema,
+    },
+    async ({ profile, query, modelTypes, cardsLimit, boardsLimit }) =>
+      withClient(profile, (client) =>
+        client.search(query, {
+          modelTypes,
+          cards_limit: cardsLimit,
+          boards_limit: boardsLimit,
+        }),
+      ),
+  );
+}