# HireLens Trello MCP Server

A small MCP server that gives the **HireLens** Dust agent read/write access to one
Trello board: the "Post-sales SE hiring" pipeline. It exposes exactly three tools —
`get_card`, `add_comment`, `set_description` — and no business logic. Everything about
*what* HireLens writes and *when* lives in the agent's own prompt, not in this code.

## How it fits together

1. A human moves a card between lists on the Trello board.
2. A Trello Butler rule fires a webhook to Dust (already set up, outside this repo).
3. Dust starts the HireLens agent with the card URL.
4. HireLens calls `get_card` on this server to read the card (name, current list,
   description, every comment oldest-first).
5. HireLens compares that against an evaluation grid (a Google Doc, connected to Dust
   natively) and drafts a summary.
6. HireLens calls `add_comment` and `set_description` on this server to write the
   summary back to the card.

This server only implements step 4 and step 6: moving data in and out of Trello. It
does not decide what to write, does not move cards, does not set due dates or labels.

## Repository layout

- `server.py` — the MCP server: declares the three tools, wires up Streamable HTTP,
  and rejects any request without the right Bearer token.
- `trello_client.py` — the actual HTTP calls to Trello's REST API (`httpx`, no
  third-party Trello wrapper), plus the board-scoping guard and readable error messages.
- `smoke_test.py` — calls the three Trello functions directly (no MCP, no server) against
  a real test card. Run this first whenever something seems broken.
- `requirements.txt` — pinned dependencies.
- `.env.example` — the four environment variables this server needs.

## Setup from zero

```bash
git clone https://github.com/PaulHERVET123/trello-mcp-hirelens.git
cd trello-mcp-hirelens
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
```

Fill in `.env` (see "Getting Trello credentials" below for the first two):

- `TRELLO_API_KEY` / `TRELLO_TOKEN` — from your Trello Power-Up.
- `TRELLO_BOARD_ID` — the board's long id (not the shortLink from the URL). Get it with:
  ```bash
  curl "https://api.trello.com/1/boards/<shortLinkFromBoardUrl>?fields=id&key=<key>&token=<token>"
  ```
- `MCP_AUTH_TOKEN` — any random string, e.g. `openssl rand -hex 32`. This is the Bearer
  token Dust must send on every request.

### Getting Trello credentials

1. Go to <https://trello.com/power-ups/admin>, click **New**, create a Power-Up (the
   name doesn't matter — it's never published, it just anchors an API key to your account).
2. Open it, go to the **API key** tab. Copy the key.
3. Build this URL yourself (don't click the "Token" link on that page — it doesn't let
   you restrict scope) and open it in your browser:
   ```
   https://trello.com/1/authorize?expiration=never&scope=read,write&response_type=token&key=<your key>
   ```
4. Click **Allow**. The page shows a long token — that's `TRELLO_TOKEN`.

### Run it locally

```bash
source .venv/bin/activate
python smoke_test.py https://trello.com/c/<shortLinkOfATestCard>
```

If that prints three green "OK"s, the Trello side works. Then start the server:

```bash
uvicorn server:app --host 0.0.0.0 --port 8000
```

### Test with MCP Inspector (no Dust involved)

The Inspector ships with a headless CLI mode, which is more reliable to script than the
web UI:

```bash
npx -y @modelcontextprotocol/inspector --cli \
  --server-url http://localhost:8000/mcp --transport http \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>" \
  --method tools/list
```

You should see a JSON listing of the three tools. To call one:

```bash
npx -y @modelcontextprotocol/inspector --cli \
  --server-url http://localhost:8000/mcp --transport http \
  --header "Authorization: Bearer <your MCP_AUTH_TOKEN>" \
  --method tools/call --tool-name get_card --tool-arg cardUrl=https://trello.com/c/<shortLink>
```

If you'd rather click through a UI: run `npx -y @modelcontextprotocol/inspector`
(no `--cli`), it opens a browser tab. Click **Add Servers → + Add manually**, set
Transport Type to **Streamable HTTP**, URL to `http://localhost:8000/mcp`, add a header
`Authorization: Bearer <your MCP_AUTH_TOKEN>`, connect, then open the **Tools** tab.

## Deploying (Render)

