dsh-trello

Trello boards, lists, cards and comments as native DeepSeek Harness tools.

Uses a Trello API key + token for authentication (no OAuth or MCP), with plain outbound HTTPS requests to api.trello.com. No public hostname, callback server, or separate HTTP service.

Installation

1. Build the files (from this folder):

   npm install
   npm run build
   

2. Install the plugin. In DeepSeek Harness, open Settings -> Plugins and add the package by pointing at this folder's absolute path. (CLI-managed profiles: dsh plugin --profile <profile> add <path>.)

3. Fill in your keys in cordis.patch.yml (see Configuration).

Restart Harness (or let HMR re-compose the profile) and the eight trello_* tools appear in the session.

Configuration

Installing the bundle inserts this row automatically (with empty credentials):

- id: tool-trello
  name: dsh-trello
  config:
    apiKey: ""
    token: ""
    # optional:
    # baseUrl: https://api.trello.com
    # timeoutMs: 30000
    # passive: false

Fill in the two values in the installed package's cordis.patch.yml (or, to survive reinstalls, in an override in your profile's cordis.patch.yml):

- id: tool-trello
  config:
    apiKey: PASTE_YOUR_API_KEY
    token: PASTE_YOUR_TOKEN

Credentials are read at first use, in this order:

1. Config value (non-empty): the apiKey / token above.
2. Environment variables (fallback): TRELLO_API_KEY and TRELLO_TOKEN in the environment of the Harness process.

Both credential fields are marked secret in the plugin config schema and are stored as volatile references.

How to get the credentials:

1. Open https://trello.com/apps/admin and create a new app (no power-ups needed); pick Trello Auth as the app type.
2. On the app page, copy the API key and click Generate Token to get your token (choose the boards you want to expose).

Use a dedicated token with only the permissions you need.

When credentials are missing, every tool fails with:

Trello plugin is not configured. Set TRELLO_API_KEY and TRELLO_TOKEN.

Rotating / revoking credentials

• Rotate: generate a new token in Trello and replace token (or TRELLO_TOKEN). With volatile config, the change applies on the next tool call without a restart.
• Revoke: delete the token in Trello (My tokens). The API key stays valid but is useless without a token.

Passive (read-only) mode

The default is passive: false (full mode, all eight tools). Turning on passive mode exposes only the five read-only tools:

• trello_list_boards
• trello_get_board
• trello_list_lists
• trello_list_cards
• trello_get_card

The three mutating tools (trello_create_card, trello_update_card, and trello_add_comment) are not registered, so the agent can read Trello but cannot create, update, or comment. Credentials work the same way in passive mode.

Toggle it from the plugin menu (no file edit)

The primary way to switch modes is the Read-only mode switch on the plugin's page. In DeepSeek Harness open Settings → Plugins, select dsh-trello, and flip the switch. It takes effect immediately: turning it on drops the three mutating tools, turning it off restores them. The choice persists across restarts.

Under the hood the switch writes passive through the normal settings pipeline (configForms → remote.settings.mutate → cordis.patch.yml → hot reload), so the tool set rebuilds on the spot. The page is provided by the plugin's browser half (src/client.ts), which registers a plugins.bundle.config entry keyed by the package name dsh-trello and reads/writes the shared settings form for the tool-trello entry — the same value the YAML flag sets.

Or set it in cordis.patch.yml

Set passive: true on the row to start in read-only mode (or to override the GUI choice for a given profile):

- id: tool-trello
  config:
    apiKey: PASTE_YOUR_API_KEY
    token: PASTE_YOUR_TOKEN
    passive: true

The flag is volatile, so changing it (by either method) rebuilds the tool set on the next re-composition (HMR or restart).

Available tools

Tool	Purpose
trello_list_boards	List boards accessible to the account
trello_get_board	Get one board by id
trello_list_lists	List the lists on a board
trello_list_cards	List the cards in a list
trello_get_card	Get one card by id
trello_create_card	Create a card in a list
trello_update_card	Update a card (only provided fields change); pass listId to move it to another list
trello_add_comment	Add a comment to a card

Every tool except trello_list_boards takes an explicit id (boardId, listId, or cardId), and all return compact summaries (not raw Trello API objects). The three list tools accept an optional limit (1–100, default 50). Card deletion is deliberately not part of the initial tool set.

The first five tools are read-only; trello_create_card, trello_update_card, and trello_add_comment are the only tools that write. In passive (read-only) mode only the read-only tools are registered.

Authentication

Trello's documented key/token mechanism: every request carries key=<apiKey>&token=<token> as query parameters, with no Authorization header or callback handling. A 401 from Trello surfaces as:

Trello authentication failed. Check TRELLO_API_KEY and TRELLO_TOKEN.

Troubleshooting

Symptom	Cause / fix
Trello plugin is not configured. Set TRELLO_API_KEY and TRELLO_TOKEN.	Add apiKey/token to the profile row or export the environment variables.
Trello authentication failed. ...	The key/token pair is wrong or the token was revoked. Regenerate the token.
Trello permission denied: ...	The token was created without access to that board. Regenerate it with the needed boards selected.
Trello board/list not found: <id>	The id is wrong, or the token cannot see that resource.
Trello API request failed: rate limit exceeded. Retry after N seconds.	Trello rate limiting. Wait N seconds; keep call volume low.
Trello service failure (HTTP 5xx).	Trello-side problem; retry later.
Plugin does not appear in the session	Check that dsh-trello is in the profile's dsh.profile.bundles list, that the package installed cleanly (pnpm list dsh-trello in the profile), and that the row is not disabled. Run dsh --profile <profile> --dump-config to inspect the composed tree.

Local development

npm install
npm run build     # build:node (tsc -> dist/src, dist/test) + build:client (browser half -> dist/src/client.js)
npm test          # builds the node half, then runs node --test over dist/test/*.test.js

The package has two halves: the host half (src/index.ts, the tools and config schema, compiled to ESM by tsconfig.json) and the browser half (src/client.ts, the plugin-menu page, compiled to CommonJS by tsconfig.client.json and shipped as the package's ./client export). The Trello REST client is exposed separately at ./trello (dist/src/trello/client.js).

Two standalone checks run against the built output (no Harness required):

node scripts/smoke.mjs      # plugin contract: 8 tools, config error, auth, no leaks
node scripts/verify-dsh.mjs # real DSH schema gate + result validation

The Trello REST client (src/trello/) is independent of Harness and is tested with a mocked fetch; no real Trello calls are made by the test suite.