Epics

Epic management through MCP. Group related user stories and features into strategic epics for high-level project planning.

Open Source — GitScrum MCP Server is open source under the MIT license. Available on npm and GitHub. Model Context Protocol server for GitScrum — Claude, GitHub Copilot, Cursor, and any MCP-compatible client full operational access to your project management stack.

The epic tool provides 3 actions for managing epics — the highest-level organizational unit in your project hierarchy. Epics group related user stories and features into strategic initiatives, giving your team a clear view of large-scale objectives. Through the MCP Server, your AI assistant can create epics, update their details, and list all epics within a project.

Epics in GitScrum represent significant bodies of work that span multiple sprints and contain multiple user stories. They answer the question "what major initiative are we working toward?" while user stories and tasks handle the "how" and "what specifically." The MCP Server makes it possible to build and manage this entire hierarchy — epics → user stories → tasks — through natural language conversation.

Actions Overview

Action	Purpose	Required Parameters
`list`	List all epics in a project	`companyslug`, `project``slug`
`create`	Create a new epic with title, description, and color	`companyslug`, `project``slug`, `title`
`update`	Modify any field on an existing epic	`epicuuid`, `company``slug`, `project_slug`

Listing Epics

The list action returns all epics within a specific project. Each epic in the response includes its uuid, title, description, color, and associated metadata. This gives your AI assistant a complete view of the project's strategic initiatives.

Use this action to review the project roadmap, identify which epics have the most activity, or check how work is distributed across strategic goals.

Required Parameters

Parameter	Type	Description
`company_slug`	string	Workspace identifier (from the `workspace` tool)
`project_slug`	string	Project identifier (from the `project` tool)

Example Prompts

You:  "List all epics in the Backend project"
AI:   Calls epic action=list → returns all epics with titles, descriptions, and colors

You:  "What are our current strategic initiatives?"
AI:   Calls epic action=list → summarizes the project's epics as high-level goals

You:  "Show me the project roadmap"
AI:   Calls epic action=list → presents epics as strategic milestones

Creating Epics

The create action builds a new epic in a single call. Epics are intentionally lightweight — they need a title and can optionally include a description and a color for visual identification on the board. The simplicity reflects their role as strategic containers rather than task-level work items.

Required Parameters

Parameter	Type	Description
`company_slug`	string	Workspace identifier (from the `workspace` tool)
`project_slug`	string	Project identifier (from the `project` tool)
`title`	string	Epic name (e.g. "Q1 Release", "Authentication Overhaul", "Mobile App v2")

Optional Parameters

Parameter	Type	Description
`description`	string	Detailed description in Markdown format. Use this for goals, scope, success criteria, and background context.
`color`	string	Hex color code without the `#` prefix (e.g. `FF5733`, `3B82F6`, `10B981`). Used for visual identification in the GitScrum interface.

Color Guidelines

Epics appear as color-coded labels throughout the GitScrum interface — on the Kanban board, in sprint views, and in reports. Choosing distinct colors for each epic helps your team visually identify which strategic initiative a task belongs to at a glance.

Common color conventions:

Color	Hex	Typical Use
Blue	`3B82F6`	Features and enhancements
Red	`EF4444`	Critical fixes or technical debt
Green	`10B981`	Infrastructure and DevOps
Purple	`8B5CF6`	Research and exploration
Orange	`F59E0B`	Client-facing deliverables

Example Prompts

You:  "Create an epic 'Q1 Release' with blue color"
AI:   Calls epic action=create with title="Q1 Release", color="3B82F6"

You:  "Create an epic called 'Authentication Overhaul' with a description covering
       OAuth2, SSO, and RBAC migration goals"
AI:   Calls epic action=create with title, description containing the scope details

You:  "Add a new epic for the mobile app redesign, use orange color"
AI:   Calls epic action=create with title="Mobile App Redesign", color="F59E0B"

You:  "Create three epics for Q1: API Performance, User Dashboard, and
       Payment Integration. Use different colors for each."
AI:   Calls epic action=create three times with distinct titles and colors

Updating Epics

The update action modifies any field on an existing epic. Only the fields you specify are changed — all other fields remain untouched. This is useful for refining epic descriptions as scope evolves, changing colors for visual reorganization, or renaming epics to better reflect their current direction.

Required Parameters

Parameter	Type	Description
`epic_uuid`	string	Epic UUID (from `list` response)
`company_slug`	string	Workspace identifier
`project_slug`	string	Project identifier

Optional Parameters

All optional parameters from create are available in update: title, description, color.

Example Prompts

You:  "Update the Q1 Release epic description to include the new API migration scope"
AI:   Finds the epic via list → calls epic action=update with expanded description

You:  "Change the Authentication Overhaul epic color to red"
AI:   Calls epic action=update with color="EF4444"

You:  "Rename the 'Mobile App v2' epic to 'Mobile App Redesign'"
AI:   Calls epic action=update with title="Mobile App Redesign"

You:  "Update all epics to include estimated completion dates in their descriptions"
AI:   Lists epics → updates each with revised descriptions

Strategic Planning Workflow

Epics are most effective when used as the top of a deliberate planning hierarchy. This workflow demonstrates how to build a complete project structure from strategic initiatives down to actionable tasks.

1. Define strategic epics

Start by establishing the major initiatives for the quarter or release cycle.

You:  "We're planning Q1. Create epics for: API Performance (green),
       User Dashboard (blue), and Payment Integration (purple)"
AI:   Creates three epics with descriptive titles and distinct colors

2. Add scope and success criteria

Refine each epic with detailed descriptions that clarify what "done" looks like.

You:  "Update the API Performance epic with a description: 'Reduce p95 latency
       to under 200ms. Migrate to connection pooling. Add caching layer.'"
AI:   Calls epic action=update with the detailed description

3. Break epics into user stories

Create user stories under each epic to define specific requirements.

You:  "Create user stories for the Payment Integration epic:
       - As a user, I want to pay with credit card
       - As a user, I want to view my payment history
       - As an admin, I want to issue refunds"
AI:   Creates three user stories linked to the project

4. Convert stories to tasks

Break each user story into implementable tasks that go on the Kanban board.

You:  "Break down the credit card payment story into development tasks"
AI:   Creates tasks for: Stripe integration, payment form UI, validation,
      error handling, and receipt generation

5. Review epic progress

Check how work is progressing across your strategic initiatives.

You:  "Show me the status of all epics in the project"
AI:   Lists epics → for each, filters tasks to calculate completion metrics

Epics and Project Visibility

Epics provide a powerful communication layer between development teams and stakeholders. When a project manager or client asks "what are we working on this quarter?", the epic list provides the answer at the right level of abstraction — strategic enough for executive reviews, structured enough for sprint planning.

Through the MCP Server, you can generate epic-level summaries on demand:

You:  "Give me a high-level status update for all epics"
AI:   Lists epics → filters tasks by epic → summarizes progress for each initiative

You:  "Which epic has the most incomplete work?"
AI:   Lists epics → analyzes task completion → identifies the epic with the most remaining tasks

Context Auto-Resolution

The epic tool supports automatic context resolution. If the AI assistant already knows your workspace and project from a previous call in the conversation, it carries that context forward. This means you can say "Create an epic" without specifying the project every time, as long as the AI assistant established project context earlier in the conversation.

Next Steps

User Stories: Define requirements within epics as structured user stories.
Tasks: Create the implementation tasks that deliver on your epics.
Sprints: Plan sprints around prioritized epic work.
Labels: Categorize tasks across epics with labels for filtering.
Quick Start: Set up the MCP server if you haven't already.