trellio-mcp 0.1.1__tar.gz

trellio_mcp-0.1.1/PKG-INFO

@@ -0,0 +1,276 @@
+Metadata-Version: 2.4
+Name: trellio-mcp
+Version: 0.1.1
+Summary: MCP server for Trello — manage boards, lists, cards, labels, checklists and more
+Author: scaratec
+License: GPL-3.0-or-later
+Project-URL: Homepage, https://github.com/scaratec/trellio-mcp
+Project-URL: Repository, https://github.com/scaratec/trellio-mcp
+Project-URL: Issues, https://github.com/scaratec/trellio-mcp/issues
+Keywords: trello,mcp,model-context-protocol,claude,gemini,ai
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.12.0
+Requires-Dist: trellio-client>=1.0.0
+Provides-Extra: dev
+Requires-Dist: behave>=1.2.6; extra == "dev"
+
+# trellio-mcp — MCP Server for Trello
+
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](https://modelcontextprotocol.io)
+
+An MCP server that gives Claude Desktop, Claude Code, and
+Gemini CLI full access to the Trello API. Built on the
+[trellio](https://github.com/scaratec/trellio) async client
+library and the official Python MCP SDK. Developed following
+the [BDD Guidelines v1.8.0](https://github.com/scaratec/burn-your-code).
+
+## Features
+
+- **40 MCP tools** — 1:1 mapping to trellio methods, plus
+  one composite `get_board_overview` tool
+- **2 resource templates** — `trello://board/{id}` and
+  `trello://card/{id}` for rich context loading
+- **3 prompts** — `summarize_board`, `create_sprint`,
+  `daily_standup` as workflow shortcuts
+- **Built-in auth flow** — `python -m trello_mcp auth` opens
+  the browser, user clicks "Allow", token stored securely
+- **Structured error handling** — Trello API errors are
+  translated into clear, actionable MCP error messages
+- **stdio transport** — runs as a local subprocess, no
+  network surface
+
+## Tools
+
+| Category    | Tools | Count |
+|-------------|-------|-------|
+| Discovery   | `list_boards`, `search` | 2 |
+| Boards      | `get_board_overview`, `create_board`, `get_board`, `update_board`, `delete_board` | 5 |
+| Lists       | `list_lists`, `create_list` | 2 |
+| Cards       | `list_cards`, `create_card`, `get_card`, `update_card`, `delete_card`, `add_label_to_card`, `remove_label_from_card` | 7 |
+| Labels      | `list_board_labels`, `create_label`, `update_label`, `delete_label` | 4 |
+| Checklists  | `list_card_checklists`, `create_checklist`, `delete_checklist`, `create_check_item`, `update_check_item`, `delete_check_item` | 6 |
+| Comments    | `list_comments`, `add_comment`, `update_comment`, `delete_comment` | 4 |
+| Members     | `get_me`, `list_board_members`, `get_member` | 3 |
+| Attachments | `list_attachments`, `create_attachment`, `delete_attachment` | 3 |
+| Webhooks    | `list_webhooks`, `create_webhook`, `get_webhook`, `update_webhook`, `delete_webhook` | 5 |
+
+Card tools support `pos` (top/bottom), `idLabels`
+(comma-separated), `due` (ISO 8601), and `dueComplete`
+(true/false) on create and update.
+
+## Prerequisites
+
+- Python 3.10+
+- A [Trello API Key](https://trello.com/power-ups/admin)
+  (add `http://localhost:8095` to Allowed Origins)
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install trellio-mcp
+```
+
+Or run without installing via `pipx` or `uvx`:
+
+```bash
+pipx run trellio-mcp
+uvx trellio-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/scaratec/trellio-mcp.git
+cd trellio-mcp
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+## Authentication
+
+### Interactive (recommended)
+
+Run the auth command on each machine:
+
+```bash
+TRELLO_API_KEY=your_api_key trellio-mcp auth
+```
+
+If using `pipx run`:
+
+```bash
+TRELLO_API_KEY=your_api_key pipx run trellio-mcp auth
+```
+
+This opens a browser where you authorize the app. The token
+is captured automatically and stored in
+`~/.config/trellio-mcp/credentials.json` (permissions 0600).
+
+After auth, no environment variables are needed — the server
+reads stored credentials on startup.
+
+### Environment Variables (fallback)
+
+If no stored credentials are found, the server falls back to
+environment variables:
+
+```bash
+export TRELLO_API_KEY=your_api_key
+export TRELLO_TOKEN=your_token
+```
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json`
+(Windows):
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "pipx",
+      "args": ["run", "trellio-mcp"]
+    }
+  }
+}
+```
+
+If using env var auth instead of stored credentials, add:
+
+```json
+"env": {
+  "TRELLO_API_KEY": "your_api_key",
+  "TRELLO_TOKEN": "your_token"
+}
+```
+
+### Claude Code
+
+Add to `~/.claude/settings.json` or project
+`.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "pipx",
+      "args": ["run", "trellio-mcp"]
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "pipx",
+      "args": ["run", "trellio-mcp"]
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+MCP Client (Claude / Gemini)
+    │ stdio (JSON-RPC)
+    ▼
+trellio-mcp (FastMCP)
+    │ async/await
+    ▼
+trellio (httpx)
+    │ HTTPS
+    ▼
+Trello API
+```
+
+**Key decisions** (documented in `docs/adr/`):
+
+| ADR | Decision |
+|-----|----------|
+| 001 | Python MCP SDK for language alignment with trellio |
+| 002 | stdio transport — no network attack surface |
+| 003 | Stored credentials with env var fallback |
+| 004 | 1:1 tool mapping — one tool per trellio method |
+| 005 | trellio as Git dependency pinned to v1.0.0 |
+| 006 | Tools + Resources + Prompts as MCP capabilities |
+| 007 | `isError=true` + structured error content |
+
+## Testing
+
+The project uses BDD with
+[behave](https://behave.readthedocs.io/), following the
+[BDD Guidelines v1.8.0](https://github.com/scaratec/burn-your-code).
+
+```bash
+PYTHONPATH=src .venv/bin/python -m behave
+```
+
+```
+15 features passed, 0 failed, 0 skipped
+122 scenarios passed, 0 failed, 0 skipped
+732 steps passed, 0 failed, 0 skipped
+```
+
+Test architecture:
+- `AsyncMock(spec=TrellioClient)` — mock at the client
+  boundary, not HTTP
+- Persistence validation via mock call records (§4.3)
+- Anti-hardcoding via Scenario Outlines with >= 2 variants
+  (§2.3)
+- Layer-by-layer failure path enumeration: 11 error scenarios
+  (§4.5)
+- Independent spec audit per §13
+
+See [Case Study](docs/case-study-bdd-mcp-server.md) for a
+detailed account of the BDD-driven development process.
+
+## Project Structure
+
+```
+trellio-mcp/
+├── src/trello_mcp/
+│   ├── __init__.py        # Tool registration
+│   ├── __main__.py        # Entry point (server + auth)
+│   ├── server.py          # FastMCP instance + client mgmt
+│   ├── auth.py            # OAuth flow + credential storage
+│   ├── errors.py          # Error translation (ADR 007)
+│   ├── tools/             # 10 modules, 40 tools
+│   ├── resources.py       # 2 resource templates
+│   └── prompts.py         # 3 prompts
+├── features/              # 15 BDD feature files
+│   └── steps/             # Step definitions
+├── docs/
+│   ├── adr/               # 7 Architecture Decision Records
+│   ├── tool-design.md     # Scenario-driven tool analysis
+│   └── case-study-bdd-mcp-server.md
+└── pyproject.toml
+```
+
+## License
+
+This project is licensed under the GNU General Public License
+v3.0 — see the [LICENSE](LICENSE) file for details.

trellio_mcp-0.1.1/README.md

@@ -0,0 +1,250 @@
+# trellio-mcp — MCP Server for Trello
+
+[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![MCP](https://img.shields.io/badge/MCP-stdio-green.svg)](https://modelcontextprotocol.io)
+
+An MCP server that gives Claude Desktop, Claude Code, and
+Gemini CLI full access to the Trello API. Built on the
+[trellio](https://github.com/scaratec/trellio) async client
+library and the official Python MCP SDK. Developed following
+the [BDD Guidelines v1.8.0](https://github.com/scaratec/burn-your-code).
+
+## Features
+
+- **40 MCP tools** — 1:1 mapping to trellio methods, plus
+  one composite `get_board_overview` tool
+- **2 resource templates** — `trello://board/{id}` and
+  `trello://card/{id}` for rich context loading
+- **3 prompts** — `summarize_board`, `create_sprint`,
+  `daily_standup` as workflow shortcuts
+- **Built-in auth flow** — `python -m trello_mcp auth` opens
+  the browser, user clicks "Allow", token stored securely
+- **Structured error handling** — Trello API errors are
+  translated into clear, actionable MCP error messages
+- **stdio transport** — runs as a local subprocess, no
+  network surface
+
+## Tools
+
+| Category    | Tools | Count |
+|-------------|-------|-------|
+| Discovery   | `list_boards`, `search` | 2 |
+| Boards      | `get_board_overview`, `create_board`, `get_board`, `update_board`, `delete_board` | 5 |
+| Lists       | `list_lists`, `create_list` | 2 |
+| Cards       | `list_cards`, `create_card`, `get_card`, `update_card`, `delete_card`, `add_label_to_card`, `remove_label_from_card` | 7 |
+| Labels      | `list_board_labels`, `create_label`, `update_label`, `delete_label` | 4 |
+| Checklists  | `list_card_checklists`, `create_checklist`, `delete_checklist`, `create_check_item`, `update_check_item`, `delete_check_item` | 6 |
+| Comments    | `list_comments`, `add_comment`, `update_comment`, `delete_comment` | 4 |
+| Members     | `get_me`, `list_board_members`, `get_member` | 3 |
+| Attachments | `list_attachments`, `create_attachment`, `delete_attachment` | 3 |
+| Webhooks    | `list_webhooks`, `create_webhook`, `get_webhook`, `update_webhook`, `delete_webhook` | 5 |
+
+Card tools support `pos` (top/bottom), `idLabels`
+(comma-separated), `due` (ISO 8601), and `dueComplete`
+(true/false) on create and update.
+
+## Prerequisites
+
+- Python 3.10+
+- A [Trello API Key](https://trello.com/power-ups/admin)
+  (add `http://localhost:8095` to Allowed Origins)
+
+## Installation
+
+### From PyPI (recommended)
+
+```bash
+pip install trellio-mcp
+```
+
+Or run without installing via `pipx` or `uvx`:
+
+```bash
+pipx run trellio-mcp
+uvx trellio-mcp
+```
+
+### From source
+
+```bash
+git clone https://github.com/scaratec/trellio-mcp.git
+cd trellio-mcp
+python3 -m venv .venv
+.venv/bin/pip install -e ".[dev]"
+```
+
+## Authentication
+
+### Interactive (recommended)
+
+Run the auth command on each machine:
+
+```bash
+TRELLO_API_KEY=your_api_key trellio-mcp auth
+```
+
+If using `pipx run`:
+
+```bash
+TRELLO_API_KEY=your_api_key pipx run trellio-mcp auth
+```
+
+This opens a browser where you authorize the app. The token
+is captured automatically and stored in
+`~/.config/trellio-mcp/credentials.json` (permissions 0600).
+
+After auth, no environment variables are needed — the server
+reads stored credentials on startup.
+
+### Environment Variables (fallback)
+
+If no stored credentials are found, the server falls back to
+environment variables:
+
+```bash
+export TRELLO_API_KEY=your_api_key
+export TRELLO_TOKEN=your_token
+```
+
+## MCP Client Configuration
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`
+(macOS) or `%APPDATA%\Claude\claude_desktop_config.json`
+(Windows):
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "pipx",
+      "args": ["run", "trellio-mcp"]
+    }
+  }
+}
+```
+
+If using env var auth instead of stored credentials, add:
+
+```json
+"env": {
+  "TRELLO_API_KEY": "your_api_key",
+  "TRELLO_TOKEN": "your_token"
+}
+```
+
+### Claude Code
+
+Add to `~/.claude/settings.json` or project
+`.claude/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "pipx",
+      "args": ["run", "trellio-mcp"]
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json`:
+
+```json
+{
+  "mcpServers": {
+    "trello": {
+      "command": "pipx",
+      "args": ["run", "trellio-mcp"]
+    }
+  }
+}
+```
+
+## Architecture
+
+```
+MCP Client (Claude / Gemini)
+    │ stdio (JSON-RPC)
+    ▼
+trellio-mcp (FastMCP)
+    │ async/await
+    ▼
+trellio (httpx)
+    │ HTTPS
+    ▼
+Trello API
+```
+
+**Key decisions** (documented in `docs/adr/`):
+
+| ADR | Decision |
+|-----|----------|
+| 001 | Python MCP SDK for language alignment with trellio |
+| 002 | stdio transport — no network attack surface |
+| 003 | Stored credentials with env var fallback |
+| 004 | 1:1 tool mapping — one tool per trellio method |
+| 005 | trellio as Git dependency pinned to v1.0.0 |
+| 006 | Tools + Resources + Prompts as MCP capabilities |
+| 007 | `isError=true` + structured error content |
+
+## Testing
+
+The project uses BDD with
+[behave](https://behave.readthedocs.io/), following the
+[BDD Guidelines v1.8.0](https://github.com/scaratec/burn-your-code).
+
+```bash
+PYTHONPATH=src .venv/bin/python -m behave
+```
+
+```
+15 features passed, 0 failed, 0 skipped
+122 scenarios passed, 0 failed, 0 skipped
+732 steps passed, 0 failed, 0 skipped
+```
+
+Test architecture:
+- `AsyncMock(spec=TrellioClient)` — mock at the client
+  boundary, not HTTP
+- Persistence validation via mock call records (§4.3)
+- Anti-hardcoding via Scenario Outlines with >= 2 variants
+  (§2.3)
+- Layer-by-layer failure path enumeration: 11 error scenarios
+  (§4.5)
+- Independent spec audit per §13
+
+See [Case Study](docs/case-study-bdd-mcp-server.md) for a
+detailed account of the BDD-driven development process.
+
+## Project Structure
+
+```
+trellio-mcp/
+├── src/trello_mcp/
+│   ├── __init__.py        # Tool registration
+│   ├── __main__.py        # Entry point (server + auth)
+│   ├── server.py          # FastMCP instance + client mgmt
+│   ├── auth.py            # OAuth flow + credential storage
+│   ├── errors.py          # Error translation (ADR 007)
+│   ├── tools/             # 10 modules, 40 tools
+│   ├── resources.py       # 2 resource templates
+│   └── prompts.py         # 3 prompts
+├── features/              # 15 BDD feature files
+│   └── steps/             # Step definitions
+├── docs/
+│   ├── adr/               # 7 Architecture Decision Records
+│   ├── tool-design.md     # Scenario-driven tool analysis
+│   └── case-study-bdd-mcp-server.md
+└── pyproject.toml
+```
+
+## License
+
+This project is licensed under the GNU General Public License
+v3.0 — see the [LICENSE](LICENSE) file for details.

trellio_mcp-0.1.1/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "trellio-mcp"
+version = "0.1.1"
+description = "MCP server for Trello — manage boards, lists, cards, labels, checklists and more"
+readme = "README.md"
+requires-python = ">=3.10"
+license = {text = "GPL-3.0-or-later"}
+authors = [
+    {name = "scaratec"},
+]
+keywords = ["trello", "mcp", "model-context-protocol", "claude", "gemini", "ai"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+    "mcp>=1.12.0",
+    "trellio-client>=1.0.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/scaratec/trellio-mcp"
+Repository = "https://github.com/scaratec/trellio-mcp"
+Issues = "https://github.com/scaratec/trellio-mcp/issues"
+
+[project.scripts]
+trellio-mcp = "trello_mcp.__main__:main"
+
+[project.optional-dependencies]
+dev = [
+    "behave>=1.2.6",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]

trellio_mcp-0.1.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+