Linear Integration Guide for Agents

This guide explains how agents should interact with Linear using MCP tools to maintain extensive documentation and project status tracking.

Prerequisites

Ensure Linear MCP server is configured in your MCP settings:

{
  "mcpServers": {
    "linear": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-linear"],
      "env": {
        "LINEAR_API_KEY": "your-api-key"
      }
    }
  }
}

Available Linear MCP Tools

1. `mcplinearsearch_issues`

Search for Linear issues by query string. Parameters:

query: Search query (e.g., “LINEAR-123” or keywords)
limit: Max number of results (default: 10)

Example:

mcp__linear__search_issues
  query: "LINEAR-123"
  limit: 1

2. `mcplinearget_issue`

Get detailed information about a specific issue. Parameters:

issue_id: The issue identifier (e.g., “LINEAR-123”)

Example:

mcp__linear__get_issue
  issue_id: "LINEAR-123"

3. `mcplinearcreate_issue`

Create a new Linear issue. Parameters:

title: Issue title
description: Detailed description (supports markdown)
team_id: Team identifier
priority: 0 (No priority), 1 (Urgent), 2 (High), 3 (Medium), 4 (Low)
state_id: State identifier (Backlog, Todo, In Progress, Done, etc.)
assignee_id: User ID to assign

Example:

mcp__linear__create_issue
  title: "Implement user authentication API"
  description: "## Overview

  Create RESTful API endpoints for user authentication.

  ## Requirements
  - POST /api/auth/register
  - POST /api/auth/login
  - GET /api/auth/me

  ## Acceptance Criteria
  - [ ] Registration endpoint validates email and password
  - [ ] Login returns JWT token
  - [ ] Me endpoint returns authenticated user info"
  team_id: "TEAM-123"
  priority: 2

4. `mcplinearupdate_issue`

Update an existing Linear issue. Parameters:

issue_id: Issue identifier
title: New title (optional)
description: New description (optional)
priority: New priority (optional)
state_id: New state (optional)
assignee_id: New assignee (optional)

Example:

mcp__linear__update_issue
  issue_id: "LINEAR-123"
  state_id: "in-progress"
  description: "## Implementation Plan

  ### Phase 1: API Setup
  - [x] Create route handlers
  - [x] Configure middleware
  - [ ] Add validation schemas

  ### Phase 2: Service Layer
  - [ ] Implement AuthService
  - [ ] Add business logic validation"

5. `mcplinearadd_comment`

Add a comment to an issue. Parameters:

issue_id: Issue identifier
body: Comment text (supports markdown)

Example:

mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Progress Update - Phase 1 Complete

  Completed tasks:
  - ✅ Created route handlers in `src/routes/authRoutes.ts`
  - ✅ Configured middleware stack
  - ✅ Added Joi validation schemas

  Commits: abc123, def456, ghi789

  Starting Phase 2: Service Layer implementation"

6. `mcplinearlist_teams`

List all teams in the Linear workspace. Example:

mcp__linear__list_teams

7. `mcplinearget_team`

Get team details including states and workflows. Parameters:

team_id: Team identifier

Example:

mcp__linear__get_team
  team_id: "TEAM-123"

Agent Workflow with Linear

1. Start of Work - Read Ticket

When starting a new task, agents should:

Search for the ticket:

# Use MCP tool to find the ticket
mcp__linear__search_issues
  query: "LINEAR-123"
  limit: 1

Get full ticket details:

mcp__linear__get_issue
  issue_id: "LINEAR-123"

Read related documents mentioned in the ticket description

2. Update Status - Starting Work

When beginning implementation:

mcp__linear__update_issue
  issue_id: "LINEAR-123"
  state_id: "in-progress"

mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Starting Implementation

**Agent**: @backend-developer
**Branch**: feature/LINEAR-123-user-auth
**Start Date**: 2025-01-10

### Implementation Plan Approved
[Link to detailed plan in docs]

### Next Steps
Starting Phase 1: API Setup"

3. Document Implementation Plan

After plan approval, update the ticket with comprehensive details:

mcp__linear__update_issue
  issue_id: "LINEAR-123"
  description: "## Overview
Create RESTful API endpoints for user authentication.

## Requirements
- POST /api/auth/register
- POST /api/auth/login
- GET /api/auth/me

## Implementation Plan

### Phase 1: API Setup ✅ [COMPLETE]
- [x] Task 1.1: Set up route handlers
  - File: `src/routes/authRoutes.ts`
  - Commit: abc123
- [x] Task 1.2: Configure middleware stack
  - File: `src/middleware/auth.ts`
  - Commit: def456
- [x] Task 1.3: Add validation schemas
  - File: `src/validators/authValidators.ts`
  - Commit: ghi789

