feat: replace work item relations with dedicated dependency and custom relation tools#148
Merged
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds workspace relation-definition tools, rewrites relation handling to split built-in and custom backends, updates project/workspace member listing and role tools to paginated APIs, and expands structured logging with user context, tool metadata, and related documentation. ChangesWork Item Relation Definitions and Dual-Mode Relation Tools
Role, project member, and workspace member pagination
Structured logging and transport middleware
Estimated code review effort🎯 4 (Complex) | ⏱️ ~45 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
plane_mcp/tools/work_item_relation_definitions.py (1)
138-142:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd missing
Returnssections to tool docstrings.Both modified tool docstrings include
Argsbut omitReturns, which violates the tool docstring standard.
plane_mcp/tools/work_item_relation_definitions.py#L138-L142: add aReturnssection (even if it is explicitNone/ack behavior).plane_mcp/tools/work_item_relations.py#L136-L150: add aReturnssection documenting the remove tool’s output contract.
As per coding guidelines, “Tool docstrings must include Args and Returns sections.”🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plane_mcp/tools/work_item_relation_definitions.py` around lines 138 - 142, Add missing `Returns` sections to both tool docstrings to comply with the tool docstring standard. In `plane_mcp/tools/work_item_relation_definitions.py` lines 138-142, add a `Returns` section to the docstring for the delete method documenting what it returns (e.g., None or acknowledgment behavior). In `plane_mcp/tools/work_item_relations.py` lines 136-150, add a `Returns` section to the docstring for the remove tool documenting its output contract. Both sections should clearly describe the return value or behavior to ensure complete documentation per coding guidelines.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plane_mcp/tools/work_item_relations.py`:
- Around line 96-127: The function currently silently chooses dependency
creation if relation_type is provided, even if custom relation fields
(relation_definition_id and relation_definition_label) are also passed. Since
these modes are mutually exclusive per the API contract, add early validation
before the existing if statements to check if both relation_type and the custom
relation fields are provided together. If this ambiguous combination is
detected, raise a ValueError explaining that these parameters are mutually
exclusive and the caller must choose only one mode.
In `@tests/test_integration.py`:
- Around line 193-200: The extract_result call for the epics_result is
incorrectly assuming the payload is wrapped in a dict with a "results" key, but
list_work_items returns the item list directly. Remove the ["results"] indexing
from the epics assignment where extract_result(epics_result) is called, so that
epics is assigned the extracted list directly rather than attempting to access a
non-existent "results" key within it.
- Around line 142-158: Before creating a new workspace-level Epic type via the
create_work_item_type call, first check if an Epic type already exists in the
workspace_types list that was just retrieved. After extracting the
workspace_types from the result, search through that list for an existing type
with the name "Epic". If found, use that existing type for epic_type instead of
creating a duplicate. Only call create_work_item_type if no Epic type already
exists in the workspace_types. This prevents duplicate-name errors and avoids
unnecessary type creation when the type is already available.
---
Outside diff comments:
In `@plane_mcp/tools/work_item_relation_definitions.py`:
- Around line 138-142: Add missing `Returns` sections to both tool docstrings to
comply with the tool docstring standard. In
`plane_mcp/tools/work_item_relation_definitions.py` lines 138-142, add a
`Returns` section to the docstring for the delete method documenting what it
returns (e.g., None or acknowledgment behavior). In
`plane_mcp/tools/work_item_relations.py` lines 136-150, add a `Returns` section
to the docstring for the remove tool documenting its output contract. Both
sections should clearly describe the return value or behavior to ensure complete
documentation per coding guidelines.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f03418e5-4715-4273-8d89-b804cb6dc997
📒 Files selected for processing (9)
README.mdplane_mcp/instructions.pyplane_mcp/tools/__init__.pyplane_mcp/tools/initiatives.pyplane_mcp/tools/work_item_relation_definitions.pyplane_mcp/tools/work_item_relations.pyplane_mcp/tools/work_item_types.pyplane_mcp/tools/work_items.pytests/test_integration.py
✅ Files skipped from review due to trivial changes (2)
- plane_mcp/tools/work_item_types.py
- README.md
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
plane_mcp/tools/work_item_relation_definitions.py (1)
138-142:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winAdd missing
Returnssections to tool docstrings.Both modified tool docstrings include
Argsbut omitReturns, which violates the tool docstring standard.
plane_mcp/tools/work_item_relation_definitions.py#L138-L142: add aReturnssection (even if it is explicitNone/ack behavior).plane_mcp/tools/work_item_relations.py#L136-L150: add aReturnssection documenting the remove tool’s output contract.
As per coding guidelines, “Tool docstrings must include Args and Returns sections.”🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plane_mcp/tools/work_item_relation_definitions.py` around lines 138 - 142, Add missing `Returns` sections to both tool docstrings to comply with the tool docstring standard. In `plane_mcp/tools/work_item_relation_definitions.py` lines 138-142, add a `Returns` section to the docstring for the delete method documenting what it returns (e.g., None or acknowledgment behavior). In `plane_mcp/tools/work_item_relations.py` lines 136-150, add a `Returns` section to the docstring for the remove tool documenting its output contract. Both sections should clearly describe the return value or behavior to ensure complete documentation per coding guidelines.Source: Coding guidelines
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plane_mcp/tools/work_item_relations.py`:
- Around line 96-127: The function currently silently chooses dependency
creation if relation_type is provided, even if custom relation fields
(relation_definition_id and relation_definition_label) are also passed. Since
these modes are mutually exclusive per the API contract, add early validation
before the existing if statements to check if both relation_type and the custom
relation fields are provided together. If this ambiguous combination is
detected, raise a ValueError explaining that these parameters are mutually
exclusive and the caller must choose only one mode.
In `@tests/test_integration.py`:
- Around line 193-200: The extract_result call for the epics_result is
incorrectly assuming the payload is wrapped in a dict with a "results" key, but
list_work_items returns the item list directly. Remove the ["results"] indexing
from the epics assignment where extract_result(epics_result) is called, so that
epics is assigned the extracted list directly rather than attempting to access a
non-existent "results" key within it.
- Around line 142-158: Before creating a new workspace-level Epic type via the
create_work_item_type call, first check if an Epic type already exists in the
workspace_types list that was just retrieved. After extracting the
workspace_types from the result, search through that list for an existing type
with the name "Epic". If found, use that existing type for epic_type instead of
creating a duplicate. Only call create_work_item_type if no Epic type already
exists in the workspace_types. This prevents duplicate-name errors and avoids
unnecessary type creation when the type is already available.
---
Outside diff comments:
In `@plane_mcp/tools/work_item_relation_definitions.py`:
- Around line 138-142: Add missing `Returns` sections to both tool docstrings to
comply with the tool docstring standard. In
`plane_mcp/tools/work_item_relation_definitions.py` lines 138-142, add a
`Returns` section to the docstring for the delete method documenting what it
returns (e.g., None or acknowledgment behavior). In
`plane_mcp/tools/work_item_relations.py` lines 136-150, add a `Returns` section
to the docstring for the remove tool documenting its output contract. Both
sections should clearly describe the return value or behavior to ensure complete
documentation per coding guidelines.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f03418e5-4715-4273-8d89-b804cb6dc997
📒 Files selected for processing (9)
README.mdplane_mcp/instructions.pyplane_mcp/tools/__init__.pyplane_mcp/tools/initiatives.pyplane_mcp/tools/work_item_relation_definitions.pyplane_mcp/tools/work_item_relations.pyplane_mcp/tools/work_item_types.pyplane_mcp/tools/work_items.pytests/test_integration.py
✅ Files skipped from review due to trivial changes (2)
- plane_mcp/tools/work_item_types.py
- README.md
🛑 Comments failed to post (3)
plane_mcp/tools/work_item_relations.py (1)
96-127:
⚠️ Potential issue | 🟠 Major | ⚡ Quick winReject ambiguous create mode inputs.
If callers pass
relation_typeand custom relation fields together, dependency creation is chosen silently. This should fail fast because the API contract is mutually exclusive.Suggested fix
client, workspace_slug = get_plane_client_context() + if relation_type and (relation_definition_id or relation_definition_label): + raise ValueError( + "Use either relation_type (dependency) or relation_definition_id + " + "relation_definition_label (custom), not both." + ) if relation_type: if relation_type not in _DEPENDENCY_TYPES: raise ValueError(📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.if relation_type and (relation_definition_id or relation_definition_label): raise ValueError( "Use either relation_type (dependency) or relation_definition_id + " "relation_definition_label (custom), not both." ) if relation_type: if relation_type not in _DEPENDENCY_TYPES: raise ValueError( f"relation_type must be one of {list(_DEPENDENCY_TYPES)}. For any " "other relationship, pass relation_definition_id + " "relation_definition_label from list_work_item_relation_definitions." ) return client.work_items.dependencies.create( workspace_slug=workspace_slug, project_id=project_id, work_item_id=work_item_id, data=CreateWorkItemDependency( relation_type=relation_type, # type: ignore[arg-type] work_item_ids=work_item_ids, ), ) if relation_definition_id and relation_definition_label: return client.work_items.custom_relations.create( workspace_slug=workspace_slug, project_id=project_id, work_item_id=work_item_id, data=CreateWorkItemCustomRelation( relation_definition_id=relation_definition_id, relation_definition_type=relation_definition_label, work_item_ids=work_item_ids, ), ) raise ValueError( "Provide relation_type for a built-in dependency, or " "relation_definition_id + relation_definition_label for a custom " "relation (call list_work_item_relation_definitions to find one)." )🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@plane_mcp/tools/work_item_relations.py` around lines 96 - 127, The function currently silently chooses dependency creation if relation_type is provided, even if custom relation fields (relation_definition_id and relation_definition_label) are also passed. Since these modes are mutually exclusive per the API contract, add early validation before the existing if statements to check if both relation_type and the custom relation fields are provided together. If this ambiguous combination is detected, raise a ValueError explaining that these parameters are mutually exclusive and the caller must choose only one mode.tests/test_integration.py (2)
142-158:
⚠️ Potential issue | 🟠 Major | ⚡ Quick winAvoid duplicate “Epic” type creation in workspace scope.
The fallback path creates a new workspace-level
Epicwheneverworkspace_typesis non-empty, without first checking whetherEpicalready exists there. That can trigger duplicate-name errors or unnecessary type churn.Suggested fix
- if workspace_types: - new_type_result = await client.call_tool("create_work_item_type", {"name": "Epic"}) - epic_type = extract_result(new_type_result) - created_workspace_epic_type = True - await client.call_tool( - "import_work_item_types_to_project", - {"project_id": project_id, "work_item_type_ids": [epic_type["id"]]}, - ) + if workspace_types: + epic_type = next((t for t in workspace_types if t.get("name", "").lower() == "epic"), None) + if epic_type is None: + new_type_result = await client.call_tool("create_work_item_type", {"name": "Epic"}) + epic_type = extract_result(new_type_result) + created_workspace_epic_type = True + await client.call_tool( + "import_work_item_types_to_project", + {"project_id": project_id, "work_item_type_ids": [epic_type["id"]]}, + )📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.if epic_type is None: workspace_types_result = await client.call_tool("list_work_item_types", {}) workspace_types = extract_result(workspace_types_result) if workspace_types: epic_type = next((t for t in workspace_types if t.get("name", "").lower() == "epic"), None) if epic_type is None: new_type_result = await client.call_tool("create_work_item_type", {"name": "Epic"}) epic_type = extract_result(new_type_result) created_workspace_epic_type = True await client.call_tool( "import_work_item_types_to_project", {"project_id": project_id, "work_item_type_ids": [epic_type["id"]]}, ) else: new_type_result = await client.call_tool( "create_work_item_type", {"name": "Epic", "project_id": project_id} ) epic_type = extract_result(new_type_result)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tests/test_integration.py` around lines 142 - 158, Before creating a new workspace-level Epic type via the create_work_item_type call, first check if an Epic type already exists in the workspace_types list that was just retrieved. After extracting the workspace_types from the result, search through that list for an existing type with the name "Epic". If found, use that existing type for epic_type instead of creating a duplicate. Only call create_work_item_type if no Epic type already exists in the workspace_types. This prevents duplicate-name errors and avoids unnecessary type creation when the type is already available.
193-200:
⚠️ Potential issue | 🟠 Major | ⚡ Quick winUse
list_work_itemsresult as a list, not["results"].Line 199 assumes a wrapped payload shape and can fail with
TypeError/KeyErrorwhen the tool returns the list directly.
Based on learnings, list endpoints should return onlyresponse.results(the item list), not pagination metadata wrappers.Suggested fix
- epics = extract_result(epics_result)["results"] + epics = extract_result(epics_result)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@tests/test_integration.py` around lines 193 - 200, The extract_result call for the epics_result is incorrectly assuming the payload is wrapped in a dict with a "results" key, but list_work_items returns the item list directly. Remove the ["results"] indexing from the epics assignment where extract_result(epics_result) is called, so that epics is assigned the extracted list directly rather than attempting to access a non-existent "results" key within it.Source: Learnings
…into chore-custom-relations
…work_item_tools function
feat: enrich tool-call logs
…ect/workspace member retrieval with pagination and filtering options
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@plane_mcp/tools/projects.py`:
- Around line 311-355: The get_project_members tool is returning the full
PaginatedProjectMemberResponse instead of matching the list-tool contract used
by list_projects and similar helpers. Update get_project_members in
plane_mcp/tools/projects.py to call client.projects.get_members_lite as it does
now, but return only the response.results list rather than the pagination
wrapper, keeping the existing filters and parameters unchanged.
In `@plane_mcp/tools/roles.py`:
- Around line 15-42: list_roles currently returns the full paginated response
envelope instead of the standard results list. Update the list_roles function in
roles.py to match list_projects by returning only the results from
client.roles.list(...), and keep the existing workspace_slug, namespace,
per_page, and cursor handling unchanged.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: c0ae1ca4-abdf-455c-a33a-6b23150e7ecb
📒 Files selected for processing (13)
.env.testCLAUDE.mdREADME.mdplane_mcp/__main__.pyplane_mcp/auth/plane_oauth_provider.pyplane_mcp/middleware.pyplane_mcp/server.pyplane_mcp/tools/__init__.pyplane_mcp/tools/projects.pyplane_mcp/tools/roles.pyplane_mcp/tools/workspaces.pypyproject.tomltests/test_integration.py
✅ Files skipped from review due to trivial changes (4)
- CLAUDE.md
- .env.test
- pyproject.toml
- README.md
🚧 Files skipped from review as they are similar to previous changes (1)
- tests/test_integration.py
Prashant-Surya
approved these changes
Jun 26, 2026
Prashant-Surya
approved these changes
Jun 26, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Introduces dedicated work item relation modules and improves structured logging for observability while tightening PII handling.
Work item relations
Replaces the legacy
work_item_relationstools with dedicated modules:work_item_relation_definitions(CRUD for workspace relation definitions)work_item_dependencies(manage the six built-in dependency types)work_item_custom_relations(manage definition-based custom relations)Removes the legacy
work_item_relations.pyimplementation backed by the deprecated/relations/endpoint.Logging improvements
PlaneLoggingMiddlewareto include thetoolname intools/calllog entries.workspace_slugto all log records for workspace-level analytics.LOG_USER_INFO(default:false) to optionally include user display names in logs while keeping PII disabled by default.stdiologs onlyworkspace_slug;LOG_USER_INFOis a no-op forstdio.Type of Change
Sample Logs
HTTP with user info (
LOG_USER_INFO=true→display_nameincluded){"timestamp": "2026-06-17T10:34:44.498814+00:00", "level": "INFO", "logger": "fastmcp.plane_mcp.auth.plane_oauth_provider", "message": "User verified: (4161e0f8-48a2-49b4-a43a-458465337135) - akhil.vamshi"} {"timestamp": "2026-06-17T10:34:44.532392+00:00", "level": "INFO", "logger": "fastmcp.middleware.structured_logging", "event": "request_start", "method": "tools/call", "source": "client", "payload": "{\"task\":null,\"_meta\":null,\"name\":\"list_projects\",\"arguments\":{}}", "payload_type": "CallToolRequestParams", "user_id": "4161e0f8-48a2-49b4-a43a-458465337135", "workspace_slug": "bronze", "display_name": "akhil.vamshi"} {"timestamp": "2026-06-17T10:34:44.630735+00:00", "level": "INFO", "logger": "fastmcp.middleware.structured_logging", "event": "request_success", "method": "tools/call", "source": "client", "duration_ms": 98.26, "tool": "list_projects", "user_id": "4161e0f8-48a2-49b4-a43a-458465337135", "workspace_slug": "bronze", "display_name": "akhil.vamshi"}HTTP without user info (default → no
display_name,user_idonly){"timestamp": "2026-06-17T11:55:51.043796+00:00", "level": "INFO", "logger": "fastmcp.plane_mcp.auth.plane_oauth_provider", "message": "User verified: (4161e0f8-48a2-49b4-a43a-458465337135)"} {"timestamp": "2026-06-17T11:55:51.084374+00:00", "level": "INFO", "logger": "fastmcp.middleware.structured_logging", "event": "request_start", "method": "tools/call", "source": "client", "payload": "{\"task\":null,\"_meta\":null,\"name\":\"list_projects\",\"arguments\":{}}", "payload_type": "CallToolRequestParams", "user_id": "4161e0f8-48a2-49b4-a43a-458465337135", "workspace_slug": "bronze"} {"timestamp": "2026-06-17T11:55:51.175255+00:00", "level": "INFO", "logger": "fastmcp.middleware.structured_logging", "event": "request_success", "method": "tools/call", "source": "client", "duration_ms": 90.76, "tool": "list_projects", "user_id": "4161e0f8-48a2-49b4-a43a-458465337135", "workspace_slug": "bronze"}Summary by CodeRabbit
New Features
Bug Fixes
Documentation