This repo is connected to a Render Web Service (Starter plan, $7/mo, always-on — the
free tier sleeps after 15 minutes of inactivity, which risks a timeout mid-demo).

- **Build command**: `pip install -r requirements.txt`
- **Start command**: `uvicorn server:app --host 0.0.0.0 --port $PORT`
- **Environment variables**: the same four as `.env`, set in the Render dashboard.
- Pushing to `main` auto-redeploys.

### Redeploying from scratch

If Render's account/service ever needs to be rebuilt:

1. [dashboard.render.com](https://dashboard.render.com) → **New +** → **Web Service**.
2. Connect the `trello-mcp-hirelens` GitHub repo, branch `main`.
3. Runtime: Python 3. Build/start commands as above.
4. Instance type: **Starter** (not Free).
5. Add the 4 environment variables.
6. Deploy. The public URL is `https://<service-name>.onrender.com`.

### Emergency fallback (not a normal workflow)

If Render has an outage the morning of the demo:

```bash
cloudflared tunnel --url http://localhost:8000
```

This prints a temporary public HTTPS URL in seconds. Point Dust at
`<that-url>/mcp` instead. Requires the server running locally
(`uvicorn server:app --host 0.0.0.0 --port 8000`) and `cloudflared` installed
(`brew install cloudflared`).

## Declaring the server in Dust (steps 7–9)

1. In Dust, go to **Spaces → Tools → Add Tool → Add MCP Server**.
2. Enter the server URL **including the `/mcp` path**:
   `https://trello-mcp-hirelens.onrender.com/mcp` (the bare domain returns 404 — the
   MCP endpoint only exists at `/mcp`).
3. Choose **Bearer token** as the authentication method, paste the value of
   `MCP_AUTH_TOKEN`.
   **What you should see:** after a short sync, the three tools (`get_card`,
   `add_comment`, `set_description`) appear listed under the new server, each with its
   description.
   **What you'll see if it fails:** a connection error at sync time almost always means
   either the URL is missing `/mcp`, or the Bearer token doesn't match — check
   Render's logs for a `401` line if so.
4. Set every tool's approval level to **Never ask**. *(We couldn't find the exact
   screen for this ahead of time — Dust's docs don't cover it for a custom remote
   server, only the concept exists in their code. It's most likely a dropdown next to
   each tool either where you add it to the agent, or on the server's tool list itself.
   Note here exactly where you found it, once you have.)*
5. Add the three tools to the HireLens agent's **Tools & Knowledge** section.
6. Move a test card between lists on the board to fire the webhook, then check the
   agent's conversation history in Dust — a new conversation should appear showing the
   tool calls it made.
   **What you'll see if it fails:** if the agent's run shows no tool call at all, the
   webhook/trigger side is the problem (outside this repo's scope). If it shows a tool
   call that errors, the error message should be readable English explaining what went
   wrong (that's exactly what `trello_client.py` was built to produce) — read it, it's
   meant for you as much as for the agent.

## When it breaks

| Symptom | Likely cause | Fix |
|---|---|---|
| Dust sync fails when adding the server, or every call times out | Free-tier-style cold start, or wrong URL | Confirm the URL ends in `/mcp`; confirm the Render service shows "Live", not "Sleeping" |
| Tool call fails with a 401-shaped message | Bearer token mismatch between Dust and `MCP_AUTH_TOKEN` on Render | Re-copy the exact value from Render's env vars into Dust's Bearer token field |
| `get_card` says "This card belongs to board X, not the configured board" | Card URL is for a different board than `TRELLO_BOARD_ID` | Expected behavior — this is the board-scoping guard working. Confirm you're testing on the right board |
| Error mentioning "invalid app token" or "invalid key" | Trello token/key was revoked, or wrong values in Render's env vars | Regenerate via the Power-Up admin page, update Render's environment variables, redeploy |
| Everything worked yesterday, nothing responds today | Render had an incident, or the free-tier-adjacent cold start crept back in somehow | Check Render's status page and this service's logs; fall back to the `cloudflared` tunnel if it's demo day |

## Write-up material

**Use case.** Interviewers on the "Post-sales SE hiring" Trello board write free-form
comments as a candidate moves through the pipeline. HireLens reads all of that when a
card changes list, compares it to an evaluation grid, and writes a consolidated summary
back — so the next interviewer doesn't have to re-read a scattered comment thread.

**How it works.** Three MCP tools, one Trello REST call each (or two, for `get_card`,
which fetches name/description/list/comments in a single Trello API call using the
`fields`, `list`, and `actions` query parameters). No sorting, filtering, or
summarization happens in this code — that's entirely HireLens's job, driven by its
prompt.

**How it was validated.** Three layers, each independently: (1) `smoke_test.py`
against a real Trello test card, calling `trello_client.py` directly; (2) the MCP
Inspector's CLI mode, talking real MCP protocol to the server running locally, with
no Dust involved; (3) the same Inspector CLI calls against the deployed Render URL,
over HTTPS, with the real Bearer token. All three are reproducible with one command
each (see above).

**Assumptions.**
- A single Trello account (mine) backs the token; HireLens acts as me. Its comments
  are prefixed `HireLens` specifically so they're distinguishable from a human
  interviewer's in the same account.
- Comment volume per card stays well under Trello's 50-actions-per-API-page limit;
  pagination was not implemented because handling it would mean the code deciding
  what to prioritize, which is scope explicitly left to the agent.
- `TRELLO_TOKEN` never expires; it can be revoked and regenerated from the Power-Up
  admin page at any time if that becomes a concern.

**Tradeoffs.**
- **Full description replacement vs. patching between markers.** Replacing the whole
  description is simpler and was chosen for that reason. A marker-based patch
  (`<!-- dust:start -->...<!-- dust:end -->`) would cost roughly 15–20 extra lines and
  15–20 minutes, but it introduces a business rule (what to do if markers are missing
  or duplicated) that the spec says belongs in the agent's prompt, not in this tool.
- **Three single-purpose tools vs. two macro-tools.** Fewer round-trips with macro-tools,
  but a single contract mixing two intents complicates error messages and removes the
  agent's ability to update just one of the two. Three tools, one responsibility each,
  were chosen for that reason.
- **DNS-rebinding protection disabled.** The MCP SDK's Streamable HTTP transport
  rejects requests by Host header unless explicitly allow-listed, by default — a
  protection against malicious webpages targeting a local dev server from a browser.
  That threat model doesn't apply to a server-to-server call from Dust's
  infrastructure, and it broke calls from Render's own domain, so it's turned off;
  the Bearer token check is the real access boundary here.

**Limits.**
- No retries on Trello API failures (429/5xx) — a failed call surfaces as a readable
  error to the agent, which can decide to retry or not. Adding retry logic here would
  duplicate a decision that's arguably the agent's to make.
- No handling of a webhook firing twice for the same move — nothing here is
  idempotent (`add_comment` would post twice). Out of scope: the spec says this
  server does no business logic, and de-duplication is exactly that.
- Single Trello account/token: every write appears to come from me, not from an
  identifiable "HireLens" service account. Documented as an accepted limitation of
  the assignment's dataset, not something to fix in code.

**Why this approach vs. reasonable alternatives.**
Syncing Trello into a Dust datasource was ruled out because a datasource is read-only
by construction — it cannot write a comment or a description back to Trello, which is
half of what this integration needs to do, regardless of how it's kept fresh. No
native Dust tool covers Trello or generic HTTP requests either (checked against
Dust's own tool/connection list), so a bridge had to be built one way or another.
MCP was chosen over a bespoke HTTP-calling layer because it gives the agent a
structured, self-describing contract — three named tools with typed arguments and
English descriptions — that the LLM can discover and invoke on its own, instead of
requiring custom code to decide which endpoint to call and how to parse the response.

## Ideas considered and deliberately not built

- **Marker-based description patching**, so a human's handwritten note in the
  description could never be overwritten by HireLens. Estimated cost: ~15–20 lines,
  ~15–20 minutes. Left out because it encodes a business decision (what counts as
  "the agent's section") that the spec keeps out of this server's code.
- **Two macro-tools** (`get_card_context` / `write_card_update`) instead of three
  primitives. Would reduce agent↔tool round-trips, at the cost of mixing two
  intents behind one contract and losing the ability to update only one field.
- **Comment pagination** for cards with more than 50 comments. Not implemented —
  see "Assumptions" above.