trelly 0.1.1 → 0.2.0

package/skills/trelly-mcp/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: trelly-mcp
+description: >-
+  Configure and use the trelly MCP stdio server (trello_boards_list,
+  trello_card_create, trello_search, etc.). Use when wiring Cursor/Claude MCP,
+  calling Trello from an IDE agent, or choosing between MCP tools vs trelly CLI.
+---
+
+# trelly-mcp
+
+MCP server for Trello (npm package **trelly**, bin **`trelly-mcp`**). Returns JSON
+envelope on every tool: `{ ok, profile, data }` /
+`{ ok: false, error, status?, details? }`. Never uses CLI human/Ink output.
+
+## Setup
+
+### 1. Auth (CLI, once)
+
+```bash
+trelly auth setup
+trelly auth login
+trelly auth list
+```
+
+### 2. Cursor — plugin or `~/.cursor/mcp.json`
+
+**Plugin (skills + MCP):** after `npm install -g trelly`:
+
+```bash
+cp -R "$(npm root -g)/trelly" ~/.cursor/plugins/local/trelly
+# or from clone: ./bin/install-cursor-plugin-local.sh
+```
+
+**MCP only** — `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "trelly": {
+      "command": "trelly-mcp",
+      "env": {
+        "TRELLO_PROFILE": "default"
+      }
+    }
+  }
+}
+```
+
+See [mcp.example.json](../../mcp.example.json).
+
+### 3. Restart the IDE
+
+Reload MCP servers after editing config.
+
+### 4. Smoke test (optional)
+
+```bash
+cd trello-cli && bun run mcp
+```
+
+Starts stdio MCP manually (IDE normally launches `trelly-mcp` itself).
+
+## Using tools
+
+- Pass **`profile`** on any tool for a non-default account (or set `TRELLO_PROFILE` in env).
+- Read **`ok`** before using **`data`**.
+- Prefer **`trello_card_archive`** / **`trello_board_archive`** to close items.
+- **`trello_card_delete`** is **permanent** — no MCP board-delete tool.
+
+## Tool catalog
+
+| Tool | Purpose |
+|------|---------|
+| `trello_profiles_list` | Saved profiles + default |
+| `trello_member_me` | Authenticated member |
+| `trello_boards_list` | Member boards (`filter`, `fields`) |
+| `trello_board_get` | Board by id |
+| `trello_board_create` | Create board |
+| `trello_board_archive` | Close board (reversible) |
+| `trello_board_lists` | Lists on board |
+| `trello_board_cards` | All cards on board |
+| `trello_list_create` | Create list |
+| `trello_list_cards` | Cards in list |
+| `trello_card_get` | Card (`fields` optional) |
+| `trello_card_create` | Create card on list |
+| `trello_card_update` | Update card fields map |
+| `trello_card_move` | Move to another list |
+| `trello_card_comments` | List comments |
+| `trello_card_comment` | Add comment |
+| `trello_card_archive` | Close card (reversible) |
+| `trello_card_delete` | **Permanent** delete |
+| `trello_checklist_create` | Checklist on card |
+| `trello_checklist_add_item` | Checklist item |
+| `trello_label_create` | Board label |
+| `trello_card_add_label` | Label on card |
+| `trello_search` | Search Trello |
+| `trello_webhooks_list` | Token webhooks |
+| `trello_webhook_create` | Create webhook |
+| `trello_webhook_delete` | Delete webhook |
+| `trello_api` | Raw REST (`method`, `path`, `query`, `body`) |
+
+## When to use MCP vs CLI
+
+| Use MCP | Use CLI |
+|---------|---------|
+| IDE agent managing Trello in chat | Terminal, shell scripts, jq pipelines |
+| Structured tool calls with schemas | `trello ui` interactive board |
+| Cursor/Codex/Claude with MCP wired | CI with `--json` |
+
+For terminal work, invoke the **trelly** skill instead.
+
+## Extending
+
+New tools: `src/mcp/tools/` — zod input, envelope `outputSchema`,
+`readOnlyHint` / `destructiveHint`. See [AGENTS.md](../../AGENTS.md).

package/src/api/client.ts