### Phase 2: Service Layer 🔄 [IN PROGRESS]
- [ ] Task 2.1: Implement AuthService
- [ ] Task 2.2: Add business logic validation
- [ ] Task 2.3: Implement JWT token generation

### Phase 3: Database Integration ⏳ [TODO]
- [ ] Task 3.1: Create User repository
- [ ] Task 3.2: Implement password hashing
- [ ] Task 3.3: Add session management

### Phase 4: Testing ⏳ [TODO]
- [ ] Task 4.1: Unit tests for AuthService
- [ ] Task 4.2: Integration tests for endpoints
- [ ] Task 4.3: Security testing

## Technical Stack
- Framework: Express.js
- Database: PostgreSQL with Prisma
- Authentication: JWT with bcrypt
- Validation: Joi

## Security Considerations
- bcrypt password hashing (cost factor: 12)
- JWT expiration: 24 hours
- Rate limiting: 5 attempts per 15 minutes
- Input validation on all endpoints

## API Endpoints
\`\`\`
POST   /api/v1/auth/register  - User registration
POST   /api/v1/auth/login     - User login
GET    /api/v1/auth/me        - Get current user
POST   /api/v1/auth/logout    - User logout
POST   /api/v1/auth/refresh   - Refresh JWT token
\`\`\`

## Documentation Links
- [API Contract](docs/architecture/api-contracts/auth-api.yaml)
- [Database Schema](docs/database/schemas/users-schema.md)
- [Implementation Plan](docs/implementation/LINEAR-123-plan.md)

## Acceptance Criteria
- [x] Registration endpoint validates email and password
- [ ] Login returns JWT token
- [ ] Me endpoint returns authenticated user info
- [ ] All endpoints have proper error handling
- [ ] Test coverage > 80%"

4. Progress Updates - After Each Phase

After completing each phase:

mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Phase 1 Complete ✅

### Completed Tasks
- ✅ Set up route handlers in `src/routes/authRoutes.ts`
- ✅ Configured middleware stack in `src/middleware/`
- ✅ Added Joi validation schemas in `src/validators/`

### Commits
- abc123: feat(api): add auth route handlers
- def456: feat(middleware): add JWT authentication middleware
- ghi789: feat(validation): add auth input validation schemas

### Files Changed
- `src/routes/authRoutes.ts` (+85 lines)
- `src/middleware/auth.ts` (+120 lines)
- `src/validators/authValidators.ts` (+65 lines)

### Progress: 25% Complete

### Next Phase
Starting Phase 2: Service Layer implementation"

5. Technical Decisions

Document all technical decisions in the ticket:

mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Technical Decision: JWT Token Storage

### Decision
Store JWT tokens in HTTP-only cookies instead of localStorage

### Rationale
- Prevents XSS attacks from stealing tokens
- Automatically sent with requests
- Can set secure and SameSite flags

### Alternatives Considered
1. localStorage - Rejected due to XSS vulnerability
2. sessionStorage - Same security concerns as localStorage
3. Memory only - Rejected due to poor UX (login on every refresh)

### Implementation Impact
- Need to handle CSRF protection
- Requires cookie parsing middleware
- Must configure CORS to allow credentials

### References
- [OWASP Token Storage Best Practices](https://example.com)
- Architecture discussion: docs/architecture/decisions/jwt-storage.md"

6. Blockers

If encountering blockers:

mcp__linear__update_issue
  issue_id: "LINEAR-123"
  priority: 1

mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## ⚠️ BLOCKER ENCOUNTERED

### Blocker Description
Cannot proceed with Phase 3 (Database Integration) because user schema is not yet created in database.

### Impact
- Phase 3 delayed by estimated 2 days
- Overall ticket completion delayed
- Blocking LINEAR-124 (User Profile API)

### Dependency
Waiting on: LINEAR-100 (Database Schema Implementation)
Assigned to: @dba

### Temporary Solution
- Continuing with mock data for testing
- Writing integration tests that will work once schema is ready
- Documenting exact schema requirements

### Required to Unblock
User table must have:
- id (UUID, primary key)
- email (VARCHAR, unique, not null)
- password_hash (VARCHAR, not null)
- created_at (TIMESTAMP)
- updated_at (TIMESTAMP)

### Next Steps
- [ ] Notify @dba of dependency
- [ ] Continue with testable work
- [ ] Resume Phase 3 once LINEAR-100 is complete"

7. Implementation Complete

When implementation is finished:

mcp__linear__update_issue
  issue_id: "LINEAR-123"
  state_id: "ready-for-review"

mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Implementation Complete ✅

### Summary
All API endpoints for user authentication have been implemented, tested, and documented.

### Completed Deliverables
- ✅ All API endpoints implemented per specification
- ✅ AuthService with complete business logic
- ✅ User repository with password hashing
- ✅ JWT token generation and validation
- ✅ Input validation on all endpoints
- ✅ Comprehensive error handling
- ✅ Rate limiting configured (5 attempts / 15 min)
- ✅ Test coverage: 87%
- ✅ All acceptance criteria met

### Git Information
- **Branch**: feature/LINEAR-123-user-auth
- **Total Commits**: 15 commits
- **Files Changed**: 12 files
- **Lines Added**: +1,247
- **Lines Removed**: -53

### Key Commits
- abc123: feat(api): implement user registration endpoint
- def456: feat(api): implement user login endpoint
- ghi789: feat(auth): add JWT token generation
- jkl012: test(auth): add comprehensive auth tests

### API Endpoints Implemented
- ✅ POST   /api/v1/auth/register - User registration
- ✅ POST   /api/v1/auth/login - User login
- ✅ GET    /api/v1/auth/me - Get current user
- ✅ POST   /api/v1/auth/logout - User logout
- ✅ POST   /api/v1/auth/refresh - Refresh token

### How to Test
\`\`\`bash
# 1. Checkout branch
git checkout feature/LINEAR-123-user-auth

# 2. Install dependencies
npm install

# 3. Set up environment
cp .env.example .env
# Add required vars: DATABASE_URL, JWT_SECRET

# 4. Run migrations
npm run migrate

# 5. Start server
npm run dev

# 6. Test registration
curl -X POST http://localhost:3000/api/v1/auth/register \\
  -H \"Content-Type: application/json\" \\
  -d '{\"email\":\"test@example.com\",\"password\":\"Test123!@#\"}'

# 7. Test login
curl -X POST http://localhost:3000/api/v1/auth/login \\
  -H \"Content-Type: application/json\" \\
  -d '{\"email\":\"test@example.com\",\"password\":\"Test123!@#\"}'
\`\`\`

### Test Results
- Unit tests: 45 tests, 45 passing ✅
- Integration tests: 12 tests, 12 passing ✅
- Coverage: 87% (target: 80%) ✅

### Security Checklist
- [x] Input validation on all endpoints
- [x] Password hashing with bcrypt (cost: 12)
- [x] JWT tokens with expiration
- [x] Rate limiting implemented
- [x] CORS configured properly
- [x] Error messages don't leak sensitive data
- [x] No SQL injection vulnerabilities
- [x] XSS prevention in place

### Documentation
- [x] API documentation updated
- [x] README updated with auth endpoints
- [x] Postman collection created
- [x] Inline code comments added

### Performance
- Registration: ~180ms avg response time
- Login: ~150ms avg response time
- Token validation: ~5ms avg response time

### Next Steps
**Ready for handoff to:**
- @app-security-engineer for security scan
- @senior-qa-engineer for QA testing

**Handoff Instructions:**
1. Review implementation in `src/routes/authRoutes.ts`
2. Run security scan: `bash .claude/skills/secure-push/scripts/pre-push-scan.sh`
3. Execute test plan: `docs/testing/auth-test-plan.md`

### Related Issues
- Blocks: LINEAR-124 (User Profile API)
- Blocks: LINEAR-125 (Password Reset Flow)
- Related: LINEAR-100 (Database Schema) - Used this schema"

8. After Review/QA Feedback

When receiving feedback:

mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## QA Feedback Received

### Issues Found
1. ⚠️ **Rate limiting not working on /register endpoint**
   - Severity: High
   - Can spam registration attempts
   - Fix: Apply rate limiter middleware to route

2. ⚠️ **Password validation too weak**
   - Severity: Medium
   - Only checks length, not complexity
   - Fix: Add complexity requirements (upper, lower, number, special char)

3. ℹ️ **Missing password strength indicator**
   - Severity: Low
   - Enhancement suggestion
   - Future improvement

### Fixes Applied
- [x] Applied rate limiter to registration endpoint (commit: xyz789)
- [x] Enhanced password validation rules (commit: uvw456)
- [ ] Password strength indicator (deferred to LINEAR-126)

### Re-test Results
- All QA test cases passing ✅
- Security scan clean ✅
- Ready for deployment"

9. Merge to Main

After merge:

mcp__linear__update_issue
  issue_id: "LINEAR-123"
  state_id: "done"

mcp__linear__add_comment
  issue_id: "LINEAR-123"
  body: "## Merged to Main ✅

### Merge Details
- **PR**: #42
- **Merged By**: [User]
- **Merge Date**: 2025-01-10
- **Merge Commit**: abc123def456

### Deployment Status
- ✅ Merged to main
- ✅ Deployed to staging (v1.2.0-rc1)
- ⏳ Awaiting production deployment

### Production Deployment
- **Scheduled**: 2025-01-12 10:00 AM UTC
- **Deployer**: @devops-engineer
- **Deployment Ticket**: LINEAR-130

### Metrics
- Total development time: 5 days
- Commits: 15
- Files changed: 12
- Test coverage: 87%

### Follow-up Items
- [ ] Monitor error rates in production
- [ ] Create LINEAR-126 for password strength indicator
- [ ] Update user documentation"

Documentation Standards

Ticket Description Structure

Every Linear ticket should have:

Overview - Brief summary of the task
Requirements - What needs to be built/fixed
Implementation Plan - Phased approach with tasks
Technical Stack - Technologies used
Security Considerations - Security measures
API/Database Details - Specific technical details
Documentation Links - Links to related docs
Acceptance Criteria - Clear success criteria

Comment Standards

Every comment should:

Use clear headers with ## markdown
Include status indicators (✅ ✓ ⏳ 🔄 ⚠️)
Reference commits when discussing code changes
Link to files when discussing implementation
Provide context - explain the “why” not just “what”
Be actionable - clear next steps

Update Frequency

Agents should update Linear:

At start of work - Status change + initial comment
After each phase - Progress update
When making decisions - Document the decision
When blocked - Immediate blocker notification
At completion - Comprehensive summary
After feedback - Document changes made
After merge - Final status update

Best Practices

DO ✅

Be comprehensive - Include all relevant details
Use markdown - Format for readability
Link extensively - Connect to files, commits, docs
Update frequently - Keep stakeholders informed
Document decisions - Explain technical choices
Include examples - Show how to test/use
Reference blockers - Call out dependencies
Provide metrics - Performance, coverage, time

DON’T ❌

Be vague - Avoid “Fixed stuff” or “Updated code”
Skip updates - Don’t go silent for days
Hide blockers - Surface issues immediately
Forget links - Always link to related work
Omit context - Explain why, not just what
Ignore feedback - Acknowledge and address all feedback
Rush documentation - Take time to be thorough

Example: Complete Ticket Lifecycle

See LINEAR-123-EXAMPLE.md for a complete example of a ticket from creation through deployment with all updates and comments.

Get Started

Workflow & Processes

Examples

LINEAR INTEGRATION GUIDE

Linear Integration Guide for Agents

Prerequisites

Available Linear MCP Tools

1. `mcplinearsearch_issues`

2. `mcplinearget_issue`

3. `mcplinearcreate_issue`

4. `mcplinearupdate_issue`

5. `mcplinearadd_comment`

6. `mcplinearlist_teams`

7. `mcplinearget_team`

Agent Workflow with Linear

1. Start of Work - Read Ticket

2. Update Status - Starting Work

3. Document Implementation Plan

4. Progress Updates - After Each Phase

5. Technical Decisions

6. Blockers

7. Implementation Complete

8. After Review/QA Feedback

9. Merge to Main

Documentation Standards

Ticket Description Structure

Comment Standards

Update Frequency

Best Practices

DO ✅

DON’T ❌

Example: Complete Ticket Lifecycle

Troubleshooting

Linear MCP Not Working

Cannot Find Issue

Cannot Update Issue

Additional Resources

​Linear Integration Guide for Agents

​Prerequisites

​Available Linear MCP Tools

​1. mcp__linear__search_issues

​2. mcp__linear__get_issue

​3. mcp__linear__create_issue

​4. mcp__linear__update_issue

​5. mcp__linear__add_comment

​6. mcp__linear__list_teams

​7. mcp__linear__get_team

​Agent Workflow with Linear

​1. Start of Work - Read Ticket

​2. Update Status - Starting Work

​3. Document Implementation Plan

​4. Progress Updates - After Each Phase

​5. Technical Decisions

​6. Blockers

​7. Implementation Complete

​8. After Review/QA Feedback

​9. Merge to Main

​Documentation Standards

​Ticket Description Structure

​Comment Standards

​Update Frequency

​Best Practices

​DO ✅

​DON’T ❌

​Example: Complete Ticket Lifecycle

​Troubleshooting

​Linear MCP Not Working

​Cannot Find Issue

​Cannot Update Issue

​Additional Resources

Linear Integration Guide for Agents

Prerequisites

Available Linear MCP Tools

1. `mcplinearsearch_issues`

2. `mcplinearget_issue`

3. `mcplinearcreate_issue`

4. `mcplinearupdate_issue`

5. `mcplinearadd_comment`

6. `mcplinearlist_teams`

7. `mcplinearget_team`

Agent Workflow with Linear

1. Start of Work - Read Ticket

2. Update Status - Starting Work

3. Document Implementation Plan

4. Progress Updates - After Each Phase

5. Technical Decisions

6. Blockers

7. Implementation Complete

8. After Review/QA Feedback

9. Merge to Main

Documentation Standards

Ticket Description Structure

Comment Standards

Update Frequency

Best Practices

DO ✅

DON’T ❌

Example: Complete Ticket Lifecycle

Troubleshooting

Linear MCP Not Working

Cannot Find Issue

Cannot Update Issue

Additional Resources