Skip to content

feat: add parent tag support for hierarchical tag structures#5

Open
zagah wants to merge 1 commit intobarryw:mainfrom
zagah:feat/parent-tag-support
Open

feat: add parent tag support for hierarchical tag structures#5
zagah wants to merge 1 commit intobarryw:mainfrom
zagah:feat/parent-tag-support

Conversation

@zagah
Copy link
Copy Markdown

@zagah zagah commented Apr 14, 2026

Summary

  • Adds optional parent field to Tag, TagCreateRequest, and TagUpdateRequest models
  • Exposes parent as an optional parameter on paperless_tags_create and paperless_tags_update MCP tools
  • No breaking changes — parent defaults to null everywhere

Background

Paperless-ngx supports nested/hierarchical tags via a parent ID on the API. This PR makes that capability accessible through the MCP interface, allowing AI assistants to create and manage tag hierarchies (e.g. a Taxes parent tag with 2023, 2024 children).

Test plan

  • Build succeeds with zero warnings
  • Existing tag tests pass unchanged
  • Manual: create a child tag with parent=<id> and verify Paperless stores the hierarchy correctly

🤖 Generated with Claude Code

Adds optional parent field to Tag, TagCreateRequest, and TagUpdateRequest
models, and exposes it as an optional parameter on the paperless_tags_create
and paperless_tags_update MCP tools.

Paperless-ngx supports nested tags via a parent ID; this change makes that
capability accessible through the MCP interface.
Copy link
Copy Markdown
Owner

@barryw barryw left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review — Parent Tag Support

Overview

Clean implementation adding parent parameter to tag Create/Update tools and the Tag model for hierarchical tag structures. Code correctness is good — WhenWritingNull is set globally so null parents won't accidentally unset values on PATCH.

Issues

# Severity Issue
1 Blocker No tests for new behavior. Zero tests cover Create with parent or Update with parent. Project convention requires test coverage for new features. At minimum, add tests for: Create_WithParent_ReturnsCreatedTagWithParent and Update_WithParent_SendsParentId.
2 Low No way to explicitly unset a parent (move tag back to root) due to WhenWritingNull. Should be documented in the parent parameter [Description] on Update, or tracked as a follow-up issue.
3 Nit TestFixtures.Tags.CreateTag doesn't accept an optional parent parameter, so fixtures can't exercise hierarchy deserialization.

What's Good

  • Tool naming follows underscore convention ✓
  • No breaking changes, no security concerns, no performance impact
  • Feature is well-scoped and the model/tool changes are minimal

Recommendation

Add tests for the new parent parameter on create and update before merge.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants