Linear MCP Guide for Project Delta¶

Overview¶

This guide documents best practices, workflows, and common patterns for using the Linear MCP integration with Project Delta. It will be updated as we discover more efficient workflows and encounter issues.

Table of Contents¶

Issue Hierarchy Structure
MCP Tool Usage
Common Patterns and Templates
Troubleshooting

Issue Hierarchy Structure¶

We're organizing our Linear issues using the following hierarchy:

Projects - High-level containers (e.g., "Web App", "AIHub App")
Features - Major functional areas with the "Feature" label
Tasks - Child issues of features that represent specific implementation components
Subtasks - Further breakdown of tasks when needed

Project Structure¶

Web App: User-facing application for budget management
AIHub App: AI processing pipeline for document analysis
Sana App: Legacy app integration components
Project/Platform Setup: Infrastructure and tooling setup

Feature Template¶

Features should include:

Title prefixed with "Feature:"
Detailed description with:
User story
Acceptance criteria
Technical requirements
The "Feature" label
Priority setting (typically 1 for core features)
Assignment to appropriate project

Task Naming¶

Tasks should have clear, action-oriented names that describe what needs to be implemented.

MCP Tool Usage¶

Core Functions¶

linear_get_teams: Get team information and available states/labels
linear_create_issue: Create new issues
linear_search_issues: Find existing issues
linear_bulk_update_issues: Update multiple issues at once
linear_get_user: Get current user information

Creating Parent-Child Relationships¶

To create a parent-child relationship:

Create the parent issue first
Get the parent issue's ID using linear_search_issues with the issue identifier
Create child issues using the parent's ID in the parentId parameter (must use the UUID, not the issue number)

Example:

First search for the parent issue to get its UUID:

{
  "query": "DEV-29"
}

Then create the child issue with the parent UUID:

{
  "title": "Child Task",
  "description": "Description here",
  "teamId": "a9f28c2c-a7ef-4878-985d-4f1ba82d605a",
  "projectId": "f7fe8535-bb6c-4a2c-a911-634cc337cfca",
  "parentId": "ae98d9e4-f702-4832-8c7e-5810be311221"
}

Adding Labels¶

When adding labels to issues, use labelIds (not labels):

{
  "title": "Feature: Example Feature",
  "description": "...",
  "teamId": "a9f28c2c-a7ef-4878-985d-4f1ba82d605a",
  "labelIds": ["0b210f6e-3447-4e6a-991f-4809b0546334"]
}

Common Patterns and Templates¶

Feature Description Template¶

## Feature: [Feature Name]

[Brief description of the feature]

### User Story

As a [type of user],
I want to [action or capability],
So that [benefit or value].

### Acceptance Criteria

- [Criterion 1]
- [Criterion 2]
- [Criterion 3]

### Technical Requirements

- [Requirement 1]
- [Requirement 2]
- [Requirement 3]

Task Description Template¶

[Brief description of the task]

### Tasks

- [Specific implementation step 1]
- [Specific implementation step 2]
- [Specific implementation step 3]

### Acceptance Criteria

- [Criterion 1]
- [Criterion 2]
- [Criterion 3]

Implementation Examples¶

Feature Structure Example¶

We've organized our core platform features with the following structure:

Dark/Light Mode Toggle (DEV-29)¶

Create Theme Context Provider (DEV-30)
Define Theme Color System (DEV-31)
Implement Theme Persistence (DEV-32)
Create Theme Toggle UI Component (DEV-33)

Multicurrency Support (DEV-34)¶

Design Currency Database Schema (DEV-35)
Implement Currency Conversion Service (DEV-36)
Create Currency UI Components (DEV-37)
Implement Project Currency Settings (DEV-38)

Multilingual UI Support (DEV-39)¶

Set Up i18n Framework (DEV-40)
Create Initial Translation Resources (DEV-41)
Implement RTL Support and Locale Formatting (DEV-42)
Create Language Selection UI (DEV-43)

AI Transaction Processing (DEV-80, AIHub App)¶

Task: AI Process 1 - Document Classification & Initial Analysis (DEV-81)
Task: AI Process 2 - OCR Data Extraction (DEV-82)
Task: AI Process 3 - Duplicate Check (DEV-83)
Task: AI Process 4 - Linking to Film Relationship (DEV-84)
Task: AI Process 5 - Budget Categorization (DEV-85)
Task: Update AI Prompts for New Data Model (DEV-86)
Sub-Task: Update Prompt for AI Process 1 (Doc Classification) (DEV-87)
Sub-Task: Update Prompt for AI Process 2 (OCR Extraction) (DEV-88)
Sub-Task: Update Prompt for AI Process 4 (Linking) (DEV-89)
Sub-Task: Update Prompt for AI Process 5 (Budget Categorization) (DEV-90)

