agentleFS
mab-gomab-go/trello-mcp/AGENTS.md

trello-mcp

AGENTS.md0 starsChanged 6 months agoMITView on GitHub

This file provides guidance to autonomous AI agents when working with code in this repository. trello-mcp is a Go MCP (Model Context Protocol) server that exposes Trello board/card/list operations as tools for LLM agents. It communicates over stdio using the MCP protocol. See SPEC.md for the full API specification. First-time setup installs project-local Go tools into ./bin (golangci-lint, goimports, gocyclo): Build the binary to ./bin/trello-mcp: Run tests (-race is on by default; set RACE=0 to disable): Optional coverage report: make…

  • Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.

    Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.

  • In this repository7 other files it gives its agents.

The file

We split this AGENTS.md into the rules it gives an agent

6 rules. About 0 are common, 4 are distinctive, and 2 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 2

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Run tests (-race is on by default.

    line 27
  2. Distinctive:

    Before ANY change is considered done, run all five targets.

    line 40
  3. Distinctive:

    When refactoring a function with high cyclomatic complexity, apply this principle: extract blocks that have their own distinct purpose into …

    line 56
  4. Very specific:

    After refactoring: Read the top-level function aloud -- does it scan as named steps?

    line 81
  5. Distinctive:

    ASCII only: Use only characters typeable on a US English keyboard in Markdown files and Go/TypeScript source comments.

    line 105
  6. Distinctive:

    All responses are JSON objects: No custom text formats.

    line 144

≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md

AGENTS.md/CLAUDE.md

This file provides guidance to autonomous AI agents when working with code in this repository.

Project

trello-mcp is a Go MCP (Model Context Protocol) server that exposes Trello board/card/list operations as tools for LLM agents. It communicates over stdio using the MCP protocol. See SPEC.md for the full API specification.

Build and Test

First-time setup installs project-local Go tools into ./bin (golangci-lint, goimports, gocyclo):

make setup

Build the binary to ./bin/trello-mcp:

make build

Run tests (-race is on by default; set RACE=0 to disable):

make test

Optional coverage report: make test:cover. See make help for other targets.

The binary is trello-mcp. It has two modes: trello-mcp auth (credential validation) and the default MCP server mode (stdio).

Verification

Before ANY change is considered done, run all five targets. All must pass. No exceptions.

make fmt
make build
make test
make lint
make cyclo

Code Composition

Top-level functions should scan as a DSL of named steps. They express WHAT happens as a sequence of well-named calls. The HOW lives in the helpers.

When refactoring a function with high cyclomatic complexity, apply this principle: extract blocks that have their own distinct purpose into named helpers, so the parent reads as a series of named steps.

Extract when a block has a distinct purpose nameable in 2-3 words, operates at a different abstraction level than its surroundings, and replacing 10-30 inline lines with a named call makes the parent more readable.

Do NOT extract when the code is purely sequential setup with no branching, the helper would need 4+ parameters (the extraction boundary is wrong), the name would just restate the code in camelCase, or the code is declarative data (tool definitions, config structs).

Naming: Helpers describe what they yield or do -- drainChat, writeEntityBuckets, shortEntityList. Never name by where it's called -- thinkStep1, handlePart2.

Placement: Helpers stay in the same file as their caller unless they serve multiple files in the package. Never create a file just for one small helper.

Anti-patterns: Helper soup (extracting every 5-line block obscures a readable 40-line flow). State-smuggling parameters (5+ params means the extraction boundary is wrong). Naming after the caller. Extracting trivial if err != nil handling.

After refactoring: Read the top-level function aloud -- does it scan as named steps? Run make cyclo -- complexity must hold steady or improve.

Architecture

cmd/trello-mcp/   # Main entry point, CLI parsing (auth subcommand)
internal/
  server/
    tools.go      # MCP tool definitions (names, parameters, descriptions)
    handler/
      handler.go  # Shared logic: board ID resolution, allowed_boards checks
      apierr.go   # mapAPIError: HTTP status -> tool error mapping
      <tool>.go   # One file per tool handler
  trello/
    client.go     # Thin HTTP client over net/http, appends key+token
    types.go      # Typed structs for Trello API responses

Config lives at ~/.config/trello-mcp/config.json (api_key, token, optional default_board, optional allowed_boards).

Conventions

ASCII only. Use only characters typeable on a US English keyboard in Markdown files and Go/TypeScript source comments. No Unicode arrows (use ->), no em-dashes (use -- or rephrase), no multiplication signs (use x), no special math symbols (use >= not the glyph). TUI box-drawing characters for terminal rendering are exempt.

Markdown line wrapping. Wrap regular prose in Markdown files at 80 characters. Exceptions: code blocks, inline code spans, CLI usage examples, Markdown tables, URLs, and cases where wrapping would reduce readability.

Prefer LSP for semantic Go queries. For finding definitions, references, implementations, call hierarchy, or type signatures in Go code, use the LSP tool over grep -- gopls is configured for this repo and returns semantic answers that disambiguate same-named symbols across packages. Grep is still fine for plain text searches, non-code files, and quick locate-by-string.

Logging. Uses github.com/mab-go/logging. Event constants live in per-package events.go files (unexported, entity.verb naming).

Key design decisions

  • No third-party Trello client. Thin wrapper in internal/trello/ over net/http. Every request gets key and token query params appended automatically.
  • Two-tier error model. Tool errors (*mcp.CallToolResult, nil) for user-recoverable problems (bad input, 400/401/403/404/429). Protocol errors (nil, error) for unexpected failures. Error messages must suggest the fix.
  • Board ID resolution is shared logic in handler.go: explicit arg -> default_board -> error. trello_search has a soft fallback (no error when both are empty).
  • allowed_boards enforcement is cross-cutting: all tools accepting card_id must check the card's idBoard against the list. trello_move_card also checks the target board.
  • List name resolution is case-insensitive exact match against the board's lists. On zero matches, the tool error lists available names.
  • Label operations are add/remove only (not replace). Label names are resolved case-insensitively against board labels; unrecognized names produce a tool error listing available labels.
  • All responses are JSON objects. No custom text formats.
  • Dates: due dates -> YYYY-MM-DD, activity timestamps -> YYYY-MM-DD HH:MM (UTC).

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.