@@ -28,7 +28,7 @@ export class TrelloClient {
     method: string,
     path: string,
     query: Query = {},
-    body?: JsonValue,
+    body?: JsonValue | FormData,
   ): Promise<T> {
     const url = new URL(`${this.base}${path.startsWith("/") ? path : `/${path}`}`);
 
@@ -43,7 +43,9 @@ export class TrelloClient {
     };
 
     const init: RequestInit = { method, headers };
-    if (body !== undefined) {
+    if (body instanceof FormData) {
+      init.body = body; // fetch sets the multipart boundary
+    } else if (body !== undefined) {
       headers["Content-Type"] = "application/json";
       init.body = JSON.stringify(body);
     }
@@ -63,7 +65,11 @@ export class TrelloClient {
     return this.request("GET", path, query);
   }
 
-  post<T = JsonValue>(path: string, query?: Query, body?: JsonValue): Promise<T> {
+  post<T = JsonValue>(
+    path: string,
+    query?: Query,
+    body?: JsonValue | FormData,
+  ): Promise<T> {
     return this.request("POST", path, query, body);
   }
 
@@ -218,6 +224,15 @@ export class TrelloClient {
     return this.post(`/cards/${id}/attachments`, query);
   }
 
+  /** Upload a local file as a card attachment (multipart). */
+  cardUploadAttachment(id: string, form: FormData) {
+    return this.post(`/cards/${id}/attachments`, {}, form);
+  }
+
+  cardDeleteAttachment(id: string, attachmentId: string) {
+    return this.delete(`/cards/${id}/attachments/${attachmentId}`);
+  }
+
   cardCustomFieldItems(id: string) {
     return this.get(`/cards/${id}/customFieldItems`);
   }

package/src/cli/commands/boards.ts

@@ -71,7 +71,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("archive <id>")
     .description("Close (archive) a board — reversible in Trello UI")
-    .action((id, cmd) =>
+    .action((id, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardArchive(id);
@@ -81,7 +81,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("delete <id>")
     .description("Permanently delete a board — irreversible")
-    .action((id, cmd) =>
+    .action((id, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardDelete(id);
@@ -102,7 +102,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("cards <boardId>")
     .description("List cards on a board")
-    .action((boardId, cmd) =>
+    .action((boardId, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardCards(boardId);
@@ -112,7 +112,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("labels <boardId>")
     .description("List labels on a board")
-    .action((boardId, cmd) =>
+    .action((boardId, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardLabels(boardId);
@@ -122,7 +122,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("members <boardId>")
     .description("List board members")
-    .action((boardId, cmd) =>
+    .action((boardId, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardMembers(boardId);
@@ -143,7 +143,7 @@ export function registerBoardCommands(program: Command): void {
   boards
     .command("custom-fields <boardId>")
     .description("List custom field definitions")
-    .action((boardId, cmd) =>
+    .action((boardId, _opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
         return client.boardCustomFields(boardId);

package/src/cli/commands/cards.ts

@@ -1,4 +1,5 @@
 import type { Command } from "commander";
+import { attachmentForm } from "../../util/attachment.ts";
 import { getClient, parseJsonFlag, parseKvPairs } from "../context.ts";
 import { rootOpts, run } from "./run.ts";
 
@@ -176,15 +177,32 @@ export function registerCardCommands(program: Command): void {
 
   cards
     .command("add-attachment <id>")
-    .requiredOption("--url <url>", "Attachment URL")
+    .option("--url <url>", "Attachment URL")
+    .option("--file <path>", "Local file to upload")
     .option("--name <name>", "Attachment name")
     .action((id, opts, cmd) =>
       run(cmd, async () => {
         const { client } = getClient(rootOpts(cmd).profile);
+        if (!opts.url === !opts.file) {
+          throw new Error("Pass exactly one of --url or --file");
+        }
+        if (opts.file) {
+          return client.cardUploadAttachment(id, attachmentForm(opts.file, opts.name));
+        }
         return client.cardAddAttachment(id, { url: opts.url, name: opts.name });
       }),
     );
 
+  cards
+    .command("delete-attachment <id> <attachmentId>")
+    .description("Delete an attachment from a card")
+    .action((id, attachmentId, _opts, cmd) =>
+      run(cmd, async () => {
+        const { client } = getClient(rootOpts(cmd).profile);
+        return client.cardDeleteAttachment(id, attachmentId);
+      }),
+    );
+
   cards.command("custom-fields <id>").action((id, _opts, cmd) =>
     run(cmd, async () => {
       const { client } = getClient(rootOpts(cmd).profile);