refactor: replace dedicated epic tools with work-item-type-based approach and add server instructions

[akhil-vamshi-konam]

Description

This PR removes epic module and replaces it with:

Server Instructions (instructions.py)

Sent to MCP clients at session initialization via FastMCP's instructions parameter. Three sections guide the LLM:

• Work item type scoping — when to use resolve_work_item_type versus manual tools.

• Epics — how to create, list, nest, and delete epics using generic work item tools.

• Initiatives — toggle-aware fallback behavior:

  • Use native initiatives when the feature is enabled.
  • Use an "Initiative" work item type when the feature is disabled.

import_work_item_types_to_project

Exposed as a standalone tool for cases where callers need explicit control over the import step.

Initiative Toggle Guard

create_initiative now raises a ToolError when the workspace initiatives feature is disabled. The error message contains guidance directing the LLM to the fallback flow.

Type of Change

• Code refactoring
• Improvement (change that would cause existing functionality to not work as expected)

Summary by CodeRabbit

Release Notes

• Documentation

  • Updated tools reference documentation.

• New Features

  • Added two new tools for importing and resolving work item types within projects.

• Changes

  • Epic-specific tools have been removed; epic operations are now handled as work item types.

[coderabbitai]

📝 Walkthrough

Walkthrough

Dedicated epic MCP tools (epics.py) are removed and epic handling is shifted to work-item types. Two new tools—import_work_item_types_to_project and resolve_work_item_type—are added to work_item_types.py. A new instructions.py module defines server-level MCP client prompt templates for epic/initiative scoping, wired into all three server transports. create_initiative gains a feature-availability gate. Integration tests and README are updated throughout.

Changes

Epic-to-Work-Item-Type Migration

Layer / File(s)	Summary
Remove dedicated epic tools and epics feature toggle plane_mcp/tools/epics.py, plane_mcp/tools/__init__.py, plane_mcp/tools/projects.py, plane_mcp/tools/work_item_types.py, README.md	epics.py is deleted and deregistered from __init__.py; update_project_features drops the epics parameter; create_work_item_type and update_work_item_type drop is_epic; README removes the Epics tool category.
New import_work_item_types_to_project and resolve_work_item_type tools plane_mcp/tools/work_item_types.py, README.md	Adds bulk workspace-type import and a name-based type resolution/creation tool that handles both workspace-owned and project-scoped modes, enabling the work_item_types feature flag when needed.
Server instruction templates and wiring plane_mcp/instructions.py, plane_mcp/server.py	New instructions.py defines WORK_ITEM_TYPE_SCOPING_INSTRUCTIONS, EPIC_INSTRUCTIONS, INITIATIVE_INSTRUCTIONS, and SERVER_INSTRUCTIONS; all three FastMCP constructors now receive SERVER_INSTRUCTIONS.
Initiative feature gate and docstring cleanup plane_mcp/tools/initiatives.py	create_initiative checks workspace features and raises ToolError when initiatives is disabled, redirecting callers to resolve_work_item_type; workspace_slug removed from all initiative tool docstrings.
Integration tests updated for work-item-type epics tests/test_integration.py	Epic setup/teardown replaced with dynamic type resolution and create_work_item/delete_work_item; epic listing uses PQL-filtered list_work_items; EXPECTED_TOOLS updated to reflect removed and added tools.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• makeplane/plane-mcp-server#133: Modifies the same plane_mcp/tools/work_item_types.py file with overlapping changes to work-item-type tool registrations and scoping behavior.

Suggested reviewers

• Saurabhkmr98
• Prashant-Surya

Poem

🐇 Hop, hop, the epics are gone,
Now work item types carry on!
resolve_work_item_type leads the way,
Instructions sent at the start of each day.
One rabbit, one type — no special endpoint today! 🥕

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately and concisely summarizes the main changes: removing dedicated epic tools, adopting a work-item-type-based approach, and adding server instructions—all of which are confirmed by the raw summary and PR objectives.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore-update-epic-initiatives-tools

---

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.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

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 `@tests/test_integration.py`:
- Line 199: The list endpoints in the plane_mcp/tools module are returning
pagination metadata (dicts) instead of just the list payload, which causes the
test code to incorrectly attempt to access a ["results"] key on what should
already be a list. Modify all list endpoints to return only `response.results`
(the list) instead of the full response object with pagination metadata, then
update line 199 in the test to remove the `["results"]` indexing since
`extract_result(epics_result)` will already be the list. This ensures
consistency where `extract_result()` on list endpoints returns the list directly
without needing additional dict key access.
- Around line 138-157: The epic-type resolution logic has two issues: first, it
checks if workspace_types is non-empty to decide whether to create at workspace
or project scope, but this doesn't properly handle the case when workspace_types
exists but is empty; second, when creating a workspace-level Epic type on line
146, it does not first check whether an "Epic" type already exists in
workspace_types, which can create duplicates. Fix this by searching
workspace_types for an existing "Epic" type using the same pattern as the
project_types search on line 141, and only create a new workspace Epic if one
doesn't already exist. Then reconsider the mode-selection logic to ensure it
correctly distinguishes between valid creation paths and doesn't fall through to
project-scoped creation when workspace-level creation is appropriate.

🪄 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: 199a60b3-9c34-4b48-b21c-a6ff4803a12a

📥 Commits

Reviewing files that changed from the base of the PR and between 3d54d1a and 657d699.

📒 Files selected for processing (9)

• README.md
• plane_mcp/instructions.py
• plane_mcp/server.py
• plane_mcp/tools/__init__.py
• plane_mcp/tools/epics.py
• plane_mcp/tools/initiatives.py
• plane_mcp/tools/projects.py
• plane_mcp/tools/work_item_types.py
• tests/test_integration.py

💤 Files with no reviewable changes (3)

• plane_mcp/tools/epics.py
• plane_mcp/tools/projects.py
• plane_mcp/tools/init.py