Bug: board item labels parameter sent as array instead of string

forgejo_admin commented

2026-03-16 03:00:35 +00:00

Owner

Lineage

bug-mcp-board-labels-array (pal-e-docs bug note). Discovered during first real use of template-ticket label conventions.

Repo

forgejo_admin/pal-e-docs-mcp

User Story

As Betty Sue triaging board items
I want to set labels via create_board_item and update_board_item MCP tools
So that the traceability triangle label conventions from template-ticket can be applied

Context

create_board_item(labels="arch:deployment,track:backend,type:bug") returns 422: "Input should be a valid string." The pal-e-docs API receives an array ["arch:deployment","track:backend","type:bug"] instead of the string "arch:deployment,track:backend,type:bug". Even single-value strings get wrapped: ["value"]. The tags parameter on create_note works correctly with commas — same description, different behavior.

Root cause is likely in how the MCP tool definition or SDK serializes the labels parameter. The SDK's create_board_item and update_board_item may have labels typed as list instead of str, or the MCP bridge infers list type from the comma-separated description.

File Targets

Files to investigate and fix:

src/pal_e_docs_mcp/tools/boards.py (or wherever board item tools are defined) — check labels parameter type annotation
Check if the SDK (pal-e-docs-sdk) also has the wrong type — if so, fix there too

Files to compare:

src/pal_e_docs_mcp/tools/notes.py — the tags parameter on create_note works correctly. Compare how tags is typed vs how labels is typed.

Acceptance Criteria

create_board_item(labels="arch:deployment,track:backend,type:bug") succeeds and stores labels as string
update_board_item(labels="type:feature,scope:planned") succeeds and replaces existing labels
Existing single-label items (e.g. "status:approved") still work
tags parameter on create_note still works (regression check)

Test Expectations

Unit test: create_board_item with multi-value labels string returns 200
Unit test: update_board_item with labels string returns 200
Run: PALDOCS_BASE_URL=... pytest tests/ -v

Constraints

The fix should match how tags is handled on create_note — use the same pattern
May also need a fix in pal-e-docs-sdk if the SDK types labels as list
Uses uv not pip for dependency management

Checklist

PR opened
Tests pass
No unrelated changes

bug-mcp-board-labels-array — pal-e-docs bug note with full diagnosis
template-ticket — blocked by this bug (label conventions can't be applied via MCP)

### Lineage `bug-mcp-board-labels-array` (pal-e-docs bug note). Discovered during first real use of `template-ticket` label conventions. ### Repo `forgejo_admin/pal-e-docs-mcp` ### User Story As Betty Sue triaging board items I want to set labels via `create_board_item` and `update_board_item` MCP tools So that the traceability triangle label conventions from `template-ticket` can be applied ### Context `create_board_item(labels="arch:deployment,track:backend,type:bug")` returns 422: "Input should be a valid string." The pal-e-docs API receives an array `["arch:deployment","track:backend","type:bug"]` instead of the string `"arch:deployment,track:backend,type:bug"`. Even single-value strings get wrapped: `["value"]`. The `tags` parameter on `create_note` works correctly with commas — same description, different behavior. Root cause is likely in how the MCP tool definition or SDK serializes the `labels` parameter. The SDK's `create_board_item` and `update_board_item` may have `labels` typed as `list` instead of `str`, or the MCP bridge infers list type from the comma-separated description. ### File Targets Files to investigate and fix: - `src/pal_e_docs_mcp/tools/boards.py` (or wherever board item tools are defined) — check `labels` parameter type annotation - Check if the SDK (`pal-e-docs-sdk`) also has the wrong type — if so, fix there too Files to compare: - `src/pal_e_docs_mcp/tools/notes.py` — the `tags` parameter on `create_note` works correctly. Compare how `tags` is typed vs how `labels` is typed. ### Acceptance Criteria - [ ] `create_board_item(labels="arch:deployment,track:backend,type:bug")` succeeds and stores labels as string - [ ] `update_board_item(labels="type:feature,scope:planned")` succeeds and replaces existing labels - [ ] Existing single-label items (e.g. `"status:approved"`) still work - [ ] `tags` parameter on `create_note` still works (regression check) ### Test Expectations - [ ] Unit test: `create_board_item` with multi-value labels string returns 200 - [ ] Unit test: `update_board_item` with labels string returns 200 - [ ] Run: `PALDOCS_BASE_URL=... pytest tests/ -v` ### Constraints - The fix should match how `tags` is handled on `create_note` — use the same pattern - May also need a fix in `pal-e-docs-sdk` if the SDK types `labels` as list - Uses `uv` not pip for dependency management ### Checklist - [ ] PR opened - [ ] Tests pass - [ ] No unrelated changes ### Related - `bug-mcp-board-labels-array` — pal-e-docs bug note with full diagnosis - `template-ticket` — blocked by this bug (label conventions can't be applied via MCP)