@omnicoreos/planka-mcp 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,86 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [0.2.0] - 2026-08-24
+
+### Added
+
+- Nine tools, bringing the server to twenty-four.
+- Attachments: `planka_add_attachment` uploads a local file and re-reads the card
+  to confirm it landed, `planka_get_attachments` lists what a card holds,
+  `planka_view_attachment` returns content — images as MCP image content up to
+  3 MB, text inline up to 50 KB, anything else as metadata and a URL — and
+  `planka_delete_attachment` removes one.
+- `planka_manage_comment`, to edit or delete an existing comment.
+- Scoped reads that answer a narrower question than `planka_get_board` and return
+  proportionally less text: `planka_list_lists` (columns and card counts),
+  `planka_board_summary` (columns, labels, and the cards awaiting a decision),
+  `planka_list_cards` (one column, paginated), and `planka_find_cards` (search by
+  label, text, or column). Measured on a board of 100 cards, they return between
+  16 and 56 times less than `planka_get_board`.
+- Honest clipping on every scoped read: `total`, `returned`, `hasMore`, and
+  `nextOffset`, so a partial answer is never mistaken for a complete one.
+- Actionable input errors. A rejected call now names the tool, the field, the
+  declared type and description, what was expected, and what actually arrived.
+  Missing required fields are caught before the handler runs, and a Planka
+  response that does not match the expected shape is labelled as an API mismatch
+  rather than an argument problem.
+- Diagnosis for a project ID passed where a board ID belongs. Both are strings of
+  digits, and Planka answers the mistake with a bare 404. The server now resolves
+  it automatically when the project has exactly one board, and otherwise explains
+  what the ID is and lists the boards it could have meant.
+- Documentation for the smoke test's optional environment variables:
+  `PLANKA_SMOKE_LIST_ID` and `PLANKA_SMOKE_FAIL_AFTER`, which injects a failure to
+  prove the cleanup path still runs.
+
+### Changed
+
+- The smoke test grew from a first-failure abort over seven tools to 64 named
+  checks covering all twenty-four end to end, each write cross-checked against the
+  raw Planka HTTP API. Cleanup runs in a `finally` and on `SIGINT`/`SIGTERM`, over
+  raw HTTP so the safety net does not depend on the component under test.
+- `npm run test:smoke` builds first, so it can no longer test a stale `dist/`.
+- Internal operation signatures take a single input object everywhere, validated
+  through one shared path. No tool payload changed.
+
+### Fixed
+
+- Long columns truncated in silence. `GET /api/lists/:id/cards` pages at 50 and
+  ignores `?limit=`; its cursor is composite (`before[id]` plus
+  `before[listChangedAt]`). A column of 77 cards returned 50 with no indication
+  that 27 were missing. The cursor is now followed, and a read that still could
+  not be completed reports `truncated: true` instead of looking complete.
+
+## [0.1.0] - 2026-08-21
+
+### Identity
+
+- Working repository name: `planka-mcp`.
+- Working npm identity: `@omnicoreos/planka-mcp`.
+- `project.identity.json` is the source of truth for repository, package, binary,
+  MCP Registry, and repository URL names. After changing it, run
+  `npm run sync:identity`.
+
+### Added
+
+- Fifteen stdio MCP tools for Planka projects, boards, cards, tasks, comments,
+  labels, and lists.
+- Guided macOS/Linux setup with authentication validation, board selection,
+  optional board bootstrap, Claude Code configuration, and real smoke verification.
+- Unit tests for schemas, parsing, request construction, the dedicated comments
+  endpoint, label criteria deletion, label aliases, list creation, and bootstrap
+  idempotency.
+- Opt-in smoke test that executes MCP tools and verifies every mutation against the
+  raw Planka API before deleting its temporary card.
+- Optional board, director/worker, and worktree methodology.
+- English and Spanish documentation.
+
+### Fixed from upstream
+
+- Empty comments on Planka 2.x.
+- Whole-board failures caused by new label colors.
+- Silent no-op `labelIds` requests.
+- Incorrect label-removal URL.
+- Missing `type` in list creation.
+- Internal `archive` and `trash` list types rejected on board reads.

package/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Thanks for improving Planka 2.x support.
+
+## Local checks
+
+Node.js 18 or newer is required.
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+Keep unit tests offline. A real Planka test is opt-in because it writes a temporary
+card:
+
+```bash
+export PLANKA_BASE_URL="https://planka.example.com"
+export PLANKA_AGENT_EMAIL="agent@example.com"
+export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
+export PLANKA_SMOKE_BOARD_ID="<BOARD_ID>"
+npm run test:smoke
+```
+
+The smoke test must clean up after itself and must compare MCP claims with the raw
+API. A `success: true` response alone is not proof.
+
+## Pull requests
+
+- Add a regression test for every Planka compatibility fix.
+- Keep Node 18 compatibility.
+- Never commit credentials, private hosts, real customer data, or screenshots with
+  personal information.
+- Preserve upstream attribution and the MIT license.
+- Update both `README.md` and `README.es.md` when setup behavior changes.
+- Do not broaden the optional workflow into a requirement for MCP-only users.

package/CREDITS.md

@@ -0,0 +1,39 @@
+# Credits and fork history
+
+This repository is a fork of
+[`gogogadgetbytes/planka-mcp`](https://github.com/gogogadgetbytes/planka-mcp),
+released under the MIT License. The original 2026 copyright notice remains in
+[`LICENSE`](LICENSE). The additional contributor notice covers changes made in this
+fork and the optional workflow documentation.
+
+This is not presented as an original MCP implementation.
+
+## Why this fork exists
+
+The upstream repository is functionally abandoned. Its four commits are the initial
+release plus registry housekeeping from 2026-02-03; there have been no code changes
+since that release batch. Two compatibility pull requests remain open and unmerged:
+
+- [PR #5: read comments from the Planka 2.x card-comments endpoint](https://github.com/gogogadgetbytes/planka-mcp/pull/5)
+- [PR #1: accept backend label colors on read paths](https://github.com/gogogadgetbytes/planka-mcp/pull/1)
+
+Both were still open when this fork was prepared on 2026-08-21.
+
+## Compatibility work in this fork
+
+This fork carries four Planka 2.x fixes:
+
+1. Comments are read from `GET /api/cards/:cardId/comments` instead of an empty
+   `included.comments` array.
+2. `planka_set_card_labels` accepts the natural `labelIds` argument as well as
+   `addLabelIds`, then verifies the final card state.
+3. Label removal uses Planka's criteria path,
+   `/card-labels/labelId:<labelId>`, instead of a junction-record ID.
+4. Label colors returned by Planka are open-ended on read paths, so a new backend
+   color cannot invalidate the whole board response.
+
+It also sends the required `type` when creating Planka 2.x lists, accepts internal
+`archive` and `trash` list types on reads, adds unit and raw-API-verified smoke tests,
+and provides the optional board/worktree method under [`workflow/`](workflow/).
+
+See [docs/planka-2x-gotchas.md](docs/planka-2x-gotchas.md) for the technical details.

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 gogogadgetbytes
+Copyright (c) 2026 planka-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,213 @@
+# planka-mcp
+
+Manejá un tablero Planka 2.x desde Claude Code mediante 24 tools MCP.
+Las escrituras se releen y verifican: un éxito informado coincide con el board.
+Un flujo opcional convierte ese board en memoria durable para el trabajo con agentes.
+
+[Read in English](README.md)
+
+```text
+Vos hablás con Claude Code
+          │
+          ▼
+  planka-mcp (stdio) ─── HTTPS + JSON ───▶ Planka 2.x
+          │                                  │
+          └──── vuelve a leer el resultado ◀─┘
+```
+
+> [!WARNING]
+> El paquete viejo `@gogogadgetbytes/planka-mcp` puede informar éxito sin haber
+> hecho nada en Planka 2.x. Leé [los cinco fallos silenciosos](docs/planka-2x-gotchas.md)
+> antes de reemplazar una instalación existente.
+
+## ¿Es tu primer MCP? Leé esto primero
+
+MCP es un estándar que permite que Claude Code llame tools provistas por otro programa.
+Este repo ejecuta un programa local pequeño que traduce esas llamadas a pedidos a la API de Planka.
+Necesita credenciales de Planka porque actúa como un usuario dedicado de Planka, no como Claude.
+Las credenciales quedan en tu máquina y nunca se escriben en el archivo de proyecto `.mcp.json`.
+Claude Code carga los servidores MCP al iniciar una sesión, así que reinicialo después del setup o de cambiar la configuración.
+
+## Requisitos
+
+- Node.js 18 o posterior y `npm`
+- Una instancia Planka 2.x accesible
+- Un usuario dedicado de Planka que pueda ver el proyecto y board elegidos
+- Claude Code instalado y disponible como `claude`
+- Rol de project manager sólo si el setup debe crear un board
+
+Funciona en Linux y macOS. Bun no es un requisito.
+
+## Instalación en 5 minutos
+
+Cloná el repo y ejecutá el instalador guiado:
+
+```bash
+git clone https://github.com/omnicoreos/planka-mcp.git
+cd planka-mcp
+./scripts/setup.sh
+```
+
+El setup pide la URL de Planka, email o usuario del agente y password. Valida esas
+credenciales antes de escribir configuración, permite elegir o crear un board y
+ejecuta un smoke real de crear, etiquetar, comentar y borrar una card.
+
+Ofrece dos formas de configurar Claude Code:
+
+| Opción | Cuándo usarla | Dónde vive |
+|---|---|---|
+| `claude mcp add` | Querés la instalación personal más simple | Configuración de usuario de Claude Code |
+| `.mcp.json` de proyecto | Un equipo debe compartir la entrada del servidor | `<TU_PROYECTO>/.mcp.json`, se puede commitear |
+
+En ambos casos, el setup guarda las credenciales fuera de Git en
+`~/.config/planka-mcp/config.json` con modo `0600` y crea el launcher privado
+`~/.local/bin/planka-mcp`. La configuración compartida no contiene el password:
+
+```json
+{
+  "mcpServers": {
+    "planka": {
+      "type": "stdio",
+      "command": "${HOME}/.local/bin/planka-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+Podés volver a ejecutar el instalador. Actualiza la entrada `planka`, reutiliza las
+listas y labels existentes del método y borra la card temporal del smoke test.
+
+## Verificá que funciona
+
+Primero, inspeccioná la configuración de Claude Code:
+
+```bash
+claude mcp list
+claude mcp get planka
+```
+
+Después cerrá y volvé a abrir Claude Code por completo. Si elegiste `.mcp.json`,
+abrí Claude Code dentro de ese proyecto y aprobá el servidor de proyecto cuando lo pida.
+
+Pedile a Claude Code:
+
+```text
+Mostrame mis proyectos y boards de Planka. En la lista Pending, creá una card llamada
+"MCP está funcionando" con la descripción "Creada desde Claude Code" y volvé a leerla.
+```
+
+Si Claude no ve las tools, reinicialo primero y después seguí
+[Solución de problemas](docs/troubleshooting.md).
+
+## Las 24 tools
+
+Los IDs son strings. Empezá con `planka_get_structure` y usá los IDs que devuelve
+Planka; no los adivines.
+
+| Tool | Qué hace |
+|---|---|
+| `planka_get_structure` | Lista proyectos, boards y listas visibles |
+| `planka_get_board` | Lee un board con listas, cards, labels y conteos opcionales de tareas |
+| `planka_list_lists` | Lista las columnas de un board con sus conteos de cards, sin las cards |
+| `planka_board_summary` | Resumen en una llamada: columnas, labels y las cards que esperan una decisión |
+| `planka_list_cards` | Lee una sola columna, paginada y sin descripciones por defecto |
+| `planka_find_cards` | Busca cards de un board por label, texto o columna |
+| `planka_create_card` | Crea una card y puede agregar tareas y labels |
+| `planka_get_card` | Lee el detalle completo de una card |
+| `planka_update_card` | Actualiza título, descripción, vencimiento o estado de completado |
+| `planka_move_card` | Mueve una card a otra lista o posición |
+| `planka_delete_card` | Borra una card permanentemente |
+| `planka_create_tasks` | Agrega tareas de checklist a una card |
+| `planka_update_task` | Renombra o completa una tarea |
+| `planka_delete_task` | Borra una tarea |
+| `planka_manage_labels` | Crea, actualiza o borra labels del board |
+| `planka_set_card_labels` | Agrega o quita labels y verifica el estado final |
+| `planka_add_comment` | Agrega un comentario por el endpoint dedicado de Planka 2.x |
+| `planka_get_comments` | Lee comentarios por el endpoint dedicado |
+| `planka_manage_comment` | Edita o borra un comentario existente |
+| `planka_manage_lists` | Crea, actualiza o borra listas del board |
+| `planka_add_attachment` | Sube un archivo local a una card y verifica que quedó |
+| `planka_get_attachments` | Lista los adjuntos de una card con tipo, tamaño y URL de descarga |
+| `planka_view_attachment` | Devuelve el contenido de un adjunto; las imágenes vuelven visibles |
+| `planka_delete_attachment` | Borra un adjunto |
+
+`planka_get_board` devuelve el board entero, que suele ser más de lo que la
+pregunta necesita. Las cuatro lecturas acotadas responden preguntas más chicas y
+devuelven mucho menos texto: medido sobre un board de 100 cards,
+`planka_list_lists` devolvió 39 veces menos que `planka_get_board`,
+`planka_board_summary` 16 veces menos, y `planka_find_cards` entre 18 y 56 veces
+menos según el filtro. Además informan `total`, `returned` y `hasMore`, así que
+una respuesta recortada nunca parece completa.
+
+Todos los campos y un payload completo por tool están en la
+[referencia de tools](docs/tools.md).
+
+## Flujo de agentes opcional
+
+El servidor MCP funciona por sí solo. El método opcional resuelve otro problema:
+preservar por qué existe un trabajo, qué cambió y qué sigue siendo cierto entre
+sesiones de agentes.
+
+Adoptalo por capas:
+
+1. Usá sólo las tools MCP.
+2. Sumá los estados del board, la plantilla de card y los handshakes humanos.
+3. Sumá un worktree por card con un director que coordina obreros.
+
+Empezá por [Un board que sobrevive a la sesión](workflow/README.md). La
+[plantilla del board](workflow/board-template.md), las
+[skills copiables de Claude Code](workflow/skills/) y el
+[helper opcional de worktrees](workflow/worktrees/README.md) son piezas independientes.
+
+## Solución de problemas
+
+- [Síntomas, causas y fixes exactos](docs/troubleshooting.md)
+- [Por qué Planka 2.x rompe MCP viejos en silencio](docs/planka-2x-gotchas.md)
+- [Payloads completos de las tools](docs/tools.md)
+
+Al reportar un bug, incluí la versión de Planka, la de Node, el nombre de la tool
+y el texto del error. Nunca pegues credenciales ni access tokens.
+
+## Créditos y licencia
+
+Este es un fork con licencia MIT de
+[`gogogadgetbytes/planka-mcp`](https://github.com/gogogadgetbytes/planka-mcp),
+no una implementación original desde cero. [CREDITS.md](CREDITS.md) documenta
+la atribución del upstream, los fixes mantenidos y los pull requests sin respuesta.
+
+[LICENSE](LICENSE) conserva los avisos del autor original y de los contribuidores actuales.
+
+## Desarrollo
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+El smoke real es opt-in porque modifica un board escribible y después limpia lo
+creado. Ejercita las 24 tools por stdio y contrasta cada escritura contra la API
+cruda de Planka: 64 checks con nombre.
+
+```bash
+export PLANKA_BASE_URL="https://planka.example.com"
+export PLANKA_AGENT_EMAIL="agent@example.com"
+export PLANKA_AGENT_PASSWORD="<TU_PASSWORD>"
+export PLANKA_SMOKE_BOARD_ID="1234567890123456789"
+npm run test:smoke
+```
+
+`npm run test:smoke` compila primero, así que no puede testear un `dist/` viejo.
+Cuatro variables opcionales lo ajustan:
+
+| Variable | Qué hace |
+|---|---|
+| `PLANKA_SMOKE_LIST_ID` | Columna donde se crea la card descartable. Sin esto elige una columna que parezca de descarte y, si no la hay, la primera |
+| `PLANKA_SMOKE_FAIL_AFTER` | Inyecta un fallo después del check `<n>`, para probar que la limpieza igual corre |
+| `PLANKA_MCP_ENTRY` | Punto de entrada del servidor. Por defecto `dist/index.js` |
+| `VERBOSE` | Poné `1` para imprimir el payload de cada check |
+
+Leé [CONTRIBUTING.md](CONTRIBUTING.md) antes de abrir un cambio. La identidad de
+release está centralizada en [project.identity.json](project.identity.json):
+actualizala y ejecutá `npm run sync:identity` antes de publicar con tu namespace.

package/README.md

@@ -0,0 +1,213 @@
+# planka-mcp
+
+Control a Planka 2.x board from Claude Code through 24 MCP tools.
+Writes are re-read and verified, so a reported success matches the board.
+An optional workflow turns that board into durable memory for agent work.
+
+[Leer en español](README.es.md)
+
+```text
+You talk to Claude Code
+          │
+          ▼
+  planka-mcp (stdio) ─── HTTPS + JSON ───▶ Planka 2.x
+          │                                  │
+          └──── reads the result back ◀──────┘
+```
+
+> [!WARNING]
+> The old `@gogogadgetbytes/planka-mcp` package can report success while doing
+> nothing on Planka 2.x. Read [the five silent-failure gotchas](docs/planka-2x-gotchas.md)
+> before replacing an existing installation.
+
+## New to MCP? Read this first
+
+MCP is a standard that lets Claude Code call tools provided by another program.
+This repository runs a small local program that translates those tool calls into Planka API requests.
+It needs Planka credentials because it acts as a dedicated Planka user, not as Claude itself.
+The credentials stay on your machine and are never written into the project-level `.mcp.json` file.
+Claude Code loads MCP servers when a session starts, so restart it after setup or configuration changes.
+
+## Requirements
+
+- Node.js 18 or newer and `npm`
+- A reachable Planka 2.x instance
+- A dedicated Planka user that can see the target project and board
+- Claude Code installed and available as `claude`
+- A project-manager role only if setup must create a board
+
+Linux and macOS are supported. No Bun runtime is required.
+
+## Install in 5 minutes
+
+Clone the repository and run the guided installer:
+
+```bash
+git clone https://github.com/omnicoreos/planka-mcp.git
+cd planka-mcp
+./scripts/setup.sh
+```
+
+Setup asks for the Planka URL, agent email or username, and password. It validates
+those credentials before writing configuration, lets you select or create a board,
+and then runs a real create/label/comment/delete smoke test.
+
+It offers two Claude Code configurations:
+
+| Choice | Use it when | Where it lives |
+|---|---|---|
+| `claude mcp add` | You want the easiest personal setup | Claude Code user configuration |
+| Project `.mcp.json` | A team should share the server entry | `<YOUR_PROJECT>/.mcp.json`, safe to commit |
+
+In both cases, setup stores credentials outside Git in
+`~/.config/planka-mcp/config.json` with mode `0600` and creates the private launcher
+`~/.local/bin/planka-mcp`. A generated team configuration contains no password:
+
+```json
+{
+  "mcpServers": {
+    "planka": {
+      "type": "stdio",
+      "command": "${HOME}/.local/bin/planka-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+The installer is safe to rerun. It updates the `planka` entry, reuses existing
+workflow lists and labels, and deletes its temporary smoke-test card.
+
+## Verify it works
+
+First, inspect Claude Code's configuration:
+
+```bash
+claude mcp list
+claude mcp get planka
+```
+
+Then fully restart Claude Code. If you chose `.mcp.json`, open Claude Code in that
+project and approve the project-scoped server when prompted.
+
+Ask Claude Code:
+
+```text
+Show me my Planka projects and boards. In the Pending list, create a card named
+"MCP is working" with the description "Created from Claude Code", then read it back.
+```
+
+If Claude cannot see the tools, restart first and then follow
+[Troubleshooting](docs/troubleshooting.md).
+
+## The 24 tools
+
+IDs are strings. Start with `planka_get_structure`, then use IDs returned by
+Planka; do not guess them.
+
+| Tool | What it does |
+|---|---|
+| `planka_get_structure` | Lists visible projects, boards, and lists |
+| `planka_get_board` | Reads one board with its lists, cards, labels, and optional task counts |
+| `planka_list_lists` | Lists a board's columns with card counts, and no cards |
+| `planka_board_summary` | One-call briefing: columns, labels, and the cards waiting on a decision |
+| `planka_list_cards` | Reads one column, paginated, without descriptions by default |
+| `planka_find_cards` | Searches a board's cards by label, text, or column |
+| `planka_create_card` | Creates a card and can attach tasks and labels |
+| `planka_get_card` | Reads complete card details |
+| `planka_update_card` | Updates title, description, due date, or completion |
+| `planka_move_card` | Moves a card to another list or position |
+| `planka_delete_card` | Permanently deletes a card |
+| `planka_create_tasks` | Adds checklist tasks to a card |
+| `planka_update_task` | Renames or completes a task |
+| `planka_delete_task` | Deletes a task |
+| `planka_manage_labels` | Creates, updates, or deletes board labels |
+| `planka_set_card_labels` | Adds or removes labels and verifies the final state |
+| `planka_add_comment` | Adds a comment through Planka 2.x's dedicated endpoint |
+| `planka_get_comments` | Reads comments through the dedicated endpoint |
+| `planka_manage_comment` | Edits or deletes an existing comment |
+| `planka_manage_lists` | Creates, updates, or deletes board lists |
+| `planka_add_attachment` | Uploads a local file to a card and verifies it landed |
+| `planka_get_attachments` | Lists a card's attachments with type, size, and download URL |
+| `planka_view_attachment` | Returns an attachment's content; images come back viewable |
+| `planka_delete_attachment` | Deletes an attachment |
+
+`planka_get_board` returns the entire board, which is often more than the
+question needs. The four scoped reads answer narrower questions and return far
+less text: measured on a board of 100 cards, `planka_list_lists` returned 39
+times less than `planka_get_board`, `planka_board_summary` 16 times less, and
+`planka_find_cards` between 18 and 56 times less depending on the filter. They
+also report `total`, `returned`, and `hasMore`, so a clipped answer never looks
+complete.
+
+Every input field and a complete payload for every tool are in
+[Tools reference](docs/tools.md).
+
+## Optional agent workflow
+
+The MCP server works on its own. The optional method solves a different problem:
+preserving why work exists, what changed, and what remains true between agent
+sessions.
+
+Adopt it in layers:
+
+1. Use only the MCP tools.
+2. Add the board states, card template, and human handshakes.
+3. Add one worktree per card with a director coordinating workers.
+
+Start with [A board that survives the session](workflow/README.md). The
+[board template](workflow/board-template.md), copyable
+[Claude Code skills](workflow/skills/), and optional
+[worktree helper](workflow/worktrees/README.md) are independent pieces.
+
+## Troubleshooting
+
+- [Symptoms, causes, and exact fixes](docs/troubleshooting.md)
+- [Why Planka 2.x breaks older MCP servers silently](docs/planka-2x-gotchas.md)
+- [Complete tool payloads](docs/tools.md)
+
+When reporting a bug, include the Planka version, Node version, the tool name,
+and the error text. Never paste credentials or access tokens.
+
+## Credits and license
+
+This is an MIT-licensed fork of
+[`gogogadgetbytes/planka-mcp`](https://github.com/gogogadgetbytes/planka-mcp),
+not an original-from-scratch implementation. See [CREDITS.md](CREDITS.md) for
+the upstream attribution, maintained fixes, and unanswered pull requests.
+
+See [LICENSE](LICENSE) for the original and current contributor notices.
+
+## Development
+
+```bash
+npm ci
+npm run build
+npm test
+```
+
+The real smoke test is opt-in because it mutates a writable board and then cleans
+up after itself. It drives all 24 tools over stdio and cross-checks every write
+against the raw Planka API — 64 named checks:
+
+```bash
+export PLANKA_BASE_URL="https://planka.example.com"
+export PLANKA_AGENT_EMAIL="agent@example.com"
+export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
+export PLANKA_SMOKE_BOARD_ID="1234567890123456789"
+npm run test:smoke
+```
+
+`npm run test:smoke` builds first, so it cannot test a stale `dist/`. Four
+optional variables tune it:
+
+| Variable | What it does |
+|---|---|
+| `PLANKA_SMOKE_LIST_ID` | Column where the scratch card is created. Without it, a scratch-looking column is picked, falling back to the first one |
+| `PLANKA_SMOKE_FAIL_AFTER` | Injects a failure after check `<n>`, to prove that cleanup still runs |
+| `PLANKA_MCP_ENTRY` | Server entry point. Defaults to `dist/index.js` |
+| `VERBOSE` | Set to `1` to print each check's payload |
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a change. Release identity
+is centralized in [project.identity.json](project.identity.json); update it and
+run `npm run sync:identity` before publishing under your own namespace.