Subscription & Payments (DEV-44)¶

Implement Stripe Integration (DEV-45)
Implement Credit Balance System (DEV-46)
Create Subscription Management UI (DEV-47)

Permissions & Roles (DEV-48)¶

Design Permission Data Model (DEV-49)
Create Permission Checking Service (DEV-50)
Implement Role Management Interface (DEV-51)

Budget Import System (DEV-52)¶

Implement Secure File Upload System (DEV-53)
Integrate with AIHub for Budget Document Processing (DEV-54)
Design AI Prompts and Output Schema for Budget Processing (DEV-55)

Expense Import and Processing (DEV-56)¶

[Tasks to be defined]

Script-to-Budget Automation (DEV-57, AIHub App)¶

Implement Script Parsing Engine (DEV-58)
Develop Budget Estimation AI Model (DEV-62)
Design Budget Output Schema and Integration API (DEV-63)
Implement Script-to-Budget Processing Pipeline (DEV-64)

Refine Framework Implementation (DEV-65)¶

[Tasks to be defined]

ApexCharts Visualization Layer (DEV-66)¶

[Tasks to be defined]

Chart-to-Table Drill-Down POC (DEV-67)¶

[Tasks to be defined]

Crew Management Screen (DEV-68)¶

[Tasks to be defined]

User Management Screen (DEV-69)¶

[Tasks to be defined]

Permissions Management Screen (DEV-70)¶

[Tasks to be defined]

Transactions Screen with Customizable DataGrid (DEV-71)¶

Task: Implement Core Refine DataGrid for Transactions (DEV-91)
Task: Implement Customizable Columns for Transaction DataGrid (DEV-92)
Task: Implement Advanced Filtering for Transaction DataGrid (DEV-93)
Task: Implement Sorting for Transaction DataGrid (DEV-94)
Task: Implement Grouping for Transaction DataGrid (DEV-95)
Task: Implement Saved Views for Transaction DataGrid (DEV-96)
Sub-Task: Define and Implement Standard Saved Views (DEV-100)
Task: Implement Transaction Details View (DEV-97)
Task: Implement Bulk Actions for Transaction DataGrid (DEV-98)
Task: Implement Export Functionality for Transactions (DEV-99)

Sana File Import Integration (DEV-73, Sana App)¶

[Tasks to be defined]

Sana Crew Onboarding Invitations (DEV-74, Sana App)¶

[Tasks to be defined]

Transaction Review Interface (DEV-76)¶

Implement Tab-based Transaction Type Interface (DEV-77)
Create Document-by-Document Review Workflow (DEV-78)
Implement Exception Handling and Manual Editing Tools (DEV-79)

Workflow Example¶

Create the parent feature with detailed description:

{
  "title": "Feature: Dark/Light Mode Toggle",
  "description": "...",
  "teamId": "a9f28c2c-a7ef-4878-985d-4f1ba82d605a",
  "projectId": "f7fe8535-bb6c-4a2c-a911-634cc337cfca",
  "priority": 1,
  "labelIds": ["0b210f6e-3447-4e6a-991f-4809b0546334"]
}

Get the UUID of the parent feature:

{
  "query": "DEV-29"
}

Create child tasks with the parent UUID:

{
  "title": "Create Theme Context Provider",
  "description": "...",
  "teamId": "a9f28c2c-a7ef-4878-985d-4f1ba82d605a",
  "projectId": "f7fe8535-bb6c-4a2c-a911-634cc337cfca",
  "parentId": "ae98d9e4-f702-4832-8c7e-5810be311221"
}

Troubleshooting¶

Common Issues¶

Invalid UUID Error - When setting parentId, you must use the UUID of the parent issue, not the issue identifier (e.g., DEV-29). Retrieve the UUID using linear_search_issues.
Labels Error - Use labelIds instead of labels when adding labels to issues.
Issue Not Found - If you're unable to retrieve an issue, double-check that you're using the correct identifier format (e.g., DEV-29).

This guide is a living document and will be updated as we discover more efficient workflows and best